System Configuration ​

As noted in the enrollment section a Pillar file for each computer is created as part of the enrollment process. This section will examine the following configuration file and explain each section. Pillar files are always in YAML format.

# Lab computer, assembled 2023-11-21, Seattle, WA USA
include:
  - projects.mycompany.secrets
system:
    highstate-on-startup: False
    services:
        ssh: True
        smb: True
        avahi-daemon: True
        cockpit: True
        nginx: True
        NetworkManager-wait-online: False
        mosquitto: False
    proxy:
        isotope: True
        cockpit: True
    firewall:
        ssh: True
        http: True
        samba: True
        mdns: True
        protopie-connect: True
        mosquitto: False
    systemd:
        enable-user-core-dumps: True
    udev:
        enable-teensy-rules: True
        enable-thumbdrive: True
        allow-serial: True
    admin:
        enable-shell: True
        password: PASSWORD HASH HERE
        enforce-password: True
        enable-sudo-no-password: True
        password-nt: PASSWORD HASH HERE
        authorized-keys:
          - ssh-rsa ... PUBLIC KEY HERE
    wireguard:
        enable: True
        address: 192.168.120.64/32
        private-key: PRIVATE KEY HERE
protopie-connect:
    enable: True
kiosk:
    enable: True
    wireplumber:
        force-single-audio-device: alsa_card.pci-0000_00_1f.3
isotope:
    enable-remote: True
    enable-cockpit-hotkey: True
    enable-desktop: True
    env:
      - ISOTOPE_AUTO_RELOAD=1
      - ISOTOPE_REMOTE_ICE_SERVERS=stun:stun.l.google.com:19302
    packages:
      - my-custom-fonts
projects:
    mycompany:
      - myproject1
      - myproject2
myproject1:
    env: test
myproject2:
    env: prod

# Lab computer, assembled 2023-11-21, Seattle, WA USA
include:
  - projects.mycompany.secrets
system:
    highstate-on-startup: False
    services:
        ssh: True
        smb: True
        avahi-daemon: True
        cockpit: True
        nginx: True
        NetworkManager-wait-online: False
        mosquitto: False
    proxy:
        isotope: True
        cockpit: True
    firewall:
        ssh: True
        http: True
        samba: True
        mdns: True
        protopie-connect: True
        mosquitto: False
    systemd:
        enable-user-core-dumps: True
    udev:
        enable-teensy-rules: True
        enable-thumbdrive: True
        allow-serial: True
    admin:
        enable-shell: True
        password: PASSWORD HASH HERE
        enforce-password: True
        enable-sudo-no-password: True
        password-nt: PASSWORD HASH HERE
        authorized-keys:
          - ssh-rsa ... PUBLIC KEY HERE
    wireguard:
        enable: True
        address: 192.168.120.64/32
        private-key: PRIVATE KEY HERE
protopie-connect:
    enable: True
kiosk:
    enable: True
    wireplumber:
        force-single-audio-device: alsa_card.pci-0000_00_1f.3
isotope:
    enable-remote: True
    enable-cockpit-hotkey: True
    enable-desktop: True
    env:
      - ISOTOPE_AUTO_RELOAD=1
      - ISOTOPE_REMOTE_ICE_SERVERS=stun:stun.l.google.com:19302
    packages:
      - my-custom-fonts
projects:
    mycompany:
      - myproject1
      - myproject2
myproject1:
    env: test
myproject2:
    env: prod

Device Description ​

# Lab computer, assembled 2023-11-21, Seattle, WA USA

# Lab computer, assembled 2023-11-21, Seattle, WA USA

Since minion names in our naming scheme can be opaque, it is a good practice to add some information at the top of the file, perhaps including the purpose of the device, its location, which project(s) it's for, and so on.

Includes ​

Other pillar files may be included within the configuration file. In this case, we include some company-specific secrets such as cryptographic keys that can be used to authorize a particular computer to receive materials protected by cryptographic authentication. Rather than repeat the same information in each configuration, it is contained in a centralized file that is included wherever needed.

include:
  - projects.mycompany.secrets

include:
  - projects.mycompany.secrets

The path here includes a file located at pillar/projects/mycompany/secrets.sls relative to the root of your admin repository. Note that according to Salt convention, the path separator (/) is replaced by periods (.) and the filename extension is omitted.

System Section ​

The system section configures options relevant to the base operating system.

highstate-on-startup ​

When set to true, the computer will automatically apply a new highstate when it first boots and connects to the Salt master server. This can be useful in some environments, but may not always be appropriate as updates to software projects and other content may take some time to download after boot, which can in turn cause certain services and processes to be restarted unexpectedly. To prevent any unwanted interruptions, leave this option set to False and manually apply highstate when desired.

services ​

Determines which services are automatically started on system boot.

• The ssh service can be enabled to
• The smb service is required for computers that host a shared drive for direct deployments. The samba firewall rule must also be enabled to access the shared drive remotely.
• The avahi-daemon service allows computers to be identified by name using multicast DNS. The mdns firewall rule must also be enabled.
• The cockpit service must be enabled to use the Cockpit web-based system administration UI. To access Cockpit remotely, the nginx service must be enabled, the cockpit proxy rule must be enabled, and the http firewall rule must also be enabled.
• The NetworkManager-wait-online rule is a special service that runs only at startup. When set to True, the system will wait until at least one network interface is online before completing the boot process. This can be useful if your projects need to immediately access network resources. However, this may cause a delay in startup when no network is available. For computers that will primarily be used offline, this should be set to False.
• The mosquitto service provides an MQTT broker that can be used for inter-program communications as an alternative to the isotope message bus.

proxy ​

Some services are remotely accessed through a reverse proxy. In order for any of these services to work, the nginx service must be enabled, and the http firewall rule must be enabled.

