``CONSFIGURATOR.PROPERTY.DISK``
===============================
API reference
-------------

Volumes
~~~~~~~

Class: ``DISK:VOLUME``
^^^^^^^^^^^^^^^^^^^^^^

Something which contains filesystems and/or other volumes.

Generic function: ``DISK:COPY-VOLUME-AND-CONTENTS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:copy-volume-and-contents volume &rest initialisations &key &allow-other-keys)``

Make a fresh copy of VOLUME, shallowly, except for the VOLUME-CONTENTS of
volume, which is recursively copied.  Keyword arguments may be used to
subsequently replace the copied values of some slots.

Generic function: ``DISK:SUBVOLUMES-OF-TYPE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:subvolumes-of-type type volume)``

Recursively examine VOLUME and its VOLUME-CONTENTS and return a list of all
volumes encountered whose type is a subtype of TYPE.
Returns as a second value a corresponding list of the immediate parents of
each returned volume.

Generic function: ``DISK:ALL-SUBVOLUMES``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:all-subvolumes volume)``

Recursively examine VOLUME and its VOLUME-CONTENTS and return a list of all
volumes encountered.

Function: ``DISK:REQUIRE-VOLUMES-DATA``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:require-volumes-data volumes)``

Call REQUIRE-DATA on each item of prerequisite data requires for opening
and/or creating each of VOLUMES.

Called by property :HOSTATTRS subroutines.

Opened volumes
~~~~~~~~~~~~~~

Class: ``DISK:OPENED-VOLUME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A VOLUME object which has been made directly accessible as a block device.

Class: ``DISK:PHYSICAL-DISK``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A physical disk drive attached to the machine, which always has a
corresponding block device in /dev available to access it.  Should be used for
whole disks, not partitions (e.g. /dev/sda, not /dev/sda1).

Disk images
~~~~~~~~~~~

Class: ``DISK:DISK-IMAGE``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Raw disk images
~~~~~~~~~~~~~~~

Class: ``DISK:RAW-DISK-IMAGE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A raw disk image, customarily given an extension of .img, suitable for
directly writing out with dd(1).

Partitioned block devices and their partitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Class: ``DISK:PARTITIONED-VOLUME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A device with a GPT partition table and partitions.

Class: ``DISK:PARTITION``
^^^^^^^^^^^^^^^^^^^^^^^^^

A GPT partition.

LVM
~~~

Class: ``DISK:LVM-PHYSICAL-VOLUME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An LVM physical volume.
We do not specify what logical volumes it contains.

Class: ``DISK:LVM-LOGICAL-VOLUME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Filesystems
~~~~~~~~~~~

Class: ``DISK:FILESYSTEM``
^^^^^^^^^^^^^^^^^^^^^^^^^^

A block device containing a filesystem, which can be mounted.

Class: ``DISK:EXT4-FILESYSTEM``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Class: ``DISK:FAT32-FILESYSTEM``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Other volumes which can be made accessible as block devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Class: ``DISK:LUKS-CONTAINER``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Class: ``DISK:LINUX-SWAP``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Recursive operations
~~~~~~~~~~~~~~~~~~~~

Macro: ``DISK:WITH-OPENED-VOLUMES``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:with-opened-volumes volumes &body propapps)``

Macro property combinator.  Where each of VOLUMES is a VOLUME which may be
opened by calling OPEN-VOLUME with NIL as the second argument, recursively
open each of VOLUMES and any contents thereof, apply PROPAPPS, and, unless
LEAVE-OPEN, close all volumes that were opened.

MOUNT-BELOW specifies a pathname to prefix to mount points when opening
FILESYSTEM volumes.  During the application of PROPAPPS, all
'DISK:OPENED-VOLUMES and 'DISK:OPENED-VOLUME-PARENTS connattrs are replaced
with lists of the volumes that were opened/already open and corresponding
immediate parent volumes.

Properties
~~~~~~~~~~

Macro: ``DISK:HAS-VOLUMES``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:has-volumes &rest volume-specifications)``

Specify non-removable volumes normally accessible to the kernel on this host.

The order of the list of volumes is significant: it is the order in which
attempts to open all of the volumes should be made.  So, for example, any LVM
volume groups should occur later in the list than the partitions containing
the LVM physical volumes corresponding to those volume groups.

Property: ``DISK:RAW-IMAGE-BUILT-FOR``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:raw-image-built-for options host image-pathname &key rebuild)``

Build a raw disk image for HOST at IMAGE-PATHNAME.
The image corresponds to the first DISK:PHYSICAL-DISK entry in the host's
volumes, as specified using DISK:HAS-VOLUMES; there must be at least one such
entry.  Other DISK:PHYSICAL-DISK entries will be ignored, so ensure that none
of the properties of the host will write to areas of the filesystem where
filesystems stored on other physical disks would normally be mounted.

OPTIONS will be passed on to CHROOT:OS-BOOTSTRAPPED-FOR, which see.

In most cases you will need to ensure that HOST has properties which do at
least the following:

  - declare the host's OS

  - install a kernel

  - install the binaries/packages needed to install the host's bootloader to
    its volumes (usually with INSTALLER:BOOTLOADER-BINARIES-INSTALLED).

Unless REBUILD, the image will not be repartitioned even if the specification
of the host's volumes changes, although the contents of the image's
filesystems will be incrementally updated when other properties change.

Property: ``DISK:FIRST-DISK-INSTALLED-FOR``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:first-disk-installed-for options host device-file &key chroot)``

Install HOST to the DISK:PHYSICAL-DISK accessible at DEVICE-FILE.
**THIS PROPERTY UNCONDITIONALLY FORMATS DISKS, POTENTIALLY DESTROYING DATA,
EACH TIME IT IS APPLIED.**

