Deploy Terminals - Other Methods

Table of Contents

1. Deploy Terminals with a Removable USB Device
2. Deploy Terminals over a Wireless Network
- 2.1. Change Wireless Credentials
- 2.2. Use Multiple Wireless Networks

If you are not able to boot terminals from the network, you can create a live USB image and deploy terminals using a removable USB storage device. You can also bootstrap terminals across a wireless network.

Hardware type groups must be created and images must be synchronized before continuing. For more information, see Deployment basics.

After you have registered new terminals, always check the Uyuni Web UI to ensure your terminals have connected successfully to the branch server, and not directly to the Uyuni Server by mistake.

1. Deploy Terminals with a Removable USB Device

If you do not want to boot terminals from the network, you can create a live USB image and deploy terminals using a removable USB storage device. This is useful if you cannot boot your terminals from the network, or if you do not have a local Uyuni for Retail branch server providing network services.

You can prepare a bootable USB device with the image and tools required to deploy a POS terminal using a remote Uyuni for Retail branch server. You can create the bootable USB device on the branch server directly, or on the Uyuni for Retail Server.

POS devices booted using the USB device are assigned to the Uyuni for Retail branch server that created the USB device.

Procedure: Creating a Bootable USB Device

On the Uyuni for Retail branch server, at the command prompt, as root, create the POS image.

You need to specify the size of the image, in megabytes.

Ensure you allow at least 300 MB:
```
salt-call image_sync_usb.create <usb image name> <size in MB>
```
Insert the USB device into the Uyuni for Retail branch server machine, and copy the image to the new location:
```
dd bs=1M if=<usb image name> of=<path to usb device>
```

When you have the image on the USB drive, check that the terminals you want to deploy allow local booting. You can check this by editing the Saltboot formula in the Uyuni for Retail Web UI. For more information about the Saltboot formula, see Saltboot Formula.

Procedure: Deploying Images to the Terminals using USB

Insert the USB device into the terminal.
Power on the POS terminal.
Boot from the USB device to begin bootstrapping.

2. Deploy Terminals over a Wireless Network

For terminals that cannot be connected directly to the physical network, you can deploy them over a wireless network. Wireless networks do not support PXE booting, so you must perform the initial booting and initialization of the wireless connection on the terminal using a USB device.

For more information about using USB devices to boot, see Deploy Terminals - Other Methods.

Bootstrapping across a wireless network could expose a security risk if you are using encrypted OS images. The boot initrd image and the partition that contains /etc/salt must be stored unencrypted on the terminal. This allows Uyuni for Retail to set up the wireless network. If this breaches your security requirements, you will need to use a separate production network, with network credentials managed by Salt, so that credentials are not stored on the terminal unencrypted.

Before you begin, you need to have created a bootable USB device. Ensure that the OS image you use to create the USB device has the dracut-wireless package included. For more information about using USB devices to boot, see Deploy Terminals - Other Methods.

When you have created the USB device, you need to provide the wireless credentials to the terminal. You can do this in a number of ways:

Directly during image build.
Add it to the initrd file on the branch server.
During terminal booting, using the kernel command line.

Procedure: Providing Wireless Credentials During Image Build

Ensure that the dracut-wireless package is included in the image template.
Set the wireless credentials by creating or editing the etc/sysconfig/network/ifcfg-wlan0 file to the image template, with these details:
```
# ALLOW_UPDATE_FROM_INITRD
WIRELESS_ESSID=<wireless network name>
WIRELESS_WPA_PSK=<wireless network password>
```
If you want to use different credentials for bootstrapping to what is used during normal operation, you can remove the ALLOW_UPDATE_FROM_INITRD line.
Build the image.
Prepare a USB device using this image, and boot the terminal. For more information about using USB devices to boot, see Deploy Terminals - Other Methods.

Procedure: Providing Wireless Credentials with initrd

Set the wireless credentials by creating or editing the etc/sysconfig/network/ifcfg-wlan0 file, with these details:
```
# ALLOW_UPDATE_FROM_INITRD
WIRELESS_ESSID=<wireless network name>
WIRELESS_WPA_PSK=<wireless network password>
```

. Copy the file to initrd on the branch server:

echo ./etc/sysconfig/network/ifcfg-wlan0 | cpio -H newc -o | gzip >> /srv/saltboot/boot/initrd.gz

Check that the terminals you want to deploy allow local booting. You can check this by editing the Saltboot formula in the Uyuni for Retail Web UI. For more information about the Saltboot formula, see Saltboot Formula.

Procedure: Providing Wireless Credentials During Terminal Boot

Mount the USB device on the terminal, and boot from it.

Append these commands to the kernel boot parameters:

WIRELESS_ESSID=<wireless_network_name>
WIRELESS_WPA_PSK=<wireless_network_password>

2.1. Change Wireless Credentials

After you have set the wireless credentials, you can change them as needed. The way to do this is different if you use one company-wide network, or if you have each branch server on its own separate network.

Procedure: Changing Wireless Credentials for Single Network

Rebuild the boot image with updated credentials.
Recreate the bootable USB device based on the new boot image.
Boot terminal from new USB device.

Procedure: Changing Wireless Credentials for Multiple Networks

In the /srv/salt/ directory, create a salt state called update-terminal-credentials.sls, and enter the new wireless network credentials:

/etc/sysconfig/network/ifcfg-wlan0
  file.managed:
   - contents: |
        WIRELESS_ESSID=<wireless_network_name>
        WIRELESS_WPA_PSK=<wireless_network_password>
# regenerate initrd
  cmd.run:
  - name: 'mkinitrd'

Apply the Salt state to the terminal:

salt <terminal_salt_name> state.apply update-terminal-credentials

If you are using a separate network for the boot phase, the managed file might need to be renamed, or extended to /etc/sysconfig/network/initrd-ifcfg-wlan0.

2.2. Use Multiple Wireless Networks

You can configure terminals to use a different set of wireless credentials during the boot process, to what they use during normal operation.

If you provide wireless credentials using initrd files, you can create two different files, one for use during boot called initrd-ifcfg-wlan0, and the other for use during normal operation, called ifcfg-wlan0.

Alternatively, you can use custom Salt states to manage wireless credentials with saltboot-hook.

First of all, you need to set the wireless details for normal operation. This will become the default settings. Then you can specify a second Salt state with the wireless details for use during the boot procedure.

Procedure: Using Different Wireless Credentials for Production Network

Write a custom Salt state named /srv/salt/saltboot_hook.sls containing the wireless details for normal operation. This Salt state is applied by Saltboot after the system image is deployed.

{% set root = salt['environ.get']('NEWROOT') %}
{{ root }}/etc/sysconfig/network/ifcfg-wlan0:
  file.managed:
   - contents: |
        WIRELESS_ESSID=<wireless_network_name>
        WIRELESS_WPA_PSK=<wireless_network_password>
    - require:
      - saltboot: saltboot_fstab
    - require_in:
      - saltboot: boot_system

The boot phase supports only WPA2 PSK wireless configuration. Salt-managed production configuration supports all features supported by all major operating systems.