Documentation Overview

  1. Operation documentation
    1. Installation
      1. Run UBOS on a PC (64bit)
      2. Run UBOS from a boot stick on a PC (64bit)
      3. Run UBOS in a VirtualBox virtual machine (64bit)
      4. Run UBOS on an Amazon Web Services EC2 virtual server
      5. Run UBOS on Raspberry Pi 5
      6. Run UBOS on ESPRESSObin
      7. Run UBOS in a Linux container on a PC (64bit)
      8. Run UBOS in an aarch64 Linux container
    2. Setting up your first Site and App
    3. Setting up networking and DNS
    4. How to create a website secured by SSL/TLS
    5. How to set up a website as a Tor hidden service
    6. Managing Sites and Apps
    7. Backup and restore
    8. Upgrading and keeping UBOS current
    9. The UBOS Staff
    10. App-specific notes
      1. Reliably send e-mail via Amazon Web Services’ Simple E-mail Service: amazonses
      2. Static website hosting with rsync-based upload: docroot
      3. Notes on Mastodon
      4. Notes on Nextcloud
      5. Notes on Redirect
      6. Notes on Wordpress
    11. Device-specific Notes
      1. ESPRESSObin
      2. Raspberry Pi
    12. Advanced management
      1. Enabling non-standard package repositories
      2. Migrating from one App to another
      3. Pinning resources
    13. Command reference
    14. FAQ, HOWTOs and Troubleshooting
      1. “Package not found error” when installing a new App or Accessory
      2. A UBOS container comes up degraded
      3. Booting UBOS on a PC starts out fine, but then the screen goes blank
      4. Can I run UBOS in a Docker container?
      5. Can I use UBOS without purchasing a domain name?
      6. Cannot access MySQL database. File missing: /etc/mysql/root-defaults-ubos.cnf
      7. Cannot boot UBOS from boot stick on a PC
      8. Cannot connect to the public internet from a UBOS container
      9. Cannot create a temporary backup; the backup directory is not empty
      10. Failed to create file /sys/devices/system/cpu/microcode/reload
      11. How are the various UBOS images different from each other?
      12. How can I install more than one web App on the same Device?
      13. How do I set up WiFi?
      14. How to enable non-standard Package Repositories
      15. How to get help
      16. How to log into your UBOS Device
      17. How to modify the configuration of your Site
      18. How to report a bug or issue
      19. How to use Pagekite to reach your UBOS Device behind a firewall
      20. How to use SSH
      21. I need a Package that isn’t in UBOS
      22. I need root
      23. I own a domain name, and I’d like to use it for my UBOS Device. How do I do that?
      24. I want to move from one device to another, or from/to the cloud to/from a device
      25. I want to run ssh on a non-standard port
      26. I’m running out of disk space, what now?
      27. Installing a new Package or updating fails with a message about “invalid or corrupted package” or “key is disabled”
      28. Installing a new Package or upgrading fails with a message about “unknown trust”
      29. Is it safe to have my Site accessible from the public web?
      30. My non-English keyboard layout is all screwed up
      31. My SD card is much larger than the UBOS image. How do I use the rest of the space?
      32. Nothing happens when UBOS is supposed to be booting
      33. Problems with “IPv6 Packet Filtering Framework”
      34. UBOS is in a “degraded” state
      35. ubos-admin status reports “Systemd unit … has failed”
      36. Verify your downloaded UBOS image
      37. What is the default “root” password?
      38. What text editor can I use on UBOS?
      39. Why did you derive UBOS Linux from Arch Linux, and what is the relationship between UBOS Linux and Arch?
      40. Why is it called UBOS?
      41. Writing a disk image to a USB stick or SD card
        1. Writing an image to a USB stick or SD card on Linux
        2. Writing an image to a USB stick or SD card on macOS
        3. Writing an image to a USB stick or SD card on Windows
  2. Developer documentation
    1. Developer setup
      1. Developing using Arch Linux on VirtualBox x86_64 with a systemd-nspawn container
      2. Developing using a UTM Arch Linux VM on Apple Silicon computers with UBOS in a systemd-nspawn container
      3. Alternate developer setups
        1. Developing using a systemd-nspawn container (Linux host only)
        2. Developing using Arch Linux using Parallels on Apple Silicon with a systemd-nspawn container
        3. Developing using a UTM Arch Linux VM on Apple x86_64 computers with UBOS in a systemd-nspawn container
    2. Developer tutorials for standalone UBOS apps (not UBOS Mesh)
      1. Build and run your first UBOS standalone App
      2. How to package UBOS standalone Apps built with a variety of languages
        1. Hello World
        2. Glad-I-Was-Here (PHP, Mariadb)
        3. An Accessory for Glad-I-Was-Here (PHP, Mariadb)
        4. Glad-I-Was-Here (PHP, Postgresql)
        5. Glad-I-Was-Here (Python, Mariadb)
    3. UBOS Gears Reference
      1. UBOS Manifest
        1. Structure of the UBOS Manifest
        2. Info section
        3. Roles section
        4. Customization points section
        5. Appinfo section
        6. Accessoryinfo section
        7. Variables available at deploy or undeploy
        8. Functions that may be applied to variables
        9. Creating random values
        10. Scripts in UBOS Manifests
      2. Site JSON
      3. A complex deployment example
      4. UBOS Networking
      5. Allocating and opening up non-default ports
      6. Logging
      7. UBOS state
      8. UBOS Backup format
      9. Format of the App Status JSON
      10. Testing standalone Apps with “webapptest”
      11. Understanding ubos-admin
        1. Command: ubos-admin backup
        2. Command: ubos-admin backupinfo
        3. Command: ubos-admin createsite
        4. Command: ubos-admin deploy
        5. Command: ubos-admin hostid
        6. Command: ubos-admin init-staff
        7. Command: ubos-admin list-data-transfer-protocols
        8. Command: ubos-admin listnetconfigs
        9. Command: ubos-admin listsites
        10. Command: ubos-admin read-configuration-from-staff
        11. Command: ubos-admin restore
        12. Command: ubos-admin setnetconfig
        13. Command: ubos-admin setup-shepherd
        14. Command: ubos-admin showappconfig
        15. Command: ubos-admin shownetconfig
        16. Command: ubos-admin showsite
        17. Command: ubos-admin status
        18. Command: ubos-admin undeploy
        19. Command: ubos-admin update
        20. Command: ubos-admin write-configuration-to-staff
    4. Release channels and UBOS release process
    5. Miscellaneous
      1. Potentially useful infrastructure for standalone Apps
        1. The UBOS rsync server
      2. Middleware-specific notes
        1. Node.js notes
        2. SMTP notes
      3. Setting up an Arch Linux system as a UBOS development system
        1. How to create a UBOS development VM for VirtualBox on x86_64
        2. How to create a UBOS development VM for UTM on x86_64 Apple computers
        3. How to create a UBOS development VM for UTM on Apple Silicon computers
        4. How to create a UBOS development VM for Parallels Desktop on Apple Silicon computers
      4. Creating cloud images
        1. Amazon Web Services EC2
    6. Developer FAQ
      1. Doesn’t apt / dpkg / yum / pacman etc. does what UBOS Gears does already?
      2. Doesn’t puppet / chef / ansible etc. does what UBOS Gears does already?
      3. Doesn’t Docker do what UBOS Gears does already?
      4. Is it possible to run UBOS Gears or Mesh on an operating system other than UBOS Linux?
      5. Can I manage apps packaged as Docker containers with UBOS?
  3. Architecture
  4. Glossary
    1. Accessory
    2. App
    3. AppConfigId
    4. AppConfigItem
    5. AppConfiguration
    6. Arch
    7. Arch Linux
    8. Attribute
    9. blessing
    10. Bot
    11. Context Path
    12. Customization Point
    13. Data Transfer Protocol
    14. Deployment
    15. Depot
    16. Device
    17. Device Class
    18. diet4j module framework
    19. EntityType
    20. Flock
    21. Gradle
    22. Handlebars
    23. History
    24. Home Server
    25. HostId
    26. Hostname
    27. IDE
    28. Installation
    29. LetsEncrypt
    30. mDNS
    31. MeshBase
    32. MeshObject
    33. MeshObjectIdentifier
    34. MeshType
    35. MeshTypeIdentifier
    36. Middleware
    37. Model
    38. Network Configuration
    39. Package
    40. Pagekite
    41. Parallels Desktop
    42. Personal Server
    43. PKGBUILD
    44. Property
    45. PropertyType
    46. Relationship
    47. RelationshipType
    48. Release Channel
    49. Repository
    50. Retention Bucket
    51. Role
    52. RoleAttribute
    53. RoleProperty
    54. RoleType
    55. Rolling Release
    56. Shepherd
    57. Site
    58. Site JSON
    59. Site JSON Template
    60. SiteId
    61. Transaction
    62. Transaction Log
    63. UBOS Gears
    64. UBOS Linux
    65. UBOS Manifest
    66. UBOS Mesh
    67. UBOS Mesh code generator
    68. UBOS Project
    69. UBOS Staff
    70. unblessing
    71. UTM
    72. VirtualBox
    73. VMWare
    74. Wildcard hostname

