Ports and processes

Ports and processes

Not every port on a machine came from a registry. These two commands look at what the operating system actually reports, and neither needs a warden running anywhere — they read the machine directly.

What is listening

$ warden ports
PORT   PROTO  PROCESS       PID    USER    ADDRESS    WARDEN
135    tcp    svchost.exe   1812   -       0.0.0.0    -
3000   tcp    node.exe      25084  dev     0.0.0.0    -
5432   tcp    postgres.exe  7712   dev     0.0.0.0    -
8000   tcp    python.exe    14204  dev     127.0.0.1  shop-api

The WARDEN column is the useful one. It names the service when the port came from the registry, so anything showing - arrived some other way — started by hand, left over from last week, or a container.

Narrow it down:

warden ports --port 3000     # one port
warden ports --no-udp        # TCP only
warden ports --json          # for scripts

Free a port

$ warden kill 3000
Stop node.exe (25084) on port 3000? [y/N]: y
stopped node.exe (25084)

The number is a port by default, because that is what a person knows. Use --pid when you mean a process id:

warden kill 25084 --pid

Flag	Effect
--yes, -y	Do not ask first
--force	Kill it outright if it will not stop politely
--pid	Read the number as a process id, not a port

Without --force, warden asks the process to stop and waits five seconds. A process that ignores that is reported, not killed:

node.exe (25084) ignored the request to stop - pass --force to kill it

What it will not do

Two things are refused however the request arrives:

• the operating system's own processes (pids 0 to 4)
• warden itself

Everything else is fair game, subject to what your account is allowed to touch.

Sockets you cannot see

A socket owned by another user shows up without a process name:

PORT   PROTO  PROCESS  PID  USER  ADDRESS  WARDEN
49152  tcp    unknown  -    -     0.0.0.0  -

That is normal, not a fault. The operating system does not hand over another user's process details to an ordinary account. warden says how many are hidden:

3 of 42 belong to another user - run warden as administrator to see them

Run it elevated (administrator on Windows, sudo on Linux) if you need those rows.

macOS is stricter than either. It will not let an unprivileged process enumerate sockets at all, so warden ports, the dashboard's ports view, warden ls --holders and warden reap need sudo there and say so plainly when they do not have it:

this system will not list sockets for your user - run warden as administrator to see them

Nothing else is affected. Handing out ports, the fleet, events, warden apply and warden export never read the socket table: warden binds a port to test it, which needs no privileges, and only listing is refused.

Across a fleet

$ warden ports --all --url http://hub:7010
NODE      PORT  PROTO  PROCESS       PID    USER  ADDRESS    WARDEN
build-01  9000  tcp    python.exe    4471   dev   127.0.0.1  build-runner
hub       3000  tcp    node.exe      25084  dev   0.0.0.0    -

A port number means nothing on its own across machines: 3000 on two nodes is two unrelated processes, and the NODE column is what tells them apart. Stopping one goes to the machine it is on, and that machine keeps its own WARDEN_ALLOW_KILL.

In the dashboard, with no warden at all

warden tui opens on the registered services, and tab swaps to the ports. If no warden is running, the ports view still works: it reads the machine directly, says this machine, no warden running in the subtitle, and d stops a process exactly as warden kill would. Only the WARDEN column goes blank, since naming the service behind a port is the one part that needs a registry.

Over HTTP

The same two things exist on the API, for a warden you are talking to over the network — they then describe that machine, not yours:

curl localhost:7010/v1/listeners

Stopping a process through the API is off unless you switch it on:

WARDEN_ALLOW_KILL=true warden serve

The reason is worth stating: a warden reachable from the network would otherwise let anyone holding the token end processes on that machine, which is a far bigger thing to hand out than a port number. warden kill on the command line is not affected — it acts locally and never asks the API.