[rb-general] [PATCH 1/1] Add information about creating ISO-9660 archives

[Mike Swanson]

---
 _docs/archives_iso9660.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 _docs/archives_iso9660.md

diff --git a/_docs/archives_iso9660.md b/_docs/archives_iso9660.md
new file mode 100644
index 0000000..c04b3cf
--- /dev/null
+++ b/_docs/archives_iso9660.md
@@ -0,0 +1,102 @@
+---
+title: Archive metadata (ISO-9660)
+layout: docs
+permalink: /docs/archives_iso9660/
+---
+
+ISO-9660 archives (also known as images and file systems) are similar
+to tar, in that they retain a lot of metadata.  This is a particular
+format useful for creating mountable CDs, DVDs, Blu-ray discs and the
+like; they can also be generated for other uses, such as virtual
+machine images and formats like AppImage.  File modification and
+access times are normally preserved, as well as ownership and
+permissions.  The volume header of the archive also, by default,
+contains information about the program that created it and the time of
+creation.
+
+We will use `xorrisofs`, from the xorriso package, to manipulate the
+necessary information for reproducible builds.
+
+Volume header
+-------------
+
+The ISO-9660 format contains some information about the archive in its
+header.  Some of it is very rarely used, and not configured by
+default.
+
+The volume ID of the archive can be set to a name, the default is
+`CDROM` but it is usually useful to change this so mounted discs
+convey basic information about the contents.  For software
+distributions, the name and version is usually sufficient information.
+This can be incorporated into a build system, and an argument such as
+`-V "libfoo 8.2.1"` to maintain consistency.
+
+The system ID of the archive is intended to be used to specify an
+operating system that can recognize and act upon system area blocks
+contained within.  `mkisofs` and `genisoimage` instead use it to
+record the operating system the archive was created under (`LINUX`,
+`FREEBSD`, etc).  `xorrisofs` does not set this by default, and it is
+not recommended to set one.
+
+Data preparer ID records the application that created the archive, and
+`xorrisofs` records the name of itself, its supporting libraries,
+their versions and build date by default.  This may be manipulated
+with the `-p` option.  To build up a similar string without the
+version numbers or dates, use `-p "XORRISO, LIBISOBURN, LIBISOFS,
+LIBBURN"`.
+
+Volume creation and modification time are also recorded by default and
+may be overridden using the `--modification-date=$DATE` argument.  The
+`strftime` string for `$DATE` is `%Y%m%d%H%M%S00`.  The last "00"
+refers to centiseconds, which may be recorded if desired, but is
+usually unnecessary.  This field is not recorded with a time zone, and
+using UTC to generate it is highly recommended.
+
+Other rarely-used informational fields, left empty by default and
+recommended to keep that way, are volume set ID, publisher ID,
+application ID, copyright file ID, abstract file ID, and bibliographic
+file ID.
+
+File ownership, modes, modification times
+-----------------------------------------
+
+ISO-9660, combined with the Rock Ridge extensions, which are enabled
+by default, supports recording a full standard POSIX file tree
+complete with ownership, modes, atime, mtime, and ctime.
+
+File ownership and modes may be normalized using the `-r` option,
+which sets all ownership to UID 0 and GID 0, sets read permissions to
+all (user, group, other), removes all write permissions (ISO-9660 is a
+read-only archive/file system, but suitable for file system backups in
+normal operation), and removes setuid, setgid, sticky bits.  Execute
+permissions are granted to all if any on the source file system had at
+least one set.
+
+File atime, mtime, ctime are normally recorded from the source file
+system as-is, but can be overriden using the `--set_all_file_dates
+$DATE` argument.  The `strftime` string for `$DATE` is
+`%Y%m%d%H%M%S00`, like `--modification-date` earlier.  Rock Ridge uses
+UTC-based timestamps counting from the Unix epoch, and passing the UTC
+time to this argument should be done.
+
+Full example
+------------
+
+The recommended way to create an ISO-9660 archive is thus:
+
+<div class="correct">
+{% highlight sh %}
+$ FILEMODDATE="$(date -u -d "@${SOURCE_DATE_EPOCH}" +%Y%m%d%H%M%S00)"
+$ xorrisofs -V "libfoo 8.2.1" \
+            -p "XORRISO, LIBISOBURN, LIBISOFS, LIBBURN" \
+			--modification-date="$FILEMODDATE" \
+			--set_all_file_dates "$FILEMODDATE" \
+            -r -o product.iso build
+{% endhighlight %}
+</div>
+
+There are a lot of varying ways to create an archive for various
+reasons.  Please document (especially in a build system) the exact
+method for creating an archive.  A common variant to provide Microsoft
+Windows compatibility, for example, is to use `-J` to generate long
+file names for that operating system.
-- 
2.12.2