Documentation:

Command reference

ubos-admin is the central administration command for UBOS. When invoked without arguments, it lists available sub-commands.

To invoke an ubos-admin sub-command, execute:

% sudo ubos-admin <subcommand> <arguments>

To obtain help on a particular sub-command, execute:

% sudo ubos-admin <subcommand> --help

For technical details how these sub-commands work, refer to Understanding ubos-admin in How to develop for UBOS.

ubos-admin backup

To create a backup of all Sites on your device and save it to all.ubos-backup:

% sudo ubos-admin backup --out all.ubos-backup

To create a backup of all Sites on your device and save it to a file in your home directory whose name contains the current timestamp:

% sudo ubos-admin backup --out ~/all-$(date +%Y%m%d%H%M).ubos-backup

To create a backup of a single Site and save it to a file:

% sudo ubos-admin backup --hostname <hostname> --out <backupfile>

or

% sudo ubos-admin backup --siteid <siteid> --out <backupfile>

To create a backup or a single AppConfiguration at a Site and save it to a file:

% sudo ubos-admin backup --appconfigid <siteid> --out <backupfile>

You can determine the SiteId or AppConfigId with ubos-admin listsites.

ubos-admin backup-to-amazon-s3

Make sure package amazons3 is installed:

% sudo pacman -S amazons3

To create a backup and automatically upload it to Amazon S3, use the same options as for ubos-admin backup. In addition, you can use:

  • --encryptid <keyid>: encrypt the backup before uploading with a GPG key with that id found in your GPG key store. Make sure you have access to the private key even once your device has died, otherwise your backup will be useless. WARNING: There are no recovery options other than you protecting your private key.
  • --bucket <bucket>: specify the name of the S3 bucket to store the backup to.

ubos-admin backupinfo

To determine the content of a .ubos-backup file:

% ubos-admin backupinfo --in <backupfile>

ubos-admin createsite

To create and deploy a new Site running one App:

% sudo ubos-admin createsite

and answer the questions at the terminal.

To create and deploy a new Site, running one App and secured by a self-signed SSL/TLS certificate:

% sudo ubos-admin createsite --tls --selfsigned

and answer the questions at the terminal.

To create and deploy a new Site, running one App and secured by a letsencrypt.org SSL/TLS certificate:

% sudo ubos-admin createsite --tls --letsencrypt

and answer the questions at the terminal.

To create and deploy a new Site, running one App and secured by an official SSL/TLS certificate, make sure you have private key and certificate files on the UBOS device, then:

% sudo ubos-admin createsite --tls

and answer the questions at the terminal.

To only create a Site JSON file, append a -n or --dry-run argument. To save the Site JSON file to a file, instead of emitting it on the console, append --out <filename> with a suitable filename.

To create a Site from a Site template file:

% sudo ubos-admin createsite --from-template <template>

ubos-admin deploy

If you have a Site JSON file for a Site, you can deploy the Site and all Apps defined for this Site with:

% sudo ubos-admin deploy --file <site.json>

To obtain a Site JSON file, either:

  • export the Site JSON file for an existing Site with ubos-admin showsite --json --site <siteid>
  • create (but do not deploy) a Site JSON file with ubos-admin createsite --dry-run
  • manually create a Site JSON file; see Site JSON.

You can take an existing Site JSON file, and edit it by, for example:

  • changing the hostname
  • adding or removing Apps running at the Site
  • changing some of the AppConfiguration, such as the path at which the App runs, or some of its customization points.

Currently, this needs to be performed using a text editor.

Then, deploy it again with ubos-admin deploy --file <site.json>. UBOS will find out what changed, and make appropriate adjustments.

Warning

If you remove an App from a Site JSON file, and redeploy the Site JSON, the data of the removed App at this Site will be deleted. There will be no warning. So save the data with ubos-admin backup first.

If you redeploy an existing Site with an existing, or new Site JSON file, you can create a backup of the old Site configuration and content with:

% sudo ubos-admin deploy --file <site.json> --backup <backupfile>

ubos-admin hostid

Displays a unique identifier for the device. It is is the fingerprint of the device’s GPG public key. This hostid is used to identify the device in the flock directory on the UBOS staff.

Note: this is a different key than the one used by the shepherd to log into the device.

ubos-admin init-staff

Turns a USB disk device into a UBOS Staff. This erases all existing content on the USB disk, so do not use a UBOS Staff device for any other purpose. Invoke as:

% sudo ubos-admin init-staff <device>

ubos-admin listnetconfigs

This command shows all network configurations that UBOS could activate for the current device. For example, if your device has two Ethernet interfaces, your device could be used as a router, while this would be impossible if the device had only one Ethernet interface. Invoke:

% ubos-admin listnetconfigs

To set one of these netconfigs, execute ubos-admin setnetconfig.

More network configurations may be available in packages not currently installed.

ubos-admin listsites

To see all Sites and Apps currently deployed on the device, invoke:

% sudo ubos-admin listsites

This will list hostnames, siteids, whether or not the Site has SSL/TLS enabled, Apps installed at the various Sites, their appconfigids, and the relative context paths.

For example:

% ubos-admin listsites
Site: example.com (s20da71ce7a6da5500abd338984217cdc8a61f8de)
    Context:           /guestbook (ab274f22ba2bcab61c84e78d944f6cdd7239a999e): gladiwashere
    Context:           /blog (a9eef9bbf4ba932baa1b500cf520da91ca4703e26): wordpress
Site: example.net (s7ad346408fed73628fcbe01d777515fdd9b1bcd2)
    Context:           /foobar (a6e51ea98c23bc701fb10339c5991224e2c75ff3b): gladiwashere