Command reference


ubos-admin is the central administration command for UBOS. When invoked without arguments, it lists the currently available sub-commands. Note that the list of available sub-commands may become longer if you install certain extra packages.

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

ubos-admin backup

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

% sudo ubos-admin 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 ubos-admin backup --all --backuptodir ~

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

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


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

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

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

You can determine the SiteId or AppConfigId with ubos-admin 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 shepherd 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 ubos-admin list-data-transfer-protocols.


  • scp:// will upload the file using scp to host, 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.

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 or more Apps:

% sudo ubos-admin 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 ubos-admin 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 ubos-admin createsite --tls --letsencrypt

and answer the questions at the terminal.

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 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 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 ubos-admin createsite --from-template <template>

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

ubos-admin 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 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; or

  • manually create a Site JSON file; see Site JSON.

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

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.


If you remove an App or an Accessory from a Site JSON file, and redeploy the Site JSON, the data of the removed App or removed Accessory 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> --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.

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.


This is a different key than the one used by the Shepherd to log into the Device over the network.

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

% sudo ubos-admin init-staff <device>

ubos-admin 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, ubos-admin 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.

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 network 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 --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:

% ubos-admin listsites --detail
Site: (s20da71ce7a6da5500abd338984217cdc8a61f8de)
    Context:           /guestbook (ab274f22ba2bcab61c84e78d944f6cdd7239a999e): gladiwashere-php-mysql
    Context:           /blog (a9eef9bbf4ba932baa1b500cf520da91ca4703e26): wordpress