Do not apply in DEFHOST.  Apply with DEPLOY-THESE/HOSTDEPLOY-THESE.

The DISK:VOLUME-CONTENTS of the first DISK:PHYSICAL-DISK entry in the host's
volumes, as specified using DISK:HAS-VOLUMES, will be created at DEVICE-FILE;
there must be at least one such DISK:PHYSICAL-DISK entry.  Other
DISK:PHYSICAL-DISK entries will be ignored, so ensure that none of the
properties of the host will write to areas of the filesystem where filesystems
stored on other physical disks would normally be mounted.

OPTIONS will be passed on to CHROOT:OS-BOOTSTRAPPED-FOR, which see.

In most cases you will need to ensure that HOST has properties which do at
least the following:

  - declare the host's OS

  - install a kernel

  - install the binaries/packages needed to install the host's bootloader to
    its volumes (usually with INSTALLER:BOOTLOADER-BINARIES-INSTALLED).

If CHROOT, an intermediate chroot is bootstrapped at CHROOT, and HOST's
properties are applied to that.  Otherwise, HOST's OS is bootstrapped directly
to DEVICE-FILE.  It's useful to supply CHROOT when you expect to install the
same HOST to a number of physical disks.  It also makes it faster to try
deploying again if failures occur during the application of HOST's properties.

Applying this property is similar to applying DISK:RAW-IMAGE-BUILT-FOR and
then immediately dd'ing out the image to DEVICE-FILE.  The advantage of this
property is that there is no need to resize filesystems to fill the size of
the host's actual physical disk upon first boot.

Property: ``DISK:VOLUMES-INSTALLED-FOR``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:volumes-installed-for options host &key chroot leave-open)``

Install HOST to its volumes, as specified using DISK:HAS-VOLUMES.
**THIS PROPERTY UNCONDITIONALLY FORMATS DISKS, POTENTIALLY DESTROYING DATA,
EACH TIME IT IS APPLIED.**

Do not apply in DEFHOST.  Apply with DEPLOY-THESE/HOSTDEPLOY-THESE.

OPTIONS will be passed on to CHROOT:OS-BOOTSTRAPPED-FOR, which see.

In most cases you will need to ensure that HOST has properties which do at
least the following:

  - declare the host's OS

  - install a kernel

  - install the binaries/packages needed to install the host's bootloader to
    its volumes (usually with INSTALLER:BOOTLOADER-BINARIES-INSTALLED).

If CHROOT, an intermediate chroot is bootstrapped at CHROOT, and HOST's
properties are applied to that.  Otherwise, HOST's OS is bootstrapped directly
to its volumes.  This parameter is useful for the case of installing HOST from
a live system which might not have network access.  See "Tutorial: OS
installation" in the Consfigurator user's manual.

If LEAVE-OPEN, HOST's volumes will not be closed.  This allows you to inspect
the result of the installation.  If you want to run this property again, you
should first manually close all the volumes.

Property: ``DISK:DEBIAN-LIVE-ISO-BUILT``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:debian-live-iso-built options image-pathname properties)``

Build a Debian Live hybrid ISO at IMAGE-PATHNAME for a host with properties
PROPERTIES, which should specify, at a minimum, the operating system for the
live system.  OPTIONS is a plist of keyword parameters:

  - :CHROOT-OPTIONS -- passed on to CHROOT:OS-BOOTSTRAPPED-FOR, which see.

Currently only BIOS boot is implemented.

Property: ``DISK:HOST-LOGICAL-VOLUMES-EXIST``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:host-logical-volumes-exist)``

Create missing logical volumes, like LVM logical volumes and BTRFS
subvolumes, as specified by DISK:HAS-VOLUMES.  Does not delete or overwrite
anything, aside from editing /etc/fstab in some cases.  Intended to make it
easy to add new logical volumes by just editing the volumes specification.

For logical volumes containing instances of FILESYSTEM with a specified
MOUNT-POINT, ensure there's an /etc/fstab entry and try to mount.

Currently only handling of LVM logical volumes is implemented.

Utilities
~~~~~~~~~

Macro: ``DISK:VOLUMES``
^^^^^^^^^^^^^^^^^^^^^^^

``(disk:volumes &body volume-specifications)``

Return a list of instances of VOLUME, one for each element of
VOLUME-SPECIFICATIONS.  Each of VOLUME-SPECIFICATIONS is an (unquoted) list of
the form (TYPE &REST INITARGS).

TYPE is a symbol naming the volume type to be initialised.  If the symbol does
not name a subclass of VOLUME, it will be replaced with a symbol of the same
name in the DISK package; this allows type names to be used unqualified.

INITARGS is an even-length plist, possibly with a final additional element,
which is either another volume specification or an (unquoted) list of volume
specifications.  This becomes the VOLUME-CONTENTS of the VOLUME.

The following keys in INITARGS are handled specially:

  - :VOLUME-SIZE -- may be a string like "100M", "2G", "1T" which will
    be converted into a whole number of mebibytes.  "M", "G", and "T"
    are currently supported.

Example usage:

.. code-block:: none

  (volumes
    (physical-disk
     (partitioned-volume
      ((partition
        :partition-typecode #xef00
        (fat32-filesystem
         :volume-size "512M"
         :mount-point #P"/boot/efi"))
       (partition
        (luks-container
         (lvm-physical-volume
          :volume-group "vg_laptop"))))))
    (lvm-logical-volume
       :volume-group "vg_laptop"
       :volume-label "lv_laptop_root"
       (ext4-filesystem :mount-point #P"/")))

Function: ``DISK:GET-PARTITION-UUID``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(disk:get-partition-uuid device)``

Return string of the form "PARTUUID=..." or "UUID=..." for DEVICE.
These values are as returned by lsblk(8).
PARTUUID is preferred to UUID if both are available.
