Configuration Specification

The configuration is a YAML document conforming to the following specification, with italicized entries being optional:

  • ignition (object): metadata about the configuration itself.
    • config (objects): options related to the configuration.
      • append (list of objects): a list of the configs to be appended to the current config.
        • source (string): the URL of the config. Supported schemes are http and https. Note: When using http, it is advisable to use the verification option to ensure the contents haven't been modified.
        • verification (object): options related to the verification of the config.
          • hash (object): the hash of the config
            • function (string): the function used to hash the config. Supported functions are sha512.
            • sum (string): the resulting sum of the hash applied to the contents.
      • replace (object): the config that will replace the current.
        • source (string): the URL of the config. Supported schemes are http and https. Note: When using http, it is advisable to use the verification option to ensure the contents haven't been modified.
        • verification (object): options related to the verification of the config.
          • hash (object): the hash of the config
            • function (string): the function used to hash the config. Supported functions are sha512.
            • sum (string): the resulting sum of the hash applied to the contents.
  • storage (object): describes the desired state of the system's storage devices.
    • disks (list of objects): the list of disks to be configured and their options.
      • device (string): the absolute path to the device. Devices are typically referenced by the /dev/disk/by-* symlinks.
      • wipe_table (boolean): whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact.
      • partitions (list of objects): the list of partitions and their configuration for this particular disk.
        • label (string): the PARTLABEL for the partition.
        • number (integer): the partition number, which dictates it's position in the partition table (one-indexed). If zero, use the next available partition slot.
        • size (integer): the size of the partition (in sectors). If zero, the partition will fill the remainder of the disk.
        • start (integer): the start of the partition (in sectors). If zero, the partition will be positioned at the earliest available part of the disk.
        • type_guid (string): the GPT partition type GUID. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data).
    • raid (list of objects): the list of RAID arrays to be configured.
      • name (string): the name to use for the resulting md device.
      • level (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.).
      • devices (list of strings): the list of devices (referenced by their absolute path) in the array.
      • spares (integer): the number of spares (if applicable) in the array.
    • filesystems (list of objects): the list of filesystems to be configured and/or used in the "files" section. Either "mount" or "path" needs to be specified.
      • name (string): the identifier for the filesystem, internal to Ignition. This is only required if the filesystem needs to be referenced in the "files" section.
      • mount (object): contains the set of mount and formatting options for the filesystem. A non-null entry indicates that the filesystem should be mounted before it is used by Ignition.
        • device (string): the absolute path to the device. Devices are typically referenced by the /dev/disk/by-* symlinks.
        • format (string): the filesystem format (ext4, btrfs, or xfs).
        • create (object): contains the set of options to be used when creating the filesystem. A non-null entry indicates that the filesystem shall be created.
          • force (boolean): whether or not the create operation shall overwrite an existing filesystem.
          • options (list of strings): any additional options to be passed to the format-specific mkfs utility.
      • path (string): the mount-point of the filesystem. A non-null entry indicates that the filesystem has already been mounted by the system at the specified path. This is really only useful for "/sysroot".
    • files (list of objects): the list of files, rooted in this particular filesystem, to be written.
      • filesystem (string): the internal identifier of the filesystem. This matches the last filesystem with the given identifier.
      • path (string): the absolute path to the file.
      • contents (object): options related to the contents of the file.
        • inline (string): the contents of the file.
        • remote (object): options related to the fetching of remote file contents.
          • compression (string): the type of compression used on the contents (null or gzip)
          • url (string): the URL of the file contents. Supported schemes are http and data. Note: When using http, it is advisable to use the verification option to ensure the contents haven't been modified.
          • verification (object): options related to the verification of the file contents.
            • hash (object): the hash of the config
              • function (string): the function used to hash the config. Supported functions are sha512.
              • sum (string): the resulting sum of the hash applied to the contents.
      • mode (integer): the file's permission mode.
      • user (object): specifies the file's owner.
        • id (integer): the user ID of the owner.
      • group (object): specifies the group of the owner.
        • id (integer): the group ID of the owner.
  • systemd (object): describes the desired state of the systemd units.
    • units (list of objects): the list of systemd units.
      • name (string): the name of the unit. This must be suffixed with a valid unit type (e.g. "thing.service").
      • enable (boolean): whether or not the service shall be enabled. When true, the service is enabled. In order for this to have any effect, the unit must have an install section.
      • mask (boolean): whether or not the service shall be masked. When true, the service is masked by symlinking it to /dev/null.
      • contents (string): the contents of the unit.
      • dropins (list of objects): the list of drop-ins for the unit.
        • name (string): the name of the drop-in. This must be suffixed with ".conf".
        • contents (string): the contents of the drop-in.
  • networkd (object): describes the desired state of the networkd files.
    • units (list of objects): the list of networkd files.
      • name (string): the name of the file. This must be suffixed with a valid unit type (e.g. "00-eth0.network").
      • contents (string): the contents of the networkd file.
  • passwd (object): describes the desired additions to the passwd database.
    • users (list of objects): the list of accounts to be added.
      • name (string): the username for the account.
      • password_hash (string): the encrypted password for the account.
      • ssh_authorized_keys (list of strings): a list of SSH keys to be added to the user's authorized_keys.
      • create (object): contains the set of options to be used when creating the user. A non-null entry indicates that the user account shall be created.
        • uid (integer): the user ID of the new account.
        • gecos (string): the GECOS field of the new account.
        • home_dir (string): the home directory of the new account.
        • no_create_home (boolean): whether or not to create the user's home directory.
        • primary_group (string): the name or ID of the primary group of the new account.
        • groups (list of strings): the list of supplementary groups of the new account.
        • no_user_group (boolean): whether or not to create a group with the same name as the user.
        • no_log_init (boolean): whether or not to add the user to the lastlog and faillog databases.
        • shell (string): the login shell of the new account.
    • groups (list of objects): the list of groups to be added.
      • name (string): the name of the group.
      • gid (integer): the group ID of the new group.
      • password_hash (string): the encrypted password of the new group.