libburnia
/
libisoburn
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Created manual pages for merge_debian_iso

This commit is contained in:
Thomas Schmitt 2022-10-19 13:23:47 +02:00
parent 847afc0095
commit fd195504ae
3 changed files with 1063 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

283
test/merge_debian_isos.1 Normal file
View File

@ -0,0 +1,283 @@
.\" 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
\fBxorriso\-dd\-target\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 \fBxorriso\-dd\-target\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.

346
test/merge_debian_isos.info Normal file
View File

@ -0,0 +1,346 @@
This is merge_debian_isos.info, produced by makeinfo version 5.2 from
merge_debian_isos.texi.
merge_debian_isos - sh script to merge multiple debian-cd ISO images
Copyright (C) 2022 Thomas Schmitt
Permission is granted to distribute this text freely.
INFO-DIR-SECTION Archiving
START-INFO-DIR-ENTRY
* Merge_debian_isos: (merge_debian_isos). Merge debian-cd ISO images to a single image
END-INFO-DIR-ENTRY

File: merge_debian_isos.info, Node: Top, Next: Overview, Up: (dir)
merge_debian_isos 1.5.5
***********************
merge_debian_isos - Program to merge multiple debian-cd ISO images
* Menu:
* Overview:: Overview
* Options:: Options
* Examples:: Examples
* Files:: Files
* Environ:: Environment
* Seealso:: See also
* Bugreport:: Reporting bugs
* Legal:: Author, Copyright, Credits
* CommandIdx:: Alphabetic Option List
* ConceptIdx:: Alphabetic List of Concepts and Objects

File: merge_debian_isos.info, Node: Overview, Next: Options, Prev: Top, Up: Top
1 Overview
**********
'merge_debian_isos' mounts by *sudo* 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 *xorriso*. If iso1 is
bootable then the new image will be bootable by the same means.
The file depicted by result_iso must not yet exist or has to be a
device which is acceptable for Linux-specific helper script
*xorriso-dd-target*. If xorriso-dd-target agrees and the user confirms
by input "yes" then xorriso will be run under sudo.
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.
Special result_iso path *xorriso-dd-target-plug-test* 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".
At least the parent directory of argument *mount_template* 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 "./".)
All arguments must be single words without using quotation marks. None
of the isoN must be equal to another isoM.
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
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:
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
With device writing involving helper script xorriso-dd-target:
dd, Linux kernel, lsblk, sleep, tr, uname, wc, whoami, xorriso-dd-target
Recommended are: sha1sum, sha512sum

File: merge_debian_isos.info, Node: Options, Next: Examples, Prev: Overview, Up: Top
2 Options
*********
merge_debian_isos has no command line options besides the input words
described above, but it reacts on some environment variables.
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.

File: merge_debian_isos.info, Node: Examples, Next: Files, Prev: Options, Up: Top
3 Examples
**********
* Menu:
* ExPlain:: Merge DVD images 1 to 5
* ExXorriso:: Use GNU xorriso instead of installed xorriso
* ExOptical:: Write result directly to an optical drive
* ExDdTarget:: Write result directly and safely to USB stick (Linux only)
* ExStdio:: Write result directly and unsafely to USB stick

File: merge_debian_isos.info, Node: ExPlain, Next: ExXorriso, Prev: Options, Up: Examples
3.1 Merge DVD images 1 to 5
===========================
The resulting image will be named "merged.iso".
Directory ./merge_mount/ will be created if not yet existing.
merge_debian_isos merged.iso merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso

File: merge_debian_isos.info, Node: ExXorriso, Next: ExOptical, Prev: ExPlain, Up: Examples
3.2 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
https://www.gnu.org/software/xorriso/#download
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:
export XORRISO="$HOME"/xorriso-1.5.4/xorriso/xorriso
merge_debian_isos merged.iso merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso

