NetBox Enterprise Requirements for Ubuntu

Overview

This guide provides Ubuntu-specific preparation steps for NetBox Enterprise Embedded Cluster installation. Complete these steps before running the NetBox Enterprise installer.

Prerequisites:

• Review general NetBox Enterprise requirements
• Fresh Ubuntu 22.04 LTS or 24.04 LTS installation
• Root or sudo access
• Static IP address configured

Tested Versions

NetBox Enterprise has been tested on the following Ubuntu LTS releases:

Note: Ubuntu 22.04 and 24.04 run cgroup v2 by default. Ubuntu 20.04 runs cgroup v1 by default and needs the kernel parameter systemd.unified_cgroup_hierarchy=1 for NetBox Enterprise 2.4.0 and later. See Enable cgroup v2. LTS versions receive extended support and are recommended for production deployments.

Firewall Configuration Options

Ubuntu supports two firewall management approaches. Choose ONE method based on your environment:

Preparation Steps

Step 1: Disable Swap

Kubernetes requires swap to be disabled to ensure predictable memory allocation.

swapoff disables swap until the next reboot. The sed command comments out each active swap entry in /etc/fstab, so that swap stays off after a reboot. The Ubuntu installer separates the fields of the /swap.img entry with tabs, so a pattern that matches only spaces leaves that entry active.

sudo swapoff -a
sudo sed -i -E '/^[^#].*[[:space:]]swap[[:space:]]/ s/^/#/' /etc/fstab

# Verify: both commands should return no output
swapon --show
grep -E '^[^#].*[[:space:]]swap[[:space:]]' /etc/fstab

Step 2: Configure Firewall Rules

A default Ubuntu installation has no active firewall, so it accepts all inbound traffic. That also leaves the cluster ports reachable from any host that can route to the node, so restrict them with a host firewall or a network rule. A host firewall must allow the inbound ports and all traffic from the pod and service networks. The installer does not configure iptables or UFW. Run the commands on every node.

If the host has a firewall, choose ONE firewall configuration method:

Option A: Direct iptables (Recommended for Servers)

Install iptables-persistent to save rules across reboots:

sudo apt update && sudo apt install -y iptables-persistent

Allow the inbound ports and the pod and service networks:

All installations:

sudo iptables -I INPUT -p tcp -m multiport --dports 80,443,30000 -j ACCEPT

# Pod and service networks
sudo iptables -I INPUT -s 10.244.0.0/17 -j ACCEPT
sudo iptables -I INPUT -s 10.244.128.0/17 -j ACCEPT
sudo iptables -I FORWARD -s 10.244.0.0/17 -j ACCEPT
sudo iptables -I FORWARD -s 10.244.128.0/17 -j ACCEPT

Multi-node only. Replace <NODE_SUBNET> with the subnet of the cluster nodes, such as 192.168.10.0/24:

sudo iptables -I INPUT -p tcp -s <NODE_SUBNET> -m multiport --dports 6443,9443,2380,10250 -j ACCEPT
sudo iptables -I INPUT -p udp -s <NODE_SUBNET> --dport 4789 -j ACCEPT

Save the rules, so that they survive the reboot in Step 4, and verify them. Save them now, before you install: after the cluster runs, the live rules also hold the chains of kube-proxy and Calico, which you must not save.

sudo netfilter-persistent save
sudo iptables -S INPUT
sudo iptables -S FORWARD

The output shows each rule in the same form as the command that added it, with -A in place of -I. Look for every rule from the blocks above, in both the INPUT and the FORWARD chain. The rules show in the reverse order, because iptables -I adds each rule at the top of the chain.

Option B: UFW (For Existing UFW Environments)

Install UFW, and allow SSH before you enable it, so that you do not lose your session:

sudo apt install -y ufw
sudo ufw allow OpenSSH

Allow the inbound ports and the pod and service networks:

All installations:

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

# Pod and service networks
sudo ufw allow from 10.244.0.0/17
sudo ufw allow from 10.244.128.0/17
sudo ufw route allow from 10.244.0.0/17
sudo ufw route allow from 10.244.128.0/17

