--- title: "Network Configuration" description: "Confirm the machine's permanent address, change it later, and open the ports Koios serves on" source_url: https://ai-ops.com/docs/installation/network-configuration --- # 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](https://ai-ops.com/docs/installation/installing-ubuntu.md#network), 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 ```bash ip -br addr ``` Your adapter should show the address you chose. Then check the machine has a route off its own network: ```bash ip route ``` There must be a line beginning `default via`, followed by your gateway. Finally, confirm names resolve as well as addresses: ```bash 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](#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. | Value | What it is | |-------|------------| | **Address** | The permanent address for this machine | | **Prefix** | How large the network is. `24` is the common case and corresponds to a `255.255.255.0` subnet mask | | **Gateway** | The router the machine sends outside traffic to | | **DNS servers** | What resolves names to addresses. Your internal server if you have one | | **Adapter name** | Found in [Step 1](#step-1-find-the-adapter-name) below | 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: ```bash 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: ```bash 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: ```yaml network: version: 2 renderer: networkd ethernets: YOUR_IFACE: dhcp4: false addresses: [YOUR_IP_CIDR] routes: - to: default via: YOUR_GATEWAY nameservers: addresses: [YOUR_DNS] ``` > [!CAUTION] Indentation is part of the syntax > This file format treats leading spaces as meaning. Use two spaces per level, exactly as shown, and **never press Tab** — a tab character is rejected outright. Getting this wrong is the usual reason the next step fails. 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: ```bash sudo chmod 600 /etc/netplan/99-koios.yaml ``` Then apply: ```bash sudo netplan apply ``` > [!WARNING] This disconnects a remote session > If you are connected over SSH, applying a new address drops the connection — you are connected to the old one. Do this at the machine's console, or reconnect to the new address afterwards. 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](#confirm-the-address) again. All three should now pass against the new address. If you were connected over SSH, reconnect using the new address: ```bash ssh YOUR_USER@YOUR_IP ``` --- ## Opening the Firewall Koios serves its web interface on ports 443 and 80. If the machine has a firewall enabled, allow them: ```bash sudo ufw status ``` If that reports `inactive`, there is nothing to do. If it reports `active`: ```bash sudo ufw allow 80/tcp sudo ufw allow 443/tcp ``` Keep SSH open too, or you will lock yourself out of the machine: ```bash sudo ufw allow 22/tcp ``` ## Checking the Ports Are Free Koios cannot start if something else already holds port 80 or 443: ```bash 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](https://ai-ops.com/docs/installation/environment-variables.md). --- ## 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: ```yaml 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: ```bash systemd-analyze blame | head -10 ``` ## What's Next - [Time Synchronization](https://ai-ops.com/docs/installation/time-synchronization.md): keep the machine's clock accurate