Set Up the Uyuni for Retail Environment with non-containerized 4.3 branch server

To set up the Uyuni for Retail environment, you will need to have already installed and configured:

  • Uyuni for Retail Server

  • one or more Uyuni for Retail branch server proxies, or containerized proxy

  • one or more Uyuni build hosts

This section covers how to configure your Uyuni for Retail environment, including:

  • Prepare POS images

  • Prepare system groups

  • Configure services for Saltboot

  • Synchronize POS images to the branch servers

The very first time you set up the Uyuni for Retail environment, you will need to perform all configuration steps. You will need to revisit some of these steps later on as you are working with Uyuni for Retail.

For example, the first time you configure the branch server, you will need to have images prepared for synchronization. If you are configuring more than one branch server, you can use the same images across different branch servers.

If you have an existing environment, and need to build new images, you do not need to re-initialize the branches. You will need to synchronize the images, and can skip setting up the services on the branch server.

Usually, POS images are rebuild when updated packages are available, and synchronized to the branch servers before the update window opens.

1. Prepare and Build Terminal Images

For information about Uyuni image building, see Image Building and Management.

Uyuni for Retail POS images are images specifically tailored for Uyuni for Retail environment and designed to be deployed using PXE booting mechanism.

1.1. POS Image Templates

As starting point, SUSE provides basic templates at https://github.com/SUSE/manager-build-profiles/tree/master/OSImage. These templates need to be adapted for specific usecases, for example by including specific applications, configuration settings, and users.

By default, POS templates do not include a system user. You will not be able to login as a user to a system that has been installed with a SUSE provided template. However you can use Salt to manage clients without a system user. You can use Salt to install a system user after the terminal has been deployed.

2. Branch Identification and Architecture Topology

Before you configure the branch server, ensure you have decided on networking topology and you choose branch id.

For information about the possible network topologies, see Network Architecture.

As a branch id select any alphanumerical string with up to 64 characters.

3. Required System Groups

Uyuni for Retail requires:

  • branch system group for every branch server proxy, using branch id as its name

  • hardware type system group for every used hardware type, using HWTYPE: prefix in its name

For more information about hardware type groups, see Deployment basics.

Missing mandatory system group will cause terminal bootstrap to fail.

Uyuni for Retail also recognizes two optional groups for better overview:

  • TERMINALS

  • SERVERS

You can create system groups using the Uyuni Web UI. Navigate to Systems  System Groups and click Create System Group.

For more information about system groups, see System Groups.

During terminal bootstrap terminal automatically joins:

  • branch system group based on received branch_id. This will make branch group formulas available to the terminal.

  • HWType group based on SMBios information received from terminal. This will make Saltboot partitioning pillar available to the terminal.

  • TERMINALS if this group exists.

Uyuni for Retail command line tools create required system groups and branch group automatically.

In case you plan to use the branch server as a monitoring server with Prometheus, be aware that Prometheus demands additional hardware resources. For more information about installing Prometheus, see Monitoring with Prometheus and Grafana.

In case you plan to use the branch server with Ansible software, be aware that Ansible demands additional hardware resources. For more information about installing Ansible, see Ansible Integration.

4. Configure Services for Saltboot

Saltboot technology is used to deploy POS images to the terminals. Saltboot consists of saltboot enabled initrd (build as part of POS images) and saltboot Salt states.

This section covers general information about generic Saltboot requirements. For configuration examples, see Example configurations.

4.1. Enable PXE Network Boot in the Terminal Network

Saltboot is usually used in network boot environment. For this to work DHCP service for the network terminal is connected to must have PXE or sometimes called BOOTP support enabled.

Example 1. Example of ISC DHCP server configuration with PXE booting enabled
if substring (option vendor-class-identifier, 0, 10) = "HTTPClient" {
  option vendor-class-identifier "HTTPClient";
  filename "<FQDN of branch server proxy>/saltboot/shim.efi";
}
else {
  if option arch = 00:07 {
     filename "boot/shim.efi";
     next-server <IP address of branch server proxy>;
  }
  else {
    filename "boot/pxelinux.0";
    next-server <IP address of branch server proxy>;
  }
}

Notice two important options, next-server which is set to the branch server IP address and filename set to the boot/pxelinux.0 for BIOS based system and boot/shim.efi for UEFI systems with SecureBoot support.

Containerized branch proxy uses different filename then regular branch server.

For containerized branch proxy set filename to the pxelinux.0 for BIOS based system and grub/shim.efi for UEFI systems with SecureBoot.

4.2. Saltboot Service Discovery

Saltboot requires some information where the Salt master is and from where to download the image. Saltboot tries multiple discoveries to obtain this information, described below.

For successful terminal deployment, both service discoveries must be successful. Depending on your architecture, choose what strategy works for you best.

4.2.1. Salt Master Discovery

During Saltboot initrd start, integrated Salt client needs to find branch server proxy to connect to. This discovery is trying following steps:

  • MASTER kernel command line option is set, then this is used as Salt master

  • resolve salt CNAME, if successful then resolved value is used as Salt master

  • use salt as a Salt master

Once Salt master is determined, Salt client configuration is generated and started.

Using fully qualified domain name in MASTER or salt CNAME is important.

If used fully qualified domain name is different from fully qualified domain name of branch server proxy known to Uyuni, Saltboot may work correctly, however proxy detection of terminal will not work.

4.2.2. Download Server Discovery

Before POS image is downloaded to the terminal, download server discovery is done to find where to download image from:

  • saltboot_download_server pillar is set for terminal, then its value is used

  • saltboot:download_server pillar is set for terminal, then its value is used

  • resolve ftp hostname

Value obtained by download server discovery is then used together with POS image pillar to fetch correct image from correct location.

4.3. Terminal Partitioning and Image Selection

Last piece for Saltboot is to provide partitioning for terminal. This is done individually for each hardware type of terminals. For more information about hardware types, see Deployment basics.

Above mentioned steps are mandatory minimum for successful Saltboot deployment. For configuration examples, see Example configurations.

5. Synchronize Images to the Branch Server

The OS image you use on the Uyuni server must be synchronized for use to the branch server. You can do this with the Salt image-sync state, part of the Image Synchronization Formula.

Procedure: Synchronizing Images to the Branch Server

  1. On the Uyuni server, run this command:

    salt <branch_server_minion_id> state.apply image-sync

  2. The image details will be transferred to /srv/saltboot on the branch server.

You can also set synchronization to run automatically on the branch server. Configure the image synchronization formula to apply the highstate regularly. For more information about Image Synchronization Formula, see Image Synchronization Formula.