File: merge_debian_isos.info, Node: ExOptical, Next: ExDdTarget, Prev: ExXorriso, Up: Examples
3.3 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:
xorriso -devices
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.
In order to directly write the merged ISO image to an optical medium,
use the desired device file path with prefix "mmc:":
merge_debian_isos mmc:/dev/sr0 merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso

File: merge_debian_isos.info, Node: ExDdTarget, Next: ExStdio, Prev: ExOptical, Up: Examples
3.4 Write result directly and safely to USB stick (Linux only)
==============================================================
The Linux-specific script *xorriso-dd-target* evaluates device files
whether they and their content look unimportant enough for being
overwritten by an image file.
This mainly means that the storage device is attached to USB and
contains no filesystems which are not of type FAT or ISO 9660.
You may get xorriso-dd-target by:
wget \
https://dev.lovelyhq.com/libburnia/libisoburn/raw/master/xorriso-dd-target/xorriso-dd-target
chmod u+x xorriso-dd-target
Consider to also download xorriso-dd-target.sig and to verify the
script by
gpg -verify xorriso-dd-target.sig xorriso-dd-target
Announce the storage location of the downloaded xorriso-dd-target:
export XORRISO_DD_TARGET_PATH="$(pwd)"
The prepared use case in merge_debian_isos uses the xorriso-dd-target
option -plug_test under *sudo*, 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.
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.
merge_debian_isos xorriso-dd-target-plug-test merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso

File: merge_debian_isos.info, Node: ExStdio, Next: Files, Prev: ExDdTarget, Up: Examples
3.5 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.
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:
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.
The xorriso run in merge_debian_isos ignores locally defined xorriso
startup files (by command -no_rc).

File: merge_debian_isos.info, Node: Files, Next: Environ, Prev: Examples, Up: Top
4 Files
*******
For now, no files are defined for configuration.

File: merge_debian_isos.info, Node: Environ, Next: Seealso, Prev: Files, Up: Top
5 Environ
*********
The following environment variables influence the program behavior:
Exported non-empty variable MERGE_DATE enforces a particular date string
in the text which gets prepended to /README.txt .
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.
Exported non-empty variable MERGE_KEEP_ISO prevents the removal of
result_iso after xorriso indicated failure of production.
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.
If XORRISO is set to "dummy" then no new ISO will emerge.
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.

File: merge_debian_isos.info, Node: Seealso, Next: Bugreport, Prev: Environ, Up: Top
6 See also
**********
xorriso(1), xorriso-dd-target(1)

File: merge_debian_isos.info, Node: Bugreport, Next: Legal, Prev: Seealso, Up: Top
7 Reporting bugs
****************
To report bugs, request help, or suggest enhancements for
'xorriso-dd-target', please send electronic mail to the public list
<bug-xorriso@gnu.org>. If more privacy is desired, mail to
<scdbackup@gmx.net>.
Please describe what you expect the program to do, the program
arguments which you used, the messages of 'xorriso-dd-target', and the
undesirable outcome of your program run.
Expect to get asked more questions before solutions can be proposed.

File: merge_debian_isos.info, Node: Legal, Next: CommandIdx, Prev: Bugreport, Up: Top
8 Author, Copyright, Credits
****************************
8.1 Author
==========
Thomas Schmitt <scdbackup@gmx.net>
for libburnia-project.org
8.2 Copyright
=============
Copyright (c) 2022 Thomas Schmitt
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.
8.3 Credits
===========
'merge_debian_isos' 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.

File: merge_debian_isos.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
9 Alphabetic Options List
*************************

File: merge_debian_isos.info, Node: ConceptIdx, Next: Top, Prev: CommandIdx, Up: Top
10 Alphabetic List of Concepts and Objects
******************************************
[index]
* Menu:
* Bugs, reporting: Bugreport. (line 6)
* Examples: Examples. (line 6)
* merge_debian_isos, options: Options. (line 6)
* Problems, reporting: Bugreport. (line 6)