firewall ​

Configure which firewall rules are enabled. In order for various services to be accessed remotely over a network, their corresponding firewall rule must be enabled. Otherwise, the service will only be available to the local computer (which is desired in some insecure environments).

systemd ​

Generic options relating to the management of services and processes.

• enable-user-core-dumps enables the automatic saving of core dumps when a process crashes. This can be useful when debugging.

udev ​

This section covers options related to external devices.

• enable-teensy-rules enables communication with Aruino-based Teensy devices for any user.
• enable-thumbdrive enables automatic updates via encrypted packages written to a USB drive.
• allow-serial enables serial port reads and writes by any user on every serial device.

admin ​

This section covers options related to the admin user account. An admin account can be used to perform administrative actions via SSH or the Cockpit web UI, and can also deploy content via file share(s).

• enable-shell enables SSH access. Note that the service and firewall rule must also be enabled to access the computer remotely. The admin account must either have an assigned password or have at least one entry in the authorized_keys section.
• password is the SHA-256 hashed password the admin would use with SSH or sudo. If no password is set, then keypair authentication is required for SSH logins using the authorized-keys setting.
• enforce-password optionally resets the admin password each time a highstate is applied. Set this to False to allow local password changes without reverting the password.
• enable-sudo-no-password optionally enables access to sudo with no password by the logged in admin.
• password-nt specifies a password for use with any shared drives. This is a separate option from password above because of the different hashing algorithm.
• authorized-keys is an array of public SSH keys, configuring who is able to log in to the admin account via SSH without using a password.

mkpasswd -m sha256crypt 'password'

mkpasswd -m sha256crypt 'password'

echo -n 'password' | iconv -t utf16le | openssl md4 -provider legacy

echo -n 'password' | iconv -t utf16le | openssl md4 -provider legacy

wireguard ​

Computers may be optionally enrolled in a WireGuard VPN network to facilitate more convenient remote access. When enabled on a computer, the client-side configuration options may be placed in this section.

• enable turns on the WireGuard feature when set to True.
• address specifies the IP address in CIDR notation. It is highly recommended that this always end in a /32 suffix since these connections should only send traffic for a single client.
• private-key contains the client-side key generated by an administrator. This must correspond to the client's public key as defined on the WireGuard server.

ProtoPie Connect section ​

The protopie-connect section determines whether the ProtoPie Connect Embedded service is installed and enabled.

• enable enables the installation of the ProtoPie Connect Embedded service and starts it on boot.
• license contains the text of the license file received from ProtoPie for this device. Without a license file, the service will only run for 10 minutes at a time.

The process for procuring a ProtoPie Connect license for a particular computer involves the following steps:

1. Retrieve the ProtoPie Device ID by looking at the protopie-connect service's logs.

When directly logged into the computer via SSH:

journalctl -u protopie-connect -n 100

journalctl -u protopie-connect -n 100

When logged into the Salt master server:

salt isotope-123456 cmd.run 'journalctl -u protopie-connect -n 100'

salt isotope-123456 cmd.run 'journalctl -u protopie-connect -n 100'

2. Send the device ID to your ProtoPie sales contact, requesting a license for some length of time.

3. When the license file is received, paste its contents as a single line into the license field.

Kiosk Section ​

This section controls options relating to kiosk mode, which configures the system to boot directly into some service such as isotope instead of a standard desktop UI or login screen.

• enable enables kiosk mode. For most computers running isotope with hardware displays connected, this should be set to True.

wireplumber ​

This sub-section contains some options specific to the WirePlumber service which handles the routing of audio streams.

• force-single-audio-device, when defined, will specify that only one audio device should be enabled and all others disabled. The name corresponds to the card name as printed by the pactl show cards command. This option is mainly used as a workaround for programs that don't properly use the default audio device selected in the web console.

isotope Section ​

This section controls configuration options related to isotope itself. When this section is present in the file, it will be installed and launched automatically on boot, provided that the enable option is also set in the kiosk section.

• enable-remote enables remote streaming of isotope outputs. To access the web console, the reverse proxy must be enabled and allowed via the firewall.
• enable-cockpit-hotkey enables a global hotkey Ctrl-Alt-F3 to locally access the Cockpit web UI via a connected display. This requires the cockpit service to be enabled, but does not require the reverse proxy or firewall rules. The admin user must log in using a password.
• enable-desktop enables global hotkey to switch to a local desktop environment as a fallback option for certain situations. The admin user must log in using a password.
• env is an array of environment variables that will be passed to isotope. These are system-specific values that control isotope's behavior. See the section below for a detailed list. Each entry in the list takes the format VARIABLE=VALUE.
• packages specifies a list of additional OS-level packages that may be required by your projects. This can include packages form the upstream OS repository, or from any custom repository that has been enabled.

Environment Variables ​

These are the environment variables recognized by isotope. They can be placed in the env list inside the isotope section. Beware that setting some of these manually may interfere with the normal operation of isotope and with other settings in the configuration file, as some of those options also set environment variables.

When the remote service is enabled, the following additional environment variables may be used:

Projects Section ​

The projects section is a dynamic section that is specific to particular projects. It can be used to deploy custom projects that were packaged as part of an automated build pipeline. The options here will depend on the Salt definitions for your particular project. Secured projects may require certain secrets to be deployed to the computer via the include section.

The example here includes Salt recipes from the salt/projects/mycmopany folder.

Per-Project Sections ​

Each project or environment can additionally specify their own sections. These sections are free-form and any names may be used as long as they don't clash with other sections. The example here defines a mycompany project group with a value env set to test. This serves as a convenient way to organize groups of devices.

salt -I 'mycompany:env:test' state.apply

salt -I 'mycompany:env:test' state.apply