Documentation Overview

  1. Operation documentation
    1. UBOS Linux 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 with Docker
      5. Run UBOS on an Amazon Web Services EC2 virtual server
      6. Run UBOS on Raspberry Pi 5
      7. Run UBOS on ESPRESSObin
      8. Run UBOS in a Linux container on a PC (64bit)
      9. 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 your Device 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. 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 use UBOS without purchasing a domain name?
      5. Cannot access MySQL database. File missing: /etc/mysql/root-defaults-ubos.cnf
      6. Cannot boot UBOS from boot stick on a PC
      7. Cannot connect to the public internet from a UBOS container
      8. Cannot create a temporary backup; the backup directory is not empty
      9. Failed to create file /sys/devices/system/cpu/microcode/reload
      10. How are the various UBOS images different from each other?
      11. How can I install more than one web App on the same Device?
      12. How do I report a bug?
      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 does UBOS ask for a domain name when installing a new Site?
      41. Why is it called UBOS?
      42. 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
    14. Command reference
  2. Developer documentation
    1. Developer setup
      1. Developing using Docker (all Intel platforms)
      2. Developing using a systemd-nspawn container (Linux host only)
      3. Developing using Arch Linux on VirtualBox x86_64 with a systemd-nspawn container
      4. Developing using Arch Linux using UTM on Apple Silicon with a systemd-nspawn container
      5. Developing using Arch Linux using Parallels on Apple Silicon with a systemd-nspawn container
    2. Developer tutorials for standalone UBOS Gears apps (not UBOS Mesh)
      1. Build and run your first UBOS Gears App
      2. How to package UBOS Standalone Apps built with a variety of languages
        1. Hello World
        2. Glad-I-Was-Here (PHP, MySQL)
        3. An Accessory for Glad-I-Was-Here (PHP, MySQL)
        4. Glad-I-Was-Here (PHP, Postgresql)
        5. Glad-I-Was-Here (Java, MySQL)
        6. Glad-I-Was-Here (Python, MySQL)
    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
        1. Prepare a PC for installing Arch Linux
        2. Prepare a VirtualBox virtual machine to develop for UBOS using Arch Linux
        3. Continuing the Arch Linux installation on a PC or virtual machine
        4. Finishing the Arch development installation by adding UBOS tools
    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. How to profile the UBOS Personal Data Mesh web application
      5. Is it possible to run the other UBOS components on an operating system other than UBOS Linux?
      6. How to create a UBOS development VM for VirtualBox
      7. How to create a UBOS development VM for UTM on Apple computers
      8. How to create a UBOS development VM for Parallels Desktop on Apple Silicon

Run UBOS on ESPRESSObin

/docs/operation/installation/espressobin/

You can run UBOS on your ESPRESSObin by downloading an image, writing it to an SD card, and booting your ESPRESSObin with that card. (Alternatively you can keep running your existing Linux distro on your ESPRESSObin, and run UBOS in a Linux container. This is described in Run UBOS in an AArch64 Linux container.)

  1. Download a UBOS boot image from the Depot. Images for the ESPRESSObin are at depot.ubosfiles.net/green/aarch64/images. Look for a file named ubos_green_aarch64-espressobin_LATEST.img.xz.

  2. Optionally, you may now verify that your image downloaded correctly by following Verify your downloaded UBOS image.

  3. Uncompress the downloaded file. This depends on your operating system, but might be as easy as double-clicking it, or executing

    % xz -d ubos_green_aarch64-espressobin_LATEST.img.xz
    

    on the command line.

  4. Write this image file “raw” to an SD card appropriate for your ESPRESSObin. This operation depends on your operating system:

  5. On first boot, you need to have a serial terminal connected to your ESPRESSObin. This is because you likely have to change your boot loader options.

  6. Remove the SD card and insert it into your ESPRESSObin. If you created a UBOS Staff, insert it into a USB port.

  7. Connect your ESPRESSObin to your Ethernet network. Use the Ethernet port that is closest to the ESPRESSObin’s USB 3 port (the one that is blue): that’s the one that UBOS, by default, configures as the “upstream” interface; the others are configured for local area networks, just like a home router.

  8. Connect the ESPRESSObin’s USB power port to your computer with a USB cable. This will become your serial connection. This is only required for the first boot.

  9. From your computer, attach a serial terminal. How to do that depends on your operating system. The ESPRESSObin site has a description for how to do this from Windows or Linux. The baudrate is 115200. For example, on Linux, you might run sudo screen /dev/ttyUSB0 115200.

  10. Connect the 12V power supply to your ESPRESSObin.

  11. When prompted on the serial terminal, interrupt the boot process by pressing a key. You get a promot that looks like:

    Marvell>>
    
  12. Enter the following commands to import the new environment variables to boot from the SD card:

    mmc dev 0
    ext4load mmc 0 $loadaddr /uEnv-sdcard.txt
    env import -t $loadaddr $filesize
    saveenv
    boot
    

    If you do not want to make permanent changes to your bootloader setup, leave out the saveenv command. If you do not execute saveenv, you will have to type the commands above every time you boot your ESPRESSObin into UBOS.

  13. Should booting fail, see below for the uBoot factory configuration.

  14. When the boot process is finished, log in as user root from the attached keyboard and monitor. For password, see I need root. If you used a UBOS Staff, you can log in over the network instead as described in The UBOS Staff.

  15. Now: wait. UBOS needs to generate a few cryptographic keys before it is ready to use and initialize a few other things on the first boot. That might take 5 or 10 minutes. To determine whether UBOS ready, execute:

    % systemctl is-system-running
    
  16. Check that your ESPRESSObin has acquired an IP address:

    % ip addr
    

    Make sure you are connected to the internet before attempting to proceed.

  17. Update UBOS to the latest and greatest:

    % sudo ubos-admin update
    
  18. You are now ready for Setting up your first Site and App.

