Allocating and opening up non-default ports

There are two separate issues here:

• making sure that when an App needs an extra port, the port can be assigned in a way that it does not conflict with the port assignment of another App on the same Device. Hard-coding the number does not work! This is particularly important if more than one AppConfiguration of the same App is being run on the same Device: the ports can’t be mixed up with each other.

• allowing an App to open up a port in the UBOS firewall so clients can use it. This may or may not be required for any extra port that App likes to use, because some of those extra ports might only be used by different processes of the same App to communicate with each other on the installed Device.

So we discuss them separately:

To allocate AppConfiguration-specific ports

This is handled by AppConfigItems of type tcpport and udpport as documented in Roles section of the UBOS Manifest.

This will allocate a unique port, but not open up the firewall.

Opening up a port in the UBOS firewall

The UBOS firewall, by default, blocks most traffic and only permits that traffic that is known to be needed, such as port 80 (HTTP), port 22 (ssh) or 67 and 68 (DHCP).

If your App needs another port, you need to instruct the UBOS firewall to open it. You do this by creating a file in /etc/ubos/open-ports.d/<name> where <name> is the name of your App’s Package, or the name of that Package with the AppConfigId appended.

This file needs to contain exactly one line per open port. This line must be <PPP>/<PROTO>, where:

• <PPP> is the port number you’d like to open;
• <PROTO> is either udp or tcp, depending on what you need.

This file will be evaluated every time the UBOS firewall gets reconfigured, such as when a Site is newly deployed or reconfigured, or when the user invokes ubos-admin setnetconfig.

It is usually sufficient to simply include such a file in your Package, or generate it via the UBOS Manifest, and UBOS will evaluate it at the right time when your App is first deployed or updates.

To allocate a single port used by all AppConfigurations of an App

The following port numbers are well-known so far:

Port	Protocol	Name of App or Accessory	Description
6001	tcp	decko	decko-memcached.service listens at this port for all Decko instances on this Device.