Introduction

UBOS can be run on many different physical and virtual hardware configurations. For example, a Device may or may not have an Ethernet port; or it may have several. It may or may not have WiFi, which may be on board or be a separate USB dongle. It may have a virtual Ethernet port if run in a container or in the cloud. Networks that a Device connects to might also be very different, from typical home networks to virtual networks on host machines running UBOS in Linux containers.

Because of all these differences, networking for Linux server devices is usually complex to set up and requires substantial expertise.

With UBOS, as usual, we try to simplify things. We do this by pre-defining some common Network Configurations, and automatically install the one most likely to work “out of the box” for a new Device of a given class without further configuration. But if you wish to use the Device in a different setting, we provide a single command to switch to a different Network Configuration.

Unlike other network management tools, UBOS Network Configurations manage all necessary layers of the networking stack at the same time including:

• individual network interfaces such as Ethernet interfaces

• IP addresses

• DHCP

• DNS on the local network

• zeroconf/mDNS

• Firewall

• Masquerading

• open ports for applications.

This works for wired (Ethernet) and wireless (WiFi) connections.

Currently available Network Configurations

The following Network Configurations are currently available:

Network configuration: client

For most Device Classes, this is the default Network Configuration after UBOS installation.

If your Device has an Ethernet port, and you connect it to your Ethernet network, the Device will automatically connect.

If your Device has more than one network interface, it should not matter which you use.

In this mode:

• network interfaces: All network interfaces are active, and looking to obtain an IP address, default gateway and DNS server information via DHCP.

• mDNS: The Device will advertise itself on all network interfaces.

• ports: Application-level ports (such as HTTP and HTTPS ports 80 and 443) will be accessible from all network interfaces.

• ssh: ssh connections are accepted on all network interfaces.

• firewall: All other ports are firewalled.

If you’d like to have a predictable IP address for your Device in this Network Configuration, we recommend that you configure your DHCP server to always hand out the same IP address to your Device. This tends to be an easier, and typically more maintainable process than maintaining static IP addresses on all the Devices on your network. For example, depending on the model of your home router, you may be able to do this:

• Log into the administrative interface of your home router, and look for a page that lists all currently connected devices on your network.

• Look for your UBOS device, and note its MAC address.

• In some part of the administrative interface of your home router, you may be able to assign a consistent IP address for the device with this MAC address.

Network configuration: standalone

This Network Configuration is useful to set up a network that is disconnected from the public internet. In this configuration, the Device assumes the role of network manager and manages the network by running a DHCP server, and a DNS server.

Other computers connected to the Device will be able to receive an IP address and use network services as if they were connected to a typical home network, but without upstream connection to the public internet.

If your Device has more than one network interface, UBOS will create separate subnets for each network interface.

In this mode:

• network interfaces: All network interfaces are active and have a static IP address assigned. Other connected computers can obtain IP address, default gateway and DNS server information from a DHCP server and a DNS server running on the Device.

• mDNS: The Device will advertise itself on all interfaces.

• ports: application-level ports (such as HTTP and HTTPS ports 80 and 443) will be accessible from all interfaces.

• ssh: ssh connections are accepted on all interfaces.

• firewall: All other ports are firewalled.

Network configuration: gateway

This Network Configuration was created to make it easy to use UBOS for home routers. In this configuration, UBOS will connect to the public internet via broadband through one network interface, and obtain an IP address from the ISP via DHCP. All other network interfaces will have statically allocated, private IP addresses that connect to the public internet via Network Address Translation (NAT, also known as masquerading).

This configuration requires the Device to have at least two network interfaces: one for the upstream connection to the public internet via the ISP, and one for the local network. Devices connecting to the local network can obtain local IP addresses from the UBOS device via DHCP. The Device also provides DNS for the local network, with delegation to the ISP’s DNS server.

If the Device has more than two network interfaces, additional interfaces will be created as separate local networks on different subnets.

Sites running on the Device are accessible from the local network (“downstream”) but not from the public internet (“upstream”).

In this mode:

• network interfaces: All network interfaces are active.

  • The first (“upstream”) interface (which one that is depends on the hardware; trial and error helps) connects to the upstream broadband connection. It obtains IP address, default gateway and upstream DNS server information via DHCP.

  • All other (“downstream”) interfaces have static IP addresses assigned. Computers connecting to those interfaces can obtain a local area network IP address, default gateway and DNS server information from a DHCP server and a DNS server running on the Device.

• masquerade: Computers connected to a “downstream” interface are masqueraded behind the IP address of the “upstream” interface.

• mDNS: The Device will advertise itself on the “downstream” interfaces only.

• ports: Application-level ports (such as HTTP and HTTPS ports 80 and 443) will be accessible from computers connected to the “downstream” interfaces only.

