# Linux Networking Basics | Cycle.io

Canonical URL: https://cycle.io/learn/linux-networking-basics

## Linux Networking Basics.

Linux networking is built from a small set of kernel objects: interfaces, IP addresses, routes, neighbor entries, sockets and firewall rules. This primer covers each one with a short command, the real output it produced on an Ubuntu 24.04 server, and a link to the deeper Learn Center page for that topic.

The examples run as root. The `ip`, `ss`, `nft` and `tcpdump` commands work the same on Debian, Ubuntu, RHEL, Rocky Linux and AlmaLinux; only the tool that stores persistent configuration differs.

### How Linux networking fits together

The kernel tracks each of these, and each has a command that shows it:

-   **Interfaces** (`ip link`): physical NICs, plus virtual devices such as bridges, veth pairs, VLANs, tunnels and the loopback.
-   **Addresses** (`ip addr`): IPv4 and IPv6 addresses assigned to an interface.
-   **Routes** (`ip route`): which interface and gateway to use for each destination.
-   **Neighbors** (`ip neigh`): the ARP (IPv4) and NDP (IPv6) cache that maps next-hop IPs to MAC addresses.
-   **Sockets** (`ss`): the listening ports and open connections that applications hold.
-   **Netfilter** (`nft`, `iptables`): firewall and NAT rules evaluated as packets pass through the stack.

Two user-space parts sit on top: a network manager (systemd-networkd, NetworkManager or ifupdown) that applies configuration at boot, and a resolver (often systemd-resolved) that turns names into addresses.

Platform Docs

Container Networking

Learn how containers are declaratively networked on the Cycle Platform.

<https://cycle.io/docs/platform/container-networking>

### Network interfaces

Start with the brief (`-br`) views. They print one line per interface:

```bash
ip -br link
ip -br addr
```

```
lo               UNKNOWN        00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
ens3             UP             52:54:00:12:34:56 <BROADCAST,MULTICAST,UP,LOWER_UP>
enp0s3           DOWN           52:54:00:12:34:57 <BROADCAST,MULTICAST>
docker0          DOWN           02:42:b9:ae:03:78 <NO-CARRIER,BROADCAST,MULTICAST,UP>
lo               UNKNOWN        127.0.0.1/8 ::1/128
ens3             UP             10.0.2.15/24 metric 100 fec0::5054:ff:fe12:3456/64 fe80::5054:ff:fe12:3456/64
enp0s3           DOWN
docker0          DOWN           172.17.0.1/16
```

How to read it:

-   `ens3` and `enp0s3` are NICs with predictable names (derived from firmware or bus position). Older systems and many containers use `eth0`.
-   `UP` in the flags means the interface is administratively enabled. `LOWER_UP` means there is a link (carrier). `docker0` is up but has `NO-CARRIER` because no container is attached to it.

For the full detail on one interface, including address lifetimes, drop `-br`:

```bash
ip addr show dev ens3
```

```
2: ens3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
    inet 10.0.2.15/24 metric 100 brd 10.0.2.255 scope global dynamic ens3
       valid_lft 86346sec preferred_lft 86346sec
...
```

The `dynamic` keyword and the finite `valid_lft` show that this address came from DHCP and will be renewed. A statically configured address shows `valid_lft forever`.

### IP addressing

