SEAPATH KIWI image builder

Table of Contents

• Introduction
• Prerequisites
  • Build with CQFD (recommended)
  • Build without CQFD
  • Activate SUSE Linux Enterprise registration (only for SEAPATH SLE)
  • Install a flashing tool
• Build a SEAPATH image
  • Configuring SSH keys
  • Available images
  • Building the image
  • Installing the image
• Configuring the system with SEAPATH Ansible

Introduction

This repository contains image descriptions, also called appliances, to build SEAPATH images using KIWI NG.

Currently, this repository provides image descriptions for the following SEAPATH flavors:

• SEAPATH SLES 16.0

Prerequisites

Build with CQFD (recommended)

KIWI-NG relies on the tools installed on the build system. Therefore, the build and target distributions must match to provide the same package manager.

To provide a distribution agnostic build, this repository wraps the build process in a container using CQFD.

Note	We recommend using this method as it greatly simplifies the build environment setup and configuration and allows building on a distribution different from the target distribution.

Install CQFD

• Install docker if it is not already done.

On Ubuntu, please run:

$ sudo apt-get install docker.io

For other distributions, please refer to the Docker install documentation.

• Install cqfd:

On Ubuntu, please run:

$ curl -LO https://github.com/savoirfairelinux/cqfd/releases/download/v5.9.0/cqfd_5.9.0_all.deb
$ sudo apt install ./cqfd_5.9.0_all.deb

For other distributions, please refer to the CQFD install instructions.

The project page on Github contains detailed information on usage and installation.

• Make sure that docker does not require sudo

Please use the following commands to add your user account to the docker group:

$ sudo groupadd docker
$ sudo usermod -aG docker $USER

Log out and log back in, so that your group membership can be re-evaluated.

Build without CQFD

If your build system distribution matche the target distribution, you can build without CQFD. In that case:

• Install kiwi-ng and others build dependencies mentioned by the CQFD Dockerfile in .cqfd corresponding to your distribution.

• Run the build.sh command for the corresponding target SEAPATH distribution as configured in .cqfdrc.

Note	This documentation doesn’t cover in detail the build process without CQFD.

Activate SUSE Linux Enterprise registration (only for SEAPATH SLE)

When building SEAPATH SLES images, you need to have on the build system:

• For SEAPATH SLES 16.0, an active SUSE Linux Enterprise registration.

• In addition for SEAPATH SLES 16.0 cluster images, an active SUSE Linux Enterprise Server High Availability Extension registration.

This is required to access the necessary repositories and packages for the build process.

When building with CQFD

When building with CQFD, you must first manually register to the SUSE Customer Center using an SLE registration code. The following command registers the system and copies the credentials directly to the .cqfd/sles<version>/ directory.

This can be done using the official SUSE Base Container Image:

$ docker run --rm \
      -v $(pwd)/.cqfd/sles<version>:/output \
      registry.suse.com/bci/bci-base:<version> bash -c " \
      zypper -n in SUSEConnect; \
      SUSEConnect --regcode <your-registration-code> -p SLES/<version>/x86_64; \
      SUSEConnect --regcode <your-additional-registration-code> -p sle-ha/<version>/x86_64; \
      cp /etc/zypp/credentials.d/SCCcredentials /output/SCCcredentials; \
      cp /etc/zypp/credentials.d/SUSE_Linux_Enterprise_High_Availability_Extension_<version>_x86_64 /output/SUSE_Linux_Enterprise_High_Availability_Extension_<version>_x86_64; \
      chmod 644 /output/SCCcredentials /output/SUSE_Linux_Enterprise_High_Availability_Extension_<version>_x86_64"

For exemple, if building for SEAPATH SLES 16.0, you should run:

$ docker run --rm \
      -v $(pwd)/.cqfd/sles16.0:/output \
      registry.suse.com/bci/bci-base:16.0 bash -c " \
      zypper -n in SUSEConnect; \
      SUSEConnect --regcode <your-registration-code> -p SLES/16.0/x86_64; \
      SUSEConnect --regcode <your-additional-registration-code> -p sle-ha/16.0/x86_64; \
      cp /etc/zypp/credentials.d/SCCcredentials /output/SCCcredentials; \
      cp /etc/zypp/credentials.d/SUSE_Linux_Enterprise_High_Availability_Extension_16.0_x86_64 /output/SUSE_Linux_Enterprise_High_Availability_Extension_16.0_x86_64; \
      chmod 644 /output/SCCcredentials /output/SUSE_Linux_Enterprise_High_Availability_Extension_16.0_x86_64"

Once the credential files are generated and placed in the correct .cqfd/sles<version>/ directory, CQFD will automatically use them to connect to the SUSE Customer Center during container initialization. This is internally done by the container-suseconnect utility.

For more information on container-suseconnect configuration, please refer to the "How to use container-suseconnect" documentation.

When building without CQFD

When building without CQFD, you can directly register to the SUSE Customer Center on the build system using the SUSEConnect command-line tool.

For SEAPATH SLES 16.0, run:

$ SUSEConnect --regcode <your-registration-code> -p SLES/16.0/x86_64
$ SUSEConnect --regcode <your-additional-registration-code> -p sle-ha/16.0/x86_64

