Lesson 2 of 8 in Networking for DevOps

Ports, TCP and UDP

Core8 min

A port is a number from 0 to 65535 that tells the operating system which program on a machine should receive incoming data. A program that waits for connections on a port is listening. A client picks a temporary port of its own and connects out to the server's port using TCP or UDP.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: IP addresses, CIDR and subnets

The problem this solves

An IP address gets a packet to a machine, but one machine runs many programs. Without ports there is no way to tell a web server from a database on the same host.

Most beginner outages in this area are really port mistakes. The service listens on a different port than you expect, listens only on the local machine, or two programs fight for the same port.

How it works

One address, many ports, one program behind each
One address, many ports, one program behind eachA client connects to an address and a port, and the operating system hands the connection to whichever program is listening on that port.1 connect toIP:802 port 80 goes hereport 5432 goes hereClientrandom port 51234Server IP10.0.1.20Web serverlistening on 80Databaselistening on 5432
  • People and clients
  • Network
  • Runs code

A client connects to an address and a port, and the operating system hands the connection to whichever program is listening on that port.

  1. Client to Server IP: 1 connect to IP:80
  2. Server IP to Web server: 2 port 80 goes here
  3. Server IP to Database: port 5432 goes here

A network connection is identified by four values: the client address and port, and the server address and port. The server's port is fixed and well known, such as 22 for SSH, 80 for HTTP, 443 for HTTPS or 5432 for PostgreSQL. The client's port is chosen by the operating system for each connection, from a high range that on Linux you can read in /proc/sys/net/ipv4/ip_local_port_range.

TCP sets up a connection first, numbers the data and resends anything that gets lost, so the receiver sees an ordered, complete stream. Web traffic, SSH and database connections use it. UDP sends independent packets with no setup and no resend. DNS queries and many streaming and game protocols use it because they prefer speed to guarantees.

A listening program also chooses which addresses it accepts connections on. Binding to 127.0.0.1 accepts only connections from the same machine. Binding to 0.0.0.0 accepts connections arriving on any of the machine's addresses. This one choice explains many cases of a service that works locally and is unreachable from outside.

Read the diagram left to right. The client connects to the server address plus a port, and the operating system matches that port to a listening program. Ports below 1024 are privileged on Linux, so ordinary users usually cannot bind them.

Try it yourself

You will start a tiny web server with Python, look at its socket with ss, and watch two mistakes happen. Use an empty folder so the server has nothing private to list. Stop each server with Ctrl+C.

  1. 1
    Make an empty practice folder
    mkdir -p ~/net-lab && cd ~/net-lab

    Keep using this folder for the rest of the topic.

  2. 2
    Listen on localhost only (terminal A)
    python3 -m http.server 8000 --bind 127.0.0.1
  3. 3
    Inspect the listening socket (terminal B)
    ss -tlnp | grep 8000

    The flags mean TCP, listening, numeric ports and the owning process. Find the LISTEN state and the local address 127.0.0.1:8000. On macOS use lsof -nP -iTCP:8000 -sTCP:LISTEN.

  4. 4
    Connect as a client
    curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/

    You should see

    200
  5. 5
    Cause the classic port clash (terminal C)
    python3 -m http.server 8000 --bind 127.0.0.1

    On Linux the second copy stops with OSError: [Errno 98] Address already in use. Only one program can listen on a given address and port.

  6. 6
    Change the bind address
    python3 -m http.server 8000 --bind 0.0.0.0

    Stop the first server before you run this. ss -tlnp | grep 8000 now shows 0.0.0.0:8000, so other machines on your network can reach it. The folder is empty, but stop it when you are done.

What breaks, and where to look

  • curl: (7) Failed to connect to localhost port 8000: Connection refused

    WHY IT HAPPENS
    The connection reached the machine, and nothing was listening on that port. The service is not running, crashed, or is on a different port.
    CHECK FIRST
    Run ss -tlnp | grep <port>. No line means no listener, so start the service or fix the port number.
  • A service in a container works inside the container but fails from the host with Empty reply from server or Connection reset by peer, even though the port is published.

    WHY IT HAPPENS
    The program inside the container is bound to 127.0.0.1. The published port forwards traffic to the container's other interface, where nothing is listening.
    CHECK FIRST
    Run docker exec <container> ss -tlnp (or read the app's config) and bind to 0.0.0.0 inside the container.
  • OSError: [Errno 98] Address already in use or PermissionError: [Errno 13] Permission denied when starting a server.

    WHY IT HAPPENS
    Errno 98 means another process owns that port, often an old copy of the same server. Errno 13 on a port below 1024 means ordinary users may not bind privileged ports.
    CHECK FIRST
    Run ss -tlnp | grep <port> to see who owns it, then stop that process or choose a port above 1024.

When not to use this

  • A port number says what a program probably is, and it is only a convention. Nothing stops a database from listening on 8080, so confirm with ss -tlnp rather than assuming.
  • Binding to 0.0.0.0 is convenient and exposes the service on every interface. For something that only needs local access, such as a database used by one app, keep it on 127.0.0.1 or a private address.

Check yourself

What is the difference between listening and connecting?

A server listens on a fixed port and waits. A client picks a temporary port and connects out to the server's port.

Why can a service work from the same machine and fail from another one?

It may be bound to 127.0.0.1, which accepts only local connections. A firewall can also block it, which is covered later.

What does TCP give you that UDP does not?

A connection with ordered, complete delivery and resends of lost data. UDP just sends packets with no setup or guarantees.

Lesson 17 of 92 in the DevOps path

Search

Search cheat sheets and projects