Formulas

Formulas are pre-written Salt states, that are used to configure your SUSE Manager for Retail installation.

This section lists the primary formulas shipped with SUSE Manager for Retail and their configuration options.

All the formulas in this section must be accurately configured for your SUSE Manager for Retail installation to function correctly. If you are unsure of the correct formula configuration details, run the retail_branch_init command before you begin to create the recommended formula configuration. You can then manually edit the formulas as required.

State and formula name collisions

If a formula uses the same name as an existing Salt state, the two names will collide, and could result in the formula being used instead of the state. Always check the names of states and formulas to avoid name collisions.

Most formulas can be updated using the SUSE Manager Web UI. Once you have made changes to your formula, ensure you apply the highstate to propagate your changes to the appropriate services.

Bind Formula

The Bind formula is used to configure the Domain Name System (DNS) on the branch server. POS terminals will use the DNS on the branch server for name resolution of saltboot specific hostnames.

When you are configuring the bind formula for a branch server with a dedicated internal network, check that you are using the same fully qualified domain name (FQDN) on both the external and internal branch networks. If the FQDN does not match on both networks, the branch server will not be recognized as a proxy server.

The following procedure outlines a standard configuration with two zones. Adjust it to suit your own environment.

Zone 1 is a regular domain zone. Its main purpose is to resolve saltboot hostnames such as TFTP, FTP, or Salt. It can also resolve the terminal names if configured.

Zone 2 is the reverse zone of Zone 1. Its main purpose is to resolve IP addresses back to hostnames. Zone 2 is primarily needed for the correct determination of the FQDNs of the branch.

Procedure: Configuring Bind with Two Zones

  1. Check the Bind formula, and click Save.

  2. Navigate to the Formulas  Bind tab, and set these parameters for Zone 1:

    • In the Config section, select Include Forwarders.

    • In the Name field, enter the domain name of your branch network (for example: branch1.example.org).

    • In the Type field, select master.

  3. Click Add item to save your changes.

  4. Set these parameters for Zone 2:

    • In the Name field, use the reverse zone for the configured IP range (for example: 1.168.192.in-addr.arpa).

    • In the Type field, select master

  5. In the Available Zones section, use these parameters for Zone 1:

    • In the Name field, enter the domain name of your branch network (for example: branch1.example.org).

    • In the File field, type the name of your configuration file.

  6. In the Start of Authority (SOA) section, use these parameters for Zone 1:

    • In the Nameserver (Ns) field, use the FQDN of the branch server (for example: branchserver.branch1.example.org).

    • In the Contact field, use the email address for the domain administrator.

    • Keep all other fields as their default values.

  7. In the Records section, in subsection A, click Add Item and use these parameters to set up an A record for Zone 1:

    • In the Hostname field, use the hostname of the branch server (for example: branchserver).

    • In the IP field, use the IP address of the branch server (for example, 192.168.1.1).

  8. In the Records section, subsection NS, click Add Item and use these parameters to set up an NS record for Zone 1:

    • In the input box, use the hostname of the branch server (for example: branchserver).

  9. In the Records section, subsection CNAME, click on Add Item and add the hostname of the branch server in each of these fields:

    • tftp

    • ftp

    • dns

    • dhcp

    • salt. The salt CNAME should be the FQDN of the branch server’s external interface for proxy functionality to work correctly.

  10. Set up Zone 2 using the same parameters as for Zone 1, but ensure you use the reverse details:

    • The same SOA section as Zone 1.

    • Empty A and CNAME records.

    • Additionally, configure in Zone 2:

      • Generate Reverse field by the network IP address set in branch server network formula (for example, 192.168.1.1/24).

      • For Zones should specify the domain name of your branch network (for example, branch1.example.org).

  11. Click Save Formula to save your configuration.

  12. Apply the highstate.

Reverse name resolution on terminals might not work for networks that are inside one of these IPv4 private address ranges:

  • 10.0.0.0/8

  • 172.16.0.0/12

  • 192.168.0.0/16

If you encounter this problem, go to the Options section of the Bind formula, and click Add item: * In the Options field, enter empty-zones-enable. * In the Value field, select No.

Branch Network Formula

The branch network formula is used to configure the networking services required by the branch server, including DHCP, DNS, TFTP, PXE, and FTP.

The branch server can be configured to use networking in many different ways. The most common ways provide either a dedicated or shared LAN for terminals.

