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:

(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"/")))