The UBOS Staff

Overview

The UBOS Staff allows the secure installation and configuration of 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.

Among other things, 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 and saved to 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 Devices.

See also this 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 drive 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 uses the following directory layout. For details, see below:

Directory	File	Description
shepherd/ssh/	id_rsa.pub	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 Device.
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, with extension .conf.
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 UBOS Staff unless a Site with the same hostname exists already on the Device, or reading Site JSON Template files has been disabled on the Device.
flock/<HOSTID>/bootlog/	%lt;timestamp%gt.txt	Text files containing the Device's boot log from the systemd journal. This may help with troubleshooting issues on Devices that don't have an attached 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 one or more Site JSON files or Site JSON Template files. Each of them will be instantiated (if a template) and deployed to the Device with HostId <HOSTID>, but ignored on other Devices.
flock/<HOSTID>/sites/	<name>.json	This directory may contain several Site JSON files, which represent the Site or Sites as they were deployed on the Device with HostId <HOSTID> at the time the UBOS 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 the shepherd SSH key pair, to authenticate the host (not just the client) over the network.
root of UBOS Staff	I-ADMINISTER-MY-UBOSBOX-MYSELF.txt	Future placeholder.

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

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.

None of the other UBOS Staff functionality is available 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 (see I need root).

If a Device is booted a second time with the UBOS 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 Device over the network as user shepherd, create the following file system layout:

shepherd/
    ssh/
        id_rsa.pub

where the file id_rsa.pub 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 id_rsa.pub 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 of the UBOS Staff.

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 that is empty or at least does not have the shepherd directory yet at the root of the UBOS Staff.

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 UBOS Staff; not with a virtual UBOS Staff 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 UBOS Staff and insert it into the computer from which you want to log into your Device. Copy the file shepherd/ssh/id_rsa from the UBOS Staff into a secure place on your computer, as anybody who has access to this file can use it to log into your Device. Also, delete the id_rsa file from the UBOS Staff for the same reason. (The file id_rsa.pub is the public key which can be shared without harm.)

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@1.2.3.4

where <id_rsa> is the name of the file containing the private key from above, and 1.2.3.4 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 it boots, you can save information about one or more WiFi networks to the UBOS Staff, and UBOS will configure your Device as a WiFi client when it boots. 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="ExampleWiFi"
psk="MySecret"

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:

WIRELESS_REGDOM="US"

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 during boot. There are two places where those files may be located:

• If placed in top-level directory site-templates/, any Device booting with the UBOS Staff will deploy the corresponding Sites. This functionality is useful if you’d like to deploy the same kind of Site running the same Apps and Accessories to several Devices.

  It is highly recommended that the files be Site JSON Template files (rather that Site JSON files) that do not contain SiteIds or AppConfigIds, in order to generate unique identifiers for Sites and AppConfigurations on different Devices.

• If placed in directory flock/<HOSTID>/site-templates/, where <HOSTID> is the host identifier of a particular Device as determined by ubos-admin hostid, UBOS will only deploy the Sites on that Device.

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.

Disabling UBOS Staff functionality

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

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