ug Command reference (future, work in progress)

The ubos-admin command is gradually being replaced with a new implementation in Python. Its central command is ug (for “UBOS Gears”).

Note that the list of available sub-commands may become longer if you install certain extra packages.

To invoke an ug sub-command, execute:

% ug <subcommand> <arguments>

or, if it requires root privileges:

% sudo ug <subcommand> <arguments>

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

% sudo ug <subcommand> --help

Command: ug backup

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

% sudo ug backup --all --backuptofile all.ubos-backup

To create a backup of all Sites on your Device and save it to a file in your home directory letting UBOS choose a timestamped file name:

% sudo ug backup --all --backuptodir ~

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

% sudo ug backup --hostname <hostname> --backuptofile <backupfile>

or

% sudo ug backup --siteid <siteid> --backuptofile <backupfile>

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

% sudo ug backup --appconfigid <siteid> --backuptofile <backupfile>

You can determine the SiteId or AppConfigId with ug listsites.

To encrypt the backup file as part of the process: add --encryptid <id> to the command, where <id> is the key identifier of a private key in the current user’s GPG repository.

To automatically upload the created file to a remote host, specify a data transfer protocol, host and (potentially) user information as part of the destination. To determine the available data transfer protocols, run ug list-data-transfer-protocols.

Examples:

• scp://user@example.com/foo.ubos-backup will upload the file using scp to host example.com, as user user.

• s3://bucket/file will upload to an Amazon S3 bucket called bucket and create file file there. This requires that the package amazons3 is installed, and that you have permissions to upload to this bucket.

Command: ug backupinfo

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

% ug backupinfo --in <backupfile>

Command: ug createsite

To create and deploy a new Site running one or more Apps:

% sudo ug createsite

and answer the questions at the terminal.

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

% sudo ug createsite --tls --selfsigned

and answer the questions at the terminal.

To create and deploy a new Site, running one or more Apps and secured by a LetsEncrypt SSL/TLS certificate:

% sudo ug createsite --tls --letsencrypt

and answer the questions at the terminal. This requires that your Device is on the public internet, so the LetsEncrypt site can talk to it.

To create and deploy a new Site, running one or more Apps and secured by an official SSL/TLS certificate, make sure you have private key and certificate files on your UBOS Device, then:

% sudo ug 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 to a file, instead of emitting it on the terminal, append --out <filename> with a suitable filename.

To create a Site from a Site JSON Template file:

% sudo ug createsite --from-template <template>

and UBOS will only ask for values not already provided in the template.

Command: ug deploy

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

% sudo ug deploy --file <site.json>

To obtain a Site JSON file, either:

• export the Site JSON file for an existing Site with ug showsite --json --site <siteid> or ug showsite --json --hostname <hostname>;

• create (but do not deploy) a Site JSON file with ug createsite --dry-run; or

• 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 AppConfigurations, such as the Context 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 ug deploy --file <site.json>. UBOS Gears will find out what changed, and make appropriate adjustments.

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 ug deploy --file <site.json> --backuptofile <backupfile>

If you additionally specify --template, you can use Site JSON Template files, so UBOS will auto-generate identifies and unique credentials during deployment.

Obsolete: ug hostid

Use ug status --hostid instead.

Command: ug 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 USB device for any other purpose. Invoke as:

% sudo ug init-staff <device>

Command: ug list-data-transfer-protocols

Lists the data transfer protocols currently available for the destinations of backups. For example, if data transfer protocol scp is listed, ug backup understands how to scp (“secure copy”) the resulting backup file over the network to another host.

Note that the list of currently available data transfer protocols may become longer if you install certain optional packages.

Command: ug 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 network interface. Invoke:

% ug listnetconfigs

To set one of these netconfigs, execute ug setnetconfig.

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

Command: ug listsites

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

% sudo ug listsites --detail

This will list hostnames, SiteIds, whether or not the Site has SSL/TLS enabled, Apps deployed at the various Sites, their AppConfigIds, and the relative Context Paths.

For example:

% ug listsites --detail
Site: example.com (s20da71ce7a6da5500abd338984217cdc8a61f8de)
    Context:           /guestbook (ab274f22ba2bcab61c84e78d944f6cdd7239a999e): gladiwashere-php-mysql
    Context:           /blog (a9eef9bbf4ba932baa1b500cf520da91ca4703e26): wordpress
Site: example.net (s7ad346408fed73628fcbe01d777515fdd9b1bcd2)
    Context:           /foobar (a6e51ea98c23bc701fb10339c5991224e2c75ff3b): gladiwashere-php-mysql

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 toy App, 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.

Command: ug read-configuration-from-staff

Performs the same operations without rebooting that the Device would perform during boot when a UBOS Staff is present, such as setting up a Shepherd account.

Invoke as:

% sudo ug read-configuration-from-staff <device>

Command: ug restore

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

% sudo ug restore --in <backupfile>

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

% sudo ug 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 ug undeploy.

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

% sudo ug 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 ug restore --help

Command: ug setnetconfig

Sets a Network Configuration for your Device. Some of these Network Configurations require the installation of additional ubos-gears-networking-XXX packages. To determine the currently installed and available Network Configurations, invoke:

% ug listnetconfigs

To switch networking off entirely:

% sudo ug setnetconfig off

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

% sudo ug setnetconfig client

To assign static IP addresses to all network interfaces:

% sudo ug setnetconfig standalone

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

% sudo ug setnetconfig gateway

Command: ug setup-shepherd

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

% sudo ug setup-shepherd

will first ask you to enter an public ssh key, and then create the Shepherd account, and allow ssh login with the provided public ssh key.

% sudo ug setup-shepherd --add-key

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

Command: ug showappconfig

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

% sudo ug showappconfig --host <hostname> --context <path>

such as:

% sudo ug showappconfig --host example.com --context /blog

or use --appconfigid instead.

Command: ug shownetconfig

To see information about the current Network Configuration, invoke:

% ug shownetconfig

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

Command: ug showsite

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

% ug showsite --siteid <siteid>

or

% ug showsite --host <hostname>

For example:

% ug showsite --siteid s20...
example.com
    /guestbook : gladiwashere-php-mysql
    /blog : 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.

To determine information about a Site’s administrator, add the --adminuser flag to invocation. In order to see the administrator’s password, the command must be invoked with sudo.

To see other credentials or otherwise not-shown customizationpoints, use --credentials and/or --privatecustomizationpoints.

Obsolete: ug start-pagekite

Not available with ug.

Command: ug status

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

% sudo ug status

There is a variety of options to control what information will be shown.

Obsolete: ug status-pagekite

Not available with ug.

Obsolete: ug stop-pagekite

Not available with ug.

Command: ug undeploy

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

% sudo ug undeploy --siteid <siteid>

or:

% sudo ug undeploy --host <hostname>

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

% sudo ug undeploy ... --backuptofile <backupfile>

or

% sudo ug undeploy ... --backuptodirectory <directory>

Command: ug update

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

% sudo ug 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, specify option --backuptofile <backupfile> or --backuptodirectory <directory>.

Command: ug write-configuration-to-staff

Saves information about the current Device to the UBOS Staff in directory flock/<HOSTID> where <HOSTID> is a unique HostId for the current Device (see ubos-admin hostid above).

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