| .\" 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 |
| |
| .br |
| Expect to see some harmless warnings like |
| .br |
| |
| xorriso : WARNING : \-volid text does not comply to ISO 9660 / ECMA 119 rules |
| |
| libisofs: WARNING : Cannot add /debian to Joliet tree. Symlinks can only be added to a Rock Ridge tree. |
| |
| libisofs: WARNING : Image size exceeds 1024 cylinders. Cannot align partition. |
| |
| .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. |
