Skip to content

kickstart file reference

Jump to bottom
Oliver Kurth edited this page Aug 6, 2024 · 21 revisions

The kickstart file defines a Photon image. It can be used in an ISO installation, or "offline" to build Photon images from scratch.

The kickstart file follows the yaml syntax and can be written in json (which is a subset of yaml).

These are the options:

additional_files (optional)

Contains list of maps from source files (or directories) to destination files (or directories) } to copy to the target system. Source files (directories) will be looked up in search_path list.

Example:

additional_files:
    - resizefs.sh: /usr/local/bin/resizefs.sh
    - resizefs.service: lib/systemd/system/resizefs.service

additional_packages

Same as packages, see below.

additional_rpms_path (optional)

Provide a path containing additional RPMS that are to be bundled into the image.

ansible

A list of configurations to run ansible scripts on the image. Example:

ansible:
    - playbook: /usr/share/ansible/stig-hardening/playbook.yml
      logfile: ansible-stig.log
      verbosity: 2
      extra-vars: "@/usr/share/ansible/stig-hardening/vars-chroot.yml"
      skip-tags:
          - PHTN-50-000245

bootmode (optional)

Sets the boot type to support: EFI, BIOS or both.

  • Acceptable values: bios, efi, dualboot

  • Default value: dualboot for x86_64 and efi for aarch64

  • bios will add a special partition (very first) for first stage grub.

  • efi will add ESP (Efi Special Partition), format is as FAT and copy their EFI binaries including grub.efi

  • dualboot will add two extra partitions for bios and efi modes.

    • This target will support both modes that can be switched in bios settings without extra actions in the OS.

Example:

    bootmode: bios

disk

Deprecated, use disks.

disks

  • Target disks to install into. Contains a map of disk ids, exactly one of them has to be default. These can contain either devices such as /dev/sda, or filenames with sizes. Sizes are in MB units. The disk ids can be referred to in the partitions section, or the default will be used.

Note that for a live (ISO) installation, you need to set a device'. Using filename is only useful when creating images (for example to create OVA images).

Examples:

disks:
    default:
        device: /dev/sda

With a device path:

disks:
    default:
        device: /dev/disk/by-path/pci-0000:03:00.0-scsi-0:0:1:0

Using a disk image:

disks:
    default:
        filename: rootdisk.img
        size: 2048

Multiple disks:

disks:
    default:
        filename: rootdisk.img
        size: 2048
    bigdisk
        filename: bigdisk.img
        size: 100000

eject_cdrom (optional)

  • Eject or not cdrom after installation is completed.
    • Boolean: true or false
    • Default value: true

Example:

eject_cdrom: False

docker (optional)

Allows installation of docker images. Contain a dictionary with one item images, which contains a list of configurations. Each configuration item contains a dict with the required field method, which can be set to either pull or load. If the method is load, the configuration requires another field filename containing an absolute path or a relative path from the current working directory to a docker image that was created using docker save. If the method is pull, the configuration requires another field image containing a docker image name that will be pulled using docker pull from a docker registry.

Example:

docker:
    images:
        - method: pull
          name: photon:5.0
        - method: load
          filename: photon-installer.tar

Additional options for each image:

  • tags is a list of tags to be added to the image
  • drop-tags (boolean) will remove the original name tag of the image. Note that if True, at least one tag needs to be set with tags or the image will be removed.

hostname (optional)

  • Set target host name.
    • Default value: "photon-randomized-string"

Example:

hostname: photon-machine

linux_flavor (optional)

Sets the package name used for the kernel.

linux_flavor: linux

linux_flavor_<arch> (optional)

Sets the package name used for the kernel, specific for an architecture. This takes precedence over linux_flavor for the given architecture.

linux_flavor_aarch64: linux

live (optional)

  • Should be set to false if target system will not be run on host machine. When it set to false, installer will not add EFI boot entries, and will not generate unique machine-id.
    • Boolean: false if "disk" is /dev/loop and true otherwise.

Example:

live: False

log_level (optional)

  • Set installer logging level.
    • Acceptable values: "error", "warning", "info", "debug"
    • Default value: "info" 
log_level: debug

manifest_file (optional)

Name of the manifest file. The installer will create a manifest file containing the configuration file used, the list of packages installed (including their versions), the partitions created and other information. The file will be compressed and copied to /var/log/poi inside the final image.

no_unmount (default: False, optional)

If set to True, directories will not be unmounted when finished. Used for debugging purposes. It is recommended to use:

no_unmount: --param unmount=False

and run the installer with --param=True to set this flag, to avoid saving (and maybe delivering) a config file with the option set.

ostree (optional)

  • Atomic flavor of Photon OS.
  • Define the type of repo data used for installing the OS
  • There are two types:
    1. Default Repo(comes with ISO)
    2. Custom Repo (Remote server)
    • "default_repo": (required)
      • Boolean: true or false
        • true : Default Repo is selected
        • false: Custom Repo is selected
      • Default value: true

