Ubuntu 22 Runtime installation and configuration

Note: See Runtime configuration for an overview of the available settings.

Requirements

For the installation of Runtime on Ubuntu 22 make sure of the following:

  • The kernel version running on your device or the linux-headers of the current kernel version shall be up to date.
  • The .NET Runtime 8 shall be installed. If it is not installed yet and the device connects to the Internet, it will automatically be downloaded and installed during the Runtime installation.
  • The Remote Desktop feature requires the installation of the X11 Window System. If Wayland is installed and enabled, disable it by editing the file:
/etc/gdm3/custom.conf

or

/etc/gdm3/daemon.conf

uncomment the following line by removing the #:

#WaylandEnable=false
  • The user of the default session (that is not SSH) must be a root folder user or a sudoers group user and shall have sbin folders in their PATH environment variable. To add a user to the sudoers group, use the following commands:
su -l
usermod -aG sudo <UserToAdd>
  • Select Settings > Users > Authentication & Login and enable the Automatic Login toggle switch.
  • Ensure that the following commands are installed on your device. Some scripts run by UbiquitySetupHost.service during the host initialization phase require these commands to work with the host system. If any of these commands are missing, the script run might be interrupted:
    • mknod (used only when the VPN is enabled): Install by entering sudo apt-get install coreutils
    • iptables (used only when the VPN is enabled): Install by entering sudo apt-get install iptables
    • brctl (used only when the VPN is enabled): Install by entering sudo apt-get install bridge-utils
    • dhclient (used only when the VPN is enabled): Install by entering sudo apt-get install isc-dhcp-client

Runtime Installation

Download the UBIQUITY Runtime package related to the Ubuntu 22 distribution on the remote device and run the installation command: 
sudo apt install ./UbiquityRuntimeSetup_Ubuntu22_<version>.deb

and replace the <version> with the actual version.

Note: See Tools to download Runtime.
Note:

The Runtime binaries are automatically installed in the folder:

/opt/ASEM/Ubiquity/Runtime/bin

And the Runtime logs are stored in the folder:

/opt/ASEM/Ubiquity/Runtime/log

Runtime Startup

Before starting Runtime, install Runtime as a service.

  1. Create two .service files named UbiquitySetupHost.service and UbiquityRuntimeService and configure them as follows, respectively: 
    
[Unit]
Description=Ubiquity Setup Host Service
After=network-online.target
Before=UbiquityRuntimeService.service

[Service]
ExecStart=/opt/ASEM/Ubiquity/Runtime/bin/setuphost.sh [OPTIONS]

[Install]
WantedBy=multi-user.target
    
[Unit]
Description=Ubiquity Runtime Service

[Service]
ExecStart=/opt/ASEM/Ubiquity/Runtime/bin/UbiquityRuntimeService
Environment="DISPLAY=:0"
Environment="RDP_USERNAME=<username>"
Restart=on-failure

[Install]
WantedBy=multi-user.target
  2. Store the newly created files in the /etc/systemd/system folder.
  3. In UbiquitySetupHost.service, replace the OPTIONS as needed.

    The script run in UbiquitySetupHost.service displays this support message:

    $ sudo ./setuphost.sh -h

Usage: ./setuphost.sh [OPTIONS]

This script configures the host prior to running the Runtime.

Options:

--enable-vpn <adapter-list>    Configure the host to enable VPN on the Runtime ad running time. The adapter-list is a single parameter that contains a list of adapter names separated by a comma (,). A conventional network bridge interface will be created on each of them to perform VPN. Example: --enable-vpn eth0,eth1

--enable-p2p-vpn    Configure the host to enable Point-to-Point VPN on the Runtime at running time.

-v, --verbose    Print detailed logs for troubleshooting.

-h, --help    Display this help message and exit.
  4. In UbiquityRuntimeService.service, replace the <username> field with the name of the authorized user that accesses the X11 server.

  5. To enable the Runtime service automatic startup, run the sudo systemctl enable UbiquitySetupHost.service UbiquityRuntimeService.service command in the /etc/systemd/system folder.

    To start the Runtime service, run the sudo systemctl start UbiquitySetupHost.service UbiquityRuntimeService.service command in the /etc/systemd/system folder.

Enable the VPN

The setuphost.sh script that runs in the UbiquitySetupHost.service initializes the host and sets the network configuration to allow the UbiquityRuntimeService.service to properly run the VPN.

Separate the interfaces mentioned in the <adapter-list> by using a comma. For example: eth0,eth1,eth2. The script establishes a standard network bridge interface for each specified interface.

Note: During the establishment of a standard network bridge, the script appends both -tap and -bridge to any interface listed in the <adapter-list> wherever tap and bridge are not already in place. The script abides by the 15-character limit imposed by Linux.
  • Example without interface truncation:
    • Adapter name (characters length 4): eth0
    • Tap name (characters length 8): eth0-tap
    • Bridge name (characters length 8): eth0-bridge
  • Example with interface truncation:
    • Adapter name (characters length 9): enp0s31f6
    • Tap name (characters length 13): enp0s31f6-tap
    • Bridge name (characters length15): enp0s31f-bridge. Considering the characters lenght limit, the adapter name truncation here consists of the elimination of the 6 digit.

      The maximum characters length limitation affects any bridge and tap interfaces with names that are equal to or longer than the name in the example above.

Note:
  • The taps and bridges created for the specified interfaces are not persistent at the host restart. Nonetheless, the UbiquitySetupHost.service is consistently run at restart before the UbiquityRuntimeService.service to carry out any essential operations for host preparation, including network configuration adjustments.
  • If you want to remove any taps and bridges that you previously created for the VPN, edit the service [OPTIONS] and restart the host.

Connection to the UBIQUITY network and domain registration

Note: See Runtime configuration to learn how to connect the Runtime with the Ubiquity network infrastructure.

Runtime Configuration

Note: See Runtime configuration for information on this subject.

Serial passthrough configuration

Note: This feature is currently not supported on Ubuntu 22.

To enable the remote use of a serial port, add a symlink to the interface in the path /dev/serial<interface number>.

Example:

In a system equipped with a serial interface /dev/ttyS0, execute the following command:

ln -s /dev/ttyS0 /dev/serial0

Password setup

To prevent unauthorized users from accessing the Runtime, set up a password. Once you have set up a password, a browser authentication page opens when you start the Runtime.

Note: To set up a password, you need to have sudo privileges.
Note: If you do not set up a password to access the Runtime, every user can access it and land directly onto the Home page.
  1. To start the application, enter https://localhost:5161 into the page browsing bar.
  2. Enter sudo UbiquityRuntimeCli --setRuntimePassword --password <runtime password>.
  3. Replace <runtime password> with a password.
    Note:

    Create a strong password to reduce cybersecurity risk.

    Your password must:
    • Be at least 8 characters long
    • Include at least three of the following requirements:
      • at least one uppercase character
      • at least one lowercase character
      • at least one numeric character
      • at least one symbolic character

    Use passphrases longer than 8 characters to enhance password strenght. Strong passwords increase the time needed to guess them.

Note: To change the password, repeat the process.