284 lines
9.9 KiB
Groff
284 lines
9.9 KiB
Groff
.\" Hey, EMACS: -*- nroff -*-
|
|
.\"
|
|
.\" IMPORTANT NOTE:
|
|
.\"
|
|
.\" The original of this file is kept in test/merge_debian_isos.texi
|
|
.\" This here was generated by program xorriso/make_xorriso_1
|
|
.\"
|
|
.\"
|
|
.\" First parameter, NAME, should be all caps
|
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
|
|
.\" other parameters are allowed: see man(7), man(1)
|
|
.TH MERGE_DEBIAN_ISOS 1 "Version 1.5.5, Oct 19, 2022"
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
.\"
|
|
.\" Some roff macros, for reference:
|
|
.\" .nh disable hyphenation
|
|
.\" .hy enable hyphenation
|
|
.\" .ad l left justify
|
|
.\" .ad b justify to both left and right margins
|
|
.\" .nf disable filling
|
|
.\" .fi enable filling
|
|
.\" .br insert line break
|
|
.\" .sp <n> insert n+1 empty lines
|
|
.\" for manpage-specific macros, see man(7)
|
|
.nh
|
|
.SH NAME
|
|
merge_debian_isos \- Program to merge multiple debian\-cd ISO images
|
|
.SH SYNOPSIS
|
|
.B merge_debian_isos
|
|
result_iso mount_template iso1 iso2 [... isoN]
|
|
.br
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBmerge_debian_isos\fR
|
|
mounts by \fBsudo\fR the ISO 9660 images iso1 to isoN at directories
|
|
mount_template1 to mount_templateN, if not already mounted that way.
|
|
Then the Debian pools and package lists get merged and a new
|
|
ISO 9660 image result_iso is produced by a run of \fBxorriso\fR.
|
|
If iso1 is bootable then
|
|
the new image will be bootable by the same means.
|
|
.br
|
|
.PP
|
|
The file depicted by result_iso must not yet exist or has to be a
|
|
device which is acceptable for Linux\-specific helper script
|
|
\fBxorriso\-dd\-target\fR. If xorriso\-dd\-target agrees and the user
|
|
confirms by input "yes" then xorriso will be run under sudo.
|
|
.br
|
|
Exempted from this evaluation are addresses which begin by "mmc:"
|
|
for an optical drive on Linux, BSDs, Solaris, or by "stdio:/dev/"
|
|
for which the user takes full and dangerous responsibility.
|
|
.br
|
|
Special result_iso path \fBxorriso\-dd\-target\-plug\-test\fR determines
|
|
on systems with Linux kernel the target USB stick by a dialog around plugging
|
|
it in.
|
|
xorriso will be run under sudo, if xorriso\-dd\-target agrees and
|
|
the user confirms by input "yes".
|
|
.br
|
|
.PP
|
|
At least the parent directory of argument \fBmount_template\fR must already
|
|
exist or has to be given by a plain name without "/" so that it can be
|
|
created in the current directory. (I.e. without even "./".)
|
|
.br
|
|
All arguments must be single words without using quotation marks.
|
|
None of the isoN must be equal to another isoM.
|
|
.br
|
|
.PP
|
|
This script creates and finally removes the following temporary tree
|
|
and files which must not yet exist in the current working directory:
|
|
./merged_dists , ./merged_md5sum.txt , ./merged_REAMDE.txt
|
|
./temp_file
|
|
.br
|
|
Further it creates and finally removes directories mount_template*
|
|
if they are needed and do not exist when the script starts. If the
|
|
parent directory in the mount_template path does not exist and
|
|
its path contains no "/" then it gets created and finally removed.
|
|
The script depends on the following programs:
|
|
.br
|
|
awk, basename, cat, chmod, cp, date, dirname, expr, fgrep, grep,
|
|
gunzip, gzip, head, ls, md5sum, mkdir, mount, mv, rm, rmdir,
|
|
sed, sh, sha256sum, sort, stat, sudo, umount, uniq, xorriso
|
|
.br
|
|
With device writing involving helper script xorriso\-dd\-target:
|
|
.br
|
|
dd, Linux kernel, lsblk, sleep, tr, uname, wc, whoami,
|
|
xorriso\-dd\-target
|
|
.br
|
|
Recommended are: sha1sum, sha512sum
|
|
|
|
.SS
|
|
.br
|
|
.SH OPTIONS
|
|
.br
|
|
.PP
|
|
merge_debian_isos has no command line options besides the input words described
|
|
above, but it reacts on some environment variables.
|
|
.br
|
|
See section ENVIRONMENT.
|
|
.br
|
|
.PP
|
|
If less than 4 arguments are given, the script will print its help text to
|
|
standard error and exit with non\-zero value, indicating failure.
|
|
.SS
|
|
.SH EXAMPLES
|
|
.SS
|
|
.B Overview of examples:
|
|
Merge DVD images 1 to 5
|
|
.br
|
|
Use GNU xorriso instead of installed xorriso
|
|
.br
|
|
Write result directly to an optical drive
|
|
.br
|
|
Write result directly and safely to USB stick (Linux only)
|
|
.br
|
|
Write result directly and unsafely to USB stick
|
|
.SS
|
|
.B Merge DVD images 1 to 5
|
|
The resulting image will be named "merged.iso".
|
|
.br
|
|
Directory ./merge_mount/ will be created if not yet existing.
|
|
.br
|
|
|
|
merge_debian_isos merged.iso merge_mount/iso \\
|
|
debian\-11.2.0\-amd64\-DVD\-[12345].iso
|
|
|
|
.SS
|
|
.B Use GNU xorriso instead of installed xorriso
|
|
merge_debian_isos will refuse to work if the installed version of xorriso
|
|
is older than 1.4.2. In this case consider to download and compile the
|
|
GNU xorriso tarball from
|
|
.br
|
|
https://www.gnu.org/software/xorriso/#download
|
|
.br
|
|
You may use it without installing it after compilation and thus without
|
|
disturbing your system's package management. Assumed that you unpacked the
|
|
xorriso\-1.5.4 tarball in your $HOME directory and have successfully compiled
|
|
it, do:
|
|
.br
|
|
|
|
export XORRISO="$HOME"/xorriso\-1.5.4/xorriso/xorriso
|
|
.br
|
|
|
|
merge_debian_isos merged.iso merge_mount/iso \\
|
|
debian\-11.2.0\-amd64\-DVD\-[12345].iso
|
|
|
|
.SS
|
|
.B Write result directly to an optical drive
|
|
xorriso is able to burn optical media on GNU/Linux (/dev/sr*),
|
|
Solaris (/dev/rdsk/*) , FreeBSD (/dev/cd*) , NetBSD (/dev/rcd*),
|
|
and OpenBSD (/dev/rcd*). Get a list of available optical drive devices by:
|
|
.br
|
|
|
|
xorriso \-devices
|
|
.br
|
|
|
|
It might be that you need superuser powers for this and then have to enable
|
|
access to the device file for the user who runs merge_debian_isos.
|
|
.br
|
|
|
|
In order to directly write the merged ISO image to an optical medium,
|
|
use the desired device file path with prefix "mmc:":
|
|
.br
|
|
|
|
merge_debian_isos mmc:/dev/sr0 merge_mount/iso \\
|
|
debian\-11.2.0\-amd64\-DVD\-[12345].iso
|
|
|
|
.SS
|
|
.B Write result directly and safely to USB stick (Linux only)
|
|
The Linux\-specific script \fBxorriso\-dd\-target\fR evaluates device files
|
|
whether they and their content look unimportant enough for being overwritten
|
|
by an image file.
|
|
.br
|
|
This mainly means that the storage device is attached to USB and contains
|
|
no filesystems which are not of type FAT or ISO 9660.
|
|
.br
|
|
You may get xorriso\-dd\-target by:
|
|
.br
|
|
|
|
wget \\
|
|
https://dev.lovelyhq.com/libburnia/libisoburn/raw/master/xorriso\-dd\-target/xorriso\-dd\-target
|
|
chmod u+x xorriso\-dd\-target
|
|
.br
|
|
|
|
Consider to also download xorriso\-dd\-target.sig and to verify the script by
|
|
.br
|
|
|
|
gpg \-\-verify xorriso\-dd\-target.sig xorriso\-dd\-target
|
|
.br
|
|
|
|
Announce the storage location of the downloaded xorriso\-dd\-target:
|
|
.br
|
|
|
|
export XORRISO_DD_TARGET_PATH="$(pwd)"
|
|
.br
|
|
|
|
The prepared use case in merge_debian_isos uses the xorriso\-dd\-target
|
|
option \-plug_test under \fBsudo\fR, which asks the user for first having
|
|
the desired USB stick unplugged so that the unwanted devices can get
|
|
registered. Then it asks the user to plug in the USB stick, so that it gets
|
|
recognized as desired target.
|
|
.br
|
|
xorriso\-dd\-target evaluates the content and decides whether it looks
|
|
disposable enough. If so, then it allows merge_debian_isos to write its
|
|
result to the device.
|
|
.br
|
|
|
|
merge_debian_isos xorriso\-dd\-target\-plug\-test merge_mount/iso \\
|
|
debian\-11.2.0\-amd64\-DVD\-[12345].iso
|
|
|
|
.SS
|
|
.B Write result directly and unsafely to USB stick
|
|
On operating systems other than GNU/Linux or with storage devices not
|
|
acceptable to xorriso\-dd\-target it is possible to remove all safety
|
|
precautions beyond those of xorriso, which can be overcome by "blanking"
|
|
the device.
|
|
.br
|
|
So after due evaluation of the device situation and on your very own risk
|
|
you may use the device path prefix "stdio:", possibly with superuser powers:
|
|
.br
|
|
|
|
xorriso \-outdev stdio:/dev/sdd \-blank as_needed
|
|
|
|
merge_debian_isos stdio:/dev/sdd merge_mount/iso \\
|
|
debian\-11.2.0\-amd64\-DVD\-[12345].iso
|
|
|
|
For details about "stdio:" and pseudo\-blanking non\-optical devices read
|
|
man xorriso.
|
|
.br
|
|
The xorriso run in merge_debian_isos ignores locally defined xorriso startup
|
|
files (by command \-no_rc).
|
|
.SH FILES
|
|
For now, no files are defined for configuration.
|
|
.SH ENVIRONMENT
|
|
The following environment variables influence the program behavior:
|
|
.br
|
|
Exported non\-empty variable MERGE_DATE enforces a particular
|
|
date string in the text which gets prepended to /README.txt .
|
|
.br
|
|
Exported non\-empty variable MERGE_FOR_DIST enforces the use of a
|
|
particular directory in /dists of iso1. Normally only one
|
|
such directory is found and thus no need to set MERGE_FOR_DIST.
|
|
.br
|
|
Exported non\-empty variable MERGE_KEEP_ISO prevents the removal
|
|
of result_iso after xorriso indicated failure of production.
|
|
.br
|
|
Exported non\-empty variable XORRISO gives the path to a xorriso binary,
|
|
which will be used instead of the system\-wide installed xorriso binary.
|
|
This may be needed if installed xorriso is older than 1.4.2.
|
|
.br
|
|
If XORRISO is set to "dummy" then no new ISO will emerge.
|
|
.br
|
|
Exported non\-empty variable XORRISO_DD_TARGET_PATH names the
|
|
directory where to find xorriso\-dd\-target, which evaluates the
|
|
suitability of result_iso devices or does the plug\-test dialog.
|
|
.br
|
|
.SH SEE ALSO
|
|
.BR xorriso(1),
|
|
.BR xorriso-dd-target(1),
|
|
.SH BUGS
|
|
To report bugs, request help, or suggest enhancements for
|
|
\fBmerge_debian_isos\fR,
|
|
please send electronic mail to the public list <bug\-xorriso@gnu.org>.
|
|
If more privacy is desired, mail to <scdbackup@gmx.net>.
|
|
.br
|
|
Please describe what you expect the program to do, the program arguments
|
|
which you used, the messages of \fBmerge_debian_isos\fR, and the
|
|
undesirable outcome of your program run.
|
|
.br
|
|
Expect to get asked more questions before solutions can be proposed.
|
|
.SH AUTHOR
|
|
Thomas Schmitt <scdbackup@gmx.net>
|
|
.br
|
|
for libburnia\-project.org
|
|
.SH COPYRIGHT
|
|
Copyright (c) 2022 Thomas Schmitt
|
|
.br
|
|
Permission is granted to distribute this text freely. It shall only be
|
|
modified in sync with the technical properties of merge_debian_isos.
|
|
If you make use of the license to derive modified versions of merge_debian_isos
|
|
then you are entitled to modify this text under that same license.
|
|
.SH CREDITS
|
|
\fBmerge_debian_isos\fR was originally developed with advise and testing
|
|
by Zhang Boyang in the course of Debian bug #1011343. Steve McIntyre provided
|
|
information about various file aspects of debian\-cd ISO images.
|