From 04bcee0f3f8fe5c15f83a41051212dacf2b19b3c Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Sat, 5 Mar 2011 14:15:32 +0000 Subject: [PATCH] Own man page and info document for xorrisofs --- libisoburn/trunk/Makefile.am | 8 +- libisoburn/trunk/xorriso/make_docs.sh | 5 +- .../trunk/xorriso/make_xorriso_standalone.sh | 4 + .../trunk/xorriso/xorriso_makefile_am.txt | 8 +- libisoburn/trunk/xorriso/xorriso_timestamp.h | 2 +- libisoburn/trunk/xorriso/xorrisofs.1 | 1427 ++++++++++++ libisoburn/trunk/xorriso/xorrisofs.info | 1762 +++++++++++++++ libisoburn/trunk/xorriso/xorrisofs.texi | 1962 +++++++++++++++++ 8 files changed, 5172 insertions(+), 6 deletions(-) create mode 100644 libisoburn/trunk/xorriso/xorrisofs.1 create mode 100644 libisoburn/trunk/xorriso/xorrisofs.info create mode 100644 libisoburn/trunk/xorriso/xorrisofs.texi diff --git a/libisoburn/trunk/Makefile.am b/libisoburn/trunk/Makefile.am index 3e5fd8c0..658f8a3d 100644 --- a/libisoburn/trunk/Makefile.am +++ b/libisoburn/trunk/Makefile.am @@ -219,9 +219,13 @@ indent: $(indent_files) nodist_pkgconfig_DATA = \ libisoburn-1.pc -man_MANS = xorriso/xorriso.1 +man_MANS = \ + xorriso/xorriso.1 \ + xorriso/xorrisofs.1 -info_TEXINFOS = xorriso/xorriso.texi +info_TEXINFOS = \ + xorriso/xorriso.texi \ + xorriso/xorrisofs.texi EXTRA_DIST = \ libisoburn-1.pc.in \ diff --git a/libisoburn/trunk/xorriso/make_docs.sh b/libisoburn/trunk/xorriso/make_docs.sh index b05ba2eb..742db9d7 100755 --- a/libisoburn/trunk/xorriso/make_docs.sh +++ b/libisoburn/trunk/xorriso/make_docs.sh @@ -1,10 +1,13 @@ #!/bin/sh # # Produce man page xorriso/xorriso.1 and info file xorriso/xorriso.info -# from base file xorris/xorriso.texi. +# from base file xorriso/xorriso.texi. +# Same for xorriso/xorrisofs.texi. ( cd xorriso ; makeinfo ./xorriso.texi ) +( cd xorriso ; makeinfo ./xorrisofs.texi ) xorriso/make_xorriso_1 -auto +xorriso/make_xorriso_1 -auto -xorrisofs diff --git a/libisoburn/trunk/xorriso/make_xorriso_standalone.sh b/libisoburn/trunk/xorriso/make_xorriso_standalone.sh index ceb20be7..5f7a0655 100755 --- a/libisoburn/trunk/xorriso/make_xorriso_standalone.sh +++ b/libisoburn/trunk/xorriso/make_xorriso_standalone.sh @@ -189,10 +189,14 @@ copy_files \ \ xorriso/changelog.txt \ xorriso/xorriso_eng.html \ + xorriso/make_docs.sh \ xorriso/xorriso.texi \ xorriso/xorriso.info \ + xorriso/xorrisofs.texi \ + xorriso/xorrisofs.info \ xorriso/make_xorriso_1.c \ xorriso/xorriso.1 \ + xorriso/xorrisofs.1 \ xorriso/man_1_xorriso.html \ "$lone_dir"/xorriso copy_files COPYRIGHT "$lone_dir"/xorriso diff --git a/libisoburn/trunk/xorriso/xorriso_makefile_am.txt b/libisoburn/trunk/xorriso/xorriso_makefile_am.txt index f8a28049..05f00250 100644 --- a/libisoburn/trunk/xorriso/xorriso_makefile_am.txt +++ b/libisoburn/trunk/xorriso/xorriso_makefile_am.txt @@ -291,9 +291,13 @@ indent: $(indent_files) # Extra things -man_MANS = xorriso/xorriso.1 +man_MANS = \ + xorriso/xorriso.1 \ + xorriso/xorrisofs.1 -info_TEXINFOS = xorriso/xorriso.texi +info_TEXINFOS = \ + xorriso/xorriso.texi \ + xorriso/xorrisofs.texi EXTRA_DIST = \ xorriso.pc.in \ diff --git a/libisoburn/trunk/xorriso/xorriso_timestamp.h b/libisoburn/trunk/xorriso/xorriso_timestamp.h index ad833d0f..795cd438 100644 --- a/libisoburn/trunk/xorriso/xorriso_timestamp.h +++ b/libisoburn/trunk/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2011.03.05.090434" +#define Xorriso_timestamP "2011.03.05.141534" diff --git a/libisoburn/trunk/xorriso/xorrisofs.1 b/libisoburn/trunk/xorriso/xorrisofs.1 new file mode 100644 index 00000000..83b014b8 --- /dev/null +++ b/libisoburn/trunk/xorriso/xorrisofs.1 @@ -0,0 +1,1427 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" +.\" IMPORTANT NOTE: +.\" +.\" The original of this file is kept in xorriso/xorrisofs.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 XORRISOFS 1 "Mar 05, 2011" +.\" 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 insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.nh +.SH NAME +xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso, +.SH SYNOPSIS +.B xorrisofs +[ options ] [-o filename ] pathspec [pathspecs ...] +.br +.SH DESCRIPTION +.PP +\fBxorrisofs\fR +produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to +such filesystems. Optionally it can produce Joliet directory trees too. +.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. +.SS +\fBRelation to program xorriso:\fR +.br +xorrisofs is actually a command mode of program \fBxorriso\fR, +which gets entered either by xorriso command "-as mkisofs" or by +starting the program by one of the names "xorrisofs", "mkisofs", +"genisoimage", or "genisofs". +.br +This command mode can be left by argument "--" which leads +to generic xorriso command mode. See \fBman xorriso\fR for its description. +.br +.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. +.br +The program messages call any file a "drive". File types which are not +supported for reading are reported as "blank". The reported free media +space may be quite fictional. +.br +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. +.SS +\fBISO 9660, Rock Ridge, Joliet:\fR +.br +\fBISO 9660\fR +(aka \fBECMA-119\fR) describes directories and data files with +very restricted filenames with no distinction of upper case and lower case. +Its metadata do not comply to fundamental POSIX specifications. +.br +\fBRock Ridge\fR +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. +.br +Rock Ridge information is produced unconditionally with any xorrisofs image. +.br +\fBJoliet\fR +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. +.br +\fBISO 9660:1999\fR +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. +.SS +.B Inserting files into the ISO image: +.PP +xorrisofs deals with two kinds of file addresses: +.br +\fBdisk_path\fR +is a path to an object in the local filesystem tree. +.br +\fBiso_rr_path\fR +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.) +.br +.PP +A program argument is handled as a \fBpathspec\fR, 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. +.br +If -graft-points is present then each pathspec gets split at the first +occurence of the =-character. +The part before the = is taken as \fBtarget\fR, the iso_rr_path for +the file object in the ISO image. The part after the first = is taken +as \fBsource\fR, the disk_path of the input object. +.br +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. +.br +.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. +.SS +.br +.SH OPTIONS +.br +.PP +.TP +.B Image loading: +.PP +The following options control loading of an existing ISO image for the purpose +of preparing a suitable add-on session. +.TP +\fB\-M\fR disk_path +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. +.TP +\fB\-prev-session\fR disk_path +Alias of -M. +.TP +\fB\-dev\fR disk_path +Alias of -M. +.TP +\fB\-C\fR last_session_start,next_writeable_address +Set the 2 KiB block address last_session_start from where to read the +ISO image out of the file given by option -M. +.br +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. +.br +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: +.br + values=$(xorriso -as cdrecord dev=/dev/... -msinfo) + echo $values +.br +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. +.TP +\fB\-cdrecord-params\fR last_session_start,next_writeable_address +Alias of -C. +.TP +.B Settings for file insertion: +.TP +\fB\-path-list\fR disk_path +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. +.TP +\fB--quoted_path_list\fR disk_path +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. +.br +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. +.TP +\fB\-f\fR +Resolve symbolic links on disk rather than storing them as symbolic +links in the ISO image. +.TP +\fB\-follow-links\fR +Alias of -f. +.TP +\fB\-graft-points\fR +Enable interpretation of input file pathspecs as combination of iso_rr_path +and disk_path, separated by a =-character. +.TP +\fB\-m\fR disk_pattern +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. +.br +It is possible to give more than one -m option. +.TP +\fB\-exclude\fR +Alias of -m. +.TP +\fB\-x\fR +Alias of -m. +.TP +\fB\-old-exclude\fR +Alias of -m. +.TP +\fB\-exclude-list\fR disk_path +Perform -m using each line out of file disk_path as argument disk_pattern. +.TP +\fB\-z\fR +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. +.TP +\fB\-transparent-compression\fR +Alias of -z. +.TP +\fB\-root\fR iso_rr_path +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. +.br +The default for -root is "/". +.TP +\fB\-old-root\fR iso_rr_path +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. +.br +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. +.TP +\fB--old-root-no-ino\fR +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. +.br +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 --old-root-devno +or disable the inode number shortcut by --old-root-no-ino. +.TP +\fB--old-root-devno\fR +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. +.TP +\fB--old-root-no-md5\fR +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. +.TP +.B Settings for image production: +.TP +\fB\-o\fR disk_path +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. +.br +Default is stdout which may also be set by disk_path "-". +.TP +\fB\-output\fR disk_path +Alias of -o. +.TP +\fB--stdio_sync\fR "on"|"off"|number +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". +.br +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. +.TP +\fB--emul-toc\fR +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. +.br +The price is 64 KiB extra space consumption. If -partition_offset is non-zero, +then it is 128 KiB plus twice the partition setup. +.TP +\fB--no-emul-toc\fR +Do not write a second superblock with the first session into random-access +files. +.br +This is the default. +.TP +\fB--sort-weight\fR weight_number iso_rr_path +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. +.br +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. +.TP +\fB\-dir-mode\fR 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 +.TP +\fB\-file-mode\fR mode +Like -dir-mode but for all regular data files in the image. +.TP +\fB\-pad\fR +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. +.br +Option -pad is the default. +.TP +\fB\-no-pad\fR +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. +.TP +\fB--old-empty\fR +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. +.TP +.B Settings for standards compliance: +.TP +\fB\-iso-level\fR number +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: +.br +Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB - 1. +.br +Level 2 allows ISO names with up to 32 characters +and file size up to 4 GiB - 1. +.br +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.) +.br +Pseudo-level 4 enables production of an additional ISO 9660:1999 +directory tree. +.TP +\fB\-disallow_dir_id_ext\fR +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. +.TP +\fB\-U\fR +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. +.br +This all violates ISO 9660 specs. +.TP +\fB\-untranslated-filenames\fR +Alias of -U. +\fB\-untranslated_name_len\fR number +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. +.br +This violates ISO 9660 specs. +.TP +\fB\-allow-lowercase\fR +Allow lowercase character in ISO file names. +.br +This violates ISO 9660 specs. +.TP +\fB\-d\fR +Do not add trailing dot to ISO file names without dot. +.br +This violates ISO 9660 specs. +.TP +\fB\-omit-period\fR +Alias of -d. +.TP +\fB\-l\fR +Allow up to 37 characters in ISO file names. +.br +This violates ISO 9660 specs. +.TP +\fB\-full-iso9660-filenames\fR +Alias of -l. +.TP +\fB\-max-iso9660-filenames\fR +Alias of -l. +.TP +\fB\-N\fR +Omit the semicolon and the version numbers at the end of ISO names. +.br +This violates ISO 9660 specs. +.TP +\fB\-omit-version-number\fR +Alias of -N. +.TP +.B Settings for standards extensions: +.TP +\fB\-R\fR +With mkisofs this option enables Rock Ridge extensions. xorrisofs produces +them unconditionally. +.TP +\fB\-rock\fR +Alias of -R. +.TP +\fB\-r\fR +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. +.TP +\fB\-rational-rock\fR +Alias of -r. +.TP +\fB--for_backup\fR +Enable options which improve backup fidelity: +--acl, --xattr, --md5, +--hardlinks. +.TP +\fB--acl\fR +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. +.TP +\fB--xattr\fR +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. +.TP +\fB--md5\fR +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: +.br + -find / -exec get_md5 +.TP +\fB--hardlinks\fR +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. +.br +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. +.TP +\fB--scdbackup_tag\fR disk_path record_name +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. +.br +Program scdbackup_verify will recognize and verify tag resp. record. +.TP +\fB\-J\fR +Enable the production of an additional Joliet directory tree along +with the ISO 9660 Rock Ridge tree. +.TP +\fB\-joliet\fR +Alias of -J. +.TP +\fB\-joliet-long\fR +Currently this option is insufficiently implemented. +It should allow 103 characters in Joliet file names but +yet only 64 are possible. +.TP +.B Settings for file hiding: +.TP +\fB\-hide\fR disk_path_pattern +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. +.br +This command does not apply to the boot catalog. +.TP +\fB\-hide-list\fR disk_path +Perform -hide using each line out of file disk_path as argument +disk_path_pattern. +.TP +\fB\-hide-joliet\fR disk_path_pattern +Like option -hide but making files invisible in the directory tree of Joliet, +if their disk_path matches the given shell parser pattern. +.TP +\fB\-hide-joliet-list\fR disk_path +Perform -hide-joliet using each line out of file disk_path as argument +disk_path_pattern. +.TP +.B ISO image ID strings: +.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. +.TP +\fB\-V\fR text +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: +.br +Conformant are ASCII characters out of [A-Z0-9_]. Like: "IMAGE_23" +.br +Joliet allows 16 UCS-2 characters. Like: "Windows name" +.br +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. +.TP +\fB\-volid\fR text +Alias of -V. +.TP +\fB\-volset\fR text +Set the Volume Set Id of the ISO image. +Permissible are up to 128 characters. +.TP +\fB\-p\fR text +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. +.TP +\fB\-publisher\fR text +Alias of -p. +.TP +\fB\-A\fR text +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. +.br +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. +.TP +\fB\-appid\fR text +Alias of -A. +.TP +\fB\-sysid\fR text +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. +.TP +\fB\-p\fR text +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. +.br +The special text "@xorriso@" gets converted to the id string of xorriso +which is default at program startup. +.TP +\fB\-preparer\fR text +Alias of -p. +.TP +\fB\-abstract\fR iso_path +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. +.TP +\fB\-biblio\fR iso_path +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. +.TP +\fB\-copyright\fR iso_path +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. +.TP +\fB--modification-date=YYYYMMDDhhmmsscc\fR +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: +.br + search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc +.br +E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds). +.TP +.B El Torito Bootable ISO images: +.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. +.br +.PP +An \fBEl Torito\fR +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. +.br +xorriso composes the boot catalog according to the boot image +files given and structured by options -b, -e, -el-torito-alt-boot, +and --efi-boot. Often it contains only one entry. +.br +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. +.br +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. +.br +.PP +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. +.br +.TP +\fB\-b\fR iso_rr_path +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. +.br +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. +.TP +\fB\-eltorito-boot\fR iso_rr_path +Alias of -b. +.TP +\fB\-eltorito-alt-boot\fR +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. +.TP +\fB\-e\fR iso_rr_path +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. +.br +Normally no other El Torito options should be used with the catalog entry +that points to an EFI image. +Consider to use --efi-boot rather than -e. +.TP +\fB--efi-boot\fR iso_rr_path +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. +.TP +\fB\-boot-load-size\fR number +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. +.TP +\fB\-hard-disk-boot\fR +Mark the boot image in the current catalog entry as emulated hard disk. +(Not suitable for any known boot loader.) +.TP +\fB\-no-emul-boot\fR +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.) +.br +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.) +.TP +\fB\-boot-info-table\fR +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. +.TP +\fB\-c\fR iso_rr_path +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. +.TP +\fB\-eltorito-catalog\fR iso_rr_path +Alias of -c. +.TP +\fB--boot-catalog-hide\fR +Prevent the El Torito boot catalog from appearing as file +in the directory trees of the image. +.TP +.B System Area, MBR, other boot blocks: +.PP +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. +.br +A \fBMBR\fR (Master Boot Record) contains boot code and a partition table. +It does not hamper El Torito booting from CDROM. +.br +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. +.br +.TP +\fB\-G\fR disk_path +Copy at most 32768 bytes from the given disk file to the very start of +the ISO image. +.br +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. +.TP +\fB\-generic-boot\fR disk_path +Alias of -G. +.TP +\fB--embedded-boot\fR disk_path +Alias of -G. +.TP +\fB\-isohybrid-mbr\fR disk_path +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. +.br +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. +.TP +\fB--protective-msdos-label\fR +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. +.TP +\fB\-partition_offset\fR 2kb_block_adr +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. +.br +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. +.TP +\fB\-partition_hd_cyl\fR number +Set the number of heads per cylinder for the partition table. +0 chooses a default value. Maximum is 255. +.TP +\fB\-partition_sec_hd\fR number +Set the number of sectors per head for the partition table. +0 chooses a default value. Maximum is 63. +.br +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. +.TP +\fB\-partition_cyl_align\fR mode +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. +.br +Mode "auto" is default. Alignment by padding happens only if +option -isohybrid-mbr is given. +.br +Mode "on" causes alignment by padding with option +--protective-msdos-label too. +Mode "off" disables alignment unconditionally. +.TP +\fB\-append_partition\fR partition_number type_code disk_path +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. +.br +Beware of subsequent multi-session runs. The appended partition will get +overwritten. +.br +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. +.br +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". +.TP +\fB\-mips-boot\fR iso_rr_path +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. +.TP +\fB\-mipsel-boot\fR iso_rr_path +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. +.TP +\fB\-B\fR disk_path[,disk_path ...] +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. +.br +The disk files should contain suitable boot images for SUN SPARC systems. +.br +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. +.TP +\fB\-sparc-boot\fR disk_path[,disk_path ...] +Alias of -B. +.TP +\fB\-sparc-label\fR text +Set the ASCII label text of a SUN Disk Label. +.TP +.B Character sets: +.PP +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. +.br +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. +.br +.TP +\fB\-input-charset\fR character_set_name +Set the character set from which to convert disk file names when +inserting them into the ISO image. +.TP +\fB\-output-charset\fR character_set_name +Set the character set from which to convert names of loaded ISO images +and to which to convert names when writing ISO images. +.TP +.B Jigdo Template Extraction: +.PP +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." +.br +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. +.br +One may determine the ability for Jigdo by: +.br + $ xorrisofs -version 2>&1 | grep '^libjte' && echo YES +.br +.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. +.br +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: +.br +MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks, +symbolic file address +.br +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. +.br +If the list of jigdo parameters is not empty, then eventual padding will be +counted as part of the ISO image. +.br +.TP +\fB\-jigdo-jigdo\fR disk_path +Set the disk_path for the .jigdo file with the checksums +and download addresses for filling the holes in .template. +.TP +\fB\-jigdo-template\fR disk_path +Set the disk_path for the .template file with the +holed and compressed ISO image copy. +.TP +\fB\-jigdo-min-file-size\fR 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). +.TP +\fB\-jigdo-force-md5\fR disk_path_pattern +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. +.TP +\fB\-jigdo-exclude\fR disk_path_pattern +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. +.TP +\fB\-jigdo-map\fR To=From +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. +.TP +\fB\-md5-list\fR disk_path +Set the disk_path where to find the .md5 input file. +.TP +\fB\-jigdo-template-compress\fR "gzip"|"bzip2" +Choose one of "bzip2" or "gzip" for the compression of +the template file. The jigdo file is put out uncompressed. +.TP +\fB\-checksum_algorithm_iso\fR list_of_names +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. +.TP +\fB\-checksum_algorithm_template\fR list_of_names +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. +.TP +.B Miscellaneous options: +.TP +\fB\-print-size\fR +Print to stdandard output the foreseeable number of 2048 byte blocks in +the emerging ISO image. Do not produce this image. +.br +The result depends on several settings. +.br +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. +.TP +\fB--no_rc\fR +Only if used as first argument this option +prevents reading and interpretation of eventual startup +files. See section FILES below. +.TP +\fB\-help\fR +List supported options to stderr. Original mkisofs options bear their +original mkisofs description texts. +.TP +\fB\-quiet\fR +Suppress most messages of the program run, except those which indicate +problems or errors. +.TP +\fB\-v\fR +Enable the output of informational program messages. +.TP +\fB\-verbose\fR +Alias of -v. +.TP +\fB\-version\fR +Print to standard output a text that begins with +.br + "mkisofs 2.01-Emulation Copyright (C)" +.br +and to standard error the version information of xorriso. +.br +.SH EXAMPLES +.SS +.B Overview of examples: +A simple image production run +.br +Set ISO image paths by -graft-points +.br +Perform multi-session runs +.br +Let xorrisofs work underneath growisofs +.br +Incremental backup of a few directory trees +.br +Incremental backup with accumulated trees +.br +Create bootable images for PC-BIOS +.br +.SS +.B 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. +.br + $ xorrisofs -r -J -o ./image.iso ./for_iso +.SS +.B 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. +.br + $ xorrisofs ... /home/me/datafile /tmp/directory +.br +yields in the ISO image root directory: +.br + /datafile +.br + /file_1_from_directory +.br + ... +.br + /file_N_from_directory +.br +.sp 1 +With option -graft-points it is possible to put files and directories to +arbitrary paths in the ISO image. +.br + $ xorrisofs ... -graft-points /home/me/datafile /dir=/tmp/directory +.br +yields in the ISO image root directory: +.br + /datafile +.br + /dir +.br +Eventually needed parent directories in +the image will be created automatically: +.br + /datafiles/file1=/home/me/datafile +.br +yields in the ISO image +.br + /datafiles/file1 +.br +The attributes of directory /datafiles get copied from /home/me on disk. +.br +.sp 1 +Normally one should avoid = and \\ characters in the ISO part of a pathspec. +But if it must be, one may escape them: +.br + /with_\\=_and_\\\\/file=/tmp/directory/file +.br +yields in the ISO image +.br + /with_=_and_\\/file +.SS +.B Perform multi-session runs +The first session is written like this: +.br + $ xorrisofs -graft-points \\ +.br + /tree1=prepared_for_iso/tree1 \\ +.br + | xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - +.br +Follow-up sessions are written like this: +.br + $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) +.br + $ xorrisofs -M /dev/sr0 -C $m -graft-points \\ +.br + /tree2/=prepared_for_iso/tree2 \\ +.br + | xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject - +.br +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. +.br +This example works for multi-session media only. +Add cdrskin option --grow_overwriteable_iso +to all -as cdrecord runs +in order to enable multi-session emulation on overwriteable media. +.SS +.B Let xorrisofs 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. +.br + $ export MKISOFS="xorrisofs" +.br + $ growisofs -Z /dev/dvd /some/files +.br + $ growisofs -M /dev/dvd /more/files +.br +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: +.br + $ ln -s $(which xorriso) "$HOME/xorrisofs" +.br + $ export MKISOFS="$HOME/xorrisofs" +.br +One may quit mkisofs emulation by argument "--" and make +use of all xorriso commands. growisofs dislikes options which +start with "-o" but -outdev must be set to "-". +So use "outdev" instead: +.br + $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files +.br + $ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files +.SS +.B 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. +.br +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. +.br +.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. +.br + $ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) +.br + $ load_opts= +.br + $ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo" +.br + $ xorrisofs $load_opts -o - --for_backup -m '*.o' -m '*.swp' \\ +.br + -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\ +.br + -old-root / \\ +.br + /projects=/home/thomas/projects \\ +.br + /personal_mail=/home/thomas/personal_mail \\ +.br + | xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject - +.br +.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. +.br +.sp 1 +\fBBetter do not use your youngest backup for -old-root\fR. +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. +.br +.sp 1 +If inode numbers on disk are not persistent, then use +option --old-root-no-ino . +In this case an update run will compare recorded MD5 +sums against the current file content on hard disk. +.br +.sp 1 +With \fBmount\fR option \fB\-o "sbsector="\fR on GNU/Linux +resp. \fB\-s\fR 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=". +.br +Multi-session media and most overwriteable media written by xorriso can tell +the sbsectors of their sessions by xorriso option -toc: +.br + $ xorriso -dev /dev/sr0 -toc +.br +xorriso can print the matching mount command for a session number: +.br + $ xorriso -mount_cmd /dev/sr0 session 12 /mnt +.br +or for a volume id that matches a search expression: +.br + $ xorriso -mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt +.br +Both yield on standard output something like: +.br + mount -t iso9660 -o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0' '/mnt' +.br +The superuser may let xorriso execute the mount command directly: +.br + # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt +.SS +.B 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. +.br +This demands to know the previously used session directory name. +.br +With the first session: +.br + $ xorrisofs -root /session1 \\ +.br + -o - --for_backup -m '*.o' -m '*.swp' \\ +.br + -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\ +.br + /projects=/home/thomas/projects \\ +.br + /personal_mail=/home/thomas/personal_mail \\ +.br + | xorriso -as cdrecord dev=/dev/sr0 -v blank=as_needed \\ +.br + -multi -waiti -eject - +.br +.sp 1 +With the second session, option -old-root refers to /session1 and the +new -root is /session2: +.br + $ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) +.br + $ load_opts= +.br + $ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo" +.br + $ xorrisofs $load_opts -root /session2 -old-root /session1 \\ +.br + -o - --for_backup -m '*.o' -m '*.swp' \\ +.br + -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\ +.br + /projects=/home/thomas/projects \\ +.br + /personal_mail=/home/thomas/personal_mail \\ +.br + | xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject - +.br +With the third session, option -old-root refers to /session2. +The new -root is /session3. And so on. +.SS +.B 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. +.br +The prescribed mkisofs options can be used unchanged with xorrisofs: +.br + $ xorrisofs -o output.iso \\ +.br + -b isolinux/isolinux.bin -c isolinux/boot.cat \\ +.br + -no-emul-boot -boot-load-size 4 -boot-info-table \\ +.br + ./CD_root +.br +.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 . +.br +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. +.br +The image from the following example will be prepared for booting via MBR +and its first parttion will start at hard disk block 64. +.br + $ xorrisofs -o output.iso \\ + -b isolinux/isolinux.bin -c isolinux/boot.cat \\ + -no-emul-boot -boot-load-size 4 -boot-info-table \\ +.br + -isohybrid-mbr /usr/lib/syslinux/isohdpfx.bin \\ +.br + -partition_offset 16 \\ +.br + ./CD_root +.br +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. +.br +CAUTION: +This will overwrite any eventual partitioning on the USB stick and make +remaining data unaccessible. +.br +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: +.br + # dd bs=2K if=/dev/sdb count=50K >/dev/null +.br +Now copy the image onto it +.br + # dd bs=2K if=output.iso of=/dev/sdb +.br +.SH FILES +.SS +.B Startup files: +.br +If not --no_rc is given as the first argument then xorrisofs +attempts on startup to read and execute lines from the following files: +.br + /etc/default/xorriso +.br + /etc/opt/xorriso/rc +.br + /etc/xorriso/xorriso.conf +.br + $HOME/.xorrisorc +.br +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. +.PP +After the xorriso startup files, the program tries one by one to open for +reading: +.br + ./.mkisofsrc +.br + $MKISOFSRC +.br + $HOME/.mkisofsrc +.br + $(dirname $0)/.mkisofsrc +.br +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. +.br +The reader currently interprets the following NAME=VALUE pairs: +.br + APPI default for -A +.br + PUBL default for -publisher +.br + SYSI default for -sysid +.br + VOLI default for -V +.br + VOLS default for -volset +.br +Any other lines will be silently ignored. +.br +.SH SEE ALSO +.TP +For generic xorriso command mode +.BR xorriso(1) +.TP +For mounting xorriso generated ISO 9660 images (-t iso9660) +.BR mount(8) +.TP +Other programs which produce ISO 9660 images +.BR mkisofs(8), +.BR genisoimage(8) +.TP +Programs which burn sessions to optical media +.BR growisofs(1), +.BR cdrecord(1), +.BR wodim(1), +.BR cdrskin(1), +.BR xorriso(1) +.TP +ACL and xattr +.BR getfacl(1), +.BR setfacl(1), +.BR getfattr(1), +.BR setfattr(1) +.TP +MD5 checksums +.BR md5sum(1) +.SH AUTHOR +Thomas Schmitt +.br +for libburnia-project.org +.SH COPYRIGHT +Copyright (c) 2011 Thomas Schmitt +.br +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. +.SH CREDITS +xorrisofs is in part based on work by Vreixo Formoso who provides libisofs +together with Mario Danic who also leads the libburnia team. +.br +Compliments towards Joerg Schilling whose cdrtools served me for ten years. diff --git a/libisoburn/trunk/xorriso/xorrisofs.info b/libisoburn/trunk/xorriso/xorrisofs.info new file mode 100644 index 00000000..cb88b933 --- /dev/null +++ b/libisoburn/trunk/xorriso/xorrisofs.info @@ -0,0 +1,1762 @@ +This is xorrisofs.info, produced by makeinfo version 4.8 from +./xorrisofs.texi. + +INFO-DIR-SECTION Archiving +START-INFO-DIR-ENTRY +* Xorrisofs: (xorrisofs). Emulates ISO 9660 program mkisofs +END-INFO-DIR-ENTRY + xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso + + Copyright (C) 2011 - 2011 Thomas Schmitt + + Permission is granted to distrubute this text freely. + + +File: xorrisofs.info, Node: Top, Next: Overview, Up: (dir) + +xorrisofs +********* + +xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso, + +* Menu: + +* Overview:: Overview +* Xorriso:: Relation to program xorriso +* Standards:: ISO 9660, Rock Ridge, Joliet +* Insert:: Inserting files into the ISO image +* Options:: Options +* Examples:: Examples +* Files:: Files +* Seealso:: See also +* Legal:: Author, Copyright, Credits +* CommandIdx:: Alphabetic Command List +* ConceptIdx:: Alphabetic List of Concepts and Objects + + +File: xorrisofs.info, Node: Overview, Next: Xorriso, Prev: Top, Up: Top + +1 Overview +********** + +*xorrisofs* produces Rock Ridge enhanced ISO 9660 filesystems and +add-on sessions to such filesystems. Optionally it can produce Joliet +directory trees too. 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. + + +File: xorrisofs.info, Node: Xorriso, Next: Standards, Prev: Overview, Up: Top + +2 Relation to program xorriso +***************************** + +xorrisofs is actually a command mode of program *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 "--" which leads to generic +xorriso command mode. See *man xorriso* for its description. + +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 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. + + +File: xorrisofs.info, Node: Standards, Next: Insert, Prev: Xorriso, Up: Top + +3 ISO 9660, Rock Ridge, Joliet +****************************** + +*ISO 9660* (aka *ECMA-119*) describes directories and data files with +very restricted filenames with no distinction of upper case and lower +case. Its metadata do not comply to fundamental POSIX specifications. +*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. +*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. +*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. + + +File: xorrisofs.info, Node: Insert, Next: Options, Prev: Standards, Up: Top + +4 Inserting files into the ISO image +************************************ + +xorrisofs deals with two kinds of file addresses: +*disk_path* is a path to an object in the local filesystem tree. +*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.) + +A program argument is handled as a *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 +*target*, the iso_rr_path for the file object in the ISO image. The +part after the first = is taken as *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. + +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. + + +File: xorrisofs.info, Node: Options, Next: Examples, Prev: Insert, Up: Top + +5 Options +********* + +* 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 + + +File: xorrisofs.info, Node: Loading, Next: SetInsert, Prev: Options, Up: Options + +5.1 Influencing the behavior of image loading +============================================= + +The following options control loading of an existing ISO image for the +purpose of preparing a suitable add-on session. + +-M disk_path + 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. + +-prev-session disk_path + Alias of -M. + +-dev disk_path + Alias of -M. + +-C last_session_start,next_writeable_address + 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. + +-cdrecord-params last_session_start,next_writeable_address + Alias of -C. + + +File: xorrisofs.info, Node: SetInsert, Next: SetProduct, Prev: Loading, Up: Options + +5.2 Settings for file insertion +=============================== + + +-path-list disk_path + 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. + +--quoted_path_list disk_path + 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. + +-f + Resolve symbolic links on disk rather than storing them as symbolic + links in the ISO image. + +-follow-links + Alias of -f. + +-graft-points + Enable interpretation of input file pathspecs as combination of + iso_rr_path and disk_path, separated by a =-character. + +-m disk_pattern + 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. + +-exclude + Alias of -m. + +-x + Alias of -m. + +-old-exclude + Alias of -m. + +-exclude-list disk_path + Perform -m using each line out of file disk_path as argument + disk_pattern. + +-z + 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. + +-transparent-compression + Alias of -z. + +-root iso_rr_path + 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 "/". + +-old-root iso_rr_path + 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. + +--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 + --old-root-devno or disable the inode number shortcut by + --old-root-no-ino. + +--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. + +--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. + + +File: xorrisofs.info, Node: SetProduct, Next: SetCompl, Prev: SetInsert, Up: Options + +5.3 Settings for image production +================================= + + +-o disk_path + 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. + Default is stdout which may also be set by disk_path "-". + +-output disk_path + Alias of -o. + +--stdio_sync "on"|"off"|number + 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. + +--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. + +--no-emul-toc + Do not write a second superblock with the first session into + random-access files. + This is the default. + +--sort-weight weight_number iso_rr_path + 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. + +-dir-mode 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 + +-file-mode mode + Like -dir-mode but for all regular data files in the image. + +-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. + +-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. + +--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. + + +File: xorrisofs.info, Node: SetCompl, Next: SetExtras, Prev: SetProduct, Up: Options + +5.4 Settings for standards compliance +===================================== + + +-iso-level number + 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. + +-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. + +-U + 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. + +-untranslated-filenames + Alias of -U. + +-untranslated_name_len number + 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. + +-allow-lowercase + Allow lowercase character in ISO file names. + This violates ISO 9660 specs. + +-d + Do not add trailing dot to ISO file names without dot. + This violates ISO 9660 specs. + +-omit-period + Alias of -d. + +-l + Allow up to 37 characters in ISO file names. + This violates ISO 9660 specs. + +-full-iso9660-filenames + Alias of -l. + +-max-iso9660-filenames + Alias of -l. + +-N + Omit the semicolon and the version numbers at the end of ISO names. + This violates ISO 9660 specs. + +-omit-version-number + Alias of -N. + + +File: xorrisofs.info, Node: SetExtras, Next: SetHide, Prev: SetCompl, Up: Options + +5.5 Settings for standards extensions +===================================== + + +-R + With mkisofs this option enables Rock Ridge extensions. xorrisofs + produces them unconditionally. + +-rock + Alias of -R. + +-r + 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. + +-rational-rock + Alias of -r. + +--for_backup + Enable options which improve backup fidelity: --acl, --xattr, + --md5, --hardlinks. + +--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. + +--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. + +--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 + +--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. + +--scdbackup_tag disk_path record_name + 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. + +-J + Enable the production of an additional Joliet directory tree along + with the ISO 9660 Rock Ridge tree. + +-joliet + Alias of -J. + +-joliet-long + Currently this option is insufficiently implemented. It should + allow 103 characters in Joliet file names but yet only 64 are + possible. + + +File: xorrisofs.info, Node: SetHide, Next: ImageId, Prev: SetExtras, Up: Options + +5.6 Settings for file hiding +============================ + + +-hide disk_path_pattern + 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. + +-hide-list disk_path + Perform -hide using each line out of file disk_path as argument + disk_path_pattern. + +-hide-joliet disk_path_pattern + Like option -hide but making files invisible in the directory tree + of Joliet, if their disk_path matches the given shell parser + pattern. + +-hide-joliet-list disk_path + Perform -hide-joliet using each line out of file disk_path as + argument disk_path_pattern. + + +File: xorrisofs.info, Node: ImageId, Next: Bootable, Prev: SetHide, Up: Options + +5.7 ISO image ID strings +======================== + +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. + +-V text + 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. + +-volid text + Alias of -V. + +-volset text + Set the Volume Set Id of the ISO image. Permissible are up to 128 + characters. + +-p text + 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. + +-publisher text + Alias of -p. + +-A text + 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. + +-appid text + Alias of -A. + +-sysid text + 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. + +-p text + 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. + +-preparer text + Alias of -p. + +-abstract iso_path + 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. + +-biblio iso_path + 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. + +-copyright iso_path + 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. + +--modification-date=YYYYMMDDhhmmsscc + 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 --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc + E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds). + + +File: xorrisofs.info, Node: Bootable, Next: SystemArea, Prev: ImageId, Up: Options + +5.8 El Torito Bootable ISO images +================================= + +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. + +An *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 +--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. + +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. + +-b iso_rr_path + 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. + +-eltorito-boot iso_rr_path + Alias of -b. + +-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. + +-e iso_rr_path + 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 + --efi-boot rather than -e. + +--efi-boot iso_rr_path + 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. + +-boot-load-size number + 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. + +-hard-disk-boot + Mark the boot image in the current catalog entry as emulated hard + disk. (Not suitable for any known boot loader.) + +-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.) + +-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 iso_rr_path + 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. + +-eltorito-catalog iso_rr_path + Alias of -c. + +--boot-catalog-hide + Prevent the El Torito boot catalog from appearing as file in the + directory trees of the image. + + +File: xorrisofs.info, Node: SystemArea, Next: Charset, Prev: Bootable, Up: Options + +5.9 System Area, MBR, other boot blocks +======================================= + +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. +A *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. + +-G disk_path + 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. + +-generic-boot disk_path + Alias of -G. + +--embedded-boot disk_path + Alias of -G. + +-isohybrid-mbr disk_path + 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. + +--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. + +-partition_offset 2kb_block_adr + 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. + +-partition_hd_cyl number + Set the number of heads per cylinder for the partition table. 0 + chooses a default value. Maximum is 255. + +-partition_sec_hd number + 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. + +-partition_cyl_align mode + 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 + --protective-msdos-label too. Mode "off" disables alignment + unconditionally. + +-append_partition partition_number type_code disk_path + 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". + +-mips-boot iso_rr_path + 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. + +-mipsel-boot iso_rr_path + 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. + +-B disk_path[,disk_path ...] + 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. + +-sparc-boot disk_path[,disk_path ...] + Alias of -B. + +-sparc-label text + Set the ASCII label text of a SUN Disk Label. + + +File: xorrisofs.info, Node: Charset, Next: Jigdo, Prev: SystemArea, Up: Options + +5.10 Character sets +=================== + +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. + +-input-charset character_set_name + Set the character set from which to convert disk file names when + inserting them into the ISO image. + +-output-charset character_set_name + Set the character set from which to convert names of loaded ISO + images and to which to convert names when writing ISO images. + + +File: xorrisofs.info, Node: Jigdo, Next: Miscellaneous, Prev: Charset, Up: Options + +5.11 Jigdo Template Extraction +============================== + +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: + +$ xorrisofs -version 2>&1 | grep '^libjte' && echo YES + +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. + +-jigdo-jigdo disk_path + Set the disk_path for the .jigdo file with the checksums and + download addresses for filling the holes in .template. + +-jigdo-template disk_path + Set the disk_path for the .template file with the holed and + compressed ISO image copy. + +-jigdo-min-file-size 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). + +-jigdo-force-md5 disk_path_pattern + 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. + +-jigdo-exclude disk_path_pattern + 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. + +-jigdo-map To=From + 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. + +-md5-list disk_path + Set the disk_path where to find the .md5 input file. + +-jigdo-template-compress "gzip"|"bzip2" + Choose one of "bzip2" or "gzip" for the compression of the + template file. The jigdo file is put out uncompressed. + +-checksum_algorithm_iso list_of_names + 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. + +-checksum_algorithm_template list_of_names + 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. + + +File: xorrisofs.info, Node: Miscellaneous, Next: ExSimple, Prev: Jigdo, Up: Options + +5.12 Miscellaneous options +========================== + + +-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. + +--no_rc + Only if used as first argument this option prevents reading and + interpretation of eventual startup files. See section FILES below. + +-help + List supported options to stderr. Original mkisofs options bear + their original mkisofs description texts. + +-quiet + Suppress most messages of the program run, except those which + indicate problems or errors. + +-v + Enable the output of informational program messages. + +-verbose + Alias of -v. + +-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. + + +File: xorrisofs.info, Node: Examples, Next: Files, Prev: Options, Up: Top + +6 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 + + +File: xorrisofs.info, Node: ExSimple, Next: ExGraft, Prev: Miscellaneous, Up: Examples + +6.1 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. + +$ xorrisofs -r -J -o ./image.iso ./for_iso + + +File: xorrisofs.info, Node: ExGraft, Next: ExMkisofs, Prev: ExSimple, Up: Examples + +6.2 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. + +$ xorrisofs ... /home/me/datafile /tmp/directory + +yields in the ISO image root directory: + +/datafile +/file_1_from_directory +... +/file_N_from_directory + +With option -graft-points it is possible to put files and directories to +arbitrary paths in the ISO image. + +$ xorrisofs ... -graft-points /home/me/datafile /dir=/tmp/directory + +yields in the ISO image root directory: + +/datafile +/dir + +Eventually needed parent directories in the image will be created +automatically: + +/datafiles/file1=/home/me/datafile + +yields in the ISO image + +/datafiles/file1 + +The attributes of directory /datafiles get copied from /home/me on disk. + +Normally one should avoid = and \ characters in the ISO part of a +pathspec. But if it must be, one may escape them: + +/with_\=_and_\\/file=/tmp/directory/file + +yields in the ISO image + +/with_=_and_\/file + + +File: xorrisofs.info, Node: ExMkisofs, Next: ExGrowisofs, Prev: ExGraft, Up: Examples + +6.3 Perform multi-session runs +============================== + +The first session is written like this: + +$ xorrisofs -graft-points \ +/tree1=prepared_for_iso/tree1 \ +| xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - + +Follow-up sessions are written like this: + +$ 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 - + +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. + +This example works for multi-session media only. Add cdrskin option +--grow_overwriteable_iso to all -as cdrecord runs in order to enable +multi-session emulation on overwriteable media. + + +File: xorrisofs.info, Node: ExGrowisofs, Next: ExIncBackup, Prev: ExMkisofs, Up: Examples + +6.4 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. + +$ export MKISOFS="xorrisofs" +$ growisofs -Z /dev/dvd /some/files +$ growisofs -M /dev/dvd /more/files + +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: + +$ ln -s $(which xorriso) "$HOME/xorrisofs" +$ export MKISOFS="$HOME/xorrisofs" + +One may quit mkisofs emulation by argument "--" and make use of all +xorriso commands. growisofs dislikes options which start with "-o" but +-outdev must be set to "-". So use "outdev" instead: + +$ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files +$ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files + + +File: xorrisofs.info, Node: ExIncBackup, Next: ExIncBckAcc, Prev: ExGrowisofs, Up: Examples + +6.5 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. + +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. + +$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) +$ load_opts= +$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo" +$ xorrisofs $load_opts -o - --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 - + +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. + +*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. + +If inode numbers on disk are not persistent, then use option +--old-root-no-ino . In this case an update run will compare recorded +MD5 sums against the current file content on hard disk. + +With *mount* option *-o "sbsector="* on GNU/Linux resp. *-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: + +$ xorriso -dev /dev/sr0 -toc + +xorriso can print the matching mount command for a session number: + +$ xorriso -mount_cmd /dev/sr0 session 12 /mnt + +or for a volume id that matches a search expression: + +$ xorriso -mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt + +Both yield on standard output something like: +mount -t iso9660 -o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0' +'/mnt' + +The superuser may let xorriso execute the mount command directly: + +# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt + + +File: xorrisofs.info, Node: ExIncBckAcc, Next: ExBootable, Prev: ExIncBackup, Up: Examples + +6.6 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: + +$ xorrisofs -root /session1 \ +-o - --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 - + +With the second session, option -old-root refers to /session1 and the +new -root is /session2: + +$ 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 - --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 - + +With the third session, option -old-root refers to /session2. The new +-root is /session3. And so on. + + +File: xorrisofs.info, Node: ExBootable, Prev: ExIncBckAcc, Up: Examples + +6.7 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: + +$ xorrisofs -o output.iso \ +-b isolinux/isolinux.bin -c isolinux/boot.cat \ +-no-emul-boot -boot-load-size 4 -boot-info-table \ +./CD_root + +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. + +$ 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 + +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: + +# dd bs=2K if=/dev/sdb count=50K >/dev/null + +Now copy the image onto it + +# dd bs=2K if=output.iso of=/dev/sdb + + +File: xorrisofs.info, Node: Files, Next: Seealso, Prev: Examples, Up: Top + +7 Files +******* + +7.1 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: + +/etc/default/xorriso +/etc/opt/xorriso/rc +/etc/xorriso/xorriso.conf +$HOME/.xorrisorc + +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. After the xorriso +startup files, the program tries one by one to open for reading: + +./.mkisofsrc +$MKISOFSRC +$HOME/.mkisofsrc +$(dirname $0)/.mkisofsrc + +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: + +APPI default for -A +PUBL default for -publisher +SYSI default for -sysid +VOLI default for -V +VOLS default for -volset + +Any other lines will be silently ignored. + +File: xorrisofs.info, Node: Seealso, Next: Legal, Prev: Files, Up: Top + +8 See also +********** + +For generic xorriso command mode + xorriso(1) + +For mounting xorriso generated ISO 9660 images (-t iso9660) + mount(8) + +Other programs which produce ISO 9660 images + mkisofs(8), genisoimage(8) + +Programs which burn sessions to optical media + growisofs(1), cdrecord(1), wodim(1), cdrskin(1), xorriso(1) + +ACL and xattr + getfacl(1), setfacl(1), getfattr(1), setfattr(1) + +MD5 checksums + md5sum(1) + + +File: xorrisofs.info, Node: Legal, Next: CommandIdx, Prev: Seealso, Up: Top + +9 Author, Copyright, Credits +**************************** + +9.1 Author +========== + +Thomas Schmitt +for libburnia-project.org + +9.2 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. + +9.3 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. + + +File: xorrisofs.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top + +10 Alphabetic Command List +************************** + +[index] +* Menu: + +* --acl Recording of ACLs: SetExtras. (line 28) +* --boot-catalog-hide Hide El Torito boot catalog: Bootable. + (line 95) +* --efi-boot El Torito EFI boot image: Bootable. (line 58) +* --embedded-boot Fill System Area e.g. by MBR: SystemArea. (line 27) +* --emul-toc enable table-of-content emulation: SetProduct. (line 29) +* --for_backup Enable backup fidelity: SetExtras. (line 24) +* --hardlinks Recording of hardlink relations: SetExtras. (line 47) +* --md5 Recording of MD5 checksums: SetExtras. (line 39) +* --modification-date set ISO image timestamps: ImageId. (line 82) +* --no-emul-toc no table-of-content emulation: SetProduct. (line 38) +* --no_rc do not execute startup files: Miscellaneous. (line 16) +* --old-empty old block addresses for empty files: SetProduct. + (line 75) +* --old-root-devno enable disk idevno with -old-root: SetInsert. + (line 97) +* --old-root-no-ino disable disk ino with -old-root: SetInsert. + (line 84) +* --old-root-no-md5 disable MD5 with -old-root: SetInsert. (line 105) +* --protective-msdos-label Patch System Area partition table: SystemArea. + (line 41) +* --quoted_path_list read pathspecs from disk file: SetInsert. + (line 13) +* --scdbackup_tag Recording of MD5 checksum: SetExtras. (line 56) +* --sort-weight set output file address: SetProduct. (line 43) +* --stdio_sync control forced output to disk files: SetProduct. + (line 19) +* --xattr Recording of xattr: SetExtras. (line 33) +* -A set Application Id: ImageId. (line 38) +* -abstract set Abstract File path: ImageId. (line 66) +* -allow-lowercase lowercase in ISO file names: SetCompl. (line 46) +* -append_partition Append MBR partition after image: SystemArea. + (line 86) +* -appid set Application Id: ImageId. (line 46) +* -b El Torito PC-BIOS boot image: Bootable. (line 32) +* -B SUN SPARC boot images: SystemArea. (line 117) +* -biblio set Biblio File path: ImageId. (line 72) +* -boot-info-table Patch El Torito boot image: Bootable. (line 80) +* -boot-load-size El Torito boot image load size: Bootable. (line 63) +* -c El Torito boot catalog name: Bootable. (line 86) +* -C set load address and write address offset: Loading. (line 22) +* -cdrecord-params set load address and write address offset: Loading. + (line 37) +* -checksum_algorithm_iso choose .jigdo checksums: Jigdo. (line 80) +* -checksum_algorithm_template choose .template checksums: Jigdo. + (line 87) +* -copyright set Copyright File path: ImageId. (line 77) +* -d omit trailing dot in ISO file names: SetCompl. (line 50) +* -dev set path for loading existing ISO image: Loading. (line 19) +* -dir-mode permissions for all directories: SetProduct. (line 54) +* -disallow_dir_id_ext enforce ISO level 1 directory names: SetCompl. + (line 24) +* -e El Torito EFI boot image: Bootable. (line 50) +* -eltorito-alt-boot begin next boot catalog entry: Bootable. + (line 43) +* -eltorito-boot El Torito PC-BIOS boot image: Bootable. (line 40) +* -eltorito-catalog El Torito boot catalog name: Bootable. (line 92) +* -exclude exclude disk files from inserting: SetInsert. (line 42) +* -exclude-list exclude disk files from inserting: SetInsert. + (line 51) +* -f follow symbolic links on disk: SetInsert. (line 24) +* -file-mode permissions for all data files: SetProduct. (line 60) +* -follow-links follow symbolic links on disk: SetInsert. (line 28) +* -full-iso9660-filenames allow 37 characters in ISO file names: SetCompl. + (line 61) +* -G Fill System Area e.g. by MBR: SystemArea. (line 17) +* -generic-boot Fill System Area e.g. by MBR: SystemArea. (line 24) +* -graft-points enable target=source pathspecs: SetInsert. (line 31) +* -hard-disk-boot El Torito boot image emulation: Bootable. (line 68) +* -help list supported options: Miscellaneous. (line 20) +* -hide keep matching files invisible in ISO tree: SetHide. (line 8) +* -hide-joliet keep matching files invisible in Joliet tree: SetHide. + (line 20) +* -hide-joliet-list keep matching files invisible in Joliet tree: SetHide. + (line 25) +* -hide-list keep matching files invisible in ISO tree: SetHide. + (line 16) +* -input-charset set character set of disk file names: Charset. + (line 17) +* -iso-level define ISO 9660 limitations: SetCompl. (line 7) +* -isohybrid-mbr Install ISOLINUX isohybrid MBR: SystemArea. + (line 30) +* -J enable production of Joliet directory tree: SetExtras. (line 65) +* -jigdo-exclude add exclusion pattern for .md5: Jigdo. (line 59) +* -jigdo-force-md5 add check pattern for .md5: Jigdo. (line 52) +* -jigdo-jigdo set name of .jigdo file: Jigdo. (line 38) +* -jigdo-map add address translation for .jigdo: Jigdo. (line 64) +* -jigdo-min-file-size set minimum extract size: Jigdo. (line 46) +* -jigdo-template set name of .template file: Jigdo. (line 42) +* -jigdo-template-compress choose compression algorithm: Jigdo. + (line 76) +* -joliet enable production of Joliet directory tree: SetExtras. + (line 69) +* -joliet-long allow longer Joliet names: SetExtras. (line 72) +* -l allow 37 characters in ISO file names: SetCompl. (line 57) +* -m exclude disk files from inserting: SetInsert. (line 35) +* -M set path for loading existing ISO image: Loading. (line 10) +* -max-iso9660-filenames allow 37 characters in ISO file names: SetCompl. + (line 64) +* -md5-list set path of readable .md5: Jigdo. (line 73) +* -mips-boot MIPS Big Endian boot image: SystemArea. (line 103) +* -mipsel-boot MIPS Little Endian boot image: SystemArea. (line 111) +* -N omit version number in ISO file names: SetCompl. (line 67) +* -no-emul-boot El Torito boot image emulation: Bootable. (line 72) +* -no-pad do not add zeros to ISO tree: SetProduct. (line 70) +* -o set output file address: SetProduct. (line 8) +* -old-exclude exclude disk files from inserting: SetInsert. + (line 48) +* -old-root enable incremental insertion: SetInsert. (line 70) +* -omit-period omit trailing dot in ISO file names: SetCompl. + (line 54) +* -omit-version-number omit version number in ISO file names: SetCompl. + (line 71) +* -output set output file address: SetProduct. (line 16) +* -output-charset set character set of ISO file names: Charset. + (line 21) +* -p set Preparer Id: ImageId. (line 54) +* -p set Publisher Id: ImageId. (line 30) +* -pad add 300 KiB of zeros to ISO tree: SetProduct. (line 63) +* -partition_cyl_align Image size alignment: SystemArea. (line 75) +* -partition_hd_cyl MBR heads per cylinder: SystemArea. (line 58) +* -partition_offset Make mountable by partition 1: SystemArea. + (line 46) +* -partition_sec_hd MBR sectors per head: SystemArea. (line 62) +* -path-list read pathspecs from disk file: SetInsert. (line 8) +* -preparer set Preparer Id: ImageId. (line 63) +* -prev-session set path for loading existing ISO image: Loading. + (line 16) +* -print-size predict ISO image size: Miscellaneous. (line 8) +* -publisher set Publisher Id: ImageId. (line 35) +* -quiet suppress most messages: Miscellaneous. (line 24) +* -R Rock Ridge (is always enabled): SetExtras. (line 8) +* -r Rock Ridge with altered owner and permission: SetExtras. + (line 15) +* -rational-rock Rock Ridge with altered owner and permission: SetExtras. + (line 21) +* -rock Rock Ridge (is always enabled): SetExtras. (line 12) +* -root redirect ISO root directory: SetInsert. (line 64) +* -sparc-boot SUN SPARC boot images: SystemArea. (line 129) +* -sparc-label SUN Disk Label text: SystemArea. (line 132) +* -sysid set System Id: ImageId. (line 49) +* -transparent-compression enable recognition of zisofs files: SetInsert. + (line 61) +* -U very relaxed filename rules: SetCompl. (line 29) +* -untranslated-filenames very relaxed filename rules: SetCompl. + (line 36) +* -untranslated_name_len untranslated file names: SetCompl. (line 39) +* -v enable verbous messages: Miscellaneous. (line 28) +* -V set Volume Id: ImageId. (line 13) +* -verbose enable verbous messages: Miscellaneous. (line 31) +* -version report program version: Miscellaneous. (line 34) +* -volid set Volume Id: ImageId. (line 23) +* -volset set Volume Set Id: ImageId. (line 26) +* -x exclude disk files from inserting: SetInsert. (line 45) +* -z enable recognition of zisofs files: SetInsert. (line 55) + + +File: xorrisofs.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top + +11 Alphabetic List of Concepts and Objects +****************************************** + +[index] +* Menu: + +* Abstract File, set path, -abstract: ImageId. (line 66) +* ACL, record and load, --acl: SetExtras. (line 28) +* Application Id, set, -A, -appid: ImageId. (line 38) +* Backup, enable fidelity, --for_backup: SetExtras. (line 24) +* Biblio File, set path, -biblio: ImageId. (line 72) +* Block address, set sort weight, --sort-weight: SetProduct. (line 43) +* Bootability, boot catalog hidden, --boot-catalog-hide: Bootable. + (line 95) +* Bootability, boot catalog name, -c, -eltorito-catalog: Bootable. + (line 86) +* Bootability, boot image emulation, -hard-disk-boot: Bootable. + (line 68) +* Bootability, boot image load size, -boot-load-size: Bootable. + (line 63) +* Bootability, boot image patching, -boot-info-table: Bootable. + (line 80) +* Bootability, control, --efi-boot: Bootable. (line 58) +* Bootability, control, -b, -eltorito-boot: Bootable. (line 32) +* Bootability, control, -B, -sparc-boot: SystemArea. (line 117) +* Bootability, control, -e: Bootable. (line 50) +* Bootability, control, -mips-boot: SystemArea. (line 103) +* Bootability, control, -mipsel-boot: SystemArea. (line 111) +* Bootability, fill System Area e.g. by MBR, -G, --embedded-boot, -generic-boot: SystemArea. + (line 17) +* Bootability, install ISOLINUX isohybrid MBR, -isohybrid-mbr: SystemArea. + (line 30) +* Bootability, next entry, -eltorito-alt-boot: Bootable. (line 43) +* Bootability, no boot image emulation, -no-emul-boot: Bootable. + (line 72) +* Bootability, patch System Area partition table, --protective-msdos-label: SystemArea. + (line 41) +* Bootability, SUN Disk Label text, -sparc-label: SystemArea. (line 132) +* Character Set, for disk file names, -input-charset: Charset. + (line 17) +* Character Set, for ISO file names, -output-charset: Charset. + (line 21) +* Character sets, _definition: Charset. (line 6) +* Copyright File, set path, -copyright: ImageId. (line 77) +* Disk files, exclude, -hide-list: SetInsert. (line 51) +* Disk files, exclude, -m, -exclude, -x, -old-exclude: SetInsert. + (line 35) +* disk_path, _definition: Insert. (line 8) +* ECMA-119, _definiton: Standards. (line 6) +* El Torito, _definiton: Bootable. (line 13) +* Examples: Examples. (line 6) +* Forced output, control, --stdio_sync: SetProduct. (line 19) +* Hiding, from ISO and Rock Ridge, -hide: SetHide. (line 8) +* Hiding, from ISO and Rock Ridge, -hide-list: SetHide. (line 16) +* Hiding, from Joliet, -hide-joliet: SetHide. (line 20) +* Hiding, from Joliet, -hide-joliet-list: SetHide. (line 25) +* Image size, alignment, -partition_cyl_align: SystemArea. (line 75) +* Incremental insertion, disable disk ino, --old-root-no-ino: SetInsert. + (line 84) +* Incremental insertion, disable MD5, --old-root-no-md5: SetInsert. + (line 105) +* Incremental insertion, enable disk devno, --old-root-devno: SetInsert. + (line 97) +* Incremental insertion, enable, -old-root: SetInsert. (line 70) +* ISO 9660, _definiton: Standards. (line 6) +* ISO 9660:1999, _definiton: Standards. (line 21) +* ISO file names, allow 37 characters, -l, -full-iso9660-filenames, -max-iso9660-filenames: SetCompl. + (line 57) +* ISO file names, allow lowercase, -allow-lowercase: SetCompl. + (line 46) +* ISO file names, omit trailing dot, -d, -omit-period: SetCompl. + (line 50) +* ISO file names, omit version number, -N, -omit-version-number: SetCompl. + (line 67) +* ISO file names, untranslated, -untranslated_name_len: SetCompl. + (line 39) +* ISO file names, very relaxed rules, -U, -untranslated-filenames: SetCompl. + (line 29) +* ISO image size, predict, -print-size: Miscellaneous. (line 8) +* ISO image, set timestamps, --modification-date=: ImageId. (line 82) +* ISO level 1, enforce directory names, -disallow_dir_id_ext: SetCompl. + (line 24) +* ISO level, specify, -iso-level: SetCompl. (line 7) +* ISO root directory, redirect, -root: SetInsert. (line 64) +* iso_rr_path, _definition: Insert. (line 9) +* Jigdo Template Extraction, -checksum_algorithm_iso: Jigdo. (line 80) +* Jigdo Template Extraction, -checksum_algorithm_template: Jigdo. + (line 87) +* Jigdo Template Extraction, -jigdo-exclude: Jigdo. (line 59) +* Jigdo Template Extraction, -jigdo-force-md5: Jigdo. (line 52) +* Jigdo Template Extraction, -jigdo-jigdo: Jigdo. (line 38) +* Jigdo Template Extraction, -jigdo-map: Jigdo. (line 64) +* Jigdo Template Extraction, -jigdo-min-file-size: Jigdo. (line 46) +* Jigdo Template Extraction, -jigdo-template: Jigdo. (line 42) +* Jigdo Template Extraction, -jigdo-template-compress: Jigdo. (line 76) +* Jigdo Template Extraction, -md5-list: Jigdo. (line 73) +* Jigdo Template Extraction, _definition: Jigdo. (line 6) +* Joliet, _definiton: Standards. (line 16) +* Joliet, allows longer names, -joliet-long: SetExtras. (line 72) +* Joliet, enable, -J, -joliet: SetExtras. (line 65) +* Links, follow on disk, -f, -follow-links: SetInsert. (line 24) +* Links, record and load hard links, --hardlinks: SetExtras. (line 47) +* MBR, _definiton: SystemArea. (line 10) +* MBR, append partition, -append_partition: SystemArea. (line 86) +* MBR, sectors per head, -partition_sec_hd: SystemArea. (line 58) +* MD5, record and load, --md5: SetExtras. (line 39) +* Message output, suppress, -quiet: Miscellaneous. (line 24) +* Mountability, by non-trivial partition 1, -partition_offset: SystemArea. + (line 46) +* Options, list, -help: Miscellaneous. (line 20) +* Output file, set address, -o, -output: SetProduct. (line 8) +* Padding, 300 KiB, -pad: SetProduct. (line 63) +* Padding, disable, --old-empty: SetProduct. (line 75) +* Padding, disable, -no-pad: SetProduct. (line 70) +* pathspec, _definition: Insert. (line 11) +* pathspec, enable target=source, -graft-points: SetInsert. (line 31) +* pathspec, read list of, --quoted_path_list: SetInsert. (line 13) +* pathspec, read list of, -path-list: SetInsert. (line 8) +* Permissions, for all data files, -file-mode: SetProduct. (line 60) +* Permissions, for all directories, -dir-mode: SetProduct. (line 54) +* Preparer Id, set, -p: ImageId. (line 54) +* Program version, report, -version: Miscellaneous. (line 34) +* Publisher Id, set, -p, -publisher: ImageId. (line 30) +* Rock Ridge, (always enabled), -R, -rock: SetExtras. (line 8) +* Rock Ridge, _definiton: Standards. (line 9) +* Rock Ridge, altered owner and permission, -r, -rational-rock: SetExtras. + (line 15) +* scdbackup, record checksum tag, --scdbackup_tag: SetExtras. (line 56) +* Session, select path, -M, -prev-session, -dev: Loading. (line 10) +* Session, set load and write address, -C, -cdrecord-params: Loading. + (line 22) +* Startup files, suppress, --no_rc: Miscellaneous. (line 16) +* System Area, _definiton: SystemArea. (line 6) +* System Id, set, -sysid: ImageId. (line 49) +* Table-of-content, emulation off, --no-emul-toc: SetProduct. (line 38) +* Table-of-content, emulation, --emul-toc: SetProduct. (line 29) +* Verbosity, high, -v, -verbose: Miscellaneous. (line 28) +* Volume Id, set, -V, -volid: ImageId. (line 13) +* Volume Set Id, set, -volset: ImageId. (line 26) +* xattr, record and load, --xattr: SetExtras. (line 33) +* xorriso, mkisofs emulation: Xorriso. (line 6) +* xorriso, options: Options. (line 6) +* zisofs file, enable recognition, -z, -transparent-compression: SetInsert. + (line 55) + + + +Tag Table: +Node: Top397 +Node: Overview1053 +Node: Xorriso1487 +Node: Standards2621 +Node: Insert4024 +Node: Options5445 +Node: Loading6161 +Node: SetInsert7792 +Node: SetProduct12194 +Node: SetCompl15533 +Node: SetExtras17852 +Node: SetHide20580 +Node: ImageId21588 +Node: Bootable25092 +Node: SystemArea29172 +Node: Charset35532 +Node: Jigdo36557 +Node: Miscellaneous40838 +Node: Examples42011 +Node: ExSimple42497 +Node: ExGraft42976 +Node: ExMkisofs44221 +Node: ExGrowisofs45146 +Node: ExIncBackup46127 +Node: ExIncBckAcc49017 +Node: ExBootable50533 +Node: Files52489 +Node: Seealso53559 +Node: Legal54074 +Node: CommandIdx54870 +Node: ConceptIdx66203 + +End Tag Table diff --git a/libisoburn/trunk/xorriso/xorrisofs.texi b/libisoburn/trunk/xorriso/xorrisofs.texi new file mode 100644 index 00000000..328fe4fb --- /dev/null +++ b/libisoburn/trunk/xorriso/xorrisofs.texi @@ -0,0 +1,1962 @@ +\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 05, 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 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 +* Xorriso:: Relation to program xorriso +* Standards:: ISO 9660, Rock Ridge, Joliet +* Insert:: Inserting files into the ISO image +* 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, Xorriso, 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. +@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 Xorriso, Standards, Overview, 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 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 Standards, Insert, Xorriso, 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}) describes directories and data files with +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, Options, 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 Options, Examples, Insert, 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. +@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. +@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. +@* +Default is stdout 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 +@* +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