Deploying SLE Micro Using a Raw Disk Image on Bare Metal
- WHAT?
SUSE Linux Enterprise Micro provides raw images (also referred to as pre-built images) that can be deployed directly to your device storage: a memory card, a USB flash disk or a hard disk. The type of device you can deploy the image to is determined by your specific hardware. Refer to your vendor's documentation for guidance.
- WHY?
You need to know how to deploy SLE Micro on your system.
- EFFORT
It takes approximately 20 minutes to read the article.
- GOAL
SLE Micro is successfully deployed on your system.
- REQUIREMENTS
Understanding for which environment the raw disk image is suited. For details, refer to the Introduction to SLE Micro article.
A device with at least 20 GB disk space, where you deploy the raw image and where SLE Micro will run
Optionally, a configuration medium, for example, a USB flash disk.
1 About pre-built images #
Pre-built images are ready-to-use representations of a running operating system. They are not installed in a traditional way using an installer, but copied to the hard disk of the target host. The topic covers basic information about these pre-built images.
The pre-built images are intended to be configured on the first boot by using tools delivered in the images. The boot loader detects the first boot as described in Section 1.1, “First boot detection”.
1.1 First boot detection #
The deployment configuration runs on the first boot only. To distinguish
between the first and subsequent boots, the file
/etc/machine-id
is created after the
first boot finishes. If the file is not present in the file system, the system assumes that
this is a first boot and triggers the configuration process. After completing the first boot, the
/etc/machine-id
file is
created.
/etc/machine-id
file is always created
Even though the configuration may not be successful because of improper
or missing configuration files, the
/etc/machine-id
file is
created.
1.1.1 Force system reconfiguration on a subsequent boot #
If you need to reconfigure your system after the first boot happened, you can force the reconfiguration on the subsequent boot. Here you have two options.
You can pass the
ignition.firstboot
orcombustion.firstboot
attribute to the kernel command line.You can delete the file
/etc/machine-id
and reboot the system.
2 Preparing the configuration device #
During the installation process, you can pass a complex configuration to define users, directories, or to provide SSH keys. To do so, create a configuration device that is later processed by either Ignition or Combustion.
By default, root
SSH login in SLE Micro is permitted only by using the SSH
key. We recommend creating an unprivileged user during the deployment process that you can
use to access the installed system. You can create an unprivileged user account on the first
boot by using either the Combustion or Ignition tool. Creating an unprivileged user
during system deployment is useful for accessing the Cockpit Web interface as well.
To prepare the configuration device, proceed as follows:
Format the disk to any file system supported by SLE Micro: Ext3, Ext4, etc.:
>
sudo mkfs.ext4 /dev/sdYSet the device label to either
ignition
(when either Ignition or Combustion is used) orcombustion
(when only Combustion is used). If needed (for example, on Windows host), use uppercase letters for the labels. To label the device, run:>
sudo e2label /dev/sdY ignitionYou can use any type of configuration storage media that your virtualization system or your hardware supports: an ISO image, a USB flash disk, etc.
Mount the device:
>
sudo mount /dev/sdY /mntCreate the directory structure as mentioned in Section 2.1.1.1, “
config.ign
” or Section 2.2, “Configuring SLE Micro deployment with Combustion”, depending on the configuration tool used:>
sudo mkdir /mnt/ignition/or:
>
sudo mkdir -p /mnt/combustion/Prepare all elements of the configuration that will be used by Ignition or Combustion.
2.1.1 How does Ignition work? #
When the system is booted for the first time, Ignition is loaded as
part of an initramfs
and searches for a
configuration file within a specific directory (on a USB flash disk, or
you can provide a URL). All changes are performed before the kernel
switches from the temporary file system to the real root file system
(before the switch_root
command is issued).
Ignition uses a configuration file in the JSON format named
config.ign
. You can either write the configuration
manually or use the Fuel Ignition Web application at
https://ignite.opensuse.org to generate it.
Fuel Ignition does not cover the complete Ignition vocabulary yet, and the resulting JSON file may need additional manual tweaking.
2.1.1.1 config.ign
#
The configuration file
config.ign
must reside in the
ignition
subdirectory on the configuration media, for example, a USB
stick labeled ignition
. The directory structure must look as follows:
<root directory> └── ignition └── config.ign
To create a disk image with the Ignition configuration, you can use the Fuel Ignition Web application at https://ignite.opensuse.org.
The config.ign
contains multiple data types:
objects, strings, integers, booleans and lists of objects. For a
complete specification, refer to
Ignition
specification v3.3.0.
The version
attribute is mandatory and in case of
SLE Micro, its value must be set either to
3.4.0
or to any lower version. Otherwise, Ignition
will fail.
To log in to your system as root
, you must at least
include a password for root
. However, it is recommended to
establish access via SSH keys. To configure a password, make sure to
use a secure one. If you use a randomly generated password, use at
least 10 characters. If you create your password manually, use even
more than 10 characters and combine uppercase and lowercase letters and
numbers.
2.1.2 Ignition configuration examples #
This section provides several examples of the Ignition configuration in the built-in JSON format.
version
attribute is mandatory
Each config.ign
must include version 3.4.0 or
lower that is then converted to the corresponding Ignition
specification.
2.1.2.1 Default partitioning #
Each image has the following subvolumes:
/home /root /opt /srv /usr/local /var
The /etc
directory is mounted as overlayFS, where the
upper directory is mounted to /var/lib/overlay/1/etc/
.
You can recognize the subvolumes mounted by default by the option
x-initrd.mount
in /etc/fstab
. Other
subvolumes or partitions must be configured either by Ignition or
Combustion.
If you want to add a new user or modify any of the files on a subvolume that is not mounted by default, you need to declare such subvolume first so that it is mounted as well.
2.1.2.2 Storage configuration #
The storage
attribute is used to configure
partitions, RAID, define file systems, create files, etc. To define
partitions, use the disks
attribute. The
filesystems
attribute is used to format partitions. The
files
attribute can be used to create files in the
file system. Each of the mentioned attributes is described in the
following sections.
2.1.2.2.1 The disks
attribute #
The disks
attribute is a list of devices that
enables you to define partitions on these devices. The
disks
attribute must contain at least one
device
, other attributes are optional. The
following example uses a single virtual device and divides the
disk into four partitions:
{ "ignition": { "version": "3.0.0" }, "storage": { "disks": [ { "device": "/dev/vda", "partitions": [ { "label": "root", "number": 1, "typeGuid": "4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709" }, { "label": "boot", "number": 2, "typeGuid": "BC13C2FF-59E6-4262-A352-B275FD6F7172" }, { "label": "swap", "number": 3, "typeGuid": "0657FD6D-A4AB-43C4-84E5-0933C84B4F4F" }, { "label": "home", "number": 4, "typeGuid": "933AC7E1-2EB4-4F13-B844-0E14E2AEF915" } ], "wipeTable": true } ] } }
2.1.2.2.2 The raid
attribute #
The raid
is a list of RAID arrays. The following
attributes of raid
are mandatory:
- level
a level of the particular RAID array (linear, raid0, raid1, raid2, raid3, raid4, raid5, raid6)
- devices
a list of devices in the array referenced by their absolute paths
- name
a name that will be used for the md device
For example:
{ "ignition": { "version": "3.0.0" }, "storage": { "raid": [ { "devices": [ "/dev/sda", "/dev/sdb" ], "level": "raid1", "name": "system" } ] } }
2.1.2.2.3 The filesystems
attribute #
The file system
attribute does not modify mount units. If you add a new partition or remove an
existing partition, you must manually adjust the mount units.
filesystems
must contain the following attributes:
- device
the absolute path to the device, typically
/dev/sda
in case of physical disk- format
the file system format (Btrfs, Ext4, xfs, vfat or swap)
NoteIn case of SLE Micro, the
root
file system must be formatted to Btrfs.
The following example demonstrates using the
filesystems
attribute. The
/opt
directory will be mounted to the
/dev/sda1
partition, which is formatted to Btrfs.
The device will not be erased.
For example:
{ "ignition": { "version": "3.0.0" }, "storage": { "filesystems": [ { "device": "/dev/sda1", "format": "btrfs", "path": "/opt", "wipeFilesystem": false } ] } }
Normally, a regular user's home directory is located in the
/home/USER_NAME
directory. Since /home
is not mounted by default
in the initrd, the mount has to be explicitly defined for the user
creation to succeed:
{ "ignition": { "version": "3.1.0" }, "passwd": { "users": [ { "name": "root", "passwordHash": "PASSWORD_HASH", "sshAuthorizedKeys": [ "ssh-rsa SSH_KEY_HASH" ] } ] }, "storage": { "filesystems": [ { "device": "/dev/sda3", "format": "btrfs", "mountOptions": [ "subvol=/@/home" ], "path": "/home", "wipeFilesystem": false } ] } }
2.1.2.2.4 The files
attribute #
You can use the files
attribute to create any
files on your machine. Bear in mind that to create files
outside the default partitioning schema, you need to define the
directories by using the filesystems
attribute.
In the following example, a host name is created by using the
files
attribute. The file
/etc/hostname
will be created with the
sl-micro1 host name:
Keep in mind that JSON accepts file modes in decimal numbers, for
example, 420
.
JSON:
{ "ignition": { "version": "3.0.0" }, "storage": { "files": [ { "overwrite": true, "path": "/etc/hostname", "contents": { "source": "data:,sl-micro1" }, "mode": 420 } ] } }
2.1.2.2.5 The directories
attribute #
The directories
attribute is a list of directories
that will be created in the file system. The
directories
attribute must contain at least one
path
attribute.
For example:
{ "ignition": { "version": "3.0.0" }, "storage": { "directories": [ { "path": "/home/tux", "user": { "name": "tux" } } ] } }
2.1.2.3 Users administration #
The passwd
attribute is used to add users. As some services, such as Cockpit, require login using a non-root user, define at
least one unprivileged user here. Alternatively, you can create such a user from a running
system as described in Section 4.3, “Adding users”.
To log in to your system, create root
and a regular user and set their
passwords. You need to hash the passwords, for example, by
using the openssl
command:
openssl passwd -6
The command creates a hash of the password you chose. Use this hash as
the value of the password_hash
attribute.
For example:
{ "ignition": { "version": "3.0.0" }, "passwd": { "users": [ { "name": "root", "passwordHash": "PASSWORD_HASH", "sshAuthorizedKeys": [ "ssh-rsa SSH_KEY_HASH USER@HOST" ] } ] } }
The users
attribute must contain at least one
name
attribute.
ssh_authorized_keys
is a list of ssh keys for the
user.
2.1.2.4 Enabling systemd
services #
You can enable systemd
services by specifying them in the
systemd
attribute.
For example:
{ "ignition": { "version": "3.0.0" }, "systemd": { "units": [ { "enabled": true, "name": "sshd.service" } ] } }
2.2 Configuring SLE Micro deployment with Combustion #
Combustion is a dracut module that enables you to configure your system on the first boot. You can use Combustion, for example, to change the default partitions, set user passwords, create files, or install packages.
2.2.1 How does Combustion work? #
Combustion is invoked after the ignition.firstboot
argument is passed to the kernel command line. Combustion reads a
provided file named script
, executes included
commands, and thus performs changes to the file system. If
script
includes the network flag, Combustion tries
to configure the network. After /sysroot
is mounted,
Combustion tries to activate all mount points in
/etc/fstab
and then calls
transactional-update
to apply other changes, for
example, setting root
password or installing packages.
The configuration file script
must reside in the
combustion
subdirectory on the configuration media labeled
combustion
. The directory structure must look as follows:
<root directory> └── combustion └── script └── other files
Combustion can be used along with Ignition. If you intend to do
so, label your configuration medium ignition
and
include the ignition
directory with the
config.ign
to your directory structure as shown
below:
<root directory> └── combustion └── script └── other files └── ignition └── config.ign
In this scenario, Ignition runs before Combustion.
2.2.2 Combustion configuration examples #
2.2.2.1 The script
configuration file #
The script
configuration file is a set of commands
that are parsed and executed by Combustion in a transactional-update
shell. This
article provides examples of configuration tasks performed by
Combustion.
As the script
file is interpreted by the shell,
always start the file with the interpreter declaration on its first
line. For example, in case of Bash:
#!/bin/bash
To log in to your system, include at least the root
password.
However, it is recommended to establish the authentication using SSH
keys. If you need to use a root
password, make sure to configure a
secure password. For a randomly generated password, use at least 10
characters. If you create your password manually, use even more than 10
characters and combine uppercase and lowercase letters and numbers.
2.2.2.1.1 Default partitioning #
Each image has the following subvolumes:
/home /root /opt /srv /usr/local /var
The /etc
directory is mounted as overlayFS, where the
upper directory is mounted to /var/lib/overlay/1/etc/
.
You can recognize the subvolumes mounted by default by the option
x-initrd.mount
in /etc/fstab
. Other
subvolumes or partitions must be configured either by Ignition or
Combustion.
If you want to add a new user or modify any of the files on a subvolume that is not mounted by default, you need to declare such subvolume first so that it is mounted as well.
2.2.2.1.2 Network configuration #
To configure and use the network connection during the first boot, add
the following statement to script
:
# combustion: network
Using this statement passes the rd.neednet=1
argument to dracut. The network configuration defaults to using DHCP.
If a different network configuration is needed, proceed as described in
Section 2.2.2.1.3, “Performing modifications in the initramfs”.
If you do not use the statement, the system remains configured without any network connection.
2.2.2.1.3 Performing modifications in the initramfs #
You may need to perform changes to the initramfs environment, for
example, to write a custom network configuration for NetworkManager into
/etc/NetworkManager/system-connections/
. To do so,
use the prepare
statement.
For example, to create a connection with a static IP address and configure DNS:
#!/bin/bash # combustion: network prepare set -euxo pipefail nm_config() { umask 077 # Required for NM config mkdir -p /etc/NetworkManager/system-connections/ cat >/etc/NetworkManager/system-connections/static.nmconnection <<-EOF [connection] id=static type=ethernet autoconnect=true [ipv4] method=manual dns=192.168.100.1 address1=192.168.100.42/24,192.168.100.1 EOF } if [ "${1-}" = "--prepare" ]; then nm_config # Configure NM in the initrd exit 0 fi # Redirect output to the console exec > >(exec tee -a /dev/tty0) 2>&1 nm_config # Configure NM in the system curl example.com # Close outputs and wait for tee to finish exec 1>&- 2>&-; wait; # Leave a marker echo "Configured with combustion" > /etc/issue.d/combustion
2.2.2.1.4 Waiting for the task to complete #
Some processes may be run in background, for example, the tee
process
that redirects output to the terminal. To ensure that all running processes are completed before the
script
execution finishes, add the following line:
exec 1>&- 2>&-; wait;
2.2.2.1.5 Partitioning #
SLE Micro raw images are delivered with a default partitioning
scheme. You might want to
use a different partitioning. The following set of example snippets
moves the /home
to a different partition.
The following script performs changes that are not included in
snapshots. If the script fails and the snapshot is discarded, certain
changes remain visible and cannot be reverted, for example, the
changes to the /dev/vdb
device.
The following snippet creates a GPT partitioning schema with a single
partition on the /dev/vdb
device:
sfdisk /dev/vdb <<EOF sleep 1 label: gpt type=linux EOF partition=/dev/vdb1
As the sfdisk
command may take longer time to complete, postpone
label
by using the
sleep
command after sfdisk
.
The partition is formatted to Btrfs:
wipefs --all ${partition} mkfs.btrfs ${partition}
Possible content of /home
is moved to the new
/home
folder location by the following snippet:
mount /home mount ${partition} /mnt rsync -aAXP /home/ /mnt/ umount /home /mnt
The snippet below removes an old entry in
/etc/fstab
and creates a new entry:
awk -i inplace '$2 != "/home"' /etc/fstab echo "$(blkid -o export ${partition} | grep ^UUID=) /home btrfs defaults 0 0" >>/etc/fstab
2.2.2.1.6 Creating new users #
As some services, such as Cockpit, require login using a non-root user, define at least one unprivileged user here. Alternatively, you can create such a user from a running system as described in Section 4.3, “Adding users”.
To add a new user account, first create a hash string that represents
the user's password. Use the openssl passwd -6
command.
After you obtain the password hash, add the following lines to the
script
:
mount /home useradd -m EXAMPLE_USER echo 'EXAMPLE_USER:PASSWORD_HASH' | chpasswd -e
2.2.2.1.7 Setting a password for root
#
Before you set the root
password, generate a hash of the
password, for example, by using the openssl passwd
-6
. To set the password, add the following line to the
script
:
echo 'root:PASSWORD_HASH' | chpasswd -e
2.2.2.1.8 Adding SSH keys #
The following snippet creates a directory to store the root
's SSH
key and then copies the public SSH key located on the configuration
device to the authorized_keys
file.
mkdir -pm700 /root/.ssh/ cat id_rsa_new.pub >> /root/.ssh/authorized_keys
The SSH service must be enabled in case you need to use remote login via SSH. For details, refer to Section 2.2.2.1.9, “Enabling services”.
2.2.2.1.9 Enabling services #
To enable system services, for example, the SSH service, add the
following line to script
:
systemctl enable sshd.service
2.2.2.1.10 Installing packages #
As certain packages may require additional subscription, you may need to register your system beforehand. An available network connection may also be needed to install additional packages.
During the first boot configuration, you can install additional
packages to your system. For example, you can install the
vim
editor by adding:
zypper --non-interactive install vim-small
Bear in mind that you will not be able to use
zypper
after the configuration is complete and you
boot to the configured system. To perform changes later, you must use
the transactional-update
command to create a
changed snapshot.
3 Deploying a raw disk image #
The following procedure describes how to deploy SLE Micro using a raw disk image.
Download the image.
Decompress the image:
>
xz -d DOWNLOADED_IMAGE.raw.xzClear the partition table and file system signature:
#
wipefs --all /dev/sdXCopy the decompressed image to the device where SLE Micro will run:
>
dd if=DOWNLOADED_IMAGE.raw conv=sparse bs=1M of=/dev/sdXThe raw image comes with a default partitioning scheme. If you want to change it or perform a complex configuration task, you need to prepare the configuration device as described in Section 2, “Preparing the configuration device”. Otherwise, you can proceed to the next step.
Boot the raw disk image, and in the boot loader screen, select
and confirm with .Without the configuration device, the JeOS Firstboot is triggered to perform minimal configuration. For details, refer to Section 3.1, “Configuring SLE Micro with JeOS Firstboot”.
After successful deployment, refer to Section 4, “Post-deployment steps” to register your system and/or create a UEFI boot record.
You may invoke reconfiguration of the system on subsequent boot, by
passing the ignition.firstboot
attribute to the kernel
command line or by deleting the file:
/boot/writable/firstboot_happened
. For more details
regarding the first boot detection, refer to
Section 1.1, “First boot detection”.
3.1 Configuring SLE Micro with JeOS Firstboot #
When booting SLE Micro for the first time without providing any configuration device, JeOS Firstboot enables you to perform a minimal configuration of your system. If you need more control over the deployment process, use a configuration device with either Ignition or Combustion configuration. Find more information in Section 2.1, “Configuring SLE Micro deployment with Ignition” and Section 2.2, “Configuring SLE Micro deployment with Combustion”.
To configure the system with JeOS Firstboot, proceed as follows:
Enter.
displays a welcome screen. Confirm withOn the next screens, select keyboard, confirm the license agreement and select the time zone.
In the
dialog window, enter a password for theroot
and confirm it.Figure 1: Enter root password #For encrypted deployments, JeOS Firstboot does the following:
Asks for a new passphrase that replaces the default passphrase.
Generates a new LUKS key and re-encrypts the partition.
Adds a secondary key slot to the LUKS header and seals it against the TPM device.
If you are deploying an encrypted image, follow these steps:
Select the desired protection method and confirm with
.Enter a recovery password for LUKS encryption and retype it. The root file system re-encryption begins.
Figure 2: Select method for encryption #After successful deployment, register your system and create an unprivileged user as described in Section 4.4, “Registering SLE Micro from CLI”.
4 Post-deployment steps #
4.1 Adding UEFI boot records #
During the deployment, the image of the system is
just copied to the selected disk. Therefore, an EFI boot entry is not
created. You may need to manually boot your system using the EFI
shell by selecting the SUSE Linux Enterprise Micro boot loader. After the first boot, you can
use efibootmgr
to create the boot entry.
efibootmgr
is available by default in the deployed
image.
4.2 Reencrypting the encrypted system #
The system is not secured. Thus, do not store any sensitive data in it until the disk reencryption is complete.
JeOS Firstboot prompts for a new passphrase during the deployment phase. After you enter it, the system is reencrypted automatically, thus no further action is needed.
SUSE Linux Enterprise Micro encrypted images are delivered with a default LUKS passphrase. To secure your system, make sure that you change it after the system is deployed. To do so, proceed as described below. Perform the steps in the same shell session.
Import the needed functions to your shell:
#
source /usr/share/fde/luksIdentify the underlying LUKS device and define further used variables:
#
luks_name=$(expr "`df --output=source / | grep /dev/`" : ".*/\(.*\)")and:
#
luks_dev=$(luks_get_underlying_device "$luks_name")Create a key file that stores the default passphrase 1234 and a key file with the new passphrase.
Change the recovery password:
#
cryptsetup luksChangeKey --key-file PATH_TO_DEFAULT --pbkdf pbkdf2 "${luks_dev}" PATH_TO_NEWPATH_TO_DEFAULT is a path to the key file with the default passphrase. PATH_TO_NEW is a path to the key file with your new passphrase.
Reencrypt the LUKS device:
#
cryptsetup reencrypt --key-file PATH_TO_NEW ${luks_dev}Create a new random key and seal it with TPM:
>
sudo
fdectl regenerate-key --passfile PATH_TO_NEWRemove both key files you created in Step 3.
Update the
grub.cfg
file by running:>
sudo
transactional-update grub.cfgReboot the system.
4.3 Adding users #
As SUSE Linux Enterprise Micro requires having a non-privileged user to log in via SSH or to access Cockpit, you need to create such an account.
This step is optional if you have defined an unprivileged user in the Ignition or
Combustion. If you deployed your system using JeOS Firstboot, then you set up only the
root
password and you need to create the unprivileged account manually, as described below:
Run the
useradd
command as follows:#
useradd -m USER_NAME
Set a password for that account:
#
passwd USER_NAMEIf needed, add the user to the
wheel
group:#
usermod -aG wheel USER_NAME
4.4 Registering SLE Micro from CLI #
After successful deployment, you need to register the system to get
technical support and receive updates. Registering the system is
possible from the command line using the transactional-update
register
command.
To register SUSE Linux Enterprise Micro with SUSE Customer Center, proceed as follows:
Run
transactional-update register
as follows:#
transactional-update register -r REGISTRATION_CODE -e EMAIL_ADDRESSTo register with a local registration server, additionally provide the URL to the server:
#
transactional-update register -r REGISTRATION_CODE -e EMAIL_ADDRESS \ --url "https://suse_register.example.com/"Replace REGISTRATION_CODE with the registration code you received with your copy of SUSE Linux Enterprise Micro. Replace EMAIL_ADDRESS with the e-mail address associated with the SUSE account you or your organization uses to manage subscriptions.
Reboot your system to switch to the latest snapshot.
SUSE Linux Enterprise Micro is now registered.
For information that goes beyond the scope of this section, refer to the
inline documentation with SUSEConnect --help
.
5 Legal Notice #
Copyright© 2006–2024 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.