PEN(1)

okay bestie, welcome to pen(1) 💖

This one lives in the General Commands Manual, and it's the whole "make a bunch of servers look like one server" situation. Buckle up, it's giving infrastructure main character energy. 👑

---

✨ NAME ✨

pen — load balancer for udp and tcp based protocols

---

🌸 SYNOPSIS 🌸

pen [-b sec] [-c N] [-e host:port] [-t sec] [-x N] [-j dir] [-u user]
[-F cfgfile] [-l logfile] [-p file ] [-w file] [-C port|/path/to/socket]
[-T sec] [-UHWXadfhrs] [-o option] [-E certfile] [-K keyfile] [-G
cacertfile] [-A cacertdir] [-Z] [-R] [-L protocol]
[host:]port|/path/to/socket h1[:p1[:maxc1[:hard1[:weight1[:prio1]]]]]
[h2[:p2[:maxc2[:hard2[:weight2[:prio2]]]]]] ...

Windows only:

pen -i service_name

pen -u service_name

---

🦋 EXAMPLE 🦋

pen 80 www1:8000:10 www2:80:10 www3

So picture this: three servers being besties in a web server farm. www1 is running its web server on port 8000 and will accept a max of 10 simultaneous connections. www2 runs on port 80 and also accepts 10 connections. And www3? Runs its web server on port 80 and says "unlimited connections, idc, bring everyone" — literally no cap. 💅

---

💜 DESCRIPTION 💜

Pen is a load balancer for udp and tcp based protocols like dns, http or smtp. It makes several servers show up as one single thing to the outside world, it automatically sniffs out servers that are down, and it spreads clients across whichever servers are still standing. The result: high availability and scalable performance. Obsessed, honestly. ✨

The load balancing algorithm remembers clients and tries to send each one back to the server it visited last time. The client table has a bunch of slots — default 2048, and you can set that with command-line arguments. When the table gets full, the least recently used entry gets yeeted out to make room for the new one. 🫶

This is way better than a plain round-robin algorithm, which would send a client that keeps reconnecting to a different server every time. That breaks applications that maintain state between connections on the server — and yes, that includes most modern web applications. So like, don't do that. 😭

When pen notices a server is unavailable, it scans for another one, starting with the server after the most recently used one. And that's how you get load balancing and "fair" failover for free. Iconic behaviour.

Configured correctly, pen can keep a server farm always available, even when individual servers get brought down for maintenance or reconfiguration. The one last single point of failure — pen itself — can be eliminated by running pen on several servers and using vrrp to decide which one is active. No single point of failure, no problem. 💪

Send pen a USR1 signal and it'll print some useful statistics on stderr, even if debugging is turned off. If pen is running in the background (i.e. without the -f option), then syslog is used instead of stderr. And if the -w option is in play, that statistics gets saved in HTML format in the given file. Cute AND functional. 🎀

Send pen a HUP signal and it'll close and reopen the logfile (if logging is enabled) and reload the configuration file.

Wanna rotate the log? Do it like this (assuming pen.log is the name of the logfile):

mv pen.log pen.log.1 kill -HUP `cat <pidfile>`

where <pidfile> is the file containing pen's process id, as written by the -p option. 🗂️

Send pen a TERM signal and it exits cleanly, closing the log file and all open sockets. A polite queen. 👑

---

💅 OPTIONS 💅

• -C port|/path/to/socket — says where the load balancer listens for commands, i.e. the control port. Peep penctl.1 for the list of commands available. Heads up: the protocol is unauthenticated, and the administrator is expected to lock it down using an access control list (for connections over a network) or Unix file permissions (for a Unix domain socket). Pen will normally refuse to open the control port if running as root — see the -u option. And if you still insist on running pen as root with a control port, use "-u root". Don't say nobody warned you. 🙈
• -F cfgfile — names a configuration file full of commands in penctl format (see penctl.1). It gets read after all command line arguments are processed, and again after receiving a HUP signal.
• -H — adds an X-Forwarded-For header to http requests.
• -U — use udp protocol support.
• -O command — lets most penctl commands be used right on the Pen command line.
• -P — use poll() for event notification.
• -W — use weight for server selection.
• -X — adds an exit command to the control interface.
• -a — used together with -dd to get communication dumps in ascii rather than hexadecimal format.
• -b sec — servers that don't respond get blacklisted (i.e. excluded from the server selection algorithm) for the specified number of seconds. Default is 30.
• -T sec — clients are tracked for the specified number of seconds so they can be sent to the same server as last time. Default is 0 = never expire clients.
• -c N — max number of clients. Default 2048.
• -d — debugging (repeat -d for more). Output goes to stderr if we're running in the foreground (see -f), and to syslog (facility user, priority debug) otherwise.
• -e host:port — host:port specifies the emergency server to contact if all the regular servers become unavailable. The backup bestie. 🚨
• -f — stay in the foreground.
• -h — use a hash on the client IP address for the initial server selection. This makes it more predictable where clients will be connected.
• -i service_name — Windows only. Install pen as a service.
• -j dir — run in a chroot environment.
• -l file — turn on logging.
• -m multi_accept — accept up to multi_accept incoming connections at a time.
• -p file — write the pid of the running daemon to file.
• -q backlog — allow the queue of pending incoming connections to grow up to a maximum of backlog entries.
• -r — go straight into round-robin server selection without looking up which server a client used the last time.
• -s — stubborn server selection: if the initial choice is unavailable, the client connection is closed without trying another server. She said what she said. 💀
• -t sec — connect timeout in seconds. Default 5.
• -u user — Posix only. Run as a different user.
• -u service_name — Windows only. Uninstall the service.
• -x N — max number of simultaneous connections. Default 500.
• -w file — file for status reports in HTML format.
• -o option — use option in penctl format.
• -E certfile — use the given certificate in PEM format.
• -K keyfile — use the given key in PEM format (it may be contained in the cert).
• -G cacertfile — file containing the CA's certificate.
• -A cacertdir — directory containing CA certificates in hashed format.
• -Z — use SSL compatibility mode.
• -R — require a valid peer certificate.
• -L protocol — ssl23 (default), ssl3 or tls1.
• [host:]port OR /path/to/socket — the local address and port pen listens to. By default pen listens to all local addresses. Pen can also use a Unix domain socket as the local listening address.
• h1:p1:soft:hard:weight:prio — the address, port and maximum number of simultaneous connections for a remote server. By default the port is the same as the local port, and the soft limit on the number of connections is unlimited. The hard limit is used for clients which have accessed the server before. The weight and prio are used for the weight- and priority-based server selection algorithms.

---

😭 LIMITATIONS 😭

Pen runs in a single process, and opens two sockets for each connection. Depending on kernel configuration, pen can run out of file descriptors. So like, watch your ulimit, bestie.

SSL support is available if pen was built with the --with-ssl option.

GeoIP support is available if pen was built with the --with-geoip option.

---

🫶 SEE ALSO 🫶

penctl(1), dwatch(1), mergelogs(1), webresolve(1)

---

👑 AUTHOR 👑

Copyright (C) 2001-2016 Ulric Eriksson, <ulric@siag.nu>.

---

🌈 ACKNOWLEDGEMENTS 🌈

In part inspired by balance by Thomas Obermair. Credit where credit is due, periodt. 💖

---

and that's the whole thing, bestie ✨ this was the LOCAL edition of pen(1) from the General Commands Manual — go forth and balance those loads, you absolute icon 🎀🦋💅