PORTSERVER.PY(1)

💖 PORTSERVER.PY — portserver.py, section 1 of the manual (User Commands) 💖

okay bestie, sit down, hydrate, and let me tell you about the little daemon that hands out port numbers like they're friendship bracelets 🎀

✨ NAME ✨

portserver.py — a server to hand out unused port numbers. that's it. that's the whole job. and it ATE. 👑

---

🌸 SYNOPSIS 🌸

usage: portserver.py [-h] [--portserver_static_pool PORTSERVER_STATIC_POOL]
                     [--portserver_address PORTSERVER_ADDRESS] [--verbose]
                     [--debug]

🦋 DESCRIPTION 🦋

so the description section is basically the usage line again (the man page said it, not me), and then we get into the good stuff.

✨ options ✨

here's the whole menu, no skips, no crumbs:

• -h, --help — shows this help message and then dips. classic. 💅
• --portserver_static_pool PORTSERVER_STATIC_POOL — a comma separated list of N-P range(s) of ports that you want it to manage, and yes the range is inclusive (both ends included, generous queen). 💖
• --portserver_address PORTSERVER_ADDRESS, --portserver_unix_socket_address PORTSERVER_ADDRESS — the address of the AF_UNIX socket it should listen on when you're on Unix (where a first @ means a NUL), OR the name of the pipe on Windows (where a first @ is the \\.\pipe\ prefix). two flags, one argument name, same vibe. 🫶
• --verbose — turns on verbose messages. it will talk to you more. 🗣️
• --debug — turns on FULL debug messages. it will tell you everything. no secrets. 💀

---

👑 PORT SERVER 👑

okay so here's the lore. a port server is meant to be run as a daemon, for use by every single process running on the host. it coordinates the use of network ports by anything that's using a portpicker library. if you're using hosts as part of a test automation cluster, then every single one of those hosts should be running a port server as a daemon. and listen — you should set the PORTSERVER_ADDRESS=@unittest-portserver environment variable on ALL of your test runners so that portpicker actually makes use of it. iykyk. ✨

here's how it works, step by step, main character energy:

a port server listens on a unix socket, reads a pid from a new connection, tests the ports it is managing, and then replies with a port assignment port for that pid. 🎀

and the important bit: a port is only reclaimed for potential reassignment to another process after the process it was originally assigned to has died. gone. deceased. resting. 💀

processes that need multiple ports can just... issue multiple requests, and they are guaranteed that each one will be unique. slay. no overlap, no drama. 🌈

---

🍓 TYPICAL USAGE 🍓

1. run one instance of this process on each of your unittest farm hosts. every single one. don't be stingy. 💅
2. set the PORTSERVER_ADDRESS environment variable in your test runner environment so the portpicker library knows to use a port server rather than trying to find ports all on its own. give it a little guidance bestie 🧚

$ /path/to/portserver.py &
$ export PORTSERVER_ADDRESS=@unittest-portserver
$ # ... launch a bunch of unittest runners using portpicker ...

like. look at that. three lines and your whole farm is vibing. 🔥

---

ok real talk though: that & at the end of the first line is doing a LOT of work — it's what makes it a daemon situation, so don't forget it. 😭

---

that's the whole page, bestie — you're officially port-pilled. go forth and never guess a port number again. 💜

this iconic little number is portserver.py version 1.6.0, dated October 2024, and it lives in section 1 of the manual (User Commands). bye babes, see you in the socket 🫶✨🎀