Build and Inspect an ISO Image with xorrisofs

xorrisofs graft points stop files landing in the wrong place inside your ISO. You will build a boot-neutral image, put selected files at deliberate paths, exclude temporary files, and inspect the result without mounting it. This is xorrisofs 1.5.6 from the Ubuntu xorriso package, matching the installed manpage here.

Allow about fifteen minutes. You need a shell, enough free space for the output image, and a readable source directory. The examples write only to a new file under /tmp and need no sudo.

1. Check the installed command

Confirm which executable is first on your PATH, then note the package version. Both are ordinary read-only commands:

$ command -v xorrisofs
/usr/bin/xorrisofs
$ dpkg-query -W -f='${Package} ${Version}\n' xorriso
xorriso 1:1.5.6-1.1ubuntu3
$ xorrisofs --version
xorrisofs 1.5.6

The manpage describes this as an mkisofs-compatible command mode of xorriso. It produces ISO 9660 with Rock Ridge information by default, which preserves useful Unix properties and longer names, so do not disable it casually. Add -J for a Joliet tree too when Windows-oriented directory names actually matter.

2. Prepare a small source tree

Use a source tree whose contents you have already checked. This example creates harmless test data so the command can be copied and run without guessing your layout:

$ mkdir -p /tmp/iso-demo/source/docs /tmp/iso-demo/source/tmp
$ printf 'release notes\n' > /tmp/iso-demo/source/docs/release-notes.txt
$ printf 'hello xorrisofs\n' > /tmp/iso-demo/source/README.txt
$ printf 'temporary data\n' > /tmp/iso-demo/source/tmp/debug.log
$ find /tmp/iso-demo/source -maxdepth 3 -type f -print
/tmp/iso-demo/source/docs/release-notes.txt
/tmp/iso-demo/source/tmp/debug.log
/tmp/iso-demo/source/README.txt

3. Build the ISO with explicit paths

Run this as one unprivileged command:

$ xorrisofs --no_rc \
    -o /tmp/iso-demo/output.iso \
    -V GUIDE_TEST \
    -graft-points \
    /docs=/tmp/iso-demo/source/docs \
    /README.txt=/tmp/iso-demo/source/README.txt \
    -m '*.log'

The expected ending includes an image summary similar to this:

ISO image produced: 185 sectors
Written to medium : 185 sectors at LBA 0
Writing to 'stdio:/tmp/iso-demo/output.iso' completed successfully.

The exact sector count depends on your files. -graft-points turns each pathspec into target=source: the left side is the path inside the ISO, the right is the local path. Here the source directory merges below /docs, while one local file becomes /README.txt. Skip graft points and directory arguments merge into the ISO root instead, with ordinary files copied there.

The -m pattern excludes matching disk files. A pattern with no slash matches against the leaf name, so '*.log' excludes the test log wherever it turns up. Quote shell patterns so the shell does not expand them before xorrisofs even sees them.

Put --no_rc first for a reproducible command: it stops xorrisofs reading its system and user startup files. Skip it and files such as /etc/xorriso/xorriso.conf and ~/.xorrisorc may contribute generic xorriso commands you never asked for, and a local .mkisofsrc can add old-style metadata defaults too.

4. Verify the image

First check the output is actually an ISO image with the expected volume identifier:

$ file /tmp/iso-demo/output.iso
/tmp/iso-demo/output.iso: ISO 9660 CD-ROM filesystem data 'GUIDE_TEST'
$ stat -c '%n %s bytes' /tmp/iso-demo/output.iso
/tmp/iso-demo/output.iso 378880 bytes
$ xorriso -indev /tmp/iso-demo/output.iso -ls /
'README.txt'
'docs'

Inspect the directory you grafted into the image:

$ xorriso -indev /tmp/iso-demo/output.iso -ls /docs
'release-notes.txt'

The excluded debug.log should not appear. If it does, check the pattern, its quoting, and the source path. These checks read the image only; nothing here mounts it or alters the source tree.

5. Handle names and compatibility deliberately

Rock Ridge names are the normal Linux view, but ISO 9660 itself keeps stricter naming rules. Need Windows compatibility? Add -J and inspect the result on the systems that will actually consume it. Do not reach for -U, -N, or other relaxed-name options just to silence a warning: the manpage flags several of these as outright violations of ISO 9660.

• Large input tree: -path-list FILE reads pathspecs one per line, or -path-list - reads them from standard input. It sidesteps an unwieldy argument list, but review that file like a script since it becomes part of the build input.
• Building for backup, not just distribution: --for_backup enables ACL, extended-attribute, MD5 and hard-link recording. Useful for restoration, but recording that metadata does not make the ISO writable or guarantee a later restore has sufficient privileges. Test restoration separately.

6. Keep burning and device writes separate

xorrisofs creates an image file; it does not directly write sequential optical media in this emulation mode. Reach for a proper burn workflow only after inspecting the image.

Picked an existing output file by accident? Stop and restore it from the backup you made before the command: there is no xorrisofs undo for a truncated file. To remove only the disposable demonstration tree, use a file manager or a carefully verified command after checking the exact path; never apply recursive deletion to a directory you have not inspected.