Network Configuration

Koios needs an address that does not change. Operators will bookmark it, your equipment will be reached from it, and a license is tied to the machine — so an address handed out automatically, which can be different after the next power cut, is not good enough.

If you set a static address during Installing Ubuntu, that is already done. Confirm it below, open the firewall, and move on — the netplan sections are for changing an address later.

Confirm the Address

ip -br addr

Your adapter should show the address you chose. Then check the machine has a route off its own network:

ip route

There must be a line beginning default via, followed by your gateway. Finally, confirm names resolve as well as addresses:

ping -c 3 1.1.1.1
ping -c 3 ubuntu.com

If the first works and the second does not, the address and gateway are right and DNS is wrong — fix the name servers using the sections below.

All three good? Skip to Opening the Firewall.

Changing the Address

Use this when the machine was installed with an automatic address, when the address has to move, or when somebody else installed Ubuntu and left it on DHCP.

Do this over SSH where you can. Editing the file at the console means typing indentation-sensitive text with no paste; over SSH you can paste it, and copy it back out to check it.

What You Need

Ask whoever runs your network for these values. Guessing them causes problems that are hard to diagnose later, and the address in particular must be one nobody else will be given.

The address has to be one nobody else will be given: pick it outside the range your router hands out automatically, or have it reserved there. If the router later gives the same address to a laptop, both stop working correctly and the cause is not obvious.

Step 1: Find the Adapter Name

Linux names network adapters by where they are attached, so the name varies by machine:

ip -br link

The output lists one adapter per line. Ignore lo, which is internal to the machine, and anything beginning docker or veth if Docker is already installed. What is left is your physical adapter — typically named eth0, eno1, enp3s0, or ens18.

Note the name exactly. The next step will not work if it is wrong, and a wrong name is the most common mistake on this page.

Step 2: Write the Configuration

Ubuntu reads its network settings from files in /etc/netplan/. Create a new one rather than editing what is already there:

sudo nano /etc/netplan/99-koios.yaml

nano is a plain text editor. Type into it, then save with Ctrl+O and Enter, and exit with Ctrl+X.

Enter the following, substituting your adapter name and your four values:

network:
  version: 2
  renderer: networkd
  ethernets:
    <your-adapter-name>:
      dhcp4: false
      addresses: [<your-server-ip>/24]
      routes:
        - to: default
          via: <your-gateway-ip>
      nameservers:
        addresses: [<your-dns-servers>]

The 99- at the start of the filename matters: the files are read in order, and a later one wins. Naming it 99-koios.yaml means it overrides whatever the Ubuntu installer wrote, without you having to edit that file — so if you get it wrong, deleting your file restores what the installer set up.

Step 3: Apply It

Netplan refuses to use a file other users can read, because it can hold wireless passwords. Restrict it first:

sudo chmod 600 /etc/netplan/99-koios.yaml

Then apply:

sudo netplan apply

Silence means success. If it reports an error, it names the line: almost always indentation, or an adapter name that does not exist.

Step 4: Check It Worked

Run the three checks from Confirm the Address again. All three should now pass against the new address.

If you were connected over SSH, reconnect using the new address:

ssh <your-username>@<your-server-ip>

Opening the Firewall

Koios serves its web interface on ports 443 and 80. If the machine has a firewall enabled, allow them:

sudo ufw status

If that reports inactive, there is nothing to do. If it reports active:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Keep SSH open too, or you will lock yourself out of the machine:

sudo ufw allow 22/tcp

Checking the Ports Are Free

Koios cannot start if something else already holds port 80 or 443:

sudo ss -lntp | grep -E ':(80|443)\s'

No output is what you want. If something is listed, another web server is running — often one installed alongside a previous application. Either remove it, or move Koios to different ports using the settings in Environment Variables.

If the Machine Takes Two Minutes to Boot

A machine with a configured adapter that has no cable in it stalls during startup, waiting for a network that is never coming. It shows a message about waiting for the network to be configured and gives up after about two minutes.

A second adapter left configured but unplugged is the usual cause. Mark it optional so startup stops waiting for it:

enp4s0:
      dhcp4: true
      optional: true

Add that alongside your main adapter, at the same indentation, then sudo netplan apply again.

To see what startup is actually spending its time on:

systemd-analyze blame | head -10

What's Next

• Time Synchronization: keep the machine's clock accurate