Tag Table:
Node: Top417
Node: Overview1014
Node: Options3381
Node: Examples3771
Node: ExPlain4196
Node: ExXorriso4548
Node: ExOptical5342
Node: ExDdTarget6126
Node: ExStdio7649
Node: Files8561
Node: Environ8717
Node: Seealso9782
Node: Bugreport9931
Node: Legal10516
Node: CommandIdx11344
Node: ConceptIdx11491

End Tag Table

434
test/merge_debian_isos.texi Normal file
View File

@ -0,0 +1,434 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename merge_debian_isos.info
@settitle merge_debian_isos 1.5.5
@c %**end of header
@c
@c man-ignore-lines begin
@dircategory Archiving
@direntry
* Merge_debian_isos: (merge_debian_isos). Merge debian-cd ISO images to a single image
@end direntry
@c man-ignore-lines end
@c
@c Notes about embedded man page:
@c This texinfo code contains the necessary info to produce a man page.
@c One can produce it by applying the following rules:
@c The first line gets discarded.
@c Line start "@c man " will become "", the remainder is put out unaltered.
@c Lines "@*" will be converted to ".br"
@c "@c man-ignore-lines N" will discard N following lines.
@c "@c man-ignore-lines begin" discards all following lines
@c up to "@c man-ignore-lines end".
@c Line blocks of "@menu" "@end menu" will be discarded.
@c "@item word words" becomes "\fBword\fR words".
@c @b{...}, @command{...}, @dfn{...}, @emph{...}, @strong{...}
@c get mapped to \fB...\fR .
@c @abbr{...}, @code{...}, @file{...}, @i{...}, @option{...}, @r{...},
@c @ref{...}, @samp{...},@var{...}, get mapped to ... .
@c @ref{...}, @xref{...} get mapped to empty text.
@c @email{...} gets mapped to <...> .
@c Mapped {...} content is subject to the rules except {...} mapping.
@c @minus{} will become "-".
@c @@ , @{, @} will get stripped of their first @.
@c Other lines which begin by "@" will be discarded.
@c In lines not stemming from "@c man", "\" becomes "\\"
@c "-" which are not preceded by an uneven number of "\" will get
@c prepended one "\".
@c
@c
@c man .\" Hey, EMACS: -*- nroff -*-
@c man .\"
@c man .\" IMPORTANT NOTE:
@c man .\"
@c man .\" The original of this file is kept in test/merge_debian_isos.texi
@c man .\" This here was generated by program xorriso/make_xorriso_1
@c man .\"
@c man .\"
@c man .\" First parameter, NAME, should be all caps
@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
@c man .\" other parameters are allowed: see man(7), man(1)
@c man .TH MERGE_DEBIAN_ISOS 1 "Version 1.5.5, Oct 19, 2022"
@c man .\" Please adjust this date whenever revising the manpage.
@c man .\"
@c man .\" Some roff macros, for reference:
@c man .\" .nh disable hyphenation
@c man .\" .hy enable hyphenation
@c man .\" .ad l left justify
@c man .\" .ad b justify to both left and right margins
@c man .\" .nf disable filling
@c man .\" .fi enable filling
@c man .\" .br insert line break
@c man .\" .sp <n> insert n+1 empty lines
@c man .\" for manpage-specific macros, see man(7)
@c man .nh
@c man-ignore-lines begin
@copying
merge_debian_isos - sh script to merge multiple debian-cd ISO images
Copyright @copyright{} 2022 Thomas Schmitt
@quotation
Permission is granted to distribute this text freely.
@end quotation
@end copying
@c man-ignore-lines end
@titlepage
@title Manual of GNU xorriso companion merge_debian_isos 1.5.5
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top merge_debian_isos 1.5.5
@c man-ignore-lines 1
@c man .SH NAME
merge_debian_isos - Program to merge multiple debian-cd ISO images
@end ifnottex
@menu
* Overview:: Overview
* Options:: Options
* Examples:: Examples
* Files:: Files
* Environ:: Environment
* Seealso:: See also
* Bugreport:: Reporting bugs
* Legal:: Author, Copyright, Credits
* CommandIdx:: Alphabetic Option List
* ConceptIdx:: Alphabetic List of Concepts and Objects
@end menu
@node Overview, Options, Top, Top
@chapter Overview
@c man .SH SYNOPSIS
@c man .B merge_debian_isos
@c man result_iso mount_template iso1 iso2 [... isoN]
@c man .br
@c man .SH DESCRIPTION
@c man .PP
@command{merge_debian_isos}
mounts by @strong{sudo} 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 @strong{xorriso}.
If iso1 is bootable then
the new image will be bootable by the same means.
@*
@sp 1
@c man .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
@strong{xorriso-dd-target}. If xorriso-dd-target agrees and the user
confirms by input "yes" then xorriso will be run under sudo.
@*
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.
@*
Special result_iso path @strong{xorriso-dd-target-plug-test} 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".
@*
@sp 1
@c man .PP
At least the parent directory of argument @strong{mount_template} 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 "./".)
@*
All arguments must be single words without using quotation marks.
None of the isoN must be equal to another isoM.
@*
@sp 1
@c man .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
@*
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:
@*
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
@*
With device writing involving helper script xorriso-dd-target:
@*
dd, Linux kernel, lsblk, sleep, tr, uname, wc, whoami,
xorriso-dd-target
@*
Recommended are: sha1sum, sha512sum
@c man .SS
@node Options, Examples, Overview, Top
@chapter Options
@cindex merge_debian_isos, options
@c man .br
@c man .SH OPTIONS
@c man .br
@c man .PP
merge_debian_isos has no command line options besides the input words described
above, but it reacts on some environment variables.
@c man .br
@c man See section ENVIRONMENT.
@*
@sp 1
@c man .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.
@c man .SS
@node Examples, Files, Options, Top
@chapter Examples
@c man .SH EXAMPLES
@c man .SS
@c man .B Overview of examples:
@c man Merge DVD images 1 to 5
@c man .br
@c man Use GNU xorriso instead of installed xorriso
@c man .br
@c man Write result directly to an optical drive
@c man .br
@c man Write result directly and safely to USB stick (Linux only)
@c man .br
@c man Write result directly and unsafely to USB stick
@cindex Examples
@menu
* ExPlain:: Merge DVD images 1 to 5
* ExXorriso:: Use GNU xorriso instead of installed xorriso
* ExOptical:: Write result directly to an optical drive
* ExDdTarget:: Write result directly and safely to USB stick (Linux only)
* ExStdio:: Write result directly and unsafely to USB stick
@end menu
@c man .SS
@c man .B Merge DVD images 1 to 5
@node ExPlain, ExXorriso, Options, Examples
@section Merge DVD images 1 to 5
The resulting image will be named "merged.iso".
@*
Directory ./merge_mount/ will be created if not yet existing.
@*
@sp 1
merge_debian_isos merged.iso merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso
@c man .SS
@c man .B Use GNU xorriso instead of installed xorriso
@node ExXorriso, ExOptical, ExPlain, Examples
@section 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
@*
https://www.gnu.org/software/xorriso/#download
@*
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:
@*
@sp 1
export XORRISO="$HOME"/xorriso-1.5.4/xorriso/xorriso
@*
@sp 1
merge_debian_isos merged.iso merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso
@c man .SS
@c man .B Write result directly to an optical drive
@node ExOptical, ExDdTarget, ExXorriso, Examples
@section 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:
@*
@sp 1
xorriso -devices
@*
@sp 1
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.
@*
@sp 1
In order to directly write the merged ISO image to an optical medium,
use the desired device file path with prefix "mmc:":
@*
@sp 1
merge_debian_isos mmc:/dev/sr0 merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso
@c man .SS
@c man .B Write result directly and safely to USB stick (Linux only)
@node ExDdTarget, ExStdio, ExOptical, Examples
@section Write result directly and safely to USB stick (Linux only)
The Linux-specific script @strong{xorriso-dd-target} evaluates device files
whether they and their content look unimportant enough for being overwritten
by an image file.
@*
This mainly means that the storage device is attached to USB and contains
no filesystems which are not of type FAT or ISO 9660.
@*
You may get xorriso-dd-target by:
@*
@sp 1
wget \
https://dev.lovelyhq.com/libburnia/libisoburn/raw/master/xorriso-dd-target/xorriso-dd-target
chmod u+x xorriso-dd-target
@*
@sp 1
Consider to also download xorriso-dd-target.sig and to verify the script by
@*
@sp 1
gpg --verify xorriso-dd-target.sig xorriso-dd-target
@*
@sp 1
Announce the storage location of the downloaded xorriso-dd-target:
@*
@sp 1
export XORRISO_DD_TARGET_PATH="$(pwd)"
@*
@sp 1
The prepared use case in merge_debian_isos uses the xorriso-dd-target
option -plug_test under @strong{sudo}, 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.
@*
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.
@*
@sp 1
merge_debian_isos xorriso-dd-target-plug-test merge_mount/iso \
debian-11.2.0-amd64-DVD-[12345].iso
@c man .SS
@c man .B Write result directly and unsafely to USB stick
@node ExStdio, Files, ExDdTarget, Examples
@section 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.
@*
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:
@*
@sp 1
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.
@*
The xorriso run in merge_debian_isos ignores locally defined xorriso startup
files (by command -no_rc).
@node Files, Environ, Examples, Top
@chapter Files
@c man .SH FILES
For now, no files are defined for configuration.
@c man .SH ENVIRONMENT
@node Environ, Seealso, Files, Top
@chapter Environ
The following environment variables influence the program behavior:
@*
Exported non-empty variable MERGE_DATE enforces a particular
date string in the text which gets prepended to /README.txt .
@*
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.
@*
Exported non-empty variable MERGE_KEEP_ISO prevents the removal
of result_iso after xorriso indicated failure of production.
@*
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.
@*
If XORRISO is set to "dummy" then no new ISO will emerge.
@*
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.
@*
@c man .SH SEE ALSO
@c man .BR xorriso(1),
@c man .BR xorriso-dd-target(1),
@c man-ignore-lines begin
@node Seealso, Bugreport, Environ, Top
@chapter See also
xorriso(1), xorriso-dd-target(1)
@c man-ignore-lines end
@c man .SH BUGS
@node Bugreport, Legal, Seealso, Top
@chapter Reporting bugs
@cindex Bugs, reporting
@cindex Problems, reporting
To report bugs, request help, or suggest enhancements for
@command{xorriso-dd-target},
please send electronic mail to the public list @email{bug-xorriso@@gnu.org}.
If more privacy is desired, mail to @email{scdbackup@@gmx.net}.
@*
@sp 1
Please describe what you expect the program to do, the program arguments
which you used, the messages of @command{xorriso-dd-target}, and the
undesirable outcome of your program run.
@*
@sp 1
Expect to get asked more questions before solutions can be proposed.
@c man .SH AUTHOR
@node Legal, CommandIdx, Bugreport, Top
@chapter Author, Copyright, Credits
@section Author
Thomas Schmitt <scdbackup@@gmx.net>
@*
for libburnia-project.org
@c man .SH COPYRIGHT
@section Copyright
Copyright (c) 2022 Thomas Schmitt
@*
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.
@c man .SH CREDITS
@section Credits
@command{merge_debian_isos} 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.
@c man-ignore-lines begin
@node CommandIdx, ConceptIdx, Legal, Top
@chapter Alphabetic Options List
@printindex ky
@node ConceptIdx, Top, CommandIdx, Top
@chapter Alphabetic List of Concepts and Objects
@printindex cp
@c man-ignore-lines end
@bye