libisoburn/xorriso/xorrisofs.texi

1983 lines
72 KiB
Plaintext

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorrisofs.info
@settitle xorrisofs
@c %**end of header
@c
@c man-ignore-lines begin
@dircategory Archiving
@direntry
* Xorrisofs: (xorrisofs). Emulates ISO 9660 program mkisofs
@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 which resembles much the version of xorriso.1 from which this code
@c was originally derived in march 2010.
@c One can produce the man page 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 "\fB\-word\fR words".
@c "@item word words" becomes "\fBword\fR words".
@c @strong{-...} gets mapped to \fB\-...\fR .
@c @strong{...} gets mapped to \fB...\fR .
@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
@c
@c man .\" Hey, EMACS: -*- nroff -*-
@c man .\"
@c man .\" IMPORTANT NOTE:
@c man .\"
@c man .\" The original of this file is kept in xorriso/xorrisofs.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 XORRISOFS 1 "Mar 06, 2011"
@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
xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso
Copyright @copyright{} 2011 - 2011 Thomas Schmitt
@quotation
Permission is granted to distrubute this text freely.
@end quotation
@end copying
@c man-ignore-lines end
@titlepage
@title Manual of xorriso personality xorrisofs
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top xorrisofs
@c man-ignore-lines 1
@c man .SH NAME
xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso
@end ifnottex
@menu
* Overview:: Overview
* Standards:: ISO 9660, Rock Ridge, Joliet
* Insert:: Inserting files into the ISO image
* Xorriso:: Relation to program xorriso
* Options:: Options
* Examples:: Examples
* Files:: Files
* Seealso:: See also
* Legal:: Author, Copyright, Credits
* CommandIdx:: Alphabetic Command List
* ConceptIdx:: Alphabetic List of Concepts and Objects
@end menu
@node Overview, Standards, Top, Top
@chapter Overview
@c man .SH SYNOPSIS
@c man .B xorrisofs
@c man [ options ] [-o filename ] pathspec [pathspecs ...]
@c man .br
@c man .SH DESCRIPTION
@c man .PP
@strong{xorrisofs}
produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to
such filesystems. Optionally it can produce Joliet directory trees too.
@*
@sp 1
@c man .PP
xorrisofs understands options of program mkisofs from cdrtools by
Joerg Schilling.
Its implementation is part of program xorriso which shares no source
code with cdrtools.
@c man .SS
@node Standards, Insert, Overview, Top
@chapter ISO 9660, Rock Ridge, Joliet
@c man \fBISO 9660, Rock Ridge, Joliet:\fR
@c man .br
@cindex ISO 9660, _definiton
@cindex ECMA-119, _definiton
@strong{ISO 9660}
(aka @strong{ECMA-119}) is a read-only filesystem that is mainly used for
optical media CD, DVD, BD, but may also reside on other storage devices like
disk files, USB sticks or disk partitions. It is widely readable by many
operating systems and by boot facilities of personal computers.
@*
ISO 9660 describes directories and data files by
very restricted filenames with no distinction of upper case and lower case.
Its metadata do not comply to fundamental POSIX specifications.
@*
@cindex Rock Ridge, _definiton
@strong{Rock Ridge}
is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
Rock Ridge allows filenames of up to 255 bytes and paths of up to
1024 bytes.
@*
Rock Ridge information is produced unconditionally with any xorrisofs image.
@*
@cindex Joliet, _definiton
@strong{Joliet}
is the name of an additional directory tree which provides
filenames up to 64 characters encoded as UTF-16.
A Joliet tree is mainly interesting for reading the ISO image by
operating systems of Microsoft Corporation.
Production of this directory tree may be enabled by option -J.
@*
@cindex ISO 9660:1999, _definiton
@strong{ISO 9660:1999}
is the name of an additional directory tree which provides longer
filenames. It allows single file names to have up to 207 characters.
It might be of use with some older computer system boot
facilities which read neither Rock Ridge nor Joliet but
need longer filenames nevertheless.
Production of this directory tree may be enabled by option -iso-level 4.
@c man .SS
@sp 1
@c man .B Inserting files into the ISO image:
@node Insert, Xorriso, Standards, Top
@chapter Inserting files into the ISO image
@c man .PP
xorrisofs deals with two kinds of file addresses:
@*
@cindex disk_path, _definition
@strong{disk_path}
is a path to an object in the local filesystem tree.
@*
@cindex iso_rr_path, _definition
@strong{iso_rr_path}
is the Rock Ridge address of a file object in the ISO image. (Do not
confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.)
@cindex pathspec, _definition
@*
@sp 1
@c man .PP
A program argument is handled as a @strong{pathspec}, if it is not
recognized as original mkisofs option or additional xorrisofs option.
A pathspec depicts an input file object by a disk_path.
If option -graft-points is not present, then this file object gets
copied into the /-directory of the ISO image.
@*
If -graft-points is present then each pathspec gets split at the first
occurence of the =-character.
The part before the = is taken as @strong{target}, the iso_rr_path for
the file object in the ISO image. The part after the first = is taken
as @strong{source}, the disk_path of the input object.
@*
It is possible to make =-characters part of the iso_rr_path by preceeding
them with a \-character. The same must be done for \-characters which
shall be part of the iso_rr_path.
@*
@sp 1
@c man .PP
If the source part of the pathspec leads to a directory, then all files
underneath this directory get inserted into the image, too.
It is possible to exclude particular files from being inserted
by help of option -m.
@c man .SS
@node Xorriso, Options, Insert, Top
@chapter Relation to program xorriso
@c man \fBRelation to program xorriso:\fR
@c man .br
@cindex xorriso, mkisofs emulation
xorrisofs is actually a command mode of program @strong{xorriso},
which gets entered either by xorriso command "-as mkisofs" or by
starting the program by one of the names "xorrisofs", "mkisofs",
"genisoimage", or "genisofs".
@*
This command mode can be left by argument "@minus{}@minus{}" which leads
to generic xorriso command mode. See @strong{man xorriso} for its description.
@*
@sp 1
@c man .PP
xorriso performs image reading and writing by help of libburn, which is
mainly intended for optical drives, but also operates on all POSIX
file types except directories.
@*
The program messages call any image file a "drive". File types which are not
supported for reading are reported as "blank". The reported free media
space may be quite fictional.
@*
Nevertheless xorrisofs does not operate directly on optical drives,
but rather forces libburn to regard them as general device files.
So for writing of sequential optical media (CD, DVD-R, DVD+R, BD-R)
one will have to use a burn program. E.g the cdrecord emulation of xorriso.
See EXAMPLES.
@c man .SS
@node Options, Examples, Xorriso, top
@chapter Options
@cindex xorriso, options
@c man .br
@c man .SH OPTIONS
@c man .br
@menu
* Loading:: Image loading
* SetInsert:: Settings for file insertion
* SetProduct:: Settings for image production
* SetCompl:: Settings for standards compliance
* SetExtras:: Settings for standards extensions
* SetHide:: Settings for file hiding
* ImageId:: ISO image ID strings
* Bootable:: El Torito Bootable ISO images
* SystemArea:: System Area, MBR, other boot blocks
* Charset:: Character sets
* Jigdo:: Jigdo Template Extraction
* Miscellaneous:: Miscellaneous options
@end menu
@c man .PP
@c man .TP
@c man .B Image loading:
@node Loading, SetInsert, Options, Options
@section Influencing the behavior of image loading
@c man .PP
The following options control loading of an existing ISO image for the purpose
of preparing a suitable add-on session.
If they are missing then a new image is composed from scratch.
@table @asis
@sp 1
@c man .TP
@item -M disk_path
@kindex -M set path for loading existing ISO image
@cindex Session, select path, -M, -prev-session, -dev
Set the path from which to load the existing ISO image directory tree
on which to base the upcomming directory tree as add-on session.
The path must lead to a random-access readable file object.
On GNU/Linux: regular data files or block device files.
@*
A special kind of pseudo disk_path has the form "/dev/fd/"number.
It depicts the open file descriptor with the given number, regardless whether
the operating system supports this feature by file nodes in /dev/fd or not.
E.g. /dev/fd/3 is file descriptor 3 which was opened by the program that
later started xorriso.
@c man .TP
@item -prev-session disk_path
@kindex -prev-session set path for loading existing ISO image
Alias of -M.
@c man .TP
@item -dev disk_path
@kindex -dev set path for loading existing ISO image
Alias of -M.
@c man .TP
@item -C last_session_start,next_writeable_address
@kindex -C set load address and write address offset
@cindex Session, set load and write address, -C, -cdrecord-params
Set the 2 KiB block address last_session_start from where to read the
ISO image out of the file given by option -M.
@*
Separated by a comma, set the next_writeable_address to which the
add-on session will finally be written. Decisive is actually the block
address which the intended readers will have to use as superblock address
on the intended media.
@*
Both values can be inquired from optical media by help of burn programs
and cdrecord option -msinfo. xorriso itself can obtain it in its
cdrecord emulation:
@*
values=$(xorriso -as cdrecord dev=/dev/... -msinfo)
echo $values
@*
Option -C may be used without option -M to create an ISO image from
scratch and prepare it for being finally written to a block address
other than 0. Parameter last_session_start should then be set to 0.
@c man .TP
@item -cdrecord-params last_session_start,next_writeable_address
@kindex -cdrecord-params set load address and write address offset
Alias of -C.
@end table
@c man .TP
@c man .B Settings for file insertion:
@node SetInsert, SetProduct, Loading, Options
@section Settings for file insertion
@table @asis
@sp 1
@c man .TP
@item -path-list disk_path
@kindex -path-list read pathspecs from disk file
@cindex pathspec, read list of, -path-list
Read pathspecs line-by-line from disk_file and insert the depicted file
objects into the ISO image. If disk_path is "-" then read the pathspecs
from standard input.
@c man .TP
@item @minus{}@minus{}quoted_path_list disk_path
@kindex @minus{}@minus{}quoted_path_list read pathspecs from disk file
@cindex pathspec, read list of, @minus{}@minus{}quoted_path_list
Like option -path-list but reading quoted words rather than plain lines.
Whitespace outside of quotes will be discarded. On the other hand it is
possible to represent pathspecs which contain newline characters.
@*
The double quotation mark " and the single quotation mark ' can be used to
enclose whitespace and make it part of pathspecs. Each mark
type can enclose the marks of the other type. A trailing backslash \ outside
quotations or an open quotation cause the next input line to be appended.
@c man .TP
@item -f
@kindex -f follow symbolic links on disk
@cindex Links, follow on disk, -f, -follow-links
Resolve symbolic links on disk rather than storing them as symbolic
links in the ISO image.
@c man .TP
@item -follow-links
@kindex -follow-links follow symbolic links on disk
Alias of -f.
@c man .TP
@item -graft-points
@kindex -graft-points enable target=source pathspecs
@cindex pathspec, enable target=source, -graft-points
Enable interpretation of input file pathspecs as combination of iso_rr_path
and disk_path, separated by a =-character.
@c man .TP
@item -m disk_pattern
@kindex -m exclude disk files from inserting
@cindex Disk files, exclude, -m, -exclude, -x, -old-exclude
Exclude files from being inserted into the image. Silently ignored are
those files of which the disk_path matches the given shell parser pattern.
If no /-character is part of the pattern, then it gets matched against
the leaf name of the disk file.
@*
It is possible to give more than one -m option.
@c man .TP
@item -exclude
@kindex -exclude exclude disk files from inserting
Alias of -m.
@c man .TP
@item -x
@kindex -x exclude disk files from inserting
Alias of -m.
@c man .TP
@item -old-exclude
@kindex -old-exclude exclude disk files from inserting
Alias of -m.
@c man .TP
@item -exclude-list disk_path
@kindex -exclude-list exclude disk files from inserting
@cindex Disk files, exclude, -hide-list
Perform -m using each line out of file disk_path as argument disk_pattern.
@c man .TP
@item -z
@kindex -z enable recognition of zisofs files
@cindex zisofs file, enable recognition, -z, -transparent-compression
Enable recognition and proper processing of zisofs compressed files
as produced by program mkzftree. These files will get equipped with the
necessary meta data so that a Linux kernel will recognize them and
deliver their content in uncompressed form.
@c man .TP
@item -transparent-compression
@kindex -transparent-compression enable recognition of zisofs files
Alias of -z.
@c man .TP
@item -root iso_rr_path
@kindex -root redirect ISO root directory
@cindex ISO root directory, redirect, -root
Insert all files under the given iso_rr_path. If option -graft-points is given,
then iso_rr_path is prepended to each target part of a pathspec.
@*
The default for -root is "/".
@c man .TP
@item -old-root iso_rr_path
@kindex -old-root enable incremental insertion
@cindex Incremental insertion, enable, -old-root
Enable incremental insertion of files into the loaded image.
The effective target and source addresses of given pathspecs get compared
whether the target already exists in the ISO image and is still identical
to the source on disk. Metadata in the ISO image will eventually get adjusted.
New files and files with changed content will get newly added.
Target files which do not exist in any of the according pathspec sources
will get removed from the ISO directory tree.
@*
If the effective setting of -root differs from the iso_rr_path given
with -old-root, then the files underneath the -old-root directory get cloned
underneath the -root directory. Cloning happens before file comparison.
@c man .TP
@item @minus{}@minus{}old-root-no-ino
@kindex @minus{}@minus{}old-root-no-ino disable disk ino with -old-root
@cindex Incremental insertion, disable disk ino, @minus{}@minus{}old-root-no-ino
Disable recording and use of disk inode numbers.
If no disk inode numbers are recorded, then option -old-root will have
to read disk file content and compare it with the MD5 checksum that is
recorded in the ISO image.
@*
With recorded disk inode numbers and with credible ctime and mtime,
it is possible to detect potential changes in the content without actually
reading it.
A loophole remains if multiple different filesystems may get mounted
at the same directory, like it is habit with /mnt.
In this case one has to use option @minus{}@minus{}old-root-devno
or disable the inode number shortcut by @minus{}@minus{}old-root-no-ino.
@c man .TP
@item @minus{}@minus{}old-root-devno
@kindex @minus{}@minus{}old-root-devno enable disk idevno with -old-root
@cindex Incremental insertion, enable disk devno, @minus{}@minus{}old-root-devno
Enable comparison of recorded device numbers together with recorded
inode numbers. This works only with good old stable device numbers which
get out of fashion, regrettably. If the hard disk has a different
device number after each reboot, then this comparison will see all
files as changed and thus prevent any incremental size saving.
@c man .TP
@item @minus{}@minus{}old-root-no-md5
@kindex @minus{}@minus{}old-root-no-md5 disable MD5 with -old-root
@cindex Incremental insertion, disable MD5, @minus{}@minus{}old-root-no-md5
Disable recording and eventual use of MD5 checksums for data file content.
If neither checksums and nor disk inode numbers are recorded, then
option -old-root will have to read ISO image file content when comparing
it with disk file content.
@end table
@c man .TP
@c man .B Settings for image production:
@node SetProduct, SetCompl, SetInsert, Options
@section Settings for image production
@table @asis
@sp 1
@c man .TP
@item -o disk_path
@kindex -o set output file address
@cindex Output file, set address, -o, -output
Set the output file address for the emerging ISO image.
If the address exists as regular file, it will be truncated to length 0
when image production begins. It may not already exist as directory.
If it does not exist yet then its parent directory must exist and
a regular file will get created.
@*
A special kind of pseudo disk_path has the form "/dev/fd/"number.
It depicts the open file descriptor with the given number, regardless whether
the operating system supports this feature by file nodes in /dev/fd or not.
E.g. /dev/fd/4 is file descriptor 4 which was opened by the program that
later started xorriso.
@*
Default is standard output (/dev/fd/1) which may also be set by disk_path "-".
@c man .TP
@item -output disk_path
@kindex -output set output file address
Alias of -o.
@c man .TP
@item @minus{}@minus{}stdio_sync "on"|"off"|number
@kindex @minus{}@minus{}stdio_sync control forced output to disk files
@cindex Forced output, control, @minus{}@minus{}stdio_sync
Set the number of bytes after which to force output to disk
in order to keep the memory from being clogged with lots of
pending data for slow devices. Default "on" is the same as "16m".
Forced output can be disabled by "off".
@*
xorriso uses an inner fifo buffer with default size 4 MiB. So forcing
the operating system i/o cache to disk does not necessarily block the
simultaneous production of more image content.
@c man .TP
@item @minus{}@minus{}emul-toc
@kindex @minus{}@minus{}emul-toc enable table-of-content emulation
@cindex Table-of-content, emulation, @minus{}@minus{}emul-toc
Write a second superblock with the first session into random-access
files. If further sessions get appended and the first superblock gets updated,
then the second superblock will not be overwritten. This allows to still
mount the first session and to find the start blocks of the further sessions.
@*
The price is 64 KiB extra space consumption. If -partition_offset is non-zero,
then it is 128 KiB plus twice the partition setup.
@c man .TP
@item @minus{}@minus{}no-emul-toc
@kindex @minus{}@minus{}no-emul-toc no table-of-content emulation
@cindex Table-of-content, emulation off, @minus{}@minus{}no-emul-toc
Do not write a second superblock with the first session into random-access
files.
@*
This is the default.
@c man .TP
@item @minus{}@minus{}sort-weight weight_number iso_rr_path
@kindex @minus{}@minus{}sort-weight set output file address
@cindex Block address, set sort weight, @minus{}@minus{}sort-weight
Attribute a LBA weight number to regular files. If iso_rr_path leads
to a directory then all regular files underneath will get the weight_number.
@*
The weight_number may range from -2147483648 to 2147483647.
The higher it is, the lower will be the block address of the file data
in the emerging ISO image.
Currently the El Torito boot catalog has a hardcoded weight of 1 billion.
Normally it should occupy the block with the lowest possible address.
Data files get added or loaded with initial weight 0.
@c man .TP
@item -dir-mode mode
@kindex -dir-mode permissions for all directories
@cindex Permissions, for all directories, -dir-mode
Set the access permissions for all directories in the image to the given
mode which is either an octal number beginning with "0" or a comma separated
list of statements of the form [ugoa]*[+-=][rwxst]* . E.g. ug=rx,a-rwx
@c man .TP
@item -file-mode mode
@kindex -file-mode permissions for all data files
@cindex Permissions, for all data files, -file-mode
Like -dir-mode but for all regular data files in the image.
@c man .TP
@item -pad
@kindex -pad add 300 KiB of zeros to ISO tree
@cindex Padding, 300 KiB, -pad
Add 300 KiB to the end of the produced ISO image. This circumvents possible
read errors from ISO images which have been written to CD media in TAO mode.
The additional bytes are claimed as part of the ISO image if not --emul-toc
is given.
@*
Option -pad is the default.
@c man .TP
@item -no-pad
@kindex -no-pad do not add zeros to ISO tree
@cindex Padding, disable, -no-pad
Disable padding of 300 KiB to the end of the produced ISO image.
This is safe if the image is not meant to be written on CD or if it
gets written to CD as only track in write mode SAO.
@c man .TP
@item @minus{}@minus{}old-empty
@kindex @minus{}@minus{}old-empty old block addresses for empty files
@cindex Padding, disable, @minus{}@minus{}old-empty
Use the old way of of giving block addresses in the range
of [0,31] to files with no own data content. The new way is to have
a dedicated block to which all such files will point.
@end table
@c man .TP
@c man .B Settings for standards compliance:
@node SetCompl, SetExtras, SetProduct, Options
@section Settings for standards compliance
@table @asis
@sp 1
@kindex -iso-level define ISO 9660 limitations
@cindex ISO level, specify, -iso-level
@c man .TP
@item -iso-level number
@kindex -iso-level define ISO 9660 limitations
@cindex ISO level, specify, -iso-level
Specify the ISO 9660 version which defines the limitations of file naming
and data file size. The naming restrictions do not apply to the
Rock Ridge names but only to the low-level ISO 9660 names.
There are three conformance levels:
@*
Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB - 1.
@*
Level 2 allows ISO names with up to 32 characters
and file size up to 4 GiB - 1.
@*
Level 3 allows ISO names with up to 32 characters
and file size of up to 400 GiB - 200 KiB. (This size limitation is
set by the xorriso implementation and not by ISO 9660 which would
allow nearly 8 TiB.)
@*
Pseudo-level 4 enables production of an additional ISO 9660:1999
directory tree.
@c man .TP
@item -disallow_dir_id_ext
@kindex -disallow_dir_id_ext enforce ISO level 1 directory names
@cindex ISO level 1, enforce directory names, -disallow_dir_id_ext
Do not follow a bad habit of mkisofs which allows dots in the ISO names
of directories. On the other hand, some bootable GNU/Linux images depend on
this bad habit.
@c man .TP
@item -U
@kindex -U very relaxed filename rules
@cindex ISO file names, very relaxed rules, -U, -untranslated-filenames
This option allows ISO file names without dot and up to 37 characters,
ISO file paths longer than 255 characters, and all ASCII characters in file
names. Further it omits the semicolon and the version numbers at the end
of ISO names.
@*
This all violates ISO 9660 specs.
@c man .TP
@item -untranslated-filenames
@kindex -untranslated-filenames very relaxed filename rules
Alias of -U.
@item -untranslated_name_len number
@kindex -untranslated_name_len untranslated file names
@cindex ISO file names, untranslated, -untranslated_name_len
Allow ISO file names up to the given number of characters
without any character conversion. The maximum number is 96.
If a file name has more characters, then image production will
fail deliberately.
@*
This violates ISO 9660 specs.
@c man .TP
@item -allow-lowercase
@kindex -allow-lowercase lowercase in ISO file names
@cindex ISO file names, allow lowercase, -allow-lowercase
Allow lowercase character in ISO file names.
@*
This violates ISO 9660 specs.
@c man .TP
@item -d
@kindex -d omit trailing dot in ISO file names
@cindex ISO file names, omit trailing dot, -d, -omit-period
Do not add trailing dot to ISO file names without dot.
@*
This violates ISO 9660 specs.
@c man .TP
@item -omit-period
@kindex -omit-period omit trailing dot in ISO file names
Alias of -d.
@c man .TP
@item -l
@kindex -l allow 37 characters in ISO file names
@cindex ISO file names, allow 37 characters, -l, -full-iso9660-filenames, -max-iso9660-filenames
Allow up to 37 characters in ISO file names.
@*
This violates ISO 9660 specs.
@c man .TP
@item -full-iso9660-filenames
@kindex -full-iso9660-filenames allow 37 characters in ISO file names
Alias of -l.
@c man .TP
@item -max-iso9660-filenames
@kindex -max-iso9660-filenames allow 37 characters in ISO file names
Alias of -l.
@c man .TP
@item -N
@kindex -N omit version number in ISO file names
@cindex ISO file names, omit version number, -N, -omit-version-number
Omit the semicolon and the version numbers at the end of ISO names.
@*
This violates ISO 9660 specs.
@c man .TP
@item -omit-version-number
@kindex -omit-version-number omit version number in ISO file names
Alias of -N.
@end table
@c man .TP
@c man .B Settings for standards extensions:
@node SetExtras, SetHide, SetCompl, Options
@section Settings for standards extensions
@table @asis
@sp 1
@c man .TP
@item -R
@kindex -R Rock Ridge (is always enabled)
@cindex Rock Ridge, (always enabled), -R, -rock
With mkisofs this option enables Rock Ridge extensions. xorrisofs produces
them unconditionally.
@c man .TP
@item -rock
@kindex -rock Rock Ridge (is always enabled)
Alias of -R.
@c man .TP
@item -r
@kindex -r Rock Ridge with altered owner and permission
@cindex Rock Ridge, altered owner and permission, -r, -rational-rock
Set Rock Ridge user and group id of all files in the ISO image to 0.
Grant r-permissions to all. Deny all w-permissions.
If any x-permission is set, grant x-permission to all.
Remove s-bit and t-bit.
@c man .TP
@item -rational-rock
@kindex -rational-rock Rock Ridge with altered owner and permission
Alias of -r.
@c man .TP
@item @minus{}@minus{}for_backup
@kindex @minus{}@minus{}for_backup Enable backup fidelity
@cindex Backup, enable fidelity, @minus{}@minus{}for_backup
Enable options which improve backup fidelity:
@minus{}@minus{}acl, @minus{}@minus{}xattr, @minus{}@minus{}md5,
@minus{}@minus{}hardlinks.
@c man .TP
@item @minus{}@minus{}acl
@kindex @minus{}@minus{}acl Recording of ACLs
@cindex ACL, record and load, @minus{}@minus{}acl
Enable recording and loading of GNU/Linux ACLs (see man getfacl, man acl).
They will not be in effect with mounted ISO images. But xorriso can
restore them when extracting files from the ISO image.
@c man .TP
@item @minus{}@minus{}xattr
@kindex @minus{}@minus{}xattr Recording of xattr
@cindex xattr, record and load, @minus{}@minus{}xattr
Enable recording and loading of GNU/Linux extended attributes in
user namespace (see man getfattr, man attr).
They will not be in effect with mounted ISO images. But xorriso can
restore them when extracting files from the ISO image.
@c man .TP
@item @minus{}@minus{}md5
@kindex @minus{}@minus{}md5 Recording of MD5 checksums
@cindex MD5, record and load, @minus{}@minus{}md5
Enable recording of MD5 checksums for the overall ISO image and for each
single data file in the image. xorriso can check the content of an ISO
image with these sums and eventually raise alert on mismatch.
See man xorriso, options -check_media, check_md5_r.
xorriso can print recorded MD5 checksums. E.g. by:
@*
-find / -exec get_md5
@c man .TP
@item @minus{}@minus{}hardlinks
@kindex @minus{}@minus{}hardlinks Recording of hardlink relations
@cindex Links, record and load hard links, @minus{}@minus{}hardlinks
Enable loading and recording of hardlink relations.
Search for families of iso_rr files which stem from the same disk file,
have identical content filtering and have identical properties.
The members of each family get the same inode number in the ISO image.
@*
Whether these numbers are respected at mount time depends on the operating
system. xorriso can create hardlink families when extracting files from
the ISO image.
@c man .TP
@item @minus{}@minus{}scdbackup_tag disk_path record_name
@kindex @minus{}@minus{}scdbackup_tag Recording of MD5 checksum
@cindex scdbackup, record checksum tag, @minus{}@minus{}scdbackup_tag
Append a scdbackup checksum record to the image. This works only if the
parameter next_writeable_address of option -C is 0.
If disk_path is not an empty string, then append a scdbackup checksum record
to the end of this file. record_name is a word that gets part of tag
and record.
@*
Program scdbackup_verify will recognize and verify tag resp. record.
@c man .TP
@item -J
@kindex -J enable production of Joliet directory tree
@cindex Joliet, enable, -J, -joliet
Enable the production of an additional Joliet directory tree along
with the ISO 9660 Rock Ridge tree.
@c man .TP
@item -joliet
@kindex -joliet enable production of Joliet directory tree
Alias of -J.
@c man .TP
@item -joliet-long
@kindex -joliet-long allow longer Joliet names
@cindex Joliet, allows longer names, -joliet-long
Currently this option is insufficiently implemented.
It should allow 103 characters in Joliet file names but
yet only 64 are possible.
@end table
@c man .TP
@c man .B Settings for file hiding:
@node SetHide, ImageId, SetExtras, Options
@section Settings for file hiding
@table @asis
@sp 1
@c man .TP
@item -hide disk_path_pattern
@kindex -hide keep matching files invisible in ISO tree
@cindex Hiding, from ISO and Rock Ridge, -hide
Make files invisible in the directory tree of ISO 9660 and Rock Ridge,
if their disk_path matches the given shell parser pattern.
The eventual data content of such hidden files will be included in the
resulting image, even if they do not show up in any directory.
But you will need own means to find nameless data in the image.
@*
This command does not apply to the boot catalog.
@c man .TP
@item -hide-list disk_path
@kindex -hide-list keep matching files invisible in ISO tree
@cindex Hiding, from ISO and Rock Ridge, -hide-list
Perform -hide using each line out of file disk_path as argument
disk_path_pattern.
@c man .TP
@item -hide-joliet disk_path_pattern
@kindex -hide-joliet keep matching files invisible in Joliet tree
@cindex Hiding, from Joliet, -hide-joliet
Like option -hide but making files invisible in the directory tree of Joliet,
if their disk_path matches the given shell parser pattern.
@c man .TP
@item -hide-joliet-list disk_path
@kindex -hide-joliet-list keep matching files invisible in Joliet tree
@cindex Hiding, from Joliet, -hide-joliet-list
Perform -hide-joliet using each line out of file disk_path as argument
disk_path_pattern.
@end table
@c man .TP
@c man .B ISO image ID strings:
@node ImageId, Bootable, SetHide, Options
@section ISO image ID strings
@c man .PP
The following strings and file addresses get stored in the Primary Volume
Descriptor of the ISO9660 image. The file addresses are ISO 9660
paths. These files should have iso_rr_paths which consist only of
the characters [A-Z0-9_] and exactly one dot which separates
at most 8 characters from at most 3 characters.
@table @asis
@sp 1
@c man .TP
@item -V text
@kindex -V set Volume Id
@cindex Volume Id, set, -V, -volid
Set the Volume Id of the ISO image.
xorriso accepts any text up to 32 characters,
but according to rarely obeyed specs stricter rules apply:
@*
Conformant are ASCII characters out of [A-Z0-9_]. Like: "IMAGE_23"
@*
Joliet allows 16 UCS-2 characters. Like: "Windows name"
@*
Be aware that the volume id might get used automatically as name of the
mount point when the media is inserted into a playful computer system.
@c man .TP
@item -volid text
@kindex -volid set Volume Id
Alias of -V.
@c man .TP
@item -volset text
@kindex -volset set Volume Set Id
@cindex Volume Set Id, set, -volset
Set the Volume Set Id of the ISO image.
Permissible are up to 128 characters.
@c man .TP
@item -p text
@kindex -p set Publisher Id
@cindex Publisher Id, set, -p, -publisher
Set the Publisher Id of the ISO image. This may identify the person or
organisation who specified what shall be recorded.
Permissible are up to 128 characters.
@c man .TP
@item -publisher text
@kindex -publisher set Publisher Id
Alias of -p.
@c man .TP
@item -A text
@kindex -A set Application Id
@cindex Application Id, set, -A, -appid
Set the Application Id of the ISO image.
This may identify the specification of how the data are recorded.
Permissible are up to 128 characters.
@*
The special text "@@xorriso@@" gets converted to the id string of xorriso
which is normally written as Preparer Id. It is a wrong tradition to write
the program id as Application Id.
@c man .TP
@item -appid text
@kindex -appid set Application Id
Alias of -A.
@c man .TP
@item -sysid text
@kindex -sysid set System Id
@cindex System Id, set, -sysid
Set the System Id of the ISO image. This may
identify the system which can recognize and act upon the content of the
System Area in image blocks 0 to 15.
Permissible are up to 32 characters.
@c man .TP
@item -p text
@kindex -p set Preparer Id
@cindex Preparer Id, set, -p
Set the Preparer Id of the ISO image. This may
identify the person or other entity which controls the preparation of the data
which shall be recorded. Normally this should be the id of xorriso and not
of the person or program which operates xorriso. Please avoid to change it.
Permissible are up to 128 characters.
@*
The special text "@@xorriso@@" gets converted to the id string of xorriso
which is default at program startup.
@c man .TP
@item -preparer text
@kindex -preparer set Preparer Id
Alias of -p.
@c man .TP
@item -abstract iso_path
@kindex -abstract set Abstract File path
@cindex Abstract File, set path, -abstract
Set the address of the Abstract File of the ISO image. This should
be the ISO 9660 path of a file in the image which contains an abstract
statement about the image content.
Permissible are up to 37 characters.
@c man .TP
@item -biblio iso_path
@kindex -biblio set Biblio File path
@cindex Biblio File, set path, -biblio
Set the address of the Biblio File of the ISO image. This should
be the ISO 9660 path of a file in the image which contains bibliographic
records.
Permissible are up to 37 characters.
@c man .TP
@item -copyright iso_path
@kindex -copyright set Copyright File path
@cindex Copyright File, set path, -copyright
Set the address of the Copyright File of the ISO image. This should
be the ISO 9660 path of a file in the image which contains a copyright
statement.
Permissible are up to 37 characters.
@c man .TP
@item @minus{}@minus{}modification-date=YYYYMMDDhhmmsscc
@kindex @minus{}@minus{}modification-date set ISO image timestamps
@cindex ISO image, set timestamps, @minus{}@minus{}modification-date=
Set a timestring that overrides ISO image creation and modification timestamps
literally.
It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc, with
YYYY between 1970 and 2999. Time zone is GMT.
It is supposed to match this GRUB line:
@*
search @minus{}@minus{}fs-uuid @minus{}@minus{}set YYYY-MM-DD-hh-mm-ss-cc
@*
E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
@end table
@c man .TP
@c man .B El Torito Bootable ISO images:
@node Bootable, SystemArea, ImageId, Options
@section El Torito Bootable ISO images
@c man .PP
The precondition for a bootable ISO image is to have in the ISO image
the files of a boot loader. The boot facilities of computers get
directed to such files, which usually execute further program files
from the ISO image.
xorrisofs can produce several kinds of boot block or boot record,
which become part of the ISO image, and get interpreted by the according
boot facility.
@*
@c man .PP
@sp 1
@cindex El Torito, _definiton
An @strong{El Torito}
boot record points the bootstrapping facility to a boot catalog
with one or more boot images, which are binary program files stored in
the ISO image.
The content of the boot image files is not in the scope of El Torito.
@*
xorriso composes the boot catalog according to the boot image
files given and structured by options -b, -e, -el-torito-alt-boot,
and @minus{}@minus{}efi-boot. Often it contains only one entry.
@*
El Torito gets interpreted by boot facilities PC-BIOS and EFI.
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images
for PC-BIOS.
@*
xorrisofs supports the example options out of the ISOLINUX wiki,
the options used in GRUB script grub-mkrescue, and the example in the
FreeBSD AvgLiveCD wiki.
@*
@c man .PP
@sp 1
For CD booting via boot facilities other than PC-BIOS and EFI, and
for booting from USB sticks or hard disks, see the next section
about the Sytem Area.
@*
@table @asis
@sp 1
@c man .TP
@item -b iso_rr_path
@kindex -b El Torito PC-BIOS boot image
@cindex Bootability, control, -b, -eltorito-boot
Specify the boot image file which shall be mentioned in the current
entry of the El Torito boot catalog. It will be marked as suitable for
PC-BIOS.
@*
With boot images from ISOLINUX and GRUB this option should be accompanied by
options -c , -no-emul-boot , -boot-load-size 4 , -boot-info-table.
@c man .TP
@item -eltorito-boot iso_rr_path
@kindex -eltorito-boot El Torito PC-BIOS boot image
Alias of -b.
@c man .TP
@item -eltorito-alt-boot
@kindex -eltorito-alt-boot begin next boot catalog entry
@cindex Bootability, next entry, -eltorito-alt-boot
Finalize the current El Torito boot catalog entry and begin a new one.
A boot image file and all its necessary options shall be specified before
option -eltorito-alt-boot.
All further El Torito boot options apply to the new catalog
entry. Up to 32 catalog entries are possible.
@c man .TP
@item -e iso_rr_path
@kindex -e El Torito EFI boot image
@cindex Bootability, control, -e
Specify the boot image file which shall be mentioned in the current
entry of the El Torito boot catalog. It will be marked as suitable for EFI.
@*
Normally no other El Torito options should be used with the catalog entry
that points to an EFI image.
Consider to use @minus{}@minus{}efi-boot rather than -e.
@c man .TP
@item @minus{}@minus{}efi-boot iso_rr_path
@kindex @minus{}@minus{}efi-boot El Torito EFI boot image
@cindex Bootability, control, @minus{}@minus{}efi-boot
Perform eventual necessary -eltorito-alt-boot, option -e with the given
iso_rr_path, and again -eltorito-alt-boot. This gesture is
used for achieving EFI-bootability of the GRUB2 rescue CD.
@c man .TP
@item -boot-load-size number
@kindex -boot-load-size El Torito boot image load size
@cindex Bootability, boot image load size, -boot-load-size
Set the number of 512-byte blocks for boot images which emulate
a floppy or a hard disk. A safe default for non-emulating boot images is 4.
@c man .TP
@item -hard-disk-boot
@kindex -hard-disk-boot El Torito boot image emulation
@cindex Bootability, boot image emulation, -hard-disk-boot
Mark the boot image in the current catalog entry as emulated hard disk.
(Not suitable for any known boot loader.)
@c man .TP
@item -no-emul-boot
@kindex -no-emul-boot El Torito boot image emulation
@cindex Bootability, no boot image emulation, -no-emul-boot
Mark the boot image in the current catalog entry as not emulating
floppy or hard disk. (This is to be used with all known boot loaders.)
@*
If neither -hard-disk-boot nor -no-emul-boot is given, then the
boot image will be marked as emulating a floppy.
(Not suitable for any known boot loader.)
@c man .TP
@item -boot-info-table
@kindex -boot-info-table Patch El Torito boot image
@cindex Bootability, boot image patching, -boot-info-table
Overwrite certain bytes in the current boot image. The information will be
supplied by xorriso in the course of image production: Block address of
the Primary Volume Descriptor, block address of the boot image file,
size of the boot image file.
@c man .TP
@item -c iso_rr_path
@kindex -c El Torito boot catalog name
@cindex Bootability, boot catalog name, -c, -eltorito-catalog
Set the address of the El Torito boot catalog file within the image.
This file address is not significant for the booting PC-BIOS or EFI,
but it may later be read by other programs in order to learn about
the available boot images.
@c man .TP
@item -eltorito-catalog iso_rr_path
@kindex -eltorito-catalog El Torito boot catalog name
Alias of -c.
@c man .TP
@item @minus{}@minus{}boot-catalog-hide
@kindex @minus{}@minus{}boot-catalog-hide Hide El Torito boot catalog
@cindex Bootability, boot catalog hidden, @minus{}@minus{}boot-catalog-hide
Prevent the El Torito boot catalog from appearing as file
in the directory trees of the image.
@end table
@c man .TP
@c man .B System Area, MBR, other boot blocks:
@node SystemArea, Charset, Bootable, Options
@section System Area, MBR, other boot blocks
@c man .PP
@cindex System Area, _definiton
The first 16 blocks of an ISO image are the System Area.
It is reserved for system dependent boot software. This may be the
CD boot facilities of exotic hardware architectures or it may be
a MBR for booting via PC-BIOS from USB stick or hard disk.
@*
@cindex MBR, _definiton
A @strong{MBR} (Master Boot Record) contains boot code and a partition table.
It does not hamper El Torito booting from CDROM.
@*
xorrisofs supports boot facilities other than PC-BIOS:
MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
Those are mutually not combinable and also not combinable with MBR.
@*
@table @asis
@sp 1
@c man .TP
@item -G disk_path
@kindex -G Fill System Area e.g. by MBR
@cindex Bootability, fill System Area e.g. by MBR, -G, @minus{}@minus{}embedded-boot, -generic-boot
Copy at most 32768 bytes from the given disk file to the very start of
the ISO image.
@*
Other than a El Torito boot image, the file disk_path needs not to be added
to the ISO image. It will not show up as file in the directory trees.
@c man .TP
@item -generic-boot disk_path
@kindex -generic-boot Fill System Area e.g. by MBR
Alias of -G.
@c man .TP
@item @minus{}@minus{}embedded-boot disk_path
@kindex @minus{}@minus{}embedded-boot Fill System Area e.g. by MBR
Alias of -G.
@c man .TP
@item -isohybrid-mbr disk_path
@kindex -isohybrid-mbr Install ISOLINUX isohybrid MBR
@cindex Bootability, install ISOLINUX isohybrid MBR, -isohybrid-mbr
Install disk_path as ISOLINUX isohybrid MBR which makes the boot image
given by option -b bootable from USB sticks and hard disks via PC-BIOS.
This preparation is normally done by ISOLINUX program isohybrid
on the already produced ISO image.
@*
The disk path should lead to one of the Syslinux files isohdp[fp]x*.bin .
The MBR gets patched according to isohybrid needs. The first partition
describes the range of the ISO image. Its start is at block 0 by default,
but may be set to 64 disk blocks by option -partition_offset 16.
@c man .TP
@item @minus{}@minus{}protective-msdos-label
@kindex @minus{}@minus{}protective-msdos-label Patch System Area partition table
@cindex Bootability, patch System Area partition table, @minus{}@minus{}protective-msdos-label
Patch the System Area by a simple PC-DOS partition table where partition 1
claims the range of the ISO image but leaves the first block unclaimed.
@c man .TP
@item -partition_offset 2kb_block_adr
@kindex -partition_offset Make mountable by partition 1
@cindex Mountability, by non-trivial partition 1, -partition_offset
Cause a partition table with a single partition that begins at the
given block address. This is counted in 2048 byte
blocks, not in 512 byte blocks. If the block address is non-zero then it must
be at least 16. Values larger than 16 are hardly of use.
A non-zero partition offset causes two superblocks to be
generated and two sets of directory trees. The image is then mountable from its
absolute start as well as from the partition start.
@*
The offset value of an ISO image gets preserved when a new session is added
to a loaded image.
So the value defined here is only in effect if a new ISO image gets written.
@c man .TP
@item -partition_hd_cyl number
@kindex -partition_hd_cyl MBR heads per cylinder
@cindex MBR, sectors per head, -partition_sec_hd
Set the number of heads per cylinder for the partition table.
0 chooses a default value. Maximum is 255.
@c man .TP
@item -partition_sec_hd number
@kindex -partition_sec_hd MBR sectors per head
@cindex MBR, sectors per head, -partition_sec_hd
Set the number of sectors per head for the partition table.
0 chooses a default value. Maximum is 63.
@*
The product partition_sec_hd * partition_hd_cyl * 512 is the cylinder size.
It should be divisible by 2048 in order to allow exact alignment.
If it is too small to describe the image size by at most 1024 cylinders,
then appropriate values of partition_hd_cyl are chosen with
partition_sec_hd 32 or 63. If the image is larger than 8,422,686,720 bytes,
then the cylinder size constraints cannot be fulfilled. They seem not overly
important anyway. Flat block addresses in partition tables are good for 1 TiB.
@c man .TP
@item -partition_cyl_align mode
@kindex -partition_cyl_align Image size alignment
@cindex Image size, alignment, -partition_cyl_align
Control image size alignment to an integer number of cylinders.
It is prescribed by isohybrid specs and it seems to please program fdisk.
Cylinder size must be divisible by 2048.
Images larger than 8,323,596,288 bytes cannot be aligned.
@*
Mode "auto" is default. Alignment by padding happens only if
option -isohybrid-mbr is given.
@*
Mode "on" causes alignment by padding with option
@minus{}@minus{}protective-msdos-label too.
Mode "off" disables alignment unconditionally.
@c man .TP
@item -append_partition partition_number type_code disk_path
@kindex -append_partition Append MBR partition after image
@cindex MBR, append partition, -append_partition
Cause a prepared filesystem image to be appended to the ISO image and to be
described by a partition table entry in a boot block at the start of the
emerging ISO image. The partition entry will bear the size of the submitted
file rounded up to the next multiple of 2048 bytes.
@*
Beware of subsequent multi-session runs. The appended partition will get
overwritten.
@*
partition_number may be 1 to 4. Number 1 will put the whole ISO image into
the unclaimed space before partition 1. So together with most xorriso MBR
features, number 2 would be the most natural choice.
@*
The type_code may be "FAT12", "FAT16", "Linux",
or a hexadecimal number between 0x00 and 0xff. Not all those numbers will
yield usable results. For a list of codes search the Internet for
"Partition Types" or run fdisk command "L".
@c man .TP
@item -mips-boot iso_rr_path
@kindex -mips-boot MIPS Big Endian boot image
@cindex Bootability, control, -mips-boot
Declare a data file in the image to be a
MIPS Big Endian boot file and cause production of a MIPS Big Endian Volume
Header. This is mutually exclusive with production of other boot blocks
like MBR.
It will overwrite the first 512 bytes of any data eventually provided by -G.
Up to 15 boot files can be declared by multiple -mips-boot options.
@c man .TP
@item -mipsel-boot iso_rr_path
@kindex -mipsel-boot MIPS Little Endian boot image
@cindex Bootability, control, -mipsel-boot
Declare a data file in the image to be the
MIPS Little Endian boot file. This is mutually exclusive with other boot
blocks.
It will overwrite the first 512 bytes of any data eventually
provided by -G.
Only a single boot file can be declared by -mipsel-boot.
@c man .TP
@item -B disk_path[,disk_path ...]
@kindex -B SUN SPARC boot images
@cindex Bootability, control, -B, -sparc-boot
Cause one or more data files on disk to be written after the end of the
ISO image. A SUN Disk Label will be written into the first 512 bytes of the
ISO image which lists this image as partition 1 and the given disk_paths as
partition 2 up to 8.
@*
The disk files should contain suitable boot images for SUN SPARC systems.
@*
The pseudo disk_path "..." causes that all empty partition entries become
copies of the last non-empty entry. If no other disk_path is given before
"..." then all partitions describe the ISO image. In this case, the boot
loader code has to be imported by option -G.
@c man .TP
@item -sparc-boot disk_path[,disk_path ...]
@kindex -sparc-boot SUN SPARC boot images
Alias of -B.
@c man .TP
@item -sparc-label text
@kindex -sparc-label SUN Disk Label text
@cindex Bootability, SUN Disk Label text, -sparc-label
Set the ASCII label text of a SUN Disk Label.
@end table
@c man .TP
@c man .B Character sets:
@node Charset, Jigdo, SystemArea, Options
@section Character sets
@c man .PP
@cindex Character sets, _definition
Character sets should not matter as long as only english alphanumeric
characters are used for file names or as long as all writers and readers
of the media use the same character set.
Outside these constraints it may be necessary to let xorriso convert byte
codes.
@*
A conversion from input character set to the output character set is
performed when an ISO image gets written.
Vice versa there is a conversion from output character set to the
input character set when an ISO image gets loaded.
The sets can be defined by options -input-charset and -output-charset,
if needed.
@*
@table @asis
@sp 1
@c man .TP
@item -input-charset character_set_name
@kindex -input-charset set character set of disk file names
@cindex Character Set, for disk file names, -input-charset
Set the character set from which to convert disk file names when
inserting them into the ISO image.
@sp 1
@c man .TP
@item -output-charset character_set_name
@kindex -output-charset set character set of ISO file names
@cindex Character Set, for ISO file names, -output-charset
Set the character set from which to convert names of loaded ISO images
and to which to convert names when writing ISO images.
@end table
@c man .TP
@c man .B Jigdo Template Extraction:
@node Jigdo, Miscellaneous, Charset, Options
@section Jigdo Template Extraction
@c man .PP
@cindex Jigdo Template Extraction, _definition
From man genisoimage:
"Jigdo is a tool to help in the distribution of large files like CD and
DVD images; see http://atterer.net/jigdo/ for more details. Debian CDs
and DVD ISO images are published on the web in jigdo format to allow
end users to download them more efficiently."
@*
If the use of libjte was enabled at compile time of xorriso, then
xorrisofs can produce a .jigdo and a .template file together with a
single-session ISO image. If not, then Jigdo options will cause a
FAILURE event, which normally leads to program abort.
@*
One may determine the ability for Jigdo by:
@*
@sp 1
$ xorrisofs -version 2>&1 | grep '^libjte' && echo YES
@*
@sp 1
@c man .PP
The .jigdo file contains checksums and symbolic file addresses.
The .template file contains the compressed ISO image with reference tags
instead of the content bytes of the listed files.
@*
Input for this process are the normal arguments for a xorrisofs session
with no image loaded, and a .md5 file which lists those data files which may be
listed in the .jigdo file and externally referenced in the .template file.
Each designated file is represented in the .md5 file by a single text line:
@*
MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks,
symbolic file address
@*
The file address in an .md5 line has to bear the same basename as the
disk_path of the file which it shall match. The directory path of
the file address is decisive for To=From mapping, not for file recognition.
After eventual To=From mapping, the file address gets written into the .jigdo
file. Jigdo restore tools will convert these addresses into really
reachable data source addresses from which they can read.
@*
If the list of jigdo parameters is not empty, then eventual padding will be
counted as part of the ISO image.
@*
@table @asis
@sp 1
@c man .TP
@item -jigdo-jigdo disk_path
@kindex -jigdo-jigdo set name of .jigdo file
@cindex Jigdo Template Extraction, -jigdo-jigdo
Set the disk_path for the .jigdo file with the checksums
and download addresses for filling the holes in .template.
@c man .TP
@item -jigdo-template disk_path
@kindex -jigdo-template set name of .template file
@cindex Jigdo Template Extraction, -jigdo-template
Set the disk_path for the .template file with the
holed and compressed ISO image copy.
@c man .TP
@item -jigdo-min-file-size size
@kindex -jigdo-min-file-size set minimum extract size
@cindex Jigdo Template Extraction, -jigdo-min-file-size
Set the minimum size for a data file to be listed
in the .jigdo file and being a hole in the .template file.
size may be a plain number counting bytes, or a number with appended
letter "k", "m", "g" to count KiB (1024 bytes), MiB (1024 KiB), or
GiB (1024 MiB).
@c man .TP
@item -jigdo-force-md5 disk_path_pattern
@kindex -jigdo-force-md5 add check pattern for .md5
@cindex Jigdo Template Extraction, -jigdo-force-md5
adds a regular expression pattern which will get compared
with the absolute disk_path of any data file that was not found in the .md5
list. A match causes a MISHAP event, which normally does not abort the
program run but finally causes a non-zero exit value of the program.
@c man .TP
@item -jigdo-exclude disk_path_pattern
@kindex -jigdo-exclude add exclusion pattern for .md5
@cindex Jigdo Template Extraction, -jigdo-exclude
Add a regular expression pattern which will get compared
with the absolute disk_path of any data file. A match causes the file to
stay in .template in any case.
@c man .TP
@item -jigdo-map To=From
@kindex -jigdo-map add address translation for .jigdo
@cindex Jigdo Template Extraction, -jigdo-map
Add a string pair of the form To=From to the parameter list.
If a data file gets listed in the .jigdo file, then it is referred by the
file address from its line in the .md5 file. This file address gets checked
whether it begins with the From string. If so, then this string will be
replaced by the To string and a ':' character, before it goes into the .jigdo
file. The From string should end by a '/' character.
@c man .TP
@item -md5-list disk_path
@kindex -md5-list set path of readable .md5
@cindex Jigdo Template Extraction, -md5-list
Set the disk_path where to find the .md5 input file.
@c man .TP
@item -jigdo-template-compress "gzip"|"bzip2"
@kindex -jigdo-template-compress choose compression algorithm
@cindex Jigdo Template Extraction, -jigdo-template-compress
Choose one of "bzip2" or "gzip" for the compression of
the template file. The jigdo file is put out uncompressed.
@c man .TP
@item -checksum_algorithm_iso list_of_names
@kindex -checksum_algorithm_iso choose .jigdo checksums
@cindex Jigdo Template Extraction, -checksum_algorithm_iso
Choose one or more of "md5", "sha1", "sha256", "sha512"
for the auxiliary "# Image Hex" checksums in the .jigdo file. The list_of_names
may e.g. look like "md5,sha1,sha512". Value "all" chooses all available
algorithms.
Note that MD5 stays always enabled.
@c man .TP
@item -checksum_algorithm_template list_of_names
@kindex -checksum_algorithm_template choose .template checksums
@cindex Jigdo Template Extraction, -checksum_algorithm_template
Choose the algorithms for the "# Template Hex" checksums in the .jigdo file.
The rules for list_of_names are the same as with -checksum_algorithm_iso.
@end table
@c man .TP
@c man .B Miscellaneous options:
@node Miscellaneous, ExSimple, Jigdo, Options
@section Miscellaneous options
@table @asis
@sp 1
@c man .TP
@item -print-size
@kindex -print-size predict ISO image size
@cindex ISO image size, predict, -print-size
Print to stdandard output the foreseeable number of 2048 byte blocks in
the emerging ISO image. Do not produce this image.
@*
The result depends on several settings.
@*
If option --emul-toc is given, then padding (see -pad) is not
counted as part of the image size. In this case either use -no-pad or
add 150 (= 300 KiB) to the resulting number.
@c man .TP
@item @minus{}@minus{}no_rc
@kindex @minus{}@minus{}no_rc do not execute startup files
@cindex Startup files, suppress, @minus{}@minus{}no_rc
Only if used as first argument this option
prevents reading and interpretation of eventual startup
files. See section FILES below.
@c man .TP
@item -help
@kindex -help list supported options
@cindex Options, list, -help
List supported options to stderr. Original mkisofs options bear their
original mkisofs description texts.
@c man .TP
@item -quiet
@kindex -quiet suppress most messages
@cindex Message output, suppress, -quiet
Suppress most messages of the program run, except those which indicate
problems or errors.
@c man .TP
@item -v
@kindex -v enable verbous messages
@cindex Verbosity, high, -v, -verbose
Enable the output of informational program messages.
@c man .TP
@item -verbose
@kindex -verbose enable verbous messages
Alias of -v.
@c man .TP
@item -version
@kindex -version report program version
@cindex Program version, report, -version
Print to standard output a text that begins with
@*
"mkisofs 2.01-Emulation Copyright (C)"
@*
and to standard error the version information of xorriso.
@end table
@c man .br
@node Examples, Files, Options, Top
@chapter Examples
@c man .SH EXAMPLES
@c man .SS
@c man .B Overview of examples:
@c man A simple image production run
@c man .br
@c man Set ISO image paths by -graft-points
@c man .br
@c man Perform multi-session runs
@c man .br
@c man Let xorrisofs work underneath growisofs
@c man .br
@c man Incremental backup of a few directory trees
@c man .br
@c man Incremental backup with accumulated trees
@c man .br
@c man Create bootable images for PC-BIOS
@c man .br
@cindex Examples
@menu
* ExSimple:: A simple image production run
* ExGraft:: Set ISO image paths by -graft-points
* ExMkisofs:: Perform multi-session runs
* ExGrowisofs:: Let xorriso work underneath growisofs
* ExIncBackup:: Incremental backup of a few directory trees
* ExIncBckAcc:: Incremental backup with accumulated trees
* ExBootable:: Create bootable images for PC-BIOS
@end menu
@c man .SS
@c man .B A simple image production run
@node ExSimple, ExGraft, Miscellaneous, Examples
@section A simple image production run
A prepared file tree in directory ./for_iso gets copied into the root
directory of the ISO image. File permissions get set to read-only for
everybody.
Joliet attributes for Microsoft systems get added.
The resulting image gets written as data file ./image.iso on disk.
@*
@sp 1
$ xorrisofs -r -J -o ./image.iso ./for_iso
@c man .SS
@c man .B Set ISO image paths by -graft-points
@node ExGraft, ExMkisofs, ExSimple, Examples
@section Set ISO image paths by -graft-points
Without option -graft-points each given disk file is copied into the root
directory of the ISO image, maintaining its name. If a directory is given,
then its files and sub-directories are copied into the root directory,
maintaining their names.
@*
@sp 1
$ xorrisofs ... /home/me/datafile /tmp/directory
@*
@sp 1
yields in the ISO image root directory:
@*
@sp 1
/datafile
@*
/file_1_from_directory
@*
...
@*
/file_N_from_directory
@*
@sp 1
@c man .sp 1
With option -graft-points it is possible to put files and directories to
arbitrary paths in the ISO image.
@*
@sp 1
$ xorrisofs ... -graft-points /home/me/datafile /dir=/tmp/directory
@*
@sp 1
yields in the ISO image root directory:
@*
@sp 1
/datafile
@*
/dir
@*
@sp 1
Eventually needed parent directories in
the image will be created automatically:
@*
@sp 1
/datafiles/file1=/home/me/datafile
@*
@sp 1
yields in the ISO image:
@sp 1
@*
/datafiles/file1
@*
@sp 1
The attributes of directory /datafiles get copied from /home/me on disk.
@*
@sp 1
@c man .sp 1
Normally one should avoid = and \ characters in the ISO part of a pathspec.
But if it must be, one may escape them:
@sp 1
@*
/with_\=_and_\\/file=/tmp/directory/file
@*
@sp 1
yields in the ISO image:
@*
@sp 1
/with_=_and_\/file
@c man .SS
@c man .B Perform multi-session runs
@node ExMkisofs, ExGrowisofs, ExGraft, Examples
@section Perform multi-session runs
The first session is written like this:
@*
@sp 1
$ xorrisofs -graft-points \
@*
/tree1=prepared_for_iso/tree1 \
@*
| xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
@*
@sp 1
Follow-up sessions are written like this:
@*
@sp 1
$ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
@*
$ xorrisofs -M /dev/sr0 -C $m -graft-points \
@*
/tree2/=prepared_for_iso/tree2 \
@*
| xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
@*
@sp 1
Always eject the drive tray between sessions. The old sessions
get read via /dev/sr0. Its device driver might not be aware
of the changed content before it loads the media again.
@*
@sp 1
This example works for multi-session media only.
Add cdrskin option @minus{}@minus{}grow_overwriteable_iso
to all -as cdrecord runs
in order to enable multi-session emulation on overwriteable media.
@c man .SS
@c man .B Let xorrisofs work underneath growisofs
@node ExGrowisofs, ExIncBackup, ExMkisofs, Examples
@section Let xorriso work underneath growisofs
growisofs expects an ISO formatter program which understands options -C and
-M. A variable is defined to override the hardcoded default name.
@*
@sp 1
$ export MKISOFS="xorrisofs"
@*
$ growisofs -Z /dev/dvd /some/files
@*
$ growisofs -M /dev/dvd /more/files
@*
@sp 1
If no "xorrisofs" is available on your system, then you will have to create
a link pointing to the xorriso binary and tell growisofs to use it. E.g. by:
@*
@sp 1
$ ln -s $(which xorriso) "$HOME/xorrisofs"
@*
$ export MKISOFS="$HOME/xorrisofs"
@*
@sp 1
One may quit mkisofs emulation by argument "@minus{}@minus{}" and make
use of all xorriso commands. growisofs dislikes options which
start with "-o" but -outdev must be set to "-".
So use "outdev" instead:
@*
@sp 1
$ growisofs -Z /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
@*
$ growisofs -M /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
@c man .SS
@c man .B Incremental backup of a few directory trees
@node ExIncBackup, ExIncBckAcc, ExGrowisofs, Examples
@section Incremental backup of a few directory trees
This changes the directory trees /open_source_project and /personal_mail
in the ISO image so that they become exact copies of their disk counterparts.
ISO file objects get created, deleted or get their attributes adjusted
accordingly.
@*
ACL, xattr, hard links and MD5 checksums will be recorded.
It is expected that inode numbers in the disk filesystem are persistent
over cycles of mounting and booting.
Files with names matching *.o or *.swp get excluded explicitly.
@*
@sp 1
@c man .sp 1
To be used several times on the same media, whenever an update of
the two disk trees to the media is desired. Begin with blank media and start
a new blank media when the run fails due to lack of remaining space on
the old one.
@*
@sp 1
$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
@*
$ load_opts=
@*
$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo"
@*
$ xorrisofs $load_opts -o - @minus{}@minus{}for_backup -m '*.o' -m '*.swp' \
@*
-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \
@*
-old-root / \
@*
/projects=/home/thomas/projects \
@*
/personal_mail=/home/thomas/personal_mail \
@*
| xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject -
@*
@sp 1
@c man .sp 1
This makes sense if the full backup leaves substantial remaining capacity
on media and if the expected changes are much smaller than the full backup.
@*
@sp 1
@c man .sp 1
@strong{Better do not use your youngest backup for -old-root}.
Have at least two media which you use alternatingly. So only older backups
get endangered by the new write operation, while the newest backup is
stored safely on a different media.
Always have a blank media ready to perform a full backup in case the update
attempt fails due to insufficient remaining capacity.
@*
@sp 1
@c man .sp 1
If inode numbers on disk are not persistent, then use
option @minus{}@minus{}old-root-no-ino .
In this case an update run will compare recorded MD5
sums against the current file content on hard disk.
@*
@sp 1
@c man .sp 1
With @strong{mount} option @strong{-o "sbsector="} on GNU/Linux
resp. @strong{-s} on FreeBSD
it is possible to access the session trees which represent the older backup
versions. With CD media, GNU/Linux mount accepts session numbers directly by
its option "session=".
@*
Multi-session media and most overwriteable media written by xorriso can tell
the sbsectors of their sessions by xorriso option -toc:
@*
@sp 1
$ xorriso -dev /dev/sr0 -toc
@*
@sp 1
xorriso can print the matching mount command for a session number:
@*
@sp 1
$ xorriso -mount_cmd /dev/sr0 session 12 /mnt
@*
@sp 1
or for a volume id that matches a search expression:
@*
@sp 1
$ xorriso -mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt
@*
@sp 1
Both yield on standard output something like:
@*
mount -t iso9660 -o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0' '/mnt'
@*
@sp 1
The superuser may let xorriso execute the mount command directly:
@*
@sp 1
# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
@c man .SS
@c man .B Incremental backup with accumulated trees
@node ExIncBckAcc, ExBootable, ExIncBackup, Examples
@section Incremental backup with accumulated trees
Solaris does not offer the option to mount older sessions.
In order to keep them accessible, one may map all files to a file tree under
a session directory and accumulate those directories from session to session.
The -root tree is cloned from the -old-root tree before it gets
compared with the appropriate trees on disk.
@*
This demands to know the previously used session directory name.
@*
With the first session:
@*
@sp 1
$ xorrisofs -root /session1 \
@*
-o - @minus{}@minus{}for_backup -m '*.o' -m '*.swp' \
@*
-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \
@*
/projects=/home/thomas/projects \
@*
/personal_mail=/home/thomas/personal_mail \
@*
| xorriso -as cdrecord dev=/dev/sr0 -v blank=as_needed \
@*
-multi -waiti -eject -
@*
@sp 1
@c man .sp 1
With the second session, option -old-root refers to /session1 and the
new -root is /session2:
@*
@sp 1
$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
@*
$ load_opts=
@*
$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo"
@*
$ xorrisofs $load_opts -root /session2 -old-root /session1 \
@*
-o - @minus{}@minus{}for_backup -m '*.o' -m '*.swp' \
@*
-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \
@*
/projects=/home/thomas/projects \
@*
/personal_mail=/home/thomas/personal_mail \
@*
| xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject -
@*
@sp 1
With the third session, option -old-root refers to /session2.
The new -root is /session3. And so on.
@c man .SS
@c man .B Create bootable images for PC-BIOS
@node ExBootable, , ExIncBckAcc, Examples
@section Create bootable images for PC-BIOS
The ISOLINUX wiki prescribes to create on disk a directory ./CD_root and
to copy all desired files underneath that directory. Especially file
isolinux.bin shall be copied to ./CD_root/isolinux/isolinux.bin .
This is the boot image file.
@*
The prescribed mkisofs options can be used unchanged with xorrisofs:
@*
@sp 1
$ xorrisofs -o output.iso \
@*
-b isolinux/isolinux.bin -c isolinux/boot.cat \
@*
-no-emul-boot -boot-load-size 4 -boot-info-table \
@*
./CD_root
@*
@sp 1
@c man .sp 1
The image from above example will boot from CD, DVD or BD, but not from
USB stick or orther hard-disk-like devices. This can be done by help of an
isohybrid MBR. Syslinux provides matching template files
as isohdp[fp]x*.bin . E.g. /usr/lib/syslinux/isohdpfx.bin .
@*
If a few hundred KB of size do not matter, then option -partition_offset
can be used to create a partition table where partition 1 starts not
at block 0. This facilitates later manipulations of the USB stick by
tools for partitioning and formatting.
@*
The image from the following example will be prepared for booting via MBR
and its first parttion will start at hard disk block 64.
@*
@sp 1
$ xorrisofs -o output.iso \
@*
-b isolinux/isolinux.bin -c isolinux/boot.cat \
@*
-no-emul-boot -boot-load-size 4 -boot-info-table \
@*
-isohybrid-mbr /usr/lib/syslinux/isohdpfx.bin \
@*
-partition_offset 16 \
@*
./CD_root
@*
@sp 1
Become superuser and copy the image to the unpartitioned base device file
of the USB stick. On GNU/Linux this is e.g. /dev/sdb, not /dev/sdb1.
@*
CAUTION:
This will overwrite any eventual partitioning on the USB stick and make
remaining data unaccessible.
@*
So first make sure you got the correct address of the intended device.
E.g. by reading 100 MiB data from it and watching it blinking:
@*
@sp 1
# dd bs=2K if=/dev/sdb count=50K >/dev/null
@*
@sp 1
Now copy the image onto it
@*
@sp 1
# dd bs=2K if=output.iso of=/dev/sdb
@*
@sp 1
@c man .SH FILES
@node Files, Seealso, Examples, Top
@chapter Files
@c man .SS
@c man .B Startup files:
@section Startup Files
@*
If not --no_rc is given as the first argument then xorrisofs
attempts on startup to read and execute lines from the following files:
@*
@sp 1
/etc/default/xorriso
@*
/etc/opt/xorriso/rc
@*
/etc/xorriso/xorriso.conf
@*
$HOME/.xorrisorc
@*
@sp 1
The files are read in the sequence given here, but none of them is required
to exist. The lines are not interpreted as xorrisofs options but as generic
xorriso commands. See man xorriso.
@c man .PP
After the xorriso startup files, the program tries one by one to open for
reading:
@*
@sp 1
./.mkisofsrc
@*
$MKISOFSRC
@*
$HOME/.mkisofsrc
@*
$(dirname $0)/.mkisofsrc
@*
@sp 1
On success it interprets the file content and does not try further files.
The last address is used only if start argument 0 has a non-trivial dirname.
@*
The reader currently interprets the following NAME=VALUE pairs:
@*
@sp 1
APPI default for -A
@*
PUBL default for -publisher
@*
SYSI default for -sysid
@*
VOLI default for -V
@*
VOLS default for -volset
@*
@sp 1
Any other lines will be silently ignored.
@*
@c man .SH SEE ALSO
@c man .TP
@c man For generic xorriso command mode
@c man .BR xorriso(1)
@c man .TP
@c man For mounting xorriso generated ISO 9660 images (-t iso9660)
@c man .BR mount(8)
@c man .TP
@c man Other programs which produce ISO 9660 images
@c man .BR mkisofs(8),
@c man .BR genisoimage(8)
@c man .TP
@c man Programs which burn sessions to optical media
@c man .BR growisofs(1),
@c man .BR cdrecord(1),
@c man .BR wodim(1),
@c man .BR cdrskin(1),
@c man .BR xorriso(1)
@c man .TP
@c man ACL and xattr
@c man .BR getfacl(1),
@c man .BR setfacl(1),
@c man .BR getfattr(1),
@c man .BR setfattr(1)
@c man .TP
@c man MD5 checksums
@c man .BR md5sum(1)
@c man-ignore-lines begin
@node Seealso, Legal, Files, Top
@chapter See also
@table @asis
@item For generic xorriso command mode
xorriso(1)
@item For mounting xorriso generated ISO 9660 images (-t iso9660)
mount(8)
@item Other programs which produce ISO 9660 images
mkisofs(8),
genisoimage(8)
@item Programs which burn sessions to optical media
growisofs(1),
cdrecord(1),
wodim(1),
cdrskin(1),
xorriso(1)
@item ACL and xattr
getfacl(1),
setfacl(1),
getfattr(1),
setfattr(1)
@item MD5 checksums
md5sum(1)
@end table
@c man-ignore-lines end
@c man .SH AUTHOR
@node Legal, CommandIdx, Seealso, Top
@chapter Author, Copyright, Credits
@section Author
Thomas Schmitt <scdbackup@@gmx.net>
@*
for libburnia-project.org
@c man .SH COPYRIGHT
@section Copyright
Copyright (c) 2011 Thomas Schmitt
@*
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of xorriso. If you make use
of the license to derive modified versions of xorriso then you are entitled
to modify this text under that same license.
@c man .SH CREDITS
@section Credits
xorrisofs is in part based on work by Vreixo Formoso who provides libisofs
together with Mario Danic who also leads the libburnia team.
@*
Compliments towards Joerg Schilling whose cdrtools served me for ten years.
@c man-ignore-lines begin
@node CommandIdx, ConceptIdx, Legal, Top
@chapter Alphabetic Command List
@printindex ky
@node ConceptIdx,, CommandIdx, top
@chapter Alphabetic List of Concepts and Objects
@printindex cp
@c man-ignore-lines end
@bye