1
.\" Hey, EMACS: -*- nroff -*-
5
.\" The original of this file is kept in xorriso/xorrisofs.texi
6
.\" This here was generated by program xorriso/make_xorriso_1
9
.\" First parameter, NAME, should be all caps
10
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
11
.\" other parameters are allowed: see man(7), man(1)
12
.TH XORRISOFS 1 "Apr 07, 2011"
13
.\" Please adjust this date whenever revising the manpage.
15
.\" Some roff macros, for reference:
16
.\" .nh disable hyphenation
17
.\" .hy enable hyphenation
18
.\" .ad l left justify
19
.\" .ad b justify to both left and right margins
20
.\" .nf disable filling
21
.\" .fi enable filling
22
.\" .br insert line break
23
.\" .sp <n> insert n+1 empty lines
24
.\" for manpage-specific macros, see man(7)
27
xorrisofs - Emulation of ISO 9660 program mkisofs by program xorriso
30
[ options ] [-o filename ] pathspec [pathspecs ...]
35
produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to
36
such filesystems. Optionally it can produce Joliet directory trees too.
39
xorrisofs understands options of program mkisofs from cdrtools by
41
Its implementation is part of program xorriso which shares no source
44
\fBISO 9660, Rock Ridge, Joliet:\fR
47
(aka \fBECMA-119\fR) is a read-only filesystem that is mainly used for
48
optical media CD, DVD, BD, but may also reside on other storage devices like
49
disk files, USB sticks or disk partitions. It is widely readable by many
50
operating systems and by boot facilities of personal computers.
52
ISO 9660 describes directories and data files by
53
very restricted filenames with no distinction of upper case and lower case.
54
Its metadata do not comply to fundamental POSIX specifications.
57
is the name of a set of additional information which enhance
58
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
59
with ownership, access permissions, symbolic links, and other attributes.
60
Rock Ridge allows filenames of up to 255 bytes and paths of up to
63
Rock Ridge information is produced unconditionally with any xorrisofs image.
66
is the name of an additional directory tree which provides
67
filenames up to 64 characters encoded as UTF-16.
68
A Joliet tree is mainly interesting for reading the ISO image by
69
operating systems of Microsoft Corporation.
70
Production of this directory tree may be enabled by option -J.
73
is the name of an additional directory tree which provides longer
74
filenames. It allows single file names to have up to 207 characters.
75
It might be of use with some older computer system boot
76
facilities which read neither Rock Ridge nor Joliet but
77
need longer filenames nevertheless.
78
Production of this directory tree may be enabled by option -iso-level 4.
80
.B Inserting files into the ISO image:
82
xorrisofs deals with two kinds of file addresses:
85
is a path to an object in the local filesystem tree.
88
is the Rock Ridge address of a file object in the ISO image. (Do not
89
confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.)
92
A program argument is handled as a \fBpathspec\fR, if it is not
93
recognized as original mkisofs option or additional xorrisofs option.
94
A pathspec depicts an input file object by a disk_path.
95
If option -graft-points is not present, then the behavior depends on the
96
file type of disk_path. Directories get merged with the /-directory of the
97
ISO image. Files of other types get copied into the /-directory.
99
If -graft-points is present then each pathspec gets split at the first
100
occurence of the =-character.
101
The part before the = is taken as \fBtarget\fR, i.e. the iso_rr_path for
102
the file object in the ISO image. The part after the first = is taken
103
as \fBsource\fR, i.e. the disk_path of the input object.
105
It is possible to make =-characters part of the iso_rr_path by preceeding
106
them with a \\-character. The same must be done for \\-characters which
107
shall be part of the iso_rr_path.
110
If the source part of the pathspec leads to a directory, then all files
111
underneath this directory get inserted into the image, too.
112
It is possible to exclude particular files from being inserted
113
by help of option -m.
115
In case that target already exists, the following rules apply:
116
Directories and other files may overwrite existing non-directories.
117
Directories get merged with existing directories.
118
Non-directories may not overwrite existing directories.
120
\fBRelation to program xorriso:\fR
122
xorrisofs is actually a command mode of program \fBxorriso\fR,
123
which gets entered either by xorriso command "-as mkisofs" or by
124
starting the program by one of the names "xorrisofs", "mkisofs",
125
"genisoimage", or "genisofs".
127
This command mode can be left by argument "--" which leads
128
to generic xorriso command mode. See \fBman xorriso\fR for its description.
131
xorriso performs image reading and writing by help of libburn, which is
132
mainly intended for optical drives, but also operates on all POSIX
133
file types except directories.
135
The program messages call any image file a "drive". File types which are not
136
supported for reading are reported as "blank". The reported free media
137
space may be quite fictional.
139
Nevertheless xorrisofs does not operate directly on optical drives,
140
but rather forces libburn to regard them as general device files.
141
So for writing of sequential optical media (CD, DVD-R, DVD+R, BD-R)
142
one will have to use a burn program. E.g the cdrecord emulation of xorriso.
152
The following options control loading of an existing ISO image for the purpose
153
of preparing a suitable add-on session.
154
If they are missing then a new image is composed from scratch.
157
Set the path from which to load the existing ISO image directory tree
158
on which to base the upcomming directory tree as add-on session.
159
The path must lead to a random-access readable file object.
160
On GNU/Linux: regular data files or block device files.
162
A special kind of pseudo disk_path has the form "/dev/fd/"number.
163
It depicts the open file descriptor with the given number, regardless whether
164
the operating system supports this feature by file nodes in /dev/fd or not.
165
E.g. /dev/fd/3 is file descriptor 3 which was opened by the program that
166
later started xorriso.
168
\fB\-prev-session\fR disk_path
171
\fB\-dev\fR disk_path
174
\fB\-C\fR last_session_start,next_writeable_address
175
Set the 2 KiB block address last_session_start from where to read the
176
ISO image out of the file given by option -M.
178
Separated by a comma, set the next_writeable_address to which the
179
add-on session will finally be written. Decisive is actually the block
180
address which the intended readers will have to use as superblock address
181
on the intended media.
183
Both values can be inquired from optical media by help of burn programs
184
and cdrecord option -msinfo. xorriso itself can obtain it in its
185
cdrecord emulation. Do not let it load the drive, but rather do this manually
186
or by a program like dd which reads a few bytes. Only then it is sure that
187
the device driver knows the true readable size of the media.
189
dd if=/dev/... count=1 >/dev/null 2>&1
191
values=$(xorriso -as cdrecord dev=/dev/... -msinfo)
195
Option -C may be used without option -M to create an ISO image from
196
scratch and prepare it for being finally written to a block address
197
other than 0. Parameter last_session_start must then be set to 0.
199
\fB\-cdrecord-params\fR last_session_start,next_writeable_address
202
.B Settings for file insertion:
204
\fB\-path-list\fR disk_path
205
Read pathspecs line-by-line from disk_file and insert the depicted file
206
objects into the ISO image. If disk_path is "-" then read the pathspecs
209
\fB--quoted_path_list\fR disk_path
210
Like option -path-list but reading quoted words rather than plain lines.
211
Whitespace outside of quotes will be discarded. On the other hand it is
212
possible to represent pathspecs which contain newline characters.
214
The double quotation mark " and the single quotation mark ' can be used to
215
enclose whitespace and make it part of pathspecs. Each mark
216
type can enclose the marks of the other type. A trailing backslash \\ outside
217
quotations or an open quotation cause the next input line to be appended.
221
Resolve symbolic links on disk rather than storing them as symbolic
222
links in the ISO image.
228
Enable interpretation of input file pathspecs as combination of iso_rr_path
229
and disk_path, separated by a =-character.
231
\fB\-m\fR disk_pattern
232
Exclude files from being inserted into the image. Silently ignored are
233
those files of which the disk_path matches the given shell parser pattern.
234
If no /-character is part of the pattern, then it gets matched against
235
the leaf name of the disk file.
237
It is possible to give more than one -m option.
249
\fB\-exclude-list\fR disk_path
250
Perform -m using each line out of file disk_path as argument disk_pattern.
254
Enable recognition and proper processing of zisofs compressed files
255
as produced by program mkzftree. These files will get equipped with the
256
necessary meta data so that a Linux kernel will recognize them and
257
deliver their content in uncompressed form.
259
\fB\-transparent-compression\fR
262
\fB\-root\fR iso_rr_path
263
Insert all files under the given iso_rr_path. If option -graft-points is given,
264
then iso_rr_path is prepended to each target part of a pathspec.
266
The default for -root is "/".
268
\fB\-old-root\fR iso_rr_path
269
Enable incremental insertion of files into the loaded image.
270
The effective target and source addresses of given pathspecs get compared
271
whether the target already exists in the ISO image and is still identical
272
to the source on disk. Metadata in the ISO image will eventually get adjusted.
273
New files and files with changed content will get newly added.
274
Target files which do not exist in any of the according pathspec sources
275
will get removed from the ISO directory tree.
277
If the effective setting of -root differs from the iso_rr_path given
278
with -old-root, then the files underneath the -old-root directory get cloned
279
underneath the -root directory. Cloning happens before file comparison.
281
\fB--old-root-no-ino\fR
282
Disable recording and use of disk inode numbers.
283
If no disk inode numbers are recorded, then option -old-root will have
284
to read disk file content and compare it with the MD5 checksum that is
285
recorded in the ISO image.
287
With recorded disk inode numbers and with credible ctime and mtime,
288
it is possible to detect potential changes in the content without actually
290
A loophole remains if multiple different filesystems may get mounted
291
at the same directory, like it is habit with /mnt.
292
In this case one has to use option --old-root-devno
293
or disable the inode number shortcut by --old-root-no-ino.
295
\fB--old-root-devno\fR
296
Enable comparison of recorded device numbers together with recorded
297
inode numbers. This works only with good old stable device numbers which
298
get out of fashion, regrettably. If the hard disk has a different
299
device number after each reboot, then this comparison will see all
300
files as changed and thus prevent any incremental size saving.
302
\fB--old-root-no-md5\fR
303
Disable recording and eventual use of MD5 checksums for data file content.
304
If neither checksums and nor disk inode numbers are recorded, then
305
option -old-root will have to read ISO image file content when comparing
306
it with disk file content.
308
.B Settings for image production:
311
Set the output file address for the emerging ISO image.
312
If the address exists as regular file, it will be truncated to length 0
313
when image production begins. It may not already exist as directory.
314
If it does not exist yet then its parent directory must exist and
315
a regular file will get created.
317
A special kind of pseudo disk_path has the form "/dev/fd/"number.
318
It depicts the open file descriptor with the given number, regardless whether
319
the operating system supports this feature by file nodes in /dev/fd or not.
320
E.g. /dev/fd/4 is file descriptor 4 which was opened by the program that
321
later started xorriso.
323
Default is standard output (/dev/fd/1) which may also be set by disk_path "-".
325
\fB\-output\fR disk_path
328
\fB--stdio_sync\fR "on"|"off"|number
329
Set the number of bytes after which to force output to disk
330
in order to keep the memory from being clogged with lots of
331
pending data for slow devices. Default "on" is the same as "16m".
332
Forced output can be disabled by "off".
334
xorriso uses an inner fifo buffer with default size 4 MiB. So forcing
335
the operating system i/o cache to disk does not necessarily block the
336
simultaneous production of more image content.
339
Write a second superblock with the first session into random-access
340
files. If further sessions get appended and the first superblock gets updated,
341
then the second superblock will not be overwritten. This allows to still
342
mount the first session and to find the start blocks of the further sessions.
344
The price is 64 KiB extra space consumption. If -partition_offset is non-zero,
345
then it is 128 KiB plus twice the partition setup.
348
Do not write a second superblock with the first session into random-access
353
\fB--sort-weight\fR weight_number iso_rr_path
354
Attribute a LBA weight number to regular files. If iso_rr_path leads
355
to a directory then all regular files underneath will get the weight_number.
357
The weight_number may range from -2147483648 to 2147483647.
358
The higher it is, the lower will be the block address of the file data
359
in the emerging ISO image.
360
Currently the El Torito boot catalog has a hardcoded weight of 1 billion.
361
Normally it should occupy the block with the lowest possible address.
362
Data files get added or loaded with initial weight 0.
364
\fB\-dir-mode\fR mode
365
Set the access permissions for all directories in the image to the given
366
mode which is either an octal number beginning with "0" or a comma separated
367
list of statements of the form [ugoa]*[+-=][rwxst]* . E.g. ug=rx,a-rwx
369
\fB\-file-mode\fR mode
370
Like -dir-mode but for all regular data files in the image.
374
Add 300 KiB to the end of the produced ISO image. This circumvents possible
375
read errors from ISO images which have been written to CD media in TAO mode.
376
The additional bytes are claimed as part of the ISO image if not --emul-toc
379
Option -pad is the default.
382
Disable padding of 300 KiB to the end of the produced ISO image.
383
This is safe if the image is not meant to be written on CD or if it
384
gets written to CD as only track in write mode SAO.
387
Use the old way of of giving block addresses in the range
388
of [0,31] to files with no own data content. The new way is to have
389
a dedicated block to which all such files will point.
391
.B Settings for standards compliance:
393
\fB\-iso-level\fR number
394
Specify the ISO 9660 version which defines the limitations of file naming
395
and data file size. The naming restrictions do not apply to the
396
Rock Ridge names but only to the low-level ISO 9660 names.
397
There are three conformance levels:
399
Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB - 1.
401
Level 2 allows ISO names with up to 32 characters
402
and file size up to 4 GiB - 1.
404
Level 3 allows ISO names with up to 32 characters
405
and file size of up to 400 GiB - 200 KiB. (This size limitation is
406
set by the xorriso implementation and not by ISO 9660 which would
409
Pseudo-level 4 enables production of an additional ISO 9660:1999
412
\fB\-disallow_dir_id_ext\fR
413
Do not follow a bad habit of mkisofs which allows dots in the ISO names
414
of directories. On the other hand, some bootable GNU/Linux images depend on
419
This option allows ISO file names without dot and up to 37 characters,
420
ISO file paths longer than 255 characters, and all ASCII characters in file
421
names. Further it omits the semicolon and the version numbers at the end
424
This all violates ISO 9660 specs.
426
\fB\-untranslated-filenames\fR
428
\fB\-untranslated_name_len\fR number
429
Allow ISO file names up to the given number of characters
430
without any character conversion. The maximum number is 96.
431
If a file name has more characters, then image production will
434
This violates ISO 9660 specs.
436
\fB\-allow-lowercase\fR
437
Allow lowercase character in ISO file names.
439
This violates ISO 9660 specs.
443
Do not add trailing dot to ISO file names without dot.
445
This violates ISO 9660 specs.
452
Allow up to 37 characters in ISO file names.
454
This violates ISO 9660 specs.
456
\fB\-full-iso9660-filenames\fR
459
\fB\-max-iso9660-filenames\fR
464
Omit the semicolon and the version numbers at the end of ISO names.
466
This violates ISO 9660 specs.
468
\fB\-omit-version-number\fR
471
.B Settings for standards extensions:
475
With mkisofs this option enables Rock Ridge extensions. xorrisofs produces
476
them unconditionally.
484
Set Rock Ridge user and group id of all files in the ISO image to 0.
485
Grant r-permissions to all. Deny all w-permissions.
486
If any x-permission is set, grant x-permission to all.
487
Remove s-bit and t-bit.
489
\fB\-rational-rock\fR
493
Enable options which improve backup fidelity:
494
--acl, --xattr, --md5,
499
Enable recording and loading of GNU/Linux ACLs (see man getfacl, man acl).
500
They will not be in effect with mounted ISO images. But xorriso can
501
restore them when extracting files from the ISO image.
505
Enable recording and loading of GNU/Linux extended attributes in
506
user namespace (see man getfattr, man attr).
507
They will not be in effect with mounted ISO images. But xorriso can
508
restore them when extracting files from the ISO image.
512
Enable recording of MD5 checksums for the overall ISO image and for each
513
single data file in the image. xorriso can check the content of an ISO
514
image with these sums and eventually raise alert on mismatch.
515
See man xorriso, options -check_media, check_md5_r.
516
xorriso can print recorded MD5 checksums. E.g. by:
518
-find / -exec get_md5
521
Enable loading and recording of hardlink relations.
522
Search for families of iso_rr files which stem from the same disk file,
523
have identical content filtering and have identical properties.
524
The members of each family get the same inode number in the ISO image.
526
Whether these numbers are respected at mount time depends on the operating
527
system. xorriso can create hardlink families when extracting files from
530
\fB--scdbackup_tag\fR disk_path record_name
531
Append a scdbackup checksum record to the image. This works only if the
532
parameter next_writeable_address of option -C is 0.
533
If disk_path is not an empty string, then append a scdbackup checksum record
534
to the end of this file. record_name is a word that gets part of tag
537
Program scdbackup_verify will recognize and verify tag resp. record.
541
Enable the production of an additional Joliet directory tree along
542
with the ISO 9660 Rock Ridge tree.
548
Allow 103 characters in Joliet file names rather than 64 as is prescribed
549
by the specification. Allow Joliet paths longer than the prescribed limit of
552
Oversized names get truncated. Without this option, oversized paths get
553
excluded from the Joliet tree.
555
.B Settings for file hiding:
557
\fB\-hide\fR disk_path_pattern
558
Make files invisible in the directory tree of ISO 9660 and Rock Ridge,
559
if their disk_path matches the given shell parser pattern.
560
The eventual data content of such hidden files will be included in the
561
resulting image, even if they do not show up in any directory.
562
But you will need own means to find nameless data in the image.
564
This command does not apply to the boot catalog.
566
\fB\-hide-list\fR disk_path
567
Perform -hide using each line out of file disk_path as argument
570
\fB\-hide-joliet\fR disk_path_pattern
571
Like option -hide but making files invisible in the directory tree of Joliet,
572
if their disk_path matches the given shell parser pattern.
574
\fB\-hide-joliet-list\fR disk_path
575
Perform -hide-joliet using each line out of file disk_path as argument
578
.B ISO image ID strings:
580
The following strings and file addresses get stored in the Primary Volume
581
Descriptor of the ISO9660 image. The file addresses are ISO 9660
582
paths. These files should have iso_rr_paths which consist only of
583
the characters [A-Z0-9_] and exactly one dot which separates
584
at most 8 characters from at most 3 characters.
587
Set the Volume Id of the ISO image.
588
xorriso accepts any text up to 32 characters,
589
but according to rarely obeyed specs stricter rules apply:
591
Conformant are ASCII characters out of [A-Z0-9_]. Like: "IMAGE_23"
593
Joliet allows 16 UCS-2 characters. Like: "Windows name"
595
Be aware that the volume id might get used automatically as name of the
596
mount point when the media is inserted into a playful computer system.
602
Set the Volume Set Id of the ISO image.
603
Permissible are up to 128 characters.
606
Set the Publisher Id of the ISO image. This may identify the person or
607
organisation who specified what shall be recorded.
608
Permissible are up to 128 characters.
610
\fB\-publisher\fR text
614
Set the Application Id of the ISO image.
615
This may identify the specification of how the data are recorded.
616
Permissible are up to 128 characters.
618
The special text "@xorriso@" gets converted to the id string of xorriso
619
which is normally written as Preparer Id. It is a wrong tradition to write
620
the program id as Application Id.
626
Set the System Id of the ISO image. This may
627
identify the system which can recognize and act upon the content of the
628
System Area in image blocks 0 to 15.
629
Permissible are up to 32 characters.
632
Set the Preparer Id of the ISO image. This may
633
identify the person or other entity which controls the preparation of the data
634
which shall be recorded. Normally this should be the id of xorriso and not
635
of the person or program which operates xorriso. Please avoid to change it.
636
Permissible are up to 128 characters.
638
The special text "@xorriso@" gets converted to the id string of xorriso
639
which is default at program startup.
641
\fB\-preparer\fR text
644
\fB\-abstract\fR iso_path
645
Set the address of the Abstract File of the ISO image. This should
646
be the ISO 9660 path of a file in the image which contains an abstract
647
statement about the image content.
648
Permissible are up to 37 characters.
650
\fB\-biblio\fR iso_path
651
Set the address of the Biblio File of the ISO image. This should
652
be the ISO 9660 path of a file in the image which contains bibliographic
654
Permissible are up to 37 characters.
656
\fB\-copyright\fR iso_path
657
Set the address of the Copyright File of the ISO image. This should
658
be the ISO 9660 path of a file in the image which contains a copyright
660
Permissible are up to 37 characters.
662
\fB--modification-date=YYYYMMDDhhmmsscc\fR
663
Set a timestring that overrides ISO image creation and modification timestamps
665
It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc, with
666
YYYY between 1970 and 2999. Time zone is GMT.
667
It is supposed to match this GRUB line:
669
search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc
671
E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
673
.B El Torito Bootable ISO images:
675
The precondition for a bootable ISO image is to have in the ISO image
676
the files of a boot loader. The boot facilities of computers get
677
directed to such files, which usually execute further program files
679
xorrisofs can produce several kinds of boot block or boot record,
680
which become part of the ISO image, and get interpreted by the according
685
boot record points the bootstrapping facility to a boot catalog
686
with one or more boot images, which are binary program files stored in
688
The content of the boot image files is not in the scope of El Torito.
690
xorriso composes the boot catalog according to the boot image
691
files given and structured by options -b, -e, -el-torito-alt-boot,
692
and --efi-boot. Often it contains only one entry.
694
El Torito gets interpreted by boot facilities PC-BIOS and EFI.
695
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images
698
xorrisofs supports the example options out of the ISOLINUX wiki,
699
the options used in GRUB script grub-mkrescue, and the example in the
700
FreeBSD AvgLiveCD wiki.
703
For CD booting via boot facilities other than PC-BIOS and EFI, and
704
for booting from USB sticks or hard disks, see the next section
705
about the Sytem Area.
708
\fB\-b\fR iso_rr_path
709
Specify the boot image file which shall be mentioned in the current
710
entry of the El Torito boot catalog. It will be marked as suitable for
713
With boot images from ISOLINUX and GRUB this option should be accompanied by
714
options -c , -no-emul-boot , -boot-load-size 4 , -boot-info-table.
716
\fB\-eltorito-boot\fR iso_rr_path
719
\fB\-eltorito-alt-boot\fR
720
Finalize the current El Torito boot catalog entry and begin a new one.
721
A boot image file and all its necessary options shall be specified before
722
option -eltorito-alt-boot.
723
All further El Torito boot options apply to the new catalog
724
entry. Up to 32 catalog entries are possible.
726
\fB\-e\fR iso_rr_path
727
Specify the boot image file which shall be mentioned in the current
728
entry of the El Torito boot catalog. It will be marked as suitable for EFI.
730
Normally no other El Torito options should be used with the catalog entry
731
that points to an EFI image.
732
Consider to use --efi-boot rather than -e.
734
\fB--efi-boot\fR iso_rr_path
735
Perform eventual necessary -eltorito-alt-boot, option -e with the given
736
iso_rr_path, and again -eltorito-alt-boot. This gesture is
737
used for achieving EFI-bootability of the GRUB2 rescue CD.
739
\fB\-boot-load-size\fR number
740
Set the number of 512-byte blocks for boot images which emulate
741
a floppy or a hard disk. A safe default for non-emulating boot images is 4.
743
\fB\-hard-disk-boot\fR
744
Mark the boot image in the current catalog entry as emulated hard disk.
745
(Not suitable for any known boot loader.)
748
Mark the boot image in the current catalog entry as not emulating
749
floppy or hard disk. (This is to be used with all known boot loaders.)
751
If neither -hard-disk-boot nor -no-emul-boot is given, then the
752
boot image will be marked as emulating a floppy.
753
(Not suitable for any known boot loader.)
755
\fB\-boot-info-table\fR
756
Overwrite certain bytes in the current boot image. The information will be
757
supplied by xorriso in the course of image production: Block address of
758
the Primary Volume Descriptor, block address of the boot image file,
759
size of the boot image file.
761
\fB\-c\fR iso_rr_path
762
Set the address of the El Torito boot catalog file within the image.
763
This file address is not significant for the booting PC-BIOS or EFI,
764
but it may later be read by other programs in order to learn about
765
the available boot images.
767
\fB\-eltorito-catalog\fR iso_rr_path
770
\fB--boot-catalog-hide\fR
771
Prevent the El Torito boot catalog from appearing as file
772
in the directory trees of the image.
774
.B System Area, MBR, other boot blocks:
776
The first 16 blocks of an ISO image are the System Area.
777
It is reserved for system dependent boot software. This may be the
778
CD boot facilities of exotic hardware architectures or it may be
779
a MBR for booting via PC-BIOS from USB stick or hard disk.
781
A \fBMBR\fR (Master Boot Record) contains boot code and a partition table.
782
It does not hamper El Torito booting from CDROM.
784
xorrisofs supports boot facilities other than PC-BIOS:
785
MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
786
Those are mutually not combinable and also not combinable with MBR.
790
Copy at most 32768 bytes from the given disk file to the very start of
793
Other than a El Torito boot image, the file disk_path needs not to be added
794
to the ISO image. It will not show up as file in the directory trees.
796
\fB\-generic-boot\fR disk_path
799
\fB--embedded-boot\fR disk_path
802
\fB\-isohybrid-mbr\fR disk_path
803
Install disk_path as ISOLINUX isohybrid MBR which makes the boot image
804
given by option -b bootable from USB sticks and hard disks via PC-BIOS.
805
This preparation is normally done by ISOLINUX program isohybrid
806
on the already produced ISO image.
808
The disk path should lead to one of the Syslinux files isohdp[fp]x*.bin .
809
The MBR gets patched according to isohybrid needs. The first partition
810
describes the range of the ISO image. Its start is at block 0 by default,
811
but may be set to 64 disk blocks by option -partition_offset 16.
813
\fB--protective-msdos-label\fR
814
Patch the System Area by a simple PC-DOS partition table where partition 1
815
claims the range of the ISO image but leaves the first block unclaimed.
817
\fB\-partition_offset\fR 2kb_block_adr
818
Cause a partition table with a single partition that begins at the
819
given block address. This is counted in 2048 byte
820
blocks, not in 512 byte blocks. If the block address is non-zero then it must
821
be at least 16. Values larger than 16 are hardly of use.
822
A non-zero partition offset causes two superblocks to be
823
generated and two sets of directory trees. The image is then mountable from its
824
absolute start as well as from the partition start.
826
The offset value of an ISO image gets preserved when a new session is added
828
So the value defined here is only in effect if a new ISO image gets written.
830
\fB\-partition_hd_cyl\fR number
831
Set the number of heads per cylinder for the partition table.
832
0 chooses a default value. Maximum is 255.
834
\fB\-partition_sec_hd\fR number
835
Set the number of sectors per head for the partition table.
836
0 chooses a default value. Maximum is 63.
838
The product partition_sec_hd * partition_hd_cyl * 512 is the cylinder size.
839
It should be divisible by 2048 in order to allow exact alignment.
840
If it is too small to describe the image size by at most 1024 cylinders,
841
then appropriate values of partition_hd_cyl are chosen with
842
partition_sec_hd 32 or 63. If the image is larger than 8,422,686,720 bytes,
843
then the cylinder size constraints cannot be fulfilled. They seem not overly
844
important anyway. Flat block addresses in partition tables are good for 1 TiB.
846
\fB\-partition_cyl_align\fR mode
847
Control image size alignment to an integer number of cylinders.
848
It is prescribed by isohybrid specs and it seems to please program fdisk.
849
Cylinder size must be divisible by 2048.
850
Images larger than 8,323,596,288 bytes cannot be aligned.
852
Mode "auto" is default. Alignment by padding happens only if
853
option -isohybrid-mbr is given.
855
Mode "on" causes alignment by padding with option
856
--protective-msdos-label too.
857
Mode "off" disables alignment unconditionally.
859
\fB\-append_partition\fR partition_number type_code disk_path
860
Cause a prepared filesystem image to be appended to the ISO image and to be
861
described by a partition table entry in a boot block at the start of the
862
emerging ISO image. The partition entry will bear the size of the submitted
863
file rounded up to the next multiple of 2048 bytes.
865
Beware of subsequent multi-session runs. The appended partition will get
868
partition_number may be 1 to 4. Number 1 will put the whole ISO image into
869
the unclaimed space before partition 1. So together with most xorriso MBR
870
features, number 2 would be the most natural choice.
872
The type_code may be "FAT12", "FAT16", "Linux",
873
or a hexadecimal number between 0x00 and 0xff. Not all those numbers will
874
yield usable results. For a list of codes search the Internet for
875
"Partition Types" or run fdisk command "L".
877
\fB\-mips-boot\fR iso_rr_path
878
Declare a data file in the image to be a
879
MIPS Big Endian boot file and cause production of a MIPS Big Endian Volume
880
Header. This is mutually exclusive with production of other boot blocks
882
It will overwrite the first 512 bytes of any data eventually provided by -G.
883
Up to 15 boot files can be declared by multiple -mips-boot options.
885
\fB\-mipsel-boot\fR iso_rr_path
886
Declare a data file in the image to be the
887
MIPS Little Endian boot file. This is mutually exclusive with other boot
889
It will overwrite the first 512 bytes of any data eventually
891
Only a single boot file can be declared by -mipsel-boot.
893
\fB\-B\fR disk_path[,disk_path ...]
894
Cause one or more data files on disk to be written after the end of the
895
ISO image. A SUN Disk Label will be written into the first 512 bytes of the
896
ISO image which lists this image as partition 1 and the given disk_paths as
899
The disk files should contain suitable boot images for SUN SPARC systems.
901
The pseudo disk_path "..." causes that all empty partition entries become
902
copies of the last non-empty entry. If no other disk_path is given before
903
"..." then all partitions describe the ISO image. In this case, the boot
904
loader code has to be imported by option -G.
906
\fB\-sparc-boot\fR disk_path[,disk_path ...]
909
\fB\-sparc-label\fR text
910
Set the ASCII label text of a SUN Disk Label.
914
Character sets should not matter as long as only english alphanumeric
915
characters are used for file names or as long as all writers and readers
916
of the media use the same character set.
917
Outside these constraints it may be necessary to let xorriso convert byte
920
A conversion from input character set to the output character set is
921
performed when an ISO image gets written.
922
Vice versa there is a conversion from output character set to the
923
input character set when an ISO image gets loaded.
924
The sets can be defined by options -input-charset and -output-charset,
928
\fB\-input-charset\fR character_set_name
929
Set the character set from which to convert disk file names when
930
inserting them into the ISO image.
932
\fB\-output-charset\fR character_set_name
933
Set the character set from which to convert names of loaded ISO images
934
and to which to convert names when writing ISO images.
936
.B Jigdo Template Extraction:
938
From man genisoimage:
939
"Jigdo is a tool to help in the distribution of large files like CD and
940
DVD images; see http://atterer.net/jigdo/ for more details. Debian CDs
941
and DVD ISO images are published on the web in jigdo format to allow
942
end users to download them more efficiently."
944
If the use of libjte was enabled at compile time of xorriso, then
945
xorrisofs can produce a .jigdo and a .template file together with a
946
single-session ISO image. If not, then Jigdo options will cause a
947
FAILURE event, which normally leads to program abort.
949
One may determine the ability for Jigdo by:
951
$ xorrisofs -version 2>&1 | grep '^libjte' && echo YES
954
The .jigdo file contains checksums and symbolic file addresses.
955
The .template file contains the compressed ISO image with reference tags
956
instead of the content bytes of the listed files.
958
Input for this process are the normal arguments for a xorrisofs session
959
with no image loaded, and a .md5 file which lists those data files which may be
960
listed in the .jigdo file and externally referenced in the .template file.
961
Each designated file is represented in the .md5 file by a single text line:
963
MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks,
964
symbolic file address
966
The file address in an .md5 line has to bear the same basename as the
967
disk_path of the file which it shall match. The directory path of
968
the file address is decisive for To=From mapping, not for file recognition.
969
After eventual To=From mapping, the file address gets written into the .jigdo
970
file. Jigdo restore tools will convert these addresses into really
971
reachable data source addresses from which they can read.
973
If the list of jigdo parameters is not empty, then eventual padding will be
974
counted as part of the ISO image.
977
\fB\-jigdo-jigdo\fR disk_path
978
Set the disk_path for the .jigdo file with the checksums
979
and download addresses for filling the holes in .template.
981
\fB\-jigdo-template\fR disk_path
982
Set the disk_path for the .template file with the
983
holed and compressed ISO image copy.
985
\fB\-jigdo-min-file-size\fR size
986
Set the minimum size for a data file to be listed
987
in the .jigdo file and being a hole in the .template file.
988
size may be a plain number counting bytes, or a number with appended
989
letter "k", "m", "g" to count KiB (1024 bytes), MiB (1024 KiB), or
992
\fB\-jigdo-force-md5\fR disk_path_pattern
993
adds a regular expression pattern which will get compared
994
with the absolute disk_path of any data file that was not found in the .md5
995
list. A match causes a MISHAP event, which normally does not abort the
996
program run but finally causes a non-zero exit value of the program.
998
\fB\-jigdo-exclude\fR disk_path_pattern
999
Add a regular expression pattern which will get compared
1000
with the absolute disk_path of any data file. A match causes the file to
1001
stay in .template in any case.
1003
\fB\-jigdo-map\fR To=From
1004
Add a string pair of the form To=From to the parameter list.
1005
If a data file gets listed in the .jigdo file, then it is referred by the
1006
file address from its line in the .md5 file. This file address gets checked
1007
whether it begins with the From string. If so, then this string will be
1008
replaced by the To string and a ':' character, before it goes into the .jigdo
1009
file. The From string should end by a '/' character.
1011
\fB\-md5-list\fR disk_path
1012
Set the disk_path where to find the .md5 input file.
1014
\fB\-jigdo-template-compress\fR "gzip"|"bzip2"
1015
Choose one of "bzip2" or "gzip" for the compression of
1016
the template file. The jigdo file is put out uncompressed.
1018
\fB\-checksum_algorithm_iso\fR list_of_names
1019
Choose one or more of "md5", "sha1", "sha256", "sha512"
1020
for the auxiliary "# Image Hex" checksums in the .jigdo file. The list_of_names
1021
may e.g. look like "md5,sha1,sha512". Value "all" chooses all available
1023
Note that MD5 stays always enabled.
1025
\fB\-checksum_algorithm_template\fR list_of_names
1026
Choose the algorithms for the "# Template Hex" checksums in the .jigdo file.
1027
The rules for list_of_names are the same as with -checksum_algorithm_iso.
1029
.B Miscellaneous options:
1032
Print to stdandard output the foreseeable number of 2048 byte blocks in
1033
the emerging ISO image. Do not produce this image.
1035
The result depends on several settings.
1037
If option --emul-toc is given, then padding (see -pad) is not
1038
counted as part of the image size. In this case either use -no-pad or
1039
add 150 (= 300 KiB) to the resulting number.
1042
Only if used as first argument this option
1043
prevents reading and interpretation of eventual startup
1044
files. See section FILES below.
1048
List supported options to stderr. Original mkisofs options bear their
1049
original mkisofs description texts.
1053
Suppress most messages of the program run, except those which indicate
1058
Enable the output of informational program messages.
1064
Print to standard output a text that begins with
1066
"mkisofs 2.01-Emulation Copyright (C)"
1068
and to standard error the version information of xorriso.
1072
.B Overview of examples:
1073
A simple image production run
1075
Set ISO image paths by -graft-points
1077
Perform multi-session runs
1079
Let xorrisofs work underneath growisofs
1081
Incremental backup of a few directory trees
1083
Incremental backup with accumulated trees
1085
Create bootable images for PC-BIOS
1088
.B A simple image production run
1089
A prepared file tree in directory ./for_iso gets copied into the root
1090
directory of the ISO image. File permissions get set to read-only for
1092
Joliet attributes for Microsoft systems get added.
1093
The resulting image gets written as data file ./image.iso on disk.
1095
$ xorrisofs -r -J -o ./image.iso ./for_iso
1097
.B Set ISO image paths by -graft-points
1098
Without option -graft-points each given disk file is copied into the root
1099
directory of the ISO image, maintaining its name. If a directory is given,
1100
then its files and sub-directories are copied into the root directory,
1101
maintaining their names.
1103
$ xorrisofs ... /home/me/datafile /tmp/directory
1105
yields in the ISO image root directory:
1109
/file_1_from_directory
1113
/file_N_from_directory
1116
With option -graft-points it is possible to put files and directories to
1117
arbitrary paths in the ISO image.
1119
$ xorrisofs ... -graft-points /home/me/datafile /dir=/tmp/directory
1121
yields in the ISO image root directory:
1127
Eventually needed parent directories in
1128
the image will be created automatically:
1130
/datafiles/file1=/home/me/datafile
1132
yields in the ISO image:
1136
The attributes of directory /datafiles get copied from /home/me on disk.
1139
Normally one should avoid = and \\ characters in the ISO part of a pathspec.
1140
But if it must be, one may escape them:
1142
/with_\\=_and_\\\\/file=/tmp/directory/file
1144
yields in the ISO image:
1148
.B Perform multi-session runs
1149
This example works for multi-session media only:
1150
CD-R[W], DVD-R[W], DVD+R, BD-R.
1151
Add cdrskin option --grow_overwriteable_iso
1152
to all -as cdrecord runs
1153
in order to enable multi-session emulation on overwriteable media.
1155
The first session is written like this:
1157
$ xorrisofs -graft-points \\
1159
/tree1=prepared_for_iso/tree1 \\
1161
| xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
1163
Follow-up sessions are written like this:
1165
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
1167
$ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
1169
$ xorrisofs -M /dev/sr0 -C $m -graft-points \\
1171
/tree2=prepared_for_iso/tree2 \\
1173
| xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
1175
Always eject the drive tray between sessions. The old sessions
1176
get read via /dev/sr0. Its device driver might not be aware
1177
of the changed content before it loads the media again.
1178
In this case the previous session would not be loaded and the
1179
new session would contain only the newly added files.
1181
For the same reason do not let xorriso -as cdrecord load the media,
1182
but rather do this manually or by a program that reads from /dev/sr0.
1184
.B Let xorrisofs work underneath growisofs
1185
growisofs expects an ISO formatter program which understands options -C and
1186
-M. A variable is defined to override the hardcoded default name.
1188
$ export MKISOFS="xorrisofs"
1190
$ growisofs -Z /dev/dvd /some/files
1192
$ growisofs -M /dev/dvd /more/files
1194
If no "xorrisofs" is available on your system, then you will have to create
1195
a link pointing to the xorriso binary and tell growisofs to use it. E.g. by:
1197
$ ln -s $(which xorriso) "$HOME/xorrisofs"
1199
$ export MKISOFS="$HOME/xorrisofs"
1201
One may quit mkisofs emulation by argument "--" and make
1202
use of all xorriso commands. growisofs dislikes options which
1203
start with "-o" but -outdev must be set to "-".
1204
So use "outdev" instead:
1206
$ growisofs -Z /dev/dvd --for_backup -- \\
1208
outdev - -update_r /my/files /files
1210
$ growisofs -M /dev/dvd --for_backup -- \\
1212
outdev - -update_r /my/files /files
1214
Note that --for_backup is given in the mkisofs emulation.
1215
To preserve the recorded extra data it must already be in effect, when
1216
the emulation loads the image.
1218
.B Incremental backup of a few directory trees
1219
This changes the directory trees /open_source_project and /personal_mail
1220
in the ISO image so that they become exact copies of their disk counterparts.
1221
ISO file objects get created, deleted or get their attributes adjusted
1224
ACL, xattr, hard links and MD5 checksums will be recorded.
1225
It is expected that inode numbers in the disk filesystem are persistent
1226
over cycles of mounting and booting.
1227
Files with names matching *.o or *.swp get excluded explicitly.
1230
To be used several times on the same media, whenever an update of
1231
the two disk trees to the media is desired. Begin with blank media and start
1232
a new blank media when the run fails due to lack of remaining space on
1235
Do not let xorriso -as cdrecord load the media,
1236
but rather do this manually or by a program that reads from /dev/sr0.
1238
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
1240
$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
1244
$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo"
1246
$ xorrisofs $load_opts -o - --for_backup -m '*.o' -m '*.swp' \\
1248
-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\
1252
/projects=/home/thomas/projects \\
1254
/personal_mail=/home/thomas/personal_mail \\
1256
| xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject -
1259
This makes sense if the full backup leaves substantial remaining capacity
1260
on media and if the expected changes are much smaller than the full backup.
1263
\fBBetter do not use your youngest backup for -old-root\fR.
1264
Have at least two media which you use alternatingly. So only older backups
1265
get endangered by the new write operation, while the newest backup is
1266
stored safely on a different media.
1267
Always have a blank media ready to perform a full backup in case the update
1268
attempt fails due to insufficient remaining capacity.
1271
If inode numbers on disk are not persistent, then use
1272
option --old-root-no-ino .
1273
In this case an update run will compare recorded MD5
1274
sums against the current file content on hard disk.
1277
With \fBmount\fR option \fB\-o "sbsector="\fR on GNU/Linux
1278
resp. \fB\-s\fR on FreeBSD
1279
it is possible to access the session trees which represent the older backup
1280
versions. With CD media, GNU/Linux mount accepts session numbers directly by
1281
its option "session=".
1283
Multi-session media and most overwriteable media written by xorriso can tell
1284
the sbsectors of their sessions by xorriso option -toc:
1286
$ xorriso -dev /dev/sr0 -toc
1288
xorriso can print the matching mount command for a session number:
1290
$ xorriso -mount_cmd /dev/sr0 session 12 /mnt
1292
or for a volume id that matches a search expression:
1294
$ xorriso -mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt
1296
Both yield on standard output something like:
1298
mount -t iso9660 -o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0' '/mnt'
1300
The superuser may let xorriso execute the mount command directly:
1302
# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
1304
.B Incremental backup with accumulated trees
1305
Solaris does not offer the option to mount older sessions.
1306
In order to keep them accessible, one may map all files to a file tree under
1307
a session directory and accumulate those directories from session to session.
1308
The -root tree is cloned from the -old-root tree before it gets
1309
compared with the appropriate trees on disk.
1311
This demands to know the previously used session directory name.
1313
With the first session:
1315
$ xorrisofs -root /session1 \\
1317
-o - --for_backup -m '*.o' -m '*.swp' \\
1319
-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\
1321
/projects=/home/thomas/projects \\
1323
/personal_mail=/home/thomas/personal_mail \\
1325
| xorriso -as cdrecord dev=/dev/sr0 -v blank=as_needed \\
1327
-multi -waiti -eject -
1330
With the second session, option -old-root refers to /session1 and the
1331
new -root is /session2.
1333
Do not let xorriso -as cdrecord load the media,
1334
but rather do this manually or by a program that reads from /dev/sr0.
1336
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
1338
$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
1342
$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo"
1344
$ xorrisofs $load_opts -root /session2 -old-root /session1 \\
1346
-o - --for_backup -m '*.o' -m '*.swp' \\
1348
-V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \\
1350
/projects=/home/thomas/projects \\
1352
/personal_mail=/home/thomas/personal_mail \\
1354
| xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject -
1356
With the third session, option -old-root refers to /session2.
1357
The new -root is /session3. And so on.
1359
.B Create bootable images for PC-BIOS
1360
The ISOLINUX wiki prescribes to create on disk a directory ./CD_root and
1361
to copy all desired files underneath that directory. Especially file
1362
isolinux.bin shall be copied to ./CD_root/isolinux/isolinux.bin .
1363
This is the boot image file.
1365
The prescribed mkisofs options can be used unchanged with xorrisofs:
1367
$ xorrisofs -o output.iso \\
1369
-b isolinux/isolinux.bin -c isolinux/boot.cat \\
1371
-no-emul-boot -boot-load-size 4 -boot-info-table \\
1375
Put it on CD by a burn program. E.g.:
1377
$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed output.iso
1380
The image from above example will boot from CD, DVD or BD, but not from
1381
USB stick or other hard-disk-like devices. This can be done by help of an
1382
isohybrid MBR. Syslinux provides matching template files
1383
as isohdp[fp]x*.bin . E.g. /usr/lib/syslinux/isohdpfx.bin .
1385
If a few hundred KB of size do not matter, then option -partition_offset
1386
can be used to create a partition table where partition 1 starts not
1387
at block 0. This facilitates later manipulations of the USB stick by
1388
tools for partitioning and formatting.
1390
The image from the following example will be prepared for booting via MBR
1391
and its first parttion will start at hard disk block 64.
1393
It will also boot from optical media.
1395
$ xorrisofs -o output.iso \\
1396
-b isolinux/isolinux.bin -c isolinux/boot.cat \\
1397
-no-emul-boot -boot-load-size 4 -boot-info-table \\
1399
-isohybrid-mbr /usr/lib/syslinux/isohdpfx.bin \\
1401
-partition_offset 16 \\
1405
Become superuser and copy the image to the unpartitioned base device file
1406
of the USB stick. On GNU/Linux this is e.g. /dev/sdb, not /dev/sdb1.
1409
This will overwrite any eventual partitioning on the USB stick and make
1410
remaining data unaccessible.
1412
So first make sure you got the correct address of the intended device.
1413
E.g. by reading 100 MiB data from it and watching it blinking:
1415
# dd bs=2K if=/dev/sdb count=50K >/dev/null
1417
Now copy the image onto it
1419
# dd bs=2K if=output.iso of=/dev/sdb
1425
If not --no_rc is given as the first argument then xorrisofs
1426
attempts on startup to read and execute lines from the following files:
1428
/etc/default/xorriso
1432
/etc/xorriso/xorriso.conf
1436
The files are read in the sequence given here, but none of them is required
1437
to exist. The lines are not interpreted as xorrisofs options but as generic
1438
xorriso commands. See man xorriso.
1440
After the xorriso startup files, the program tries one by one to open for
1449
$(dirname $0)/.mkisofsrc
1451
On success it interprets the file content and does not try further files.
1452
The last address is used only if start argument 0 has a non-trivial dirname.
1454
The reader currently interprets the following NAME=VALUE pairs:
1458
PUBL default for -publisher
1460
SYSI default for -sysid
1464
VOLS default for -volset
1466
Any other lines will be silently ignored.
1470
For generic xorriso command mode
1473
For mounting xorriso generated ISO 9660 images (-t iso9660)
1476
Other programs which produce ISO 9660 images
1480
Programs which burn sessions to optical media
1496
Thomas Schmitt <scdbackup@gmx.net>
1498
for libburnia-project.org
1500
Copyright (c) 2011 Thomas Schmitt
1502
Permission is granted to distribute this text freely. It shall only be
1503
modified in sync with the technical properties of xorriso. If you make use
1504
of the license to derive modified versions of xorriso then you are entitled
1505
to modify this text under that same license.
1507
xorrisofs is in part based on work by Vreixo Formoso who provides libisofs
1508
together with Mario Danic who also leads the libburnia team.
1510
Compliments towards Joerg Schilling whose cdrtools served me for ten years.