Example:

ostree:
    default_repo: True
  • repo_url (Required, Only If Custom Repo is selected)
    • Supported Values: Valid "repo" URL of remote server where repo data exists
  • repo_ref (Required, Only If Custom Repo is selected)
    • Supported Value: Valid "ref" path which was mentioned for creation of Base Tree on remote server

Example:

ostree
    default_repo: False,
    repo_url: http://<ip>:<port>/repo
    repo_ref: photon/4.0/x86_64/minimal

packagelist_file

Contains file name which has a list of packages to install. See also packagelist_files below.

Example:

packagelist_file: packages_minimal.json

packagelist_files

Similar to packagelist_file, but can set a list of multiple package list files.

Example:

packagelist_files:
  - packages_minimal.json
  - packages_stig.json

A package list file is a file in json format, containing a dictionary with the key packages, with a list of packages. Example:

{
    "packages": [
        "acl",
        "bc",
        "bridge-utils",
        ...
    ]
}

Architecture specific packages can be specified with packages_<arch>, for example:

...
    "packages_x86_64": ["linux"]
}

Other keys can be present but will be ignored.

packages

Contains list of packages to install. Similar to specifying file(s) with a list of packages with packagelist_files, but inline.

Example:

packages
  - minimal
  - linux
  - initramfs

partition_type (optional)

  • Set partition table type. Supported values are: "gpt", "msdos".
  • Default value: "gpt"

Example:

partition_type: msdos

partitions (optional)

  • Contains a list of partitions to create.
  • Each partition is a dictionary of the following items:
  • filesystem (optional)
  • Filesystem type.
    • Supported values: swap, ext4, vfat, xfs, btrfs. If not set ext4 will be used.
  • disk_id (optional) If not set, the default from disks (see above) will be used.
  • mountpoint (required for non "swap" partitions)
    • Mount point for the partition.
  • size:
    • Exactly one of size or sizepercent (see below) is required.
    • Size of the partition in MB. If 0 then partition is considered as expansible to fill rest of the disk. Only one expansible partition is allowed.
  • sizepercent:
    • Size of the partition in percent of the total disk space.
    • Only one of size and sizepercent can be set per partition.

Examples:

partitions:
    - mountpoint: /
      size: 0
      filesystem: ext4
    - mountpoint: /boot
      size: 128
      filesystem: ext4
    - mountpoint: /root
      sizepercent: 5
      filesystem: ext4
    - sizepercent: 5
      filesystem: swap
  • mkfs_options: (optional)
    • Additional parameters for the mkfs command as a string
  • fs_options: (optional)
    • fs options to be passed to the mount command as a string

Example:

fs_options: nodev,noexec,nosuid
  • btrfs: (optional)
    • Creates btrfs volumes and subvolumes.
    • Value is a dictionary with 1 required and 1 optional key.
    • label: (optional)
      • Name of the parent volume label.
    • subvols (optional)
      • Subvolumes inside parent volume.

Example:

        disk_id: default
        partitions:
            mountpoint: /
            size: 0
            filesystem: btrfs

Example to create subvols:

    partitions:
        mountpoint: /
        size: 2048
        filesystem: btrfs
        btrfs:
            label: main
            subvols:
                - name: rootfs
                  mountpoint: /root
                - name: home
                  mountpoint: /home
                  subvols:
                      - name: dir
                        mountpoint: dir1
  • lvm: (optional)
    • Will logical volume (LVM) for this partition.
    • Value is a dictionary with 2 required keys:
    • _vg_name (required)
      • Name of a virtual group to put the current partition into.
      • Several partitions may have the same "vg_name"
    • lv_name (required)
      • Unique logical volume name of the partition.

Example, also showing partitions on multiple disks:

partitions:
    - mountpoint: /boot
      size: 128
      filesystem: ext4
    - mountpoint: /
      size: 0
      filesystem: ext4
      lvm:
          vg_name: vg_root_0
          lv_name: lv_root_0
    - size: 0
      filesystem: swap
      disk_id: swap
    - mountpoint: /rpms
      size: 0
      lvm:
          vg_name: vg_rpm_0
          lv_name: lv_rpm_0
      disk_id: rpms
      fs_options:
          - noauto

network: (optional)