On this device, two Sites (aka virtual hosts) are hosted. The first Site, responding to example.com, runs two Apps: the Glad-I-Was-Here guestbook, and Wordpress, at the URLs http://example.com/guestbook and http://example.com/blog, respectively. The second Site at example.net, runs a second, independent instance of Glad-I-Was-Here at http://example.net/foobar.

ubos-admin read-configuration-from-staff

Performs the same operations without rebooting that the UBOS device would perform during boot when a UBOS staff is present, such as setting up a shepherd account.

Invoke as:

% sudo ubos-admin read-configuration-from-staff <device>

ubos-admin restore

To restore all Sites and Apps contained in a previously created backup file that you have on your device, invoke:

% sudo ubos-admin restore --in <backupfile>

If your backup is available on-line at a URL instead, invoke:

% sudo ubos-admin restore --url <url-to-backupfile>

Either command will not overwrite existing Sites or Apps; if you wish to replace them, you need to undeploy them first with ubos-admin undeploy.

To only restore a single Site (of several) contained in the same backup file, specify the --siteid or --hostname as an argument:

% sudo ubos-admin restore --siteid <siteid> --in <backupfile>

If one or more Apps were upgraded since the backup was created, UBOS attempts to transparently upgrade the data during the restore operation.

This command has many other ways of invocation; please refer to:

% sudo ubos-admin restore --help

ubos-admin setnetconfig

Sets a network configuration for your device. Some of these networking configurations require the installation of additional ubos-networking-XXX packages. To determine the currently installed and available networking configurations, execute ubos-admin listnetconfigs.

To switch networking off:

% sudo ubos-admin setnetconfig off

To configure all network interfaces to automatically obtain IP addresses via DHCP, if possible:

% sudo ubos-admin setnetconfig client

To assign static IP addresses to all network interfaces:

% sudo ubos-admin setnetconfig standalone

If your device has two Ethernet interfaces and you would like to use it as a home gateway/router:

% sudo ubos-admin setnetconfig gateway

ubos-admin setup-shepherd

This command is particularly useful if you run UBOS in a Linux container.

% sudo ubos-admin setup-shepherd '<public-ssh-key>'

will create the UBOS shepherd, and allow ssh login with the provided public ssh key. The ssh key, although long, needs to be provided on the command-line, and in quotes.

% sudo ubos-admin setup-shepherd --add-key '<public-ssh-key>'

will add a public ssh key and not overwrite any public ssh key already on the shepherd’s account.

ubos-admin showappconfig

To see information about a currently deployed single AppConfiguration, invoke:

% sudo ubos-admin showappconfig --host <hostname> --context <path>

such as:

% sudo ubos-admin showappconfig --host example.com --context /blog

ubos-admin shownetconfig

To see information about the current network configuration, run:

% ubos-admin shownetconfig

This lists all attached network interfaces, and various attributes such as whether the interface uses DHCP, allows App access etc.

ubos-admin showsite

To see information about a currently deployed Site and its Apps, invoke:

% ubos-admin showsite --siteid <siteid>

or

% ubos-admin showsite --host <hostname>

For example:

% ubos-admin showsite --siteid s20...
Site: example.com (s20da71ce7a6da5500abd338984217cdc8a61f8de)
    Context:           /guestbook (ab274f22ba2bcab61c84e78d944f6cdd7239a999e): gladiwashere
    Context:           /blog (a9eef9bbf4ba932baa1b500cf520da91ca4703e26): wordpress

This Site responds to example.com and runs two Apps: the Glad-I-Was-Here guestbook, and Wordpress, at the URLs http://example.com/guestbook and http://example.com/blog, respectively. Nothing is being said about other Sites that may or may not run on the same device.

ubos-admin start-pagekite

To allow access from the public internet to one or more of the sites on your device using the pagekite.net service, install package pagekite and execute:

% sudo ubos-admin start-pagekite --kitesecret <SSS> <NNN>

where <NNN> is the name of your primary kite (e.g. johndoe.pagekite.me) and <SSS> is the secret for the name. You can find both of them on the pagekite.net website after you have logged into your account there.

ubos-admin status

To print interesting information about the device, such as available disk and memory, invoke:

% sudo ubos-admin status --all

ubos-admin status-pagekite

Shows you the status of pagekite on your device if you have installed it. See ubos-admin start-pagekite above.

ubos-admin stop-pagekite

Stops pagekite on your device if you have installed and activated it it. See ubos-admin start-pagekite above.

ubos-admin undeploy

To undeploy an existing Site and all Apps running at this Site as if they had never existed, invoke:

% sudo ubos-admin undeploy --siteid <siteid>

or:

% sudo ubos-admin undeploy --host <hostname>

Warning

Undeploying a Site is like rm -rf. All the data at the Site will be lost. To retain the data, first run ubos-admin backup before undeploying (see Backup and restore)

If you want to create a backup of the Site before it is undeployed:

% sudo ubos-admin undeploy ... --backup <backupfile>

ubos-admin update

To upgrade all code on your device to the latest version, invoke:

% sudo ubos-admin update

This may cause your device to reboot, depending on what code is being updated.

If you would like to create a backup of all Sites on the device as they were before the update:

% sudo ubos-admin update ... --backup <backupfile>

ubos-admin write-configuration-to-staff

Saves information about the current device to the UBOS Staff in directory flock/<HOSTID> where <HOSTID> is a unique identifier for the current device (the same as printed by ubos-admin hostid).

The saved information includes current IP address, device class, SSH server-side keys and others.