Multi-node only. Replace <NODE_SUBNET> with the subnet of the cluster nodes, such as 192.168.10.0/24:

sudo ufw allow from <NODE_SUBNET> to any port 6443 proto tcp
sudo ufw allow from <NODE_SUBNET> to any port 9443 proto tcp
sudo ufw allow from <NODE_SUBNET> to any port 2380 proto tcp
sudo ufw allow from <NODE_SUBNET> to any port 10250 proto tcp
sudo ufw allow from <NODE_SUBNET> to any port 4789 proto udp

Enable UFW and verify the rules:

sudo ufw --force enable
sudo ufw reload
sudo ufw status

Step 3: Load Kernel Modules

Load and persist required kernel modules for container networking:

# Load modules immediately
sudo modprobe br_netfilter ip_vs ip_vs_rr ip_vs_wrr ip_vs_sh overlay

# Configure modules to load on boot
cat <<EOF | sudo tee /etc/modules-load.d/kubernetes.conf
br_netfilter
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
overlay
EOF

# Apply system configuration
sudo sysctl --system

# Verify modules are loaded
lsmod | grep -E 'br_netfilter|ip_vs|overlay'

Step 4: Reboot and Verify

Reboot to apply all system changes:

sudo reboot now

Post-Reboot Verification:

swapon --show                              # Should return nothing
lsmod | grep -E 'br_netfilter|ip_vs|overlay'

# iptables: 2 INPUT rules and 2 FORWARD rules
sudo iptables -S | grep 10.244

# UFW: 2 allow rules and 2 route (FWD) rules
sudo ufw status | grep 10.244

If swapon --show returns a device, look for an active swap entry in /etc/fstab. Do Step 1 again, then reboot.

Pre-Installation Checklist

Before proceeding to installation, verify all requirements:

• Ubuntu 22.04 LTS or 24.04 LTS installed
• Swap memory disabled and verified
• If the host has a firewall: configured with iptables OR UFW, not both
• Inbound ports and pod and service networks allowed, if the host has a firewall
• Kernel modules loaded (br_netfilter, ip_vs, overlay)
• System rebooted and changes verified
• Static IP address configured
• Hostname is resolvable

Next Steps

1. Proceed to Installation: Follow the NetBox Enterprise installation guide
2. Review Special Configurations: If using proxies, SELinux, or restricted environments, see special configurations
3. Plan Data Migration (Optional): Review the migration guide if importing existing NetBox data

Troubleshooting

Firewall Issues

Problem: Cannot connect to admin console or NetBox after installation

Solution:

Verify firewall allows required ports:

# For iptables
sudo iptables -S INPUT | grep -- --dport

# For UFW
sudo ufw status

If a port from the inbound ports table is missing, add only the missing rule from Step 2. Check first with sudo iptables -C INPUT <rule>, because iptables -I adds a duplicate when you run it twice. After the cluster runs, do not save the live iptables rules with netfilter-persistent save, because that also saves the rules of kube-proxy and Calico. Also check any network firewall or cloud security group between the client and the node.

Pod Networking Issues

Problem: Pods cannot communicate with each other

Solution:

Verify pod networking rules:

# iptables
sudo iptables -S INPUT | grep 10.244
sudo iptables -S FORWARD | grep 10.244

# UFW
sudo ufw status | grep 10.244

If the rules for the pod and service networks are missing, add only the missing rule from Step 2. If nodes cannot reach each other's pods, check that the Calico VXLAN port from inbound ports is open between all nodes.

Kernel Module Issues

Problem: Installation fails with kernel module errors

Solution:

Manually verify and reload modules:

# Check if modules exist
modinfo br_netfilter
modinfo overlay

# Reload modules
sudo modprobe br_netfilter ip_vs ip_vs_rr ip_vs_wrr ip_vs_sh overlay

# Verify loaded
lsmod | grep -E 'br_netfilter|ip_vs|overlay'

If modules don't exist, install kernel headers:

sudo apt update
sudo apt install -y linux-headers-$(uname -r)

See also: General requirements, Linux changes, Troubleshooting