The UBOS Staff


The UBOS Staff allows the secure installation and configuration of UBOS devices without ever having to attach a keyboard or monitor to the device. This is particularly convenient for physical hardware that is “hidden away” somewhere, and where attaching a monitor and keyboard would be cumbersome, like inside an IoT device.

In particular, the UBOS Staff can be used:

  • to provision an administrator account on the device called the Shepherd account, into which the user can ssh over the network. Either existing ssh credentials provided by the user can be used, or UBOS can generate a new key pair automatically.
  • to connect to a WiFi access point with credentials provided by the user on the UBOS Staff;
  • to automatically install and configure a Site upon boot.

The UBOS Staff is simply a standard USB flash drive whose name and directory layout follows certain conventions. A similar mechanism is available for virtualized machines.

See also blog post with a longer discussion.

UBOS Staff device format and name

Any standard USB flash drive can be used as the UBOS staff. It is recommended that such a USB flash drive only be used as UBOS staff, and not for other purposes at the same time.

The drive must have a “VFAT” (“Windows”) partition called UBOS-STAFF – otherwise UBOS will not recognize the device as a UBOS staff. This can often be accomplished simply by inserting a new USB flash drive in a computer, and renaming the device to UBOS-STAFF.

The USB flash drive can have any size; the amount of storage required for use as UBOS staff is minimal. Speed is also largely irrelevant.

The UBOS Staff device uses the following directory layout. For details, see below:

Directory File Description
shepherd/ssh/ SSH public key for the shepherd account.
id_rsa SSH private key for the shepherd account. You can delete it here once you have copied it to your workstation from where you will be logging into your UBOS device(s).
wifi/ <ssid>.conf This directory may contain several files, one for each to-be-configured WiFi SSID. Each file must be named based on the SSID it configures.
site-templates/ <name>.json This directory may contain several Site JSON template files. Each of them will be instantiated and deployed to any device that reads this Staff unless a Site with the same hostname exists already on the device.
flock/<HOSTID>/bootlog/ <timestamp>.txt Text files containing the UBOS device’s boot log from the journal. This may help with troubleshooting issues on devices that don’t have a monitor.
flock/<HOSTID>/device-info/ device.json A JSON file containing information about the device.
flock/<HOSTID>/site-templates/ <name>.json This directory may contain several Site JSON files or Site JSON template files. Each of them will be instantiated (if a template) and deployed to the device with host id <HOSTID>, but ignored on other devices.
flock/<HOSTID>/sites/ <name>.json This directory may contain several Site JSON files, which represent the Site(s) as deployed on the device at the time the Staff was written last.
flock/<HOSTID>/ssh/ ssh_host_<type>_key This directory may contain one or more of the device’s SSH host keys of different types, such as rsa or ecdsa. This can be used, in addition to shepherd SSH key pair, to authenticate the host (not just the client) over the network.
root of Staff device I-ADMINISTER-MY-UBOSBOX-MYSELF.txt If package ubos-live is installed, a Staff device is present at boot and a file with this name is NOT present, the UBOS device will register itself with Indie Computing’s UBOS Live device management service. To prevent this, do not install package ubos-live or create a file (content is irrelevant) with this name on the UBOS Staff device.

<HOSTID> refers to the device’s unique hostid, which can be printed with ubos-admin hostid.

Note: all files and directories are optional and may not be present on a given UBOS Staff: an empty drive called UBOS-STAFF is entirely valid.

Virtual UBOS Staff devices

In the cloud

When booting an UBOS image on Amazon EC2, UBOS instead will take the key pair specified by the user in the instance creation wizard on the Amazon website, and configure the Shepherd account with it. No actual Staff device is required.

UBOS will never auto-generate a new key pair in the cloud.

In a Linux container

When booting UBOS in a Linux container, UBOS will treat the directory /UBOS-STAFF as the UBOS Staff, assuming it is present in the container (not the host).

It may be advantageous to bind a suitable directory into the container with the --bind flag to systemd-nspawn.

UBOS will never auto-generate a new key pair when running UBOS in a container.

Provisioning a shepherd account

An automatically provisioned shepherd account can be used as the primary administration account on a UBOS device. By default, it has the rights to invoke sudo ubos-admin, sudo systemctl and the like. It can also become root with su without password.

If the device is booted a second time with the Staff present, the ssh key will be updated. (We work under the assumption that if an attacker has the ability to physically insert a USB device into the USB port and reboot the device, the device should be considered compromised in any case.)

Provision a shepherd account with an existing ssh public key

If you would like to use an existing ssh public key to log into your UBOS device(s) over the network as user shepherd, create the following file system layout:


where the file contains a valid ssh public key. You can use any existing ssh public key for which you have the corresponding private key.

I.e., the file called must be contained in a directory named ssh, which in turn must be contained in a directory called shepherd at the root level of the directory hierarchy.

Provision a shepherd account with a newly generated ssh key pair