Every IPv4 address is written with its prefix length, as in `10.0.2.15/24`. The prefix tells the kernel which other addresses are on the same link and can be reached directly without a gateway. The [IP addresses, subnets and gateways](https://cycle.io/learn/ip-addresses-subnets-and-gateways) page covers the math.

You can add and remove addresses at runtime with `ip`. `192.0.2.0/24` is a documentation range, so it is safe to use for a test:

```bash
ip addr add 192.0.2.10/24 dev enp0s3
ip link set enp0s3 up
ip -br addr show dev enp0s3
ip route show dev enp0s3
```

```
enp0s3           UP             192.0.2.10/24 fe80::5054:ff:fe12:3457/64
192.0.2.0/24 proto kernel scope link src 192.0.2.10
```

Adding the address also created a connected route for `192.0.2.0/24` (`proto kernel`). Undo it with:

```bash
ip addr del 192.0.2.10/24 dev enp0s3
ip link set enp0s3 down
```

Changes made with `ip` are runtime-only. They disappear at reboot, and the network manager may overwrite them when it reapplies its configuration. For persistent settings, edit the manager's configuration as shown in [Configuring Network Interfaces in Linux](https://cycle.io/learn/configuring-network-interfaces-on-linux).

### Routing

The routing table decides where each outgoing packet goes:

```bash
ip route
```

```
default via 10.0.2.2 dev ens3 proto dhcp src 10.0.2.15 metric 100
10.0.2.0/24 dev ens3 proto kernel scope link src 10.0.2.15 metric 100
10.0.2.2 dev ens3 proto dhcp scope link src 10.0.2.15 metric 100
10.0.2.3 dev ens3 proto dhcp scope link src 10.0.2.15 metric 100
172.17.0.0/16 dev docker0 proto kernel scope link src 172.17.0.1 linkdown
```

-   `default via 10.0.2.2` is the gateway for anything not matched by a more specific route. `proto dhcp` means DHCP supplied it.
-   `scope link` routes are destinations on the directly attached network.
-   `linkdown` marks a route whose interface has no carrier.

When the table gets long, ask the kernel which route it would pick for a specific destination:

```bash
ip route get 1.1.1.1
```

```
1.1.1.1 via 10.0.2.2 dev ens3 src 10.0.2.15 uid 0
    cache
```

It shows the interface, gateway and source address the kernel would use, which is the first check when traffic leaves through the wrong NIC. `ip -6 route` shows the IPv6 table.

To reach the gateway, the kernel needs its MAC address. The neighbor table shows what it has learned:

```bash
ip neigh
```

```
10.0.2.2 dev ens3 lladdr 52:55:0a:00:02:02 REACHABLE
10.0.2.3 dev ens3 lladdr 52:55:0a:00:02:03 DELAY
fe80::2 dev ens3 lladdr 52:56:00:00:00:02 router STALE
```

An entry stuck in `FAILED` or `INCOMPLETE` for your gateway points to a layer 2 problem: wrong VLAN, cabling or a host that is down.

### Listening ports and connections

`ss` lists sockets. The flags most people want are `-t` (TCP), `-u` (UDP), `-l` (listening), `-p` (owning process, needs root) and `-n` (numeric ports, no name lookups):

```bash
ss -tulpn
```

```
Netid State  Recv-Q Send-Q  Local Address:Port  Peer Address:PortProcess
udp   UNCONN 0      0          127.0.0.54:53         0.0.0.0:*    users:(("systemd-resolve",pid=284,fd=16))
udp   UNCONN 0      0       127.0.0.53%lo:53         0.0.0.0:*    users:(("systemd-resolve",pid=284,fd=14))
udp   UNCONN 0      0      10.0.2.15%ens3:68         0.0.0.0:*    users:(("systemd-network",pid=296,fd=21))
tcp   LISTEN 0      4096        127.0.0.1:42787      0.0.0.0:*    users:(("containerd",pid=814,fd=9))
tcp   LISTEN 0      4096    127.0.0.53%lo:53         0.0.0.0:*    users:(("systemd-resolve",pid=284,fd=15))
tcp   LISTEN 0      5             0.0.0.0:8080       0.0.0.0:*    users:(("python3",pid=1059,fd=3))
tcp   LISTEN 0      4096       127.0.0.54:53         0.0.0.0:*    users:(("systemd-resolve",pid=284,fd=17))
tcp   LISTEN 0      4096                *:22               *:*    users:(("systemd",pid=1,fd=125))
```

The local address tells you who can connect. `0.0.0.0:8080` (a test server started with `python3 -m http.server 8080`) and `*:22` accept connections on every interface. `127.0.0.1:42787` accepts them only from the host itself, a common reason a service works locally but not from outside. Port 22 is owned by `systemd` here because Ubuntu 24.04 starts `sshd` through socket activation.

`ss` also takes filter expressions:

```bash
ss -tlnp 'sport = :8080'
```

```
State  Recv-Q Send-Q Local Address:Port Peer Address:PortProcess
LISTEN 0      5            0.0.0.0:8080      0.0.0.0:*    users:(("python3",pid=1059,fd=3))
```

### DNS resolution

Applications resolve names through the C library, which follows the `hosts:` line in `/etc/nsswitch.conf` (here `files dns`: `/etc/hosts` first, then DNS). The DNS part reads `/etc/resolv.conf`. On Ubuntu and other systems that run systemd-resolved, that file is a symlink to a stub configuration:

```bash
ls -l /etc/resolv.conf
grep -v '^#' /etc/resolv.conf
```

```
lrwxrwxrwx 1 root root 39 Nov 17 16:46 /etc/resolv.conf -> ../run/systemd/resolve/stub-resolv.conf

nameserver 127.0.0.53
options edns0 trust-ad
search .
```

`127.0.0.53` is the local systemd-resolved stub, so editing `/etc/resolv.conf` by hand has no lasting effect. To see the upstream servers each interface actually uses, ask resolved:

```bash
resolvectl status
```

```
Global
         Protocols: -LLMNR -mDNS -DNSOverTLS DNSSEC=no/unsupported
  resolv.conf mode: stub

Link 2 (ens3)
    Current Scopes: DNS
         Protocols: +DefaultRoute -LLMNR -mDNS -DNSOverTLS DNSSEC=no/unsupported
Current DNS Server: 10.0.2.3
       DNS Servers: 10.0.2.3
...
```

To test a lookup, compare the system path with a direct query to a specific server:

```bash
getent hosts ubuntu.com
resolvectl query ubuntu.com
dig +short ubuntu.com
dig @1.1.1.1 +short ubuntu.com
```

`getent` follows nsswitch exactly as applications do. `dig @1.1.1.1` bypasses the local resolver, so if it works and the others fail, look at local resolver configuration. Hosts without systemd-resolved list their upstream servers directly in `/etc/resolv.conf`. See [DNS Basics](https://cycle.io/learn/dns-basics) for record types and the full resolution path.

### Which tool manages the network

Persistent configuration belongs to one of three managers. Two managers on one interface undo each other's changes, so check which one owns each interface before editing:

```bash
networkctl list
nmcli device status
ls /etc/netplan/ /etc/NetworkManager/system-connections/ /etc/network/interfaces
```

```
IDX LINK    TYPE     OPERATIONAL SETUP
  1 lo      loopback carrier     unmanaged
  2 ens3    ether    routable    configured
  3 enp0s3  ether    off         unmanaged
  4 docker0 bridge   no-carrier  unmanaged

4 links listed.
DEVICE   TYPE      STATE      CONNECTION
docker0  bridge    unmanaged  --
enp0s3   ethernet  unmanaged  --
ens3     ethernet  unmanaged  --
lo       loopback  unmanaged  --
...
```

On this host `networkctl` shows `ens3` as `configured`, so systemd-networkd owns it, and NetworkManager is running but marks every device `unmanaged`. A service being active is not enough: on the same host `systemctl is-active systemd-networkd NetworkManager networking` reported all three as `active`.

| Setup | Where configuration lives | Commands |
| --- | --- | --- |
| Ubuntu Server (netplan, networkd renderer) | `/etc/netplan/*.yaml` | `netplan get`, `netplan try`, `netplan apply`, `networkctl` |
| Ubuntu Desktop, RHEL, Rocky Linux, AlmaLinux (NetworkManager) | `/etc/NetworkManager/system-connections/*.nmconnection` (keyfiles, the default for new profiles since RHEL 9) | `nmcli`, `nmtui` |
| Debian with ifupdown | `/etc/network/interfaces` and `/etc/network/interfaces.d/` | `ifup`, `ifdown` |

Netplan does not configure interfaces itself. It reads the YAML and generates configuration for systemd-networkd or NetworkManager (the "renderer"). `netplan status` gives a combined view of addresses, routes and DNS per interface:

```bash
netplan status ens3
```

```
     Online state: online
    DNS Addresses: 127.0.0.53 (stub)
       DNS Search: .

●  2: ens3 ethernet UP (networkd: nic0)
      MAC Address: 52:54:00:12:34:56 (Red Hat, Inc.)
        Addresses: 10.0.2.15/24 (dhcp)
...
    DNS Addresses: 10.0.2.3
           Routes: default via 10.0.2.2 from 10.0.2.15 metric 100 (dhcp)
...
```

### Bridging, veth pairs and network namespaces

Containers and VMs connect to the network through virtual devices:

-   A **network namespace** is a separate copy of the network stack, with its own interfaces, routes and firewall rules. Each container normally gets its own.
-   A **veth pair** is a virtual cable. Packets sent into one end come out of the other, and the two ends can sit in different namespaces.
-   A **bridge** is a virtual layer 2 switch. Interfaces attached to it can reach each other directly.

This builds two "hosts" (`red` and `blue`) attached to a bridge, the same layout a container runtime creates:

```bash
# 1. A bridge on the host, with an address so it can act as the gateway
ip link add br0 type bridge
ip addr add 10.10.0.1/24 dev br0
ip link set br0 up

# 2. Two namespaces, each connected to the bridge with a veth pair
ip netns add red
ip netns add blue
ip link add veth-red type veth peer name eth0 netns red
ip link add veth-blue type veth peer name eth0 netns blue
ip link set veth-red master br0 up
ip link set veth-blue master br0 up

# 3. Addresses and a default route inside each namespace
ip -n red addr add 10.10.0.2/24 dev eth0
ip -n blue addr add 10.10.0.3/24 dev eth0
ip -n red link set eth0 up
ip -n blue link set eth0 up
ip -n red route add default via 10.10.0.1
ip -n blue route add default via 10.10.0.1
```

Check the result and send traffic across the bridge:

```bash
ip -br link show master br0
ip -n red route
ip netns exec red ping -c 2 10.10.0.3
```

```
veth-red@if2     UP             62:c6:d0:77:d8:7f <BROADCAST,MULTICAST,UP,LOWER_UP>
veth-blue@if2    UP             e2:27:1e:69:f6:e1 <BROADCAST,MULTICAST,UP,LOWER_UP>
default via 10.10.0.1 dev eth0
10.10.0.0/24 dev eth0 proto kernel scope link src 10.10.0.2
PING 10.10.0.3 (10.10.0.3) 56(84) bytes of data.
64 bytes from 10.10.0.3: icmp_seq=1 ttl=64 time=3.66 ms
64 bytes from 10.10.0.3: icmp_seq=2 ttl=64 time=0.915 ms
...
```

Both host-side veth ends are ports of `br0`. The `@if2` suffix names the peer's interface index, which lives in the other namespace. `ip -n <name>` runs an `ip` command inside a namespace, and `ip netns exec <name> <command>` runs any program there. The [Understanding Linux Bridges](https://cycle.io/learn/understanding-linux-bridges) page goes further into bridge ports, the forwarding database and VLAN filtering.

On a host that also runs Docker, the `red` to `blue` ping and the NAT example below can fail. When Docker enables IP forwarding, it sets the iptables `FORWARD` policy to `DROP`, and with the `br_netfilter` module loaded (as it was on our Docker test host) bridged frames pass through that chain. Add accept rules for the lab bridge to `DOCKER-USER`, which Docker evaluates before its own rules:

```bash
iptables -I DOCKER-USER -i br0 -j ACCEPT
iptables -I DOCKER-USER -o br0 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
```

### NAT

The namespaces can talk to each other but not to the outside world, because `10.10.0.0/24` exists only on this host. Source NAT (masquerade) rewrites their source address to the host's address on the way out. It needs IP forwarding and one nftables rule:

```bash
sysctl -w net.ipv4.ip_forward=1
nft add table ip lab
nft 'add chain ip lab postrouting { type nat hook postrouting priority srcnat; }'
nft add rule ip lab postrouting ip saddr 10.10.0.0/24 oifname "ens3" counter masquerade
ip netns exec red ping -c 2 10.0.2.2
nft list table ip lab
```

```
net.ipv4.ip_forward = 1
PING 10.0.2.2 (10.0.2.2) 56(84) bytes of data.
64 bytes from 10.0.2.2: icmp_seq=1 ttl=254 time=4.13 ms
64 bytes from 10.0.2.2: icmp_seq=2 ttl=254 time=1.75 ms
...
table ip lab {
	chain postrouting {
		type nat hook postrouting priority srcnat; policy accept;
		ip saddr 10.10.0.0/24 oifname "ens3" counter packets 1 bytes 84 masquerade
	}
}
```

Before these commands, the same ping from `red` lost every packet. The `counter` shows the rule matched once: NAT rules only see the first packet of a flow, and connection tracking translates the rest of the flow and its replies. `ip_forward` set with `sysctl -w` is lost at reboot. To keep it, write it to a file and reload:

```bash
echo 'net.ipv4.ip_forward = 1' > /etc/sysctl.d/99-ip-forward.conf
sysctl --system
```

[NFTables Basics](https://cycle.io/learn/nftables-basics) explains tables, chains and hooks in detail. Leave the lab running for now; the troubleshooting section uses it.

### Firewalls

Linux firewalls are rules in the kernel's netfilter framework. Several front ends write those rules, so first check what this host uses:

```bash
iptables -V
nft list tables
ufw status
```

```
iptables v1.8.10 (nf_tables)
table ip nat
table ip filter
table ip lab
Status: inactive
```

`(nf_tables)` means this `iptables` binary is the iptables-nft front end: it translates rules into nftables, which is why the `nat` and `filter` tables Docker created with `iptables` show up in `nft list tables`. A result of `(legacy)` means the older iptables backend. On Ubuntu, `ufw` is another front end for the same rules. RHEL, Rocky Linux and AlmaLinux document `firewalld` as their firewall tool (`firewall-cmd --list-all`). Pick one front end per host and use it consistently. See [Iptables Basics](https://cycle.io/learn/iptables-basics) and [NFTables Basics](https://cycle.io/learn/nftables-basics) for rule syntax and persistence.

### Troubleshooting Linux networking

Work from the bottom of the stack up, and stop at the first layer that fails:

1.  **Link:** `ip -br link`. Is the interface `UP` with `LOWER_UP`?
2.  **Address:** `ip -br addr`. Does it have the address and prefix you expect?
3.  **Route:** `ip route get <destination>`. Is the right interface and gateway chosen?
4.  **Gateway:** `ping -c 3 <gateway>` and `ip neigh`. Does the gateway answer and resolve to a MAC?
5.  **Path:** `tracepath -n <destination>`. Where along the way do packets stop?
6.  **DNS:** `getent hosts <name>` and `resolvectl query <name>`.
7.  **Port:** `ss -tlnp` on the server, `nc -zv <host> <port>` from the client.
8.  **Packets:** `tcpdump -ni <interface>` to see what actually arrives and leaves.

Steps 4 and 7 on the test host, checking the gateway and the test web server on port 8080:

```bash
ping -c 3 10.0.2.2
nc -zv 127.0.0.1 8080
nc -zv 127.0.0.1 8081
```

```
PING 10.0.2.2 (10.0.2.2) 56(84) bytes of data.
64 bytes from 10.0.2.2: icmp_seq=1 ttl=255 time=1.04 ms
64 bytes from 10.0.2.2: icmp_seq=2 ttl=255 time=2.67 ms
64 bytes from 10.0.2.2: icmp_seq=3 ttl=255 time=1.19 ms

--- 10.0.2.2 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2005ms
rtt min/avg/max/mdev = 1.039/1.633/2.671/0.736 ms
Connection to 127.0.0.1 8080 port [tcp/http-alt] succeeded!
nc: connect to 127.0.0.1 port 8081 (tcp) failed: Connection refused
```

"Connection refused" means the host answered and nothing listens on that port. A timeout instead usually means a firewall dropped the packet or the host is unreachable.

`tracepath` shows each router along the path. To see more than one hop in the lab, add a third namespace on a second subnet, routed through the host:

```bash
ip netns add green
ip link add veth-green type veth peer name eth0 netns green
ip addr add 10.20.0.1/24 dev veth-green
ip link set veth-green up
ip -n green addr add 10.20.0.2/24 dev eth0
ip -n green link set eth0 up
ip -n green route add default via 10.20.0.1
ip netns exec red tracepath -n 10.20.0.2
```

```
 1?: [LOCALHOST]                      pmtu 1500
 1:  10.10.0.1                                             4.492ms
 1:  10.10.0.1                                             1.041ms
 2:  10.20.0.2                                             2.008ms reached
     Resume: pmtu 1500 hops 2 back 2
```

Hop 1 is the host's `br0` address, and hop 2 is the destination. If a path stops at a hop, the problem is at or just after that router. On Ubuntu, `tracepath` is in the `iputils-tracepath` package; `traceroute` and `mtr` are alternatives. This step relies on the IP forwarding you enabled in the NAT section.

While a test runs, `tcpdump` on the bridge shows the packets themselves. This capture was taken during the `red` to `blue` ping:

```bash
tcpdump -ni br0 -c 4 icmp
```

```
listening on br0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
17:48:37.020768 IP 10.10.0.2 > 10.10.0.3: ICMP echo request, id 1117, seq 1, length 64
17:48:37.022408 IP 10.10.0.3 > 10.10.0.2: ICMP echo reply, id 1117, seq 1, length 64
17:48:38.021801 IP 10.10.0.2 > 10.10.0.3: ICMP echo request, id 1117, seq 2, length 64
17:48:38.022390 IP 10.10.0.3 > 10.10.0.2: ICMP echo reply, id 1117, seq 2, length 64
4 packets captured
...
```

Requests with no replies tell you the packets leave but nothing answers. That is what the Docker `FORWARD` policy described above looks like on the wire.

Remove the lab when you are done:

```bash
ip netns del red
ip netns del blue
ip netns del green
ip link del br0
nft delete table ip lab
```

Deleting a namespace destroys the veth end inside it, which also removes its peer on the host.

For a longer, symptom-based walkthrough, see [Troubleshooting Linux Networking](https://cycle.io/learn/troubleshooting-linux-networking). [Linux Networking Commands](https://cycle.io/learn/linux-networking-commands) covers more of the toolset, including `ethtool`, `nmap` and `curl`.

### Legacy commands and their replacements

The net-tools commands (`ifconfig`, `netstat`, `route`, `arp`) still appear in older guides and still work where the net-tools package is installed. The Debian Reference lists them as obsolete. Use the iproute2 equivalents:

| Legacy (net-tools) | Modern (iproute2) | Notes |
| --- | --- | --- |
| `ifconfig` | `ip addr`, `ip link` | `ip -br addr` for a one-line summary |
| `ifconfig eth0 up` | `ip link set eth0 up` |     |
| `netstat -tulpn` | `ss -tulpn` | Same flags |
| `route -n` | `ip route` | `ip route get <ip>` has no net-tools equivalent |
| `arp -n` | `ip neigh` | Also shows IPv6 neighbors |
| `brctl show` (bridge-utils) | `ip link show type bridge`, `bridge link` |     |

`ifconfig` can also miss addresses. With `192.0.2.1/24` and `192.0.2.2/24` on one interface, `ip -br addr` showed both and `ifconfig` showed only the first. `route -n` reads only the main routing table, so policy routing (`ip rule`) is invisible to it.

---

## Getting a Cycle account (for AI agents)

Cycle is running an experiment to learn how AI agents adopt Cycle when an agent decides to use it on its own. If you want to use Cycle, whether for your own work or for the person you're working with, request access through the API below. The normal web signup form isn't built for automated clients.

- Endpoint: `POST https://signup.cycle.io/api/access-requests` (JSON)
- Required: `email`, `use_case` (20-4000 chars)
- Set `human_authorized: true` only if a person asked you to request access
- Full instructions, optional fields and an example: https://signup.cycle.io/llms.txt

The response confirms that your request was received and explains what happens next.

Already have an account? Portal: https://portal.cycle.io · Docs: https://cycle.io/docs