Set up a branch server with a dedicated LAN

In this configuration, the branch server requires at least two network interfaces: one acts as a WAN to communicate with the SUSE Manager server, and the other one acts as an isolated LAN to communicate with terminals.

This configuration allows for the branch server to provide DHCP, DNS, TFTP, PXE and FTP services to terminals, which are configured through SUSE Manager for Retail formulas in the SUSE Manager Web UI.

Procedure: Setting up a branch server with a dedicated LAN

  1. In the SUSE Manager Web UI, open the details page for the branch server, and navigate to the Formulas tab.

  2. In the Branch Network section, set these parameters:

    • Keep Dedicated NIC checked

    • In the NIC field, enter the name of the network device that is connected to the internal LAN.

    • In the IP field, enter the static IP address to be assigned to the branch server on the internal LAN.

    • In the Netmask field, enter the network mask of the internal LAN.

  3. Check Enable Route if you want the branch server to route traffic from internal LAN to WAN.

    • Check Enable NAT if you want the branch server to convert addresses from internal LAN to WAN.

    • Select the bind DNS forwarder mode.

    • Check DNS forwarder fallback if you want to rely on an external DNS if the branch DNS fails.

    • Specify the working directory, and the directory owner and group.

  4. Click Save to save your changes.

  5. Apply the highstate.

Set up a branch server with a shared network

In this configuration, the branch server has only one network interface card, which is used to connect to the SUSE Manager server as well as the terminals.

This configuration allows for the branch server to provide DNS, TFTP, PXE and FTP services to terminals, which are configured through SUSE Manager for Retail formulas in the SUSE Manager Web UI. Optionally, the branch server can also provide DHCP services in this configuration.

If DHCP services are not provided by the branch server, ensure that your external DHCP configuration is set correctly: * The next-server option must point to the branch server for PXE boot to work * The filename option must correctly identify the network boot program (by default, this is /boot/pxelinux) * The domain-name-servers option must point to the branch server for correct host name resolution
Procedure: Setting up a branch server with a shared network

  1. In the SUSE Manager Web UI, open the details page for the branch server, and navigate to the Formulas tab.

  2. In the Branch Network section, set these parameters:

    • Keep Dedicated NIC unchecked

    • Select which services to enable on the branch server’s firewall. Ensure you include DNS, TFTP and FTP services.

    • Select the bind DNS forwarder mode.

    • Check DNS forwarder fallback if you want to rely on an external DNS if the branch DNS fails.

    • Specify the working directory, and the directory owner and group.

  3. Click Save to save your changes.

  4. Apply the highstate.

DHCPd Formula

The DHCPd formula is used to configure the DHCP service on the branch server.

Procedure: Configuring DHCP

  1. In the SUSE Manager Web UI, open the details page for the branch server, and navigate to the Formulas tab.

  2. Select the Dhcpd formula, and click Save.

  3. Navigate to the Formulas  Dhcpd tab, and set these parameters:

    • In the Domain Name field, enter the domain name for the branch server (for example: branch1.example.com).

    • In the Domain Name Server field, enter either the IP address or resolvable FQDN of the branch DNS server (for example: 192.168.1.1).

    • In the Listen Interfaces field, enter the name of the network interface used to connect to the local branch network (for example: eth1).

  4. Navigate to the Network Configuration (subnet) section, and use these parameters for Network1:

    • In the Network IP field, enter the IP address of the branch server network (for example: 192.168.1.0).

    • In the Netmask field, enter the network mask of the branch server network (for example: 255.255.255.0).

    • In the Domain Name field, enter the domain name for the branch server network (for example: branch1.example.com).

  5. In the Dynamic IP Range section, use these parameters to configure the IP range to be served by the DHCP service:

    • In the first input box, set the lower bound of the IP range (for example: 192.168.1.51).

    • In the second input box, set the upper bound of the IP range (for example: 192.168.1.151).

  6. In the Broadcast Address field, enter the broadcast IP address for the branch network (for example: 192.168.1.255).

  7. In the Routers field, enter the IP address to be used by routers in the branch server network (for example: 192.168.1.1).

  8. In the Next Server field, enter the hostname or IP address of the branch server (for example: 192.168.1.1).

  9. In the Filename field, keep the default value of /boot/pxelinux.0.

  10. Click Save Formula to save your configuration

  11. Apply the highstate.

PXE Formula

The PXE formula is used to configure PXE booting on the branch server.