For more information about SLE registration, please refer to the official SUSE documentation.

Note	This method is available only if the build system is running a SUSE Linux Enterprise Server distribution.

Warning

Registering the SLE RT base product may conflict with your build system SLES base product. For that reason we strongly recommend using the CQFD method that fully sets up the build environment.

Install a flashing tool

Tools like dd, bmap-tools or balena-etcher can be used to manually flash the built image on a disk. We recommend using bmap-tools for better performances.

Build a SEAPATH image

Configuring SSH keys

SEAPATH configure two main users: admin and ansible. These users only accept login via an SSH session using SSH keys.

In the keys/ directory, put the SSH public keys you wish to use in the following files:

• admin_public_ssh_key.pub: public keys used to log in with the admin user.

• ansible_public_ssh_key.pub: public keys used to log in with the ansible user.

To quickly generate and use an SSH key on your local system:

• Generate an SSH key pair with the ssh-keygen command.

• Copy the generated *.pub file in keys:

  $ cp <ssh-key-name>.pub keys/admin_public_ssh_key.pub
  $ cp <ssh-key-name>.pub keys/ansible_public_ssh_key.pub

Note	This step can be skipped when using the SEAPATH live installer. In that case the SSH keys should be added into the live installer and selected during the installation process. See the With the SEAPATH live installer (recommended) section for more details.

Available images

The following instructions suppose that you are building with CQFD.

Identify the CQFD flavor corresponding to the SEAPATH image you want to build. For now the following flavors are available:

• SEAPATH SLES 16.0

  • sles16-seapath-hypervisor-standalone: SEAPATH SLES 16.0 standalone hypervisor image.

  • sles16-seapath-hypervisor-standalone-cockpit: SEAPATH SLES 16.0 standalone hypervisor image with Cockpit.

  • sles16-seapath-hypervisor-cluster: SEAPATH SLES 16.0 cluster hypervisor image.

  • sles16-seapath-hypervisor-cluster-cockpit: SEAPATH SLES 16.0 cluster hypervisor image with Cockpit.

  • sles16-seapath-observer: SEAPATH SLES 16.0 observer image for use in a SEAPATH cluster.

Note	When building a SLE based SEAPATH image, make sure to first configure your SLE registration. See the Activate SUSE Linux Enterprise registration (only for SEAPATH SLE) section.

Building the image

• Initialize CQFD. For SLE builds, this automatically import the provided SLE credentials.

  $ cqfd -b <cqfd-flavor> init

For exemple, when building the SEAPATH SLES 16.0 standalone hypervisors image;

$ cqfd -b sles16-seapath-hypervisor-standalone init

• Build the image.

  $ cqfd -b <cqfd-flavor>

For exemple, when building the SEAPATH SLES 16.0 standalone hypervisors image;

$ cqfd -b sles16-seapath-hypervisor-standalone

Installing the image

There are two ways to install SEAPATH images:

• Using the SEAPATH live installer

• Directly flashing on the target disk the raw image files with tools such as dd or bmap-tools.

The following image files, generated by the build process, are used to install SEAPATH on the target hardware:

• With the SEAPATH live installer or bmap-tools:

  • seapath-<distribution>.<architecture>-<kiwi-appliance-version>.raw.gz

  • seapath-<distribution>.<architecture>-<kiwi-appliance-version>.raw.bmap

• With dd:

  • seapath-<distribution>.<architecture>-<kiwi-appliance-version>.raw

With the SEAPATH live installer (recommended)

• Get an .iso file of an empty SEAPATH live installer:

  • By building locally, see https://github.com/seapath/seapath-live-installer#building-seapath-live-installer.

  • By downloading a pre-built image from https://releases.seapath.org/builds/:

    • Select the release folder for the latest SEAPATH version.

    • Download and extract seapath-live-installer-<version>-empty.iso.zip.

• Flash the .iso file on a USB stick and add the image files to it.

  • See Advanced SEAPATH image installation instructions on the SEAPATH wiki.

• Insert the SEAPATH live installer USB stick in your target hardware and follow the installation process.

  • See Use the installer on the SEAPATH wiki for further information about the installation process.

With a raw image

If you have direct access to the target storage disk on the hardware, you can directly flash the image on the disk with tools such as dd or bmap-tools. We recommend using bmap-tools for faster flashing.

• With bmap-tools`:

  • Install the bmap-tools package on the distribution accessing the target storage disk.

  • Copy the .raw.bmap and .raw.gz files in the same directory on the distribution accessing the target storage disk.

  • Run

    $ sudo bmaptool copy <seapath-image-name>.raw.gz /dev/<target-disk>

• With dd:

  • On the distribution accessing the target storage disk, copy the .raw file or extract the .raw.gz file.

  • Run

    $ sudo dd if=<seapath-image-name>.raw of=/dev/<usb-stick-disk> bs=4M status=progress

• Boot on the flashed disk on the target hardware.

Configuring the system with SEAPATH Ansible

Flashing the image is the first step to deploy SEAPATH. The SEAPATH Ansible playbooks and roles must then be used to configure and manage SEAPATH.

See the SEAPATH Ansible repository for more information on how to use SEAPATH Ansible.