Lesson 2 of 8 in Networking for DevOps
Ports, TCP and UDP
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
- 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.
- Client to Server IP: 1 connect to IP:80
- Server IP to Web server: 2 port 80 goes here
- 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.
- 1Make an empty practice folder
mkdir -p ~/net-lab && cd ~/net-lab
Keep using this folder for the rest of the topic.
- 2Listen on localhost only (terminal A)
python3 -m http.server 8000 --bind 127.0.0.1
- 3Inspect the listening socket (terminal B)
ss -tlnp | grep 8000
The flags mean TCP, listening, numeric ports and the owning process. Find the
LISTENstate and the local address127.0.0.1:8000. On macOS uselsof -nP -iTCP:8000 -sTCP:LISTEN. - 4Connect as a client
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/You should see
200
- 5Cause 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. - 6Change the bind address
python3 -m http.server 8000 --bind 0.0.0.0
Stop the first server before you run this.
ss -tlnp | grep 8000now shows0.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 serverorConnection 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 to0.0.0.0inside the container.
OSError: [Errno 98] Address already in useorPermissionError: [Errno 13] Permission deniedwhen 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 -tlnprather than assuming. - Binding to
0.0.0.0is 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 on127.0.0.1or 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.
Keep going
Lesson 17 of 92 in the DevOps path