If you don’t have an ssh key pair yet, and would like UBOS to generate one for you, simply use a UBOS Staff device that is empty or at least does not have the shepherd directory yet at the root of the device.

During boot, UBOS will automatically generate the key pair, save it to the UBOS Staff, and create the shepherd account on the device. (This behavior only occurs with a physical Staff device; not with a virtual Staff device in case of running UBOS in the cloud or in a Linux container.)

Once UBOS has booted and generated the ssh keys, you can unplug the Staff device and insert it into the computer from which you want to log into your UBOS device. Copy the file shepherd/ssh/id_rsa from the Staff device into a secure place on your computer, as anybody who has access to this file can use it to log into your UBOS device. Also, delete the id_rsa file from the UBOS Staff for the same reason. (The file is the public key which can be shared without harm.)

Assuming you have saved the private key to file ~/private/my-ubos-shepherd-key and the hostname of your UBOS device is ubos-device.local, you can now ssh into your UBOS device with the command:

% ssh -i ~/private/my-ubos-shepherd-key shepherd@ubos-device.local

To log into a remote UBOS device as the shepherd

On the computer that has the private id_rsa file, execute the following command:

% ssh -i <id_rsa> shepherd@

where <id_rsa> is the name of the file containing the private key from above, and is replaced with the IP address or hostname of your device, such as ubos-pc.local (see Setting up networking and DNS).

If you had UBOS generate the key pair, copy the private key file id_rsa to your computer first: ssh will not let you use the id_rsa directly from the UBOS Staff.

If you use a Windows workstation and PuTTY as your ssh client, you need to first convert the id_rsa file into the “PuTTY Private Key Files (.ppk)” format by running puttygen.exe. Then, use the converted file as the authentication parameter with the PuTTY-Client.

To setup WiFi

If you would like your device to be able to connect to WiFi immediately after its boots, you can provide information about one or more WiFi networks on on the UBOS Staff, and UBOS will configure your device as a WiFi client. Of course, this assumes that your device has WiFi support and all relevant drivers have been installed (if not, this will do nothing).

To provide information on a WiFi network called ExampleWiFi, create file wifi/ExampleWiFi.conf with the following content:


ssid must be the WiFi network’s SSID (here: ExampleWiFi) and psk must be the corresponding WiFi passphrase.

You can specify more than one file in directory wifi/, and your device will be able to connect to any of those networks. If your network needs more configuration, you can add additional settings accepted by wpa_supplicant into these files: UBOS simply inserts the content of those files into the network={ ... } section of a generated wpa_supplicant.conf file, and so you can add any settings there acceptable to wpa_supplicant.

You should also create a file in directory wifi/ called wireless-regdom. Allowed WiFi frequencies are different in different countries, and this allows you to conform to radio emission regulations in your country. This file should contain a single line that, if you are based in the United States, looks like this:


If you are based in another country, use your two-letter country code instead of US.

To auto-deploy Sites upon boot

If you place one or more Site JSON files, or Site JSON template files in the correct place on the UBOS Staff, UBOS will automatically deploy those Sites. There are two places where those Site JSON template files may be located:

  • If placed in top-level directory site-templates/, any UBOS device booting with the UBOS Staff will deploy the corresponding Sites. It is highly recommended that the files be Site JSON template files that do not contain SiteIds or AppConfigIds in order to generate unique identifiers on different devices.
  • If placed in directory flock/<HOSTID>/site-templates/, where <HOSTID> is the host identifier of a particular device, UBOS will only deploy the Sites on that device.

Sites or Site templates will not be deployed if the device already as a Site with either the same hostname or the same SiteId or AppConfigId.

The Site JSON files of the Sites deployed through this mechanism will, once the Site has been deployed, stored in flock/<HOSTID>/sites/<SITEID>.json. This gives the user a way of knowing automatically-generated credentials, for example.

UBOS boot behavior with Staff present

When UBOS boots, UBOS checks for the presence of a disk with a partition named UBOS-STAFF. If it detects such a disk, it looks for the file in the location described above.

If UBOS finds such a file, UBOS:

  1. Creates a Linux user called shepherd unless it exists already.
  2. Saves the content of verbatim as ~shepherd/.ssh/ This means that the user can log into the device over the network, as user shepherd, as long as the user uses the corresponding private key for authentication.

UBOS also looks for two further directories:

  • one directory called site-templates below the shepherd directory
  • one directory called site-templates below the host directory below the flock directory, where the host directory is named after the host identifier of the current device.

UBOS looks for Site template files in both of those directories. If those exist, UBOS will deploy the specified Sites when booting has completed.

Disabling Staff functionality

To disable reading the Staff device on boot at all, change the setting host.readstaffonboot to false in /etc/ubos/config.json.

To disable modifying the Staff device on boot, such as by generating a new SSH keypair, change the setting host.initializestaffonboot to false in /etc/ubos/config.json.