Site: (s7ad346408fed73628fcbe01d777515fdd9b1bcd2)
    Context:           /foobar (a6e51ea98c23bc701fb10339c5991224e2c75ff3b): gladiwashere-php-mysql

On this Device, two Sites (aka virtual hosts) are hosted. The first Site, responding to, runs two Apps: the Glad-I-Was-Here guestbook toy App, and Wordpress, at the URLs and, respectively. The second Site at, runs a second, independent instance of Glad-I-Was-Here at

ubos-admin 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 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 Network Configurations require the installation of additional ubos-networking-XXX packages. To determine the currently installed and available Network Configurations, invoke:

% ubos-admin listnetconfigs

To switch networking off entirely:

% 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

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 ubos-admin setup-shepherd --add-key

will add another 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 --context /blog

or use --appconfigid instead.

ubos-admin shownetconfig

To see information about the current Network Configuration, invoke:

% 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>


% ubos-admin showsite --host <hostname>

For example:

% ubos-admin showsite --siteid s20...
    /guestbook : gladiwashere-php-mysql
    /blog : wordpress

This Site responds to and runs two Apps: the Glad-I-Was-Here guestbook, and Wordpress, at the URLs and, 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.

ubos-admin start-pagekite

To allow access from the public internet to one or more of the Sites on your Device using the Pagekite service, install package pagekite with sudo pacman -S pagekite and then execute:

% sudo ubos-admin start-pagekite <NNN>

where <NNN> is the name of your primary kite (e.g. UBOS will then ask you for the secret that goes with the kite name. You can find both of them on the 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

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

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. 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>


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


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.

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 ... --backuptofile <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 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.