Portal:MicroOS/Ignition

First Boot Configuration

To make your system accessible after booting our prebuild disk images (neither Ignition nor Combustion are run by default when using the DVD) you need to provide a configuration file on first boot. At least a password for root is required. Depending on the variation of openSUSE MicroOS these first boot configuration systems are supported:

Ignition
has its origins in Fedora CoreOS and is fully supported by openSUSE MicroOS. Best choice for beginners. Find a Quick Start Documentation below.
Combustion
is part of openSUSE's MicroOS project and is more powerful and flexible than Ignition and requires bash programming skills. Learn more about it from the Combustion Quick Start Documentation.
Cloud-Init
is used only for the OpenStack Cloud variant of openSUSE MicroOS. Learn more from the Cloud-Init Quick Start Documentation.
Ignition and Combustion scripts can be created using the Ignition & Combustion Config Generator.

Ignition Quick Start

On first boot the system will try to configure itself using Ignition. The configuration is read from a file called config.ign that needs to be stored on an storage media in the directory ignition besides the main disk image containing MicroOS. This configuration storage media can be any of what your virtualization system or your hardware does support, e.g. an ISO-Image, an USB Flash drive or even a floppy disk.

Whatever media you use, the volume label needs to be ignition. On this media, you create a directory ignition containing a file with the name config.ign. The resulting directory structure needs to look like this:

<root directory>
└── ignition
    └── config.ign

Example config.ign:

{
  "ignition": { "version": "3.1.0" },
  "passwd": {
    "users": [
      {
        "name": "root",
        "passwordHash": "pemFK1OejzrTI"
      }
    ]
  }
}

Create the value for the key passwordHash by using the command line

# openssl passwd

which prompts you for a password of your choice. The password from the example above is opensuse.

USB flash drive

Especially on bare metal or the Raspberry Pi and other ARM images the best solution to provide config.ign is on a USB flash drive.

To use this feature:

Format your USB flash drive with any file system supported by MicroOS (e.g. FAT, EXT4, …)
Set the partition label to ignition (lower case; for an EXT4 formatted drive with one partition, use e2label /dev/sdX1 ignition)
Mount that partition
Create the directory structure as mentioned above and add your config.ign

Create an ISO-Image

Using a virtual machine the most generic way to provide config.ign is to create an ISO-Image. Create the directory structure from above by using this commands:

# mkdir -p disk/ignition
# touch disk/ignition/config.ign

Open disk/ignition/config.ign with the editor of your choice and copy & paste the code from the example above.

Create the ISO-Image using mkisofs:

# mkisofs -o ignition.iso -V ignition disk

Now add ignition.iso to your VM and you are ready to go.

Use fw_cfg qemu feature in libvirt

If you use libvirt with qemu/kvm to run your virtual machines, you can make ignition file available by editing libvirt XML for your created VM. You can use virt-manager UI or virsh edit.

Under the <domain> section, insert the following XML section:

 <sysinfo type="fwcfg">
   <entry name="opt/com.coreos/config" file="/location/for/your/file/config.ign"/>
 </sysinfo>

You can also using it at the creation of your VM with virt-install with the --sysinfo option:

 --sysinfo type=fwcfg,entry0.name="opt/com.coreos/config",entry0.file="/location/for/your/file/config.ign" \

Create a Config File using `butane`

Ignition configurations are formatted as JSON, which is quick and easy for a machine to read. However, these files are not easy for humans to read or write. The solution is a two-step configuration process that is friendly for both humans and machines:

Produce a YAML-formatted Butane configuration file.
Run butane to convert the YAML file into a JSON Ignition file.

During the transpilation process, butane verifies the syntax of the YAML file, which can catch errors before you use it to launch MicroOS.

You can run the butane container which works on every system able to run containers or you can install it on a compatible system:

Get the latest version of butane from the Kubic Devel repo:

Using Tumbleweed:

# zypper ar -f https://download.opensuse.org/repositories/devel:/kubic:/ignition/openSUSE_Tumbleweed/ devel_kubic_ignition

Using Leap:

# zypper ar -f 'https://download.opensuse.org/repositories/devel:/kubic:/ignition/openSUSE_Leap_$releasever/' devel_kubic_ignition

Using SLE 15:

# zypper ar -f https://download.opensuse.org/repositories/devel:/kubic:/ignition/SLE_15/ devel_kubic_ignition

then (for all distributions)

# zypper in butane

Invocation

# butane -p -o config.ign config.yaml

Where config.yaml is the YAML input file and config.ign the JSON output file. -p makes the output prettier by adding line breaks and indentation.

Advanced Usage

To learn more about Ignition and its capabilities please continue with the official documentation or check out the examples below for some of the common use cases.

FCC/YAML Examples

Add a password and a SSH key for the root user

variant: fcos
version: 1.0.0
passwd:
  users:
    - name: root
      password_hash: "hash, created with e.g. `openssl passwd -6`"
      ssh_authorized_keys:
        - ssh-rsa long...key user@host

Create new users