Used to configure the network.

  • The syntax roughly follows the cloud-init or netplan configuration, but not all options are supported.

  • version: Set to "2". If set to "1" the legacy config will be used, see below.

  • hostname: set the hostname.

  • ethernets Settings for ethernet interfaces. Each interface has an 'id', which can be any name that may be referenced for example for VLANs. It can be the interface name.

    • Within any id:

      • match : set a way to match this interface. Can be 'name' or 'macaddress'.

      • dhcp4 : boolean, set to true or false

      • dhcp6 : boolean, set to true or false

      • accept-ra : boolean, set to true or false. Whether to accept Router Advertisement for IPv6.

      • addresses : a list of ip addresses (IPv4 or IPv6) with cidr netmask.

      • gateway : the default gateway.

      • nameservers : a dictionary with "addresses" containing a list of name servers, and "search" with a list of search domains.

  • vlans: Settings for VLAN interfaces. Similar to "ethernets" above, but with these additional required settings:

    • id: the VLAN id (integer in the range 1..4094)

    • link : the id of the ethernet interface to use, from the "ethernets" configured. Note that the interface needs a "name" (without wildcards) in its "match". For example "match":"eth0" is allowed, but "match":"e*" is not, or just a macaddress is not allowed.

Example:

network:
    version: "2"
    nameservers:
        addresses:
            - 8.8.8.8
            - 8.8.4.4
    ethernets:
        id0:
            match:
                name: eth0
            dhcp4: True

Example using DHCP on any physical interface with a name starting with "e" (for example "eth0" or "ens33"):

network:
    version: 2
    hostname: photon-machine
    ethernets:
        id0:
            match:
                name: "e*"
            dhcp4: True

Example with the first physical interfaces identified by their MAC address, the second by its name and a VLAN interface using the second physical interface:

network:
  version: '2'
  hostname: photon-machine
  ethernets:
    id0:
      match:
        macaddress: '11:22:33:44:55:66'
      addresses:
        - 192.168.2.58/24
      gateway: 192.168.2.254
    nameservers:
      addresses:
        - 8.8.8.8
        - 8.8.4.4
      search:
        - vmware.com
        - eng.vmware.com
    id1:
      match:
        name: eth1
      addresses:
        - 192.168.4.58/24
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4
        search:
          - vmware.com
          - eng.vmware.com
  vlans:
    vlan0:
      id: 100
      link: id1
      addresses:
        - 192.168.100.58/24
      gateway: 192.168.100.254
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4
        search:
          - vmware.com
          - eng.vmware.com

password (optional)

  • Set root password. It is dictionary of the following items:
    • "text" (required) password plain text ("crypted" : false) or encrypted ("crypted": true)
    • "crypted" (required) Hint on how to interpret "text" content.
    • "age" (optional) Set password expiration date. If not set, then used Photon OS default password aging value.
    • Value: integer. Meanings:
      • Any positive number - password will be expired in so many days from today.
      • Zero (0) - marks password as already expired. root will be asked to change current password during the first login.
      • Minus one (-1) - removes root password expiration date.
    • Default value:
password:
    crypted": true,
    text: "*"

Example:

password:
    crypted: False
    text: changeme
    age: 0

postinstall (optional)

  • Contains a list of lines to be executed as a single script on the target after installation.

Example:

postinstall":
  - #!/bin/sh
  - echo \"Hello World\" > /etc/postinstall

postinstallscripts (optional)

  • Contains list of scripts to execute on the target after installation.
  • Scripts will be looked up in search_path list.

Example:

postinstallscripts:
  - rpi3-custom-patch.sh

preinstall (optional)

  • Contains list of lines to be executed as a single script on the target before installation starts.
  • if ks file defines any value($VALUE) that need to be populated dynamically during runtime then it should be determined and exported in preinstall script.

Example:

disk: $DISK
preinstall
  - #!/bin/sh",
  - ondisk=$(ls -lh /dev/disk/by-path/ | grep 'scsi-0:0:1:0' | cut -d' ' -f 9)
  - export DISK="/dev/disk/by-path/$ondisk"

preinstallscripts (optional)

  • Contains list of scripts to execute on the target before installation starts.
  • Scripts will be looked up in search_path list.

Example:

preinstallscripts
  - find_disk.sh

public_key (optional)

To inject entry to authorized_keys as a string. Setting this variable enables root login in sshd config.

repos

Sets the repositories used for package installation. This is a dictionary with the repo names as keys, containing the repository configurations. The same options as in https://github.com/vmware/tdnf/wiki/Repository-Configuration can be used. The variables $releasever and $basearch can be used for baseurl.

Example:

repos:
    photon:
        name: "Photon 4.0"
        baseurl: https://artifactory.eng.vmware.com/artifactory/photonos-rpm-local/$releasever/photon_updates_$releasever_$basearch/
        enabled: 1
        gpgcheck: 0

search_path (optional)

List of directories to search for additional files and scripts.

Example:

search_path:
  - /home/user
  - /tmp

tdnf_cachedir (optional)

If set, this directory will be used as the cache dir for tdnf. This is useful if the cache can be reused for another image build, or the cached packages can be used for other purposes. It may also save using space in the compressed disk image because the packages will never be written to it, which may consume space even if the files are deleted but the unused blocks are not zero'ed.

Clone this wiki locally