• ssh: ssh connections are accepted on all interfaces.

• firewall: All parts other than ssh are firewalled on the “upstream” interface. Application ports are accessible from the “downstream” interfaces.

Network configuration: public-gateway

This Network Configuration is identical to gateway, except that Sites running on the Device are accessible both from the local network (“downstream”) and from the public internet (“upstream”).

Network configuration: container

This Network Configuration is used by UBOS when run in a Linux container started by systemd-nspawn or the like. It is very similar to client but there are no mDNS advertisements.

Network configuration: off

In this network configuration, UBOS has turned off all networking. This is useful as an emergency setting.

Network configuration: espressobin

This ESPRESSObin-specific Network Configuration is like gateway. It configures the Ethernet port closest to the USB 3 port (the blue USB port) on the ESPRESSObin to be the upstream network interface, and the other network interfaces to be downstream.

mDNS hostnames

By default, Devices announce themselves on the local-area network with a name derived from the type of Device, such as ubos-pc.local.

The advantage of using these mDNS hostnames is that no DNS setup is required, and you do not need to assign a static IP address to your Device.

The disadvantage of using these hostnames is that they only work on the local network, and that you cannot run more than one Site on the same Device. There may also be collisions if you run more than one Device of the same type on the same network.

If you wish to change your Device’s mDNS hostname, change its Linux hostname, and restart the Avahi daemon. Assuming you would like the new name to be mydevice, you can do this by executing the following commands as root:

% hostname mydevice
% hostname > /etc/hostname
% sudo systemctl restart avahi-daemon

Non-mDNS (regular) hostnames

If you would like to use more than one Site on the same Device, or you would like to use a hostname of your choosing (say, family.example.com) you need to set up DNS yourself. This can sometimes be performed in the administration interface of your home router.

For example, depending on the model of your home router, you may be able to do this:

• Log into the administrative interface of your home router, and look for a page that lists all currently connected devices on your network.

• Look for your Device, and note its MAC address.

• In some part of the administrative interface of your home router, you may be able to assign a consistent hostname for the device with this MAC address.

Unfortunately, this entirely depends on the features of your home router, and is outside of the control of UBOS.

Persistence of network configuration settings

Once a Network Configuration is set with:

% sudo ubos-admin setnetconfig <name>

it will survive a reboot. Furthermore, when a Network Configuration is restored – for example because temporarily another Network Configuration was activated – the previous settings will be restored as much as possible. Consider this sequence:

% sudo ubos-admin setnetconfig standalone
% sudo ubos-admin setnetconfig off
% sudo ubos-admin setnetconfig standalone

In the standalone Network Configuration, UBOS assigns static IP addresses to all network interfaces found. Which IP address is assigned to which network interface is basically random. However, it would be desirable if the same IP address was assigned to the same interface when the standalone network configuration was restored after temporarily being off. UBOS accomplishes this by saving the actual assignments in file /etc/ubos/netconfig-standalone.json (replace standalone with the name of the network configuration). If such a file exists, UBOS will restore its settings as much as possible.

This enables a user not scared of editing a JSON file to override the standard settings of a particular Network Configuration. For example, if a Device has two network interfaces and is used in the client network configuration, by editing /etc/ubos/netconfig-client.json and executing ubos-admin setnetconfig client again, the user could, for example, keep one of those interfaces off, or have different ports open.

To display information about the most recently set Network Configuration:

% sudo ubos-admin shownetconfig

Extra DHCP and DNS configuration settings

UBOS uses dnsmasq (home page) to issue DHCP leases and manage DNS on the local network. UBOS makes it straightforward for you to add your own settings to the ones managed by UBOS:

• Settings generated and managed by UBOS are in directory /etc/dnsmasq.ubos.d.

• Add your settings to directory /etc/dnsmasq.d. You can use any file name, as long as it ends in .conf.

For details, please refer to the dnsmasq documentation.

For example: you could use this setup to implement a DHCP “white list” so only devices that are know are allowed to obtain an IP address, which in turn will be the same every time the same device connects to the network.

External Dynamic DNS

If your Device can be reached over the public internet, such as if it acts as a broadband router, it may be advantageous to run Dynamic DNS: this provides a consistent DNS hostname for the Device, even if the internet service provider changes the Device’s IP address from time to time.

For that purpose, UBOS includes the ddclient package, which supports a broad range of paid and free dynamic DNS providers. To set it up, first install the package:

% sudo pacman -S ddclient

Then, as root, edit /etc/ddclient/ddclient.conf with the settings for your dynamic DNS provider. Finally, run ddclient as a daemon:

% sudo systemctl enable --now ddclient.service

This is described in more detail on the Arch Linux Wiki.