Document the various global filesystem options

These options have always been a bit of a mess since v2 when we added
all the block-device flexibility.  Add some explicit documentation to
try and help explain the relationship between these options and the
block-device config.

Change-Id: I49affcbef868d644f673b833bef8310cf25cfd0f
This commit is contained in:
Ian Wienand 2019-04-29 16:05:00 +10:00
parent 29f5759a4d
commit d18e73147e

View File

@ -606,27 +606,69 @@ Example:
dump-freq: 2
Filesystem Caveat
-----------------
Legacy global filesystem configuration
--------------------------------------
By default, disk-image-create uses a 4k byte-to-inode ratio when
creating the filesystem in the image. This allows large 'whole-system'
images to utilize several TB disks without exhausting inodes. In
contrast, when creating images intended for tenant instances, this
ratio consumes more disk space than an end-user would expect (e.g. a
50GB root disk has 47GB avail.). If the image is intended to run
within a tens to hundrededs of gigabyte disk, setting the
byte-to-inode ratio to the ext4 default of 16k will allow for more
usable space on the instance. The default can be overridden by passing
``--mkfs-options`` like this::
The ``disk-image-create`` tool has a number of historic global
disk-related command-line options which are maintained for backwards
compatibility. These options are merged as necessary by the
block-device layer into the active configuration. If you are using
more complicated block-device layouts with multiple partitions, you
may need to take into account the special behaviour described below.
disk-image-create --mkfs-options '-i 16384' <distro> vm
The ``local_loop`` module will take it's default size from the
following argument.
You can also select a different filesystem by setting the ``FS_TYPE``
environment variable.
``--image-size``
The size of loopback device which the image will be generated in,
in gigabytes. If this is left unset, the size will be calculated
from the on-disk size of the image and then scaled up by a fixed
60% factor. Can also set ``DIB_IMAGE_SIZE``.
Note ``--mkfs-options`` are options passed to the mfks *driver*,
rather than ``mkfs`` itself (i.e. after the initial `-t` argument).
The special node named ``mkfs_root`` is affected by the following;
this reflects that the standard layout has only a single root
partition so the options are, in effect, global for the default
configuration. Note that if you are using multiple partitions,
settings such as ``--mkfs-options`` will *not* apply to other
partitions.
The file-system type for the ``mkfs_root`` node is set by the
``FS_TYPE`` environment variable, and defaults to ``ext4``. ``xfs``
should also work. There is no command-line argument for this.
The following options also affect the ``mkfs_root`` node
configuration:
``--mkfs-options``
Options passed to mkfs when making the root partition. For
``ext4`` partitions, this by default sets a 4k byte-to-inode ratio
(see below) and a default journal size of 64MiB. Note
``--mkfs-options`` are options passed to the mfks *driver*
(i.e. ``mkfs.ext4``) rather than ``mkfs`` itself (i.e. arguments
come after the initial ``mkfs -t <fstype>`` argument). You also
need to be careful with quoting. Can also set ``MKFS_OPTS``.
By default, ``disk-image-create`` uses a 4k byte-to-inode ratio
when creating the filesystem in the image. This allows large
'whole-system' images to utilize several TB disks without
exhausting inodes. In contrast, when creating images intended for
tenant instances, this ratio consumes more disk space than an
end-user would expect (e.g. a 50GB root disk has 47GB available).
If the image is intended to run within a tens to hundrededs of
gigabyte disk, setting the byte-to-inode ratio to the ext4 default
of 16k will allow for more usable space on the instance. The
default can be overridden by passing ``'-i 16384'`` as a
``--mkfs-options`` argument.
``--max-online-resize``
Only valid for ``FS_TYPE==ext4``; this value sets the maximum
filesystem blocks when resizing. Can also set
``MAX_ONLINE_RESIZE``.
``--root-label``
The file-system label specified when creating the root file system.
Defaults to ``cloudimg-rootfs`` for ``ext4`` and ``img-rootfs`` for
``xfs``. Can also set ``ROOT_LABEL``.
Speedups
--------