Set Up the Uyuni for Retail Environment

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

  • Uyuni Server

  • one or more Uyuni for Retail branch server containerized proxy

  • one or more Uyuni build hosts

  • network stack depending on selected network architecture, see Network Architecture

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

  • Prepare POS images

  • Prepare system groups for Saltboot

  • Configure services for Saltboot

The very first time you set up the Uyuni for Retail environment, you will need to perform all configuration steps in order. 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 group, you will need to have images prepared already. If you are configuring more than one branch server, the same images are reused across different branch server groups.

If you have an existing environment, and need to build new images, you do not need to re-initialize the branches.

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.

POS image templates and resulting images do not set a system user password. You will not be able to login as a system user to a system that has been installed with a SUSE provided template without customization. However you can use Salt to manage clients without a system user password. You can use Salt to set up a system user password after the terminal has been deployed.

1.2. Validate POS Image Registration

After POS image is successfully built and inspected by Uyuni, you can validate that POS boot image was correctly registered by following procedure.

Procedure Validate POS boot image

  1. On Uyuni command line execute following command:

    mgrctl exec cobbler distro list

  2. Your POS image should be listed with organization number before image name

2. Branch Identification

For every branch server choose branch id.

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.

In case you plan to use the branch server container host 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 container host with Ansible software, be aware that Ansible demands additional hardware resources. For more information about installing Ansible, see Ansible Integration.

3.1. Saltboot group

Before configuring Saltboot group, make sure you already have at least one POS image available.

Containerized Uyuni for Retail is configured using so called Saltboot Group.

Saltboot Group is a branch groups, system group with branch id as its name created in previous step, with Saltboot Group formula enabled.

saltboot group

Saltboot Group formula is a successor of Branch Network formula, PXE formula and TFTP formula previously used in Uyuni for Retail setups.

To connect Saltboot group with containerized proxy fill Image Download Server entry with Fully Qualified Domain Name (FQDN) of the containerized proxy.

4. Configure Network 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 "grub/shim.efi";
     next-server <IP address of branch server proxy>;
  }
  else {
    filename "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 pxelinux.0 for BIOS based system and grub/shim.efi for UEFI systems with SecureBoot support.

Uyuni for Retail branch proxy uses different filename then previous non-containerized 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.

5. Terminal Partitioning and Image Selection

Saltboot requires instructions how to partitioning terminal harddisk and what image to deploy. This is done individually for each hardware type of terminals. For more information about hardware types and partitioning, see Deployment basics.

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

6. Synchronize Images to the Branch Server

Uyuni for Retail 2024.12 no longer need manual image synchronization, all images are available to all clients automatically.

This may not be always desired, for example to allow images gradual deployments across all branches. For a way how to limit image deployment, see Best practices.