Normally, regular user's home directory is located in /home/<username>. Since /home is not mounted by default in the initrd, the mount has to be explicitly defined for user creation to succeed. See Mounts Example for details.

variant: fcos
version: 1.1.0
storage:
  filesystems:
    - path: /home
      device: "Path to the root device such as /dev/sda3, /dev/mmcblk0p2 or /dev/disk/by-label/ROOT"
      format: btrfs
      wipe_filesystem: false
      mount_options:
       - "subvol=/@/home"
passwd:
  users:
   - name: root
     password_hash: "hash, created with e.g. `openssl passwd -6`"
     ssh_authorized_keys:
       - ssh-rsa long...key user@host

Mounts

Default mounted subvolumes are:

/
/var
/etc
/root

To access to other subvolumes or partitions such as /home or /opt, explicitly define define them in your Ignition configuration file.

variant: fcos
version: 1.0.0
storage:
  filesystems:
    - path: /opt
      device: "/dev/sdXY"
      format: btrfs
      wipe_filesystem: false

Create files

Like in the example before, if you want to create files outside of the default initrd mount directories you will also have to add storage -> filesystem for the corresponding device in addition to the snippet below.

variant: fcos
version: 1.0.0
storage:
  files:
    - path: /var/test.txt
      mode: 0644
      overwrite: true
      contents:
        inline: "testcontents"

Change hostname

According to the example before, we can set the hostname by creating the /etc/hostname file.

variant: fcos
version: 1.0.0
storage:
  files:
    - path: /etc/hostname
      mode: 0644
      overwrite: true
      contents:
        inline: "kubic-1"

Enable services

Ignition can also enable systemd services

variant: fcos
version: 1.0.0
systemd:
  units:
    - name: sshd.service
      enabled: true

More Examples

Find some more FCC examples on the Fedora Core OS documentation website.

JSON Examples

Add a password and a SSH key for the root user

{
	"ignition": { "version": "3.1.0" },
	"passwd": {
		"users": [
			{
				"name": "root",
				"passwordHash": "hash, created with e.g. `openssl passwd -6`",
				"sshAuthorizedKeys": [
					"ssh-rsa long...key user@host"
				]
			}
		]
	}
}

Create new users

By default the user's home directory will be located in /home/<username>. As /home is not mounted in the initrd by default the mount has to be defined explicitly. Check out the Mounts Example for details.

{
	"ignition": { "version": "3.1.0" },
	"storage": {
		"filesystems": [
			{
				"path": "/home",
				"device": "Path to the root device such as /dev/sda3, /dev/mmcblk0p2 or /dev/disk/by-label/ROOT",
				"format": "btrfs",
				"wipeFilesystem": false,
				"mountOptions": [
					"subvol=/@/home"
				]
			}
		]
	},
	"passwd": {
		"users": [
			{
				"name": "username",
				"passwordHash": "hash, created with e.g. `openssl passwd -6`",
				"sshAuthorizedKeys": [
					"ssh-rsa long...key user@host"
				]
			}
		]
	}
}

Mounts

In an openSUSE MicroOS based image the subvolumes mounted by default are:

/
/var
/etc
/root

If access to other subvolumes or partitions such as /home or /opt is required, you need to define them in Ignition's configuration file explicitly.

{
	"ignition": { "version": "3.1.0" },
	"storage": {
		"filesystems": [
			{
				"path": "/opt",
				"device": "/dev/sdXY",
 				"format": "btrfs",
				"wipeFilesystem": false,
			}
		]
	}
}

Create files

Like in the example before, if you want to create files outside of the default initrd mount directories you will also have to add storage -> filesystem for the corresponding device in addition to the snippet below.

{
	"ignition": { "version": "3.0.0" },
	"storage": {
		"files": [
			{
				"path": "/var/test.txt",
				"mode": 420,
				"contents": {
					"source": "data:,testcontents"
				},
				"overwrite": true
			}
		]
	}
}

Change hostname

According to the example before, we can set the hostname by creating the /etc/hostname file.

{
	"ignition": { "version": "3.0.0" },
	"storage": {
		"files": [{
			"filesystem": "root",
			"path": "/etc/hostname",
			"mode": 420,
			"overwrite": true,
			"contents": { "source": "data:,kubic-1" }
		}]
	}
}

Enable services

Ignition can also enable systemd services

 {
 	"ignition": { "version": "3.0.0" },
 	"systemd": {
 		"units": [{
 			"name": "sshd.service",
 			"enabled": true
 		}]
 	}
 }

More Examples

Find some more examples on the Ignition documentation website.

Portal:MicroOS/Ignition

First Boot Configuration

Ignition Quick Start

USB flash drive

Create an ISO-Image

Use fw_cfg qemu feature in libvirt

Create a Config File using butane

Invocation

Advanced Usage

FCC/YAML Examples

Add a password and a SSH key for the root user

Create new users

Mounts

Create files

Change hostname

Enable services

More Examples

JSON Examples

Add a password and a SSH key for the root user

Create new users

Mounts

Create files

Change hostname

Enable services

More Examples

Create a Config File using `butane`