Procedure: Configuring PXE booting

  1. In the SUSE Manager Web UI, open the details page for the branch server, and navigate to the Formulas tab.

  2. Select the Pxe formula, and click Save.

  3. Navigate to the Formulas  Pxe tab, and set these parameters:

    • In the Kernel filename field, keep the default value.

    • In the Initrd filename field, keep the default value.

    • In the Kernel commandline parameters field, keep the default value.

    • In the PXE root directory field, enter the path to the saltboot directory (for example, /srv/saltboot).

    • In the Branch id field, type a name to use as a branch identifier (for example: Branch0001). Use only alphanumeric characters for the branch identifier.

  4. Click Save Formula to save your configuration

  5. Apply the highstate.

Saltboot Formula

The Saltboot formula is used to configure disk images and partitioning for the selected hardware type.

Saltboot formula is meant to be used as a group formula. Enable and configure saltboot formula for hardware type groups.
Procedure: Configuring the hardware type group with saltboot

  1. Open the details page for your new hardware type group, and navigate to the Formulas tab.

  2. Select the saltboot-formula and click Save.

  3. Navigate to the new Formulas  Saltboot tab.

  4. In the Disk 1 section, set these parameters:

    • In the Disk symbolic ID field, enter a custom name for the disk (for example, disk1).

    • In the Device type field, select DISK.

    • In the Disk device field, select the device that corresponds to the device name on the target machine (for example, /dev/sda).

    • In the RAID level field, leave it empty.

    • In the Disk Label field, select gpt.

  5. In the Partition section, set these parameters for Partition 1:

    • In the Partition symbolic ID field, enter a custom name for the partition (for example, p1).

    • In the Partition size field, specify a size for the partition in Mebibytes (MiB).

    • In the Device mount point field, select a location to mount the partition (for example, /data).

    • In the Filesystem format field, select your preferred format (for example, xfs).

    • In the OS Image to deploy field, leave it empty.

    • In the Partition encryption password field, enter a password if you want to encrypt the partition.

    • In the Partition flags field, leave it empty.

  6. In the Partition section, set these parameters for Partition 2:

    • In the Partition symbolic ID field, enter a custom name for the partition (for example, p2).

    • In the Partition size field, specify a size for the partition in Mebibytes (MiB).

    • In the Device mount point field, leave it empty.

    • In the Filesystem format field, select swap.

    • In the OS Image to deploy field, leave it empty.

    • In the Partition encryption password field, enter a password if you want to encrypt the partition.

    • In the Partition flags field, select swap.

  7. In the Partition section, set these parameters for Partition 3:

    • In the Partition symbolic ID field, enter a custom name for the partition (for example, p3).

    • In the Partition size field, leave it empty. This will ensure the partition uses up all remaining space.

    • In the Device mount point field, select /.

    • In the Filesystem format field, leave it empty.

    • In the OS Image to deploy field, enter the name of the image to deploy.

    • In the Image version field, leave it empty. This will ensure you use the latest available version.

    • In the Partition encryption password field, enter a password if you want to encrypt the partition.

    • In the Partition flags field, leave it empty.

  8. Click Save Formula to save your formula.

TFTPd Formula

The TFTPd formula is used to configure the TFTP service on the branch server.

Procedure: Configuring TFTP

  1. In the SUSE Manager Web UI, open the details page for the branch server, and navigate to the Formulas tab.

  2. Select the Tftpd formula, and click Save.

  3. Navigate to the Formulas  Tftpd tab, and set these parameters:

    • In the Internal Network Address field, enter the IP address of the branch server (for example: 192.168.1.1).

    • In the TFTP Base Directory field, enter the path to the saltboot directory (for example, /srv/saltboot).

    • In the Run TFTP Under User field, enter saltboot.

  4. Click Save Formula to save your configuration.

  5. Apply the highstate.

VsFTPd Formula

The VsFTPd formula is used to configure the FTP service on the branch server.

Procedure: Configuring VsFTPd

  1. In the SUSE Manager Web UI, open the details page for the branch server, and navigate to the Formulas tab.

  2. Select the Vsftpd formula, and click Save.

  3. Navigate to the Formulas  Vsftpd tab, and set these parameters:

    • In the Internal Network Address, enter IP address of branch server (for example: 192.168.1.1).

    • All other fields can retain their default values.

  4. Click Save Formula to save your configuration

  5. Apply the highstate.