Optional: boot from a SATA disk, instead of an SD card

In the previous section, you installed UBOS on an SD card and booted from it. If you would like to use a SATA disk instead, do this:

  1. Acquire a suitable SATA power connector. The ESPRESSObin has a male power connector on the board, which is very unusual. It may be difficult to find a suitable power connector.

  2. Assuming you have the disk connected and powered up, boot the ESPRESSObin from a UBOS SD card as described above.

  3. Once booted, execute:

    % lsblk
    

    This will show all attached block devices, including the attached disk. Determine which of the shown devices is your disk. It might be /dev/sda, which we’ll assume from now.

  4. Install UBOS on that disk with the command:

    % sudo ubos-install /dev/sda
    
  5. Shut down the ESPRESSObin and turn off power.

  6. Remove the SD card from your ESPRESSObin. If you created a UBOS Staff, insert it into a USB port. Then, connect the ESPRESSObin’s USB power port to your computer.

  7. Connect the ESPRESSObin’s USB power port to your computer with a USB cable. This will become your serial connection.

  8. From your computer, attach a serial terminal. How to do that depends on your operating system. The ESPRESSObin site has a description for how to do this from Windows or Linux. The baudrate is 115200. For example, on Linux, you might run sudo screen /dev/ttyUSB0 115200.

  9. Connect the 12V power supply to your ESPRESSObin.

  10. When prompted on the serial terminal, interrupt the boot process by pressing a key. You get a promot that looks like:

    Marvell>>
    
  11. Enter the following commands to import the new environment variables to boot from the SD card:

    env default -a
    scsi scan
    scsi dev 0
    ext4load scsi 0 $loadaddr /uEnv-sata.txt
    env import -t $loadaddr $filesize
    saveenv
    boot
    

    If you do not want to make permanent changes to your bootloader setup, leave out the saveenv command. If you do not execute saveenv, you will have to type the commands above every time you boot your ESPRESSObin into UBOS.

  12. The ESPRESSObin will now boot from the SATA disk. If you have executed the saveenv command, you can remove the SD Card; it will not be needed for future boots.

Note

If your ESPRESSObin fails to detect the SATA disk in the middle of the boot process, you may need to upgrade its pre-installed boot loader (see next section).

u-Boot upgrade

More recent Linux kernels (2019) require the u-Boot bootloader to be upgraded, otherwise the kernel may not detect the SATA disk. If this occurs, the kernel will start booting but some time into the process, it will fail to find the very disk it is running from. To perform the u-Boot upgrade, do this:

  • You need a USB flash stick. It needs to be VFAT-formatted (the default for USB flash sticks).

  • Determine the exact version of your ESPRESSObin, specifically version number (such as V5) and the amount of RAM on your board (like 1G).

  • From our friends at Armbian at dl.armbian.com/espressobin/u-boot, download the correct, prebuilt u-Boot binary for your ESPRESSObin and save it to your USB flash stick:

    • If your ESPRESSObin is V5 or lower, look for files that start with flash-image-ddr3-. For versions after V5, look for files that start with flash-image-ddr4-.

    • The next element in the filename is the RAM size of your ESPRESSObin, such as 512m-, 1g- or 2g-.

    • The next element in the filename is your ESPRESSObin’s number of RAM chips. If your ESPRESSObin was produced before 2019, the number is likely 2: “one on each side of the PCB opposite to each other. Recent (e.g. 2019) 1GB models have only one chip at the bottom” (thanks, Armbian!). Depending, the next element is 1cs- or 2cs-.

    • The last element is the speed at which to run the board. It is recommended to err on the side of lower numbers, otherwise the ESPRESSObin might become unstable. The first number is the CPU speed in MHz; the second the memory speed. We use 1000_800.

  • Once you saved the downloaded file to your USB stick, insert the stick into the ESPRESSObin’s USB3 port (the one that’s blue) and boot your ESPRESSObin with a serial terminal attached. Press a key, so the boot process is interrupted.

  • Flash the boot loader with this command:

    bubt <BIN> spi usb
    

    where <BIN> is the full name of the file your downloaded to the USB stick.

  • Then, go through setting up the parameters just as if you attempted to boot for the first time (see above).

u-Boot bootloader factory configuration

If you have difficulty booting the ESPRESSObin with the provided instructions, it may be because you previously changed the ESPRESSObin’s boot loader configuration from the factory default. For reference, here is the ESPRESSObin’s factory configuration as determined by executing

> printenv

in uBoot of a brand-new device:

baudrate=115200
bootargs=console=ttyMV0,115200 earlycon=ar3700_uart,0xd0012000 root=/dev/nfs rw ip=0.0.0.0:0.0.0.0:10.4.50.254:255.255.255.0:marvell:eth0:none nfsroot=0.0.0.0:/srv/nfs/
bootcmd=mmc dev 0; ext4load mmc 0:1 $kernel_addr $image_name;ext4load mmc 0:1 $fdt_addr $fdt_name;setenv bootargs $console root=/dev/mmcblk0p1 rw rootwait; booti $kernel_addr - $fdt_addr
bootdelay=3
bootmmc=mmc dev 0; ext4load mmc 0:1 $kernel_addr $image_name;ext4load mmc 0:1 $fdt_addr $fdt_name;setenv bootargs $console root=/dev/mmcblk0p1 rw rootwait; booti $kernel_addr - $fdt_addr
console=console=ttyMV0,115200 earlycon=ar3700_uart,0xd0012000
eth1addr=00:00:00:00:51:82
eth2addr=00:00:00:00:51:83
ethact=neta0
ethaddr=F0:AD:4E:03:6A:EA
ethprime=egiga0
fdt_addr=0x1000000
fdt_high=0xffffffffffffffff
fdt_name=boot/armada-3720-community.dtb
fileaddr=2000000
filesize=400000
gatewayip=10.4.50.254
get_images=mmc dev 0; fatload mmc 0 $kernel_addr $image_name; fatload mmc 0 $fdt_addr $fdt_name; run get_ramfs
get_ramfs=if test "${ramfs_name}" != "-"; then setenv ramfs_addr 0x3000000; tftp $ramfs_addr $ramfs_name; else setenv ramfs_addr -;fi
hostname=marvell
image_name=boot/Image
initrd_addr=0xa00000
initrd_size=0x2000000
ipaddr=10.4.50.4
kernel_addr=0x2000000
loadaddr=0x2000000
loads_echo=0
netdev=eth0
netmask=255.255.255.0
ramfs_addr=-
ramfs_name=-
root=root=/dev/mmcblk0p1 rw
rootpath=/srv/nfs/
serverip=10.4.50.5
set_bootargs=setenv bootargs $console $root ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname:$netdev:none nfsroot=$serverip:$rootpath $extra_params
stderr=serial
stdin=serial
stdout=serial

(Some of these values will necessarily be different on your device, e.g. the Mac addresses.)

In an attempt to trouble-shoot, manually set the environment variables in your device’s uBoot configuration to these values as closely as possible, before attempting to boot UBOS.