Configuration Specification v3.0.0
配置规范 v3.0.0

The Ignition configuration is a JSON document conforming to the following specification, with italicized entries being optional:
点火配置是符合以下规范的 JSON 文档，其中斜体条目是可选的：

• ignition (object): metadata about the configuration itself.
  点火（对象）：关于配置本身的元数据。
  • version (string): the semantic version number of the spec. The spec version must be compatible with the latest version (3.0.0). Compatibility requires the major versions to match and the spec version be less than or equal to the latest version. -experimental versions compare less than the final version with the same number, and previous experimental versions are not accepted.
    版本（字符串）：规范的语义版本号。规范版本必须与最新版本兼容（ 3.0.0 ）。兼容性要求主要版本匹配，并且规范版本小于或等于最新版本。 -experimental 版本比具有相同数字的最终版本小，并且不接受以前的实验性版本。
  • config (object): options related to the configuration.
    配置（对象）：与配置相关的选项。
    • merge (list of objects): a list of the configs to be merged to the current config.
      合并（对象列表）：要合并到当前配置的配置列表。
      • source (string): the URL of the config. Supported schemes are http, https, tftp, s3, and data. When using http, it is advisable to use the verification option to ensure the contents haven’t been modified.
        源（字符串）：配置的 URL。支持的方案有 http ， https ， tftp ， s3 和 data 。当使用 http 时，建议使用验证选项以确保内容未被修改。
      • verification (object): options related to the verification of the config.
        验证（对象）：与配置验证相关的选项。
        • hash (string): the hash of the config, in the form <type>-<value> where type is sha512.
          哈希（字符串）：配置的哈希值，格式为 <type>-<value> ，其中类型为 sha512 。
    • replace (object): the config that will replace the current.
      替换（对象）：将替换当前配置的配置。
      • source (string): the URL of the config. Supported schemes are http, https, tftp, s3, and data. When using http, it is advisable to use the verification option to ensure the contents haven’t been modified.
        源（字符串）：配置的 URL。支持的方案有 http ， https ， tftp ， s3 和 data 。当使用 http 时，建议使用验证选项以确保内容未被修改。
      • verification (object): options related to the verification of the config.
        验证（对象）：与配置验证相关的选项。
        • hash (string): the hash of the config, in the form <type>-<value> where type is sha512.
          哈希（字符串）：配置的哈希值，格式为 <type>-<value> ，其中类型为 sha512 。
  • timeouts (object): options relating to http timeouts when fetching files over http or https.
    超时（对象）：在通过 http 或 https 获取文件时与 http 超时相关的选项。
    • httpResponseHeaders (integer): the time to wait (in seconds) for the server’s response headers (but not the body) after making a request. 0 indicates no timeout. Default is 10 seconds.
      httpResponseHeaders（整数）：在发出请求后等待服务器响应标头（但不包括正文）的时间（以秒为单位）。 0 表示无超时。默认为 10 秒。
    • httpTotal (integer): the time limit (in seconds) for the operation (connection, request, and response), including retries. 0 indicates no timeout. Default is 0.
      httpTotal（整数）：操作的时间限制（连接、请求和响应），包括重试。 0 表示无超时。默认为 0。
  • security (object): options relating to network security.
    security（对象）：与网络安全相关的选项。
    • tls (object): options relating to TLS when fetching resources over https.
      tls（对象）：在通过 https 获取资源时与 TLS 相关的选项。
      • certificateAuthorities (list of objects): the list of additional certificate authorities (in addition to the system authorities) to be used for TLS verification when fetching over https. All certificate authorities must have a unique source.
        certificateAuthorities（对象列表）：用于在通过 https 获取时进行 TLS 验证的其他证书颁发机构列表（除系统证书颁发机构外）。所有证书颁发机构必须具有唯一的 source 。
        • source (string): the URL of the certificate bundle (in PEM format). The bundle can contain multiple concatenated certificates. Supported schemes are http, https, tftp, s3, and data. When using http, it is advisable to use the verification option to ensure the contents haven’t been modified.
          source（字符串）：证书包的 URL（以 PEM 格式）。该包可以包含多个连接的证书。支持的方案有 http ， https ， tftp ， s3 和 data 。使用 http 时，建议使用验证选项以确保内容未被修改。
        • verification (object): options related to the verification of the certificate bundle.
          验证（对象）：与证书包验证相关的选项。
          • hash (string): the hash of the certificate bundle, in the form <type>-<value> where type is sha512.
            哈希（字符串）：证书包的哈希值，格式为 <type>-<value> ，其中类型为 sha512 。
• 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. Every entry must have a unique device.
    磁盘（对象列表）：要配置的磁盘列表及其选项。每个条目必须具有唯一的 device 。
    • device (string): the absolute path to the device. Devices are typically referenced by the /dev/disk/by-* symlinks.
      设备（字符串）：设备的绝对路径。设备通常由 /dev/disk/by-* 符号链接引用。
    • wipeTable (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.
      清除表（布尔值）：是否清除分区表。当为 true 时，在进行任何进一步操作之前会擦除分区表。否则，现有条目将保持不变。
    • partitions (list of objects): the list of partitions and their configuration for this particular disk. Every partition must have a unique number, or if 0 is specified, a unique label.
      分区 (对象列表): 此特定磁盘的分区及其配置列表。每个分区必须具有唯一的 number ，或者如果指定为 0，则必须具有唯一的 label 。
      • label (string): the PARTLABEL for the partition.
        标签 (字符串): 分区的 PARTLABEL。
      • number (integer): the partition number, which dictates its position in the partition table (one-indexed). If zero, use the next available partition slot.
        编号 (整数): 分区号，决定其在分区表中的位置（从 1 开始计数）。如果为零，则使用下一个可用的分区槽位。
      • sizeMiB (integer): the size of the partition (in mebibytes). If zero, the partition will be made as large as possible.
        sizeMiB（整数）：分区的大小（以 mebibytes 为单位）。如果为零，则分区将尽可能大。
      • startMiB (integer): the start of the partition (in mebibytes). If zero, the partition will be positioned at the start of the largest block available.
        startMiB（整数）：分区的起始位置（以 mebibytes 为单位）。如果为零，则分区将定位在可用最大块的开头。
      • typeGuid (string): the GPT partition type GUID. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data).
        typeGuid（字符串）：GPT 分区类型 GUID。如果省略，将使用默认值 0FC63DAF-8483-4772-8E79-3D69D8477DE4（Linux 文件系统数据）。
      • guid (string): the GPT unique partition GUID.
        guid（字符串）：GPT 唯一分区 GUID。
      • wipePartitionEntry (boolean): if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead.
        wipePartitionEntry（布尔值）：如果为 true，则 Ignition 将覆盖现有分区，如果与配置不匹配。如果为 false（默认），Ignition 将失败。
      • shouldExist (boolean): whether or not the partition with the specified number should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on wipePartitionEntry. If false number must be specified and non-zero and label, start, size, guid, and typeGuid must all be omitted.
        shouldExist（布尔值）：指定的 number 分区是否应存在。如果省略，默认为 true。如果为 false，Ignition 将删除指定的分区或失败，取决于 wipePartitionEntry 。如果为 false，必须指定 number 且非零， label ， start ， size ， guid 和 typeGuid 必须全部省略。
  • raid (list of objects): the list of RAID arrays to be configured. Every RAID array must have a unique name.
    RAID（对象列表）：要配置的 RAID 阵列列表。每个 RAID 阵列必须具有唯一的 name 。
    • name (string): the name to use for the resulting md device.
      名称（字符串）：用于生成的 md 设备的名称。
    • level (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.).
      等级（字符串）：阵列的冗余级别（例如线性、raid1、raid5 等）。
    • 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.
      备用（整数）：数组中备用的数量（如果适用）。
    • options (list of strings): any additional options to be passed to mdadm.
      选项（字符串列表）：要传递给 mdadm 的任何附加选项。
  • filesystems (list of objects): the list of filesystems to be configured. device and format need to be specified. Every filesystem must have a unique device.
    文件系统（对象列表）：要配置的文件系统列表。需要指定 device 和 format 。每个文件系统必须具有唯一的 device 。
    • device (string): the absolute path to the device. Devices are typically referenced by the /dev/disk/by-* symlinks.
      设备（字符串）：设备的绝对路径。设备通常由 /dev/disk/by-* 符号链接引用。
    • format (string): the filesystem format (ext4, btrfs, xfs, vfat, or swap).
      格式（字符串）：文件系统格式（ext4、btrfs、xfs、vfat 或 swap）。
    • path (string): the mount-point of the filesystem while Ignition is running relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but it is encouraged to make it the same.
      路径（字符串）：Ignition 运行时文件系统的挂载点，相对于将要挂载根文件系统的位置。这不一定与实际根目录中应该挂载的位置相同，但建议使其相同。
    • wipeFilesystem (boolean): whether or not to wipe the device before filesystem creation, see Ignition’s documentation on filesystems for more information. Defaults to false.
      wipeFilesystem（布尔值）：在创建文件系统之前是否擦除设备，请参阅 Ignition 关于文件系统的文档以获取更多信息。默认值为 false。
    • label (string): the label of the filesystem.
      标签（字符串）：文件系统的标签。
    • uuid (string): the uuid of the filesystem.
      文件系统的 uuid（字符串）。
    • options (list of strings): any additional options to be passed to the format-specific mkfs utility.
      附加选项列表，用于传递给特定格式的 mkfs 实用程序。
  • files (list of objects): the list of files to be written. Every file, directory and link must have a unique path.
    要写入的文件列表。每个文件、目录和链接必须具有唯一的 path 。
    • path (string): the absolute path to the file.
      路径（字符串）：文件的绝对路径。
    • overwrite (boolean): whether to delete preexisting nodes at the path. contents must be specified if overwrite is true. Defaults to false.
      覆盖（布尔值）：是否删除路径上预先存在的节点。如果为真，则必须指定 contents 。默认为 false。
    • contents (object): options related to the contents of the file.
      内容（对象）：与文件内容相关的选项。
      • source (string): the URL of the file. Supported schemes are http, https, tftp, s3, and data. When using http, it is advisable to use the verification option to ensure the contents haven’t been modified. If source is omitted and a regular file already exists at the path, Ignition will do nothing. If source is omitted and no file exists, an empty file will be created.
        源（字符串）：文件的 URL。支持的方案有 http ， https ， tftp ， s3 和 data 。当使用 http 时，建议使用验证选项以确保内容未被修改。如果省略源并且路径处已经存在常规文件，则 Ignition 将不执行任何操作。如果省略源并且不存在文件，则将创建一个空文件。
      • compression (string): the type of compression used on the file (null or gzip). Compression cannot be used with S3.
        压缩（字符串）：文件使用的压缩类型（null 或 gzip）。无法在 S3 中使用压缩。
      • verification (object): options related to the verification of the file.
        验证（对象）：与文件验证相关的选项。
        • hash (string): the hash of the file, in the form <type>-<value> where type is sha512. If compression is specified, the hash describes the decompressed file.
          哈希（字符串）：文件的哈希值，格式为 <type>-<value> ，其中类型为 sha512 。如果指定了 compression ，哈希值描述的是解压后的文件。
    • append (list of objects): list of fragments to be appended to the file. Follows the same structure as contents.
      追加（对象列表）：要追加到文件的片段列表。遵循与 contents 相同的结构。
      • source (string): the URL of the fragment. Supported schemes are http, https, tftp, s3, and data. When using http, it is advisable to use the verification option to ensure the contents haven’t been modified.
        源（字符串）：片段的 URL。支持的方案有 http ， https ， tftp ， s3 ，和 data 。当使用 http 时，建议使用验证选项以确保内容未被修改。
      • compression (string): the type of compression used on the fragment (null or gzip). Compression cannot be used with S3.
        压缩 (字符串): 片段上使用的压缩类型 (null 或 gzip)。无法在 S3 上使用压缩。
      • verification (object): options related to the verification of the fragment.
        验证 (对象): 与片段验证相关的选项。
        • hash (string): the hash of the fragment, in the form <type>-<value> where type is sha512. If compression is specified, the hash describes the decompressed fragment.
          哈希 (字符串): 片段的哈希值，格式为 <type>-<value> ，其中类型为 sha512 。如果指定了 compression ，哈希值描述的是解压后的片段。
    • mode (integer): the file’s permission mode. Note that the mode must be properly specified as a decimal value (i.e. 0644 -> 420). Setuid/setgid/sticky bits are not supported. If not specified, the permission mode for files defaults to 0644 or the existing file’s permissions if overwrite is false, contents is unspecified, and a file already exists at the path.
      模式（整数）：文件的权限模式。请注意，模式必须正确指定为十进制值（即 0644 -> 420）。不支持 Setuid/setgid/sticky 位。如果未指定，则文件的权限模式默认为 0644，或者如果 overwrite 为 false， contents 未指定，并且路径处已存在文件，则使用现有文件的权限。
    • user (object): specifies the file’s owner.
      用户（对象）：指定文件的所有者。
      • id (integer): the user ID of the owner.
        ID（整数）：所有者的用户 ID。
      • name (string): the user name of the owner.
        name（字符串）：所有者的用户名。
    • group (object): specifies the file’s group.
      组（对象）：指定文件的组。
      • id (integer): the group ID of the group.
        ID（整数）：组的组 ID。
      • name (string): the group name of the group.
        名称（字符串）：组的组名称。
  • directories (list of objects): the list of directories to be created. Every file, directory, and link must have a unique path.
    目录（对象列表）：要创建的目录列表。每个文件、目录和链接必须具有唯一的 path 。
    • path (string): the absolute path to the directory.
      路径（字符串）：目录的绝对路径。
    • overwrite (boolean): whether to delete preexisting nodes at the path. If false and a directory already exists at the path, Ignition will only set its permissions. If false and a non-directory exists at that path, Ignition will fail. Defaults to false.
      覆盖（布尔值）：是否删除路径上已存在的节点。如果为 false，并且路径上已经存在一个目录，Ignition 只会设置其权限。如果为 false，并且路径上存在一个非目录节点，Ignition 将会失败。默认为 false。
    • mode (integer): the directory’s permission mode. Note that the mode must be properly specified as a decimal value (i.e. 0755 -> 493). Setuid/setgid/sticky bits are not supported. If not specified, the permission mode for directories defaults to 0755 or the mode of an existing directory if overwrite is false and a directory already exists at the path.
      模式（整数）：目录的权限模式。请注意，模式必须以十进制值正确指定（即 0755 -> 493）。不支持 Setuid/setgid/sticky 位。如果未指定，则目录的权限模式默认为 0755，或者如果 overwrite 为 false 且路径上已经存在一个目录，则为现有目录的模式。
    • user (object): specifies the directory’s owner.
      用户（对象）：指定目录的所有者。
      • id (integer): the user ID of the owner.
        ID（整数）：所有者的用户 ID。
      • name (string): the user name of the owner.
        name（字符串）：所有者的用户名。
    • group (object): specifies the directory’s group.
      group（对象）：指定目录的组。
      • id (integer): the group ID of the group.
        ID（整数）：组的组 ID。
      • name (string): the group name of the group.
        名称（字符串）：组的组名称。
  • links (list of objects): the list of links to be created. Every file, directory, and link must have a unique path.
    链接（对象列表）：要创建的链接列表。每个文件、目录和链接必须具有唯一的 path 。
    • path (string): the absolute path to the link
      路径（字符串）：链接的绝对路径
    • overwrite (boolean): whether to delete preexisting nodes at the path. If overwrite is false and a matching link exists at the path, Ignition will only set the owner and group. Defaults to false.
      覆盖（布尔值）：是否删除路径上已存在的节点。如果覆盖为 false 并且路径上存在匹配的链接，Ignition 只会设置所有者和组。默认为 false。
    • user (object): specifies the owner for a symbolic link. Ignored for hard links.
      用户（对象）：指定符号链接的所有者。对于硬链接不起作用。
      • id (integer): the user ID of the owner.
        ID（整数）：所有者的用户 ID。
      • name (string): the user name of the owner.
        name（字符串）：所有者的用户名。
    • group (object): specifies the group for a symbolic link. Ignored for hard links.
      group（对象）：指定符号链接的组。对于硬链接不起作用。
      • id (integer): the group ID of the group.
        ID（整数）：组的组 ID。
      • name (string): the group name of the group.
        名称（字符串）：组的组名称。
    • target (string): the target path of the link
      target（字符串）：链接的目标路径。
    • hard (boolean): a symbolic link is created if this is false, a hard one if this is true.
      硬 (布尔值): 如果为 false，则创建一个符号链接，如果为 true，则创建一个硬链接。
• systemd (object): describes the desired state of the systemd units.
  systemd (对象): 描述 systemd 单元的期望状态。
  • units (list of objects): the list of systemd units. Every unit must have a unique name.
    单元 (对象列表): systemd 单元的列表。每个单元必须具有唯一的 name 。
    • name (string): the name of the unit. This must be suffixed with a valid unit type (e.g. “thing.service”).
      名称（字符串）：单位的名称。必须以有效的单位类型结尾（例如“thing.service”）。
    • enabled (boolean): whether or not the service shall be enabled. When true, the service is enabled. When false, the service is disabled. When omitted, the service is unmodified. In order for this to have any effect, the unit must have an install section.
      启用（布尔值）：服务是否应启用。为 true 时，服务已启用。为 false 时，服务已禁用。如果省略，则服务未修改。为了使其生效，单位必须有一个安装部分。
    • mask (boolean): whether or not the service shall be masked. When true, the service is masked by symlinking it to /dev/null. When false, the service is unmasked by deleting the symlink to /dev/null if it exists.
      掩码（布尔值）：服务是否应该被掩盖。为 true 时，通过将其符号链接到 /dev/null 来掩盖服务。为 false 时，通过删除符号链接 /dev/null （如果存在）来取消掩盖服务。
    • contents (string): the contents of the unit.
      内容（字符串）：单元的内容。
    • dropins (list of objects): the list of drop-ins for the unit. Every drop-in must have a unique name.
      dropins（对象列表）：单元的插件列表。每个插件必须具有唯一的 name 。
      • name (string): the name of the drop-in. This must be suffixed with “.conf”.
        名称（字符串）：插件的名称。必须以“.conf”结尾。
      • contents (string): the contents of the drop-in.
        内容（字符串）：插入内容的内容。
• passwd (object): describes the desired additions to the passwd database.
  密码（对象）：描述要添加到密码数据库的内容。
  • users (list of objects): the list of accounts that shall exist. All users must have a unique name.
    用户（对象列表）：应存在的帐户列表。所有用户必须具有唯一的 name 。
    • name (string): the username for the account.
      名称（字符串）：账户的用户名。
    • passwordHash (string): the hashed password for the account.
      密码哈希（字符串）：账户的哈希密码。
    • sshAuthorizedKeys (list of strings): a list of SSH keys to be added as an SSH key fragment at .ssh/authorized_keys.d/ignition in the user’s home directory. All SSH keys must be unique.
      SSH 授权密钥（字符串列表）：要添加为用户主目录中的 SSH 密钥片段的 SSH 密钥列表。所有 SSH 密钥必须是唯一的。
    • uid (integer): the user ID of the account.
      uid（整数）：账户的用户 ID。
    • gecos (string): the GECOS field of the account.
      gecos（字符串）：账户的 GECOS 字段。
    • homeDir (string): the home directory of the account.
      homeDir（字符串）：账户的主目录。
    • noCreateHome (boolean): whether or not to create the user’s home directory. This only has an effect if the account doesn’t exist yet.
      noCreateHome（布尔值）：是否创建用户的主目录。仅当帐户尚不存在时才会生效。
    • primaryGroup (string): the name of the primary group of the account.
      primaryGroup（字符串）：帐户的主组名称。
    • groups (list of strings): the list of supplementary groups of the account.
      groups（字符串列表）：帐户的附加组列表。
    • noUserGroup (boolean): whether or not to create a group with the same name as the user. This only has an effect if the account doesn’t exist yet.
      noUserGroup（布尔值）：是否创建与用户同名的组。仅当帐户尚不存在时才会生效。
    • noLogInit (boolean): whether or not to add the user to the lastlog and faillog databases. This only has an effect if the account doesn’t exist yet.
      noLogInit（布尔值）：是否将用户添加到 lastlog 和 faillog 数据库。仅当帐户尚不存在时才会生效。
    • shell (string): the login shell of the new account.
      shell（字符串）：新帐户的登录 shell。
    • system (boolean): whether or not this account should be a system account. This only has an effect if the account doesn’t exist yet.
      系统（布尔值）：此帐户是否应为系统帐户。仅当帐户尚不存在时才会生效。
  • groups (list of objects): the list of groups to be added. All groups must have a unique name.
    组（对象列表）：要添加的组列表。所有组必须具有唯一的 name 。
    • name (string): the name of the group.
      名称（字符串）：组的名称。
    • gid (integer): the group ID of the new group.
      gid（整数）：新组的组 ID。
    • passwordHash (string): the hashed password of the new group.
      passwordHash（字符串）：新组的哈希密码。
    • system (boolean): whether or not the group should be a system group. This only has an effect if the group doesn’t exist yet.
      system（布尔值）：该组是否应为系统组。仅当该组尚不存在时才会生效。