PENCTL(1)

💖 penctl(1) — the control a running pen load balancer era 💖

okay bestie, gather round, because this is the General Commands Manual page for penctl, and it is lowkey the remote control for your pen load balancer. yes, the whole thing. no cap.

✨ SYNOPSIS ✨

penctl host:port|/path/to/socket command

🌸 EXAMPLE 🌸

penctl lbhost:8888 roundrobin

Turns off client tracking on the load balancer running on lbhost. (yes, that's what roundrobin does here. it's giving "turning things off by asking for them", we love a plot twist 💅)

penctl /var/run/pen/tmp/ctrl status

Prints status information in html format. iconic behaviour, honestly.

🦋 DESCRIPTION 🦋

So. penctl connects to the optional control socket on a pen load balancer. That's the whole vibe. It reads commands from the command line, does a lil minimal syntax checking (she's not your mom, she's not validating everything), and sends them off to pen. Replies, if there are any, get printed on stdout. periodt.

The program can also be used through the cgi script penctl.cgi, which allows pen to be controlled from any web browser. browser-based load balancer control, main character energy fr fr 🌈

✨ OPTIONS ✨

• host:port — specifies a control port where the load balancer listens for commands. that's it, that's the option, she's a one-option icon 👑

🎀 COMMANDS 🎀

okay this is the big one. every single command, no skipping, bestie. buckle up 🫶

• abort_on_error — Call abort() when a fatal error is encountered. This will create a core file which allows further troubleshooting. Disabled by default.
• no abort_on_error — Exit normally on fatal error with an error code which indicates failure.
• acl N permit|deny sourceip4 [mask] — Adds an entry to access list N, where N is a number from 0 to 9. The source and mask addresses are in the usual dotted quad notation. If mask is omitted, it defaults to 255.255.255.255.
• acl N permit|deny sourceip6[/length] — If the source address contains the character ':', the address is interpreted as IPv6. Unlike IPv4 access entries, a length is used to indicate the mask. If length is omitted, it defaults to 128.
• acl N permit|deny country NN — If the source address is the special word "country", a two-letter country code can be used to restrict access to the load balancer. For this to work, pen must be built with geoip support. 🌍
• no acl N — Deletes all entries from access list N. The resulting access list permits all traffic. (everyone's invited now, party's open 💀)
• ascii — Communication dumps in ascii format (cf option -a).
• no ascii — Communication dumps in hex format.
• blacklist — Return current blacklist time in seconds.
• blacklist T — Set the blacklist time in seconds.
• block — Do not make sockets nonblocking. This is obsolete as of 0.26.0 and does nothing. (she's retired, let her rest 😭)
• no block — Make sockets nonblocking.
• client_acl N — Check connecting clients against access list N (default 0).
• clients_max [N] — With argument, increase the maximum number of known clients. Returns max number of clients.
• close N — Close connection N
• connection N — Display some basic information about connection N.
• conn_max [N] — With argument, increase the max number of simultaneous connections. Returns max number.
• control — Return address and port where pen listens for control connections.
• control_acl N — Check accesses to the control port against access list N (default 0).
• debug — Return current debug level.
• debug N — Set debug level to N.
• delayed_forward — Always wait for the next round of the main loop before forwarding data. Normally pen tries to do that immediately. This is obsolete as of 0.26.0 and does nothing.
• no delayed_forward — Try to forward data immediately, to avoid the overhead of copying it to a temporary buffer and waiting for the next main loop round.
• dsr_if IF — Use IF as the interface for Direct Server Return.
• dummy — Act as a dummy web server with very limited functionality but high performance. Only useful for testing. Disabled by default.
• no dummy — Do not act as a dummy web server.
• epoll — Use epoll for event management (Linux). This is the default on Linux.
• exit — Exit. Only available if pen was started with the -X option.
• hash — Use a hash on the client IP address for initial server selection.
• no hash — Do not use a hash.
• http — Add X-Forwarded-For headers to http requests.
• no http — Do not add X-Forwarded-For headers.
• idle_timeout N — Close connections that have been inactive for N seconds. Default 0 = never close.
• idlers [N] — Create N reliable idle connections to the backend servers. Without argument, display the current/requested number of reliable idlers.
• include FILE — Read commands from file.
• kqueue — Use kqueue for event management (FreeBSD, NetBSD, OpenBSD). This is the default on the systems that have it.
• listen — Return local address and port pen listens to for incoming client connections.
• listen [address:]:port — Close the listening socket and reopen using specified address (optional) and port.
• log — Show where pen is logging, if anywhere.
• log FILE — Log to FILE.
• mode — Write a summary of the current mode of operation. The listed modes are block, delayed_forward, hash, roundrobin, stubborn.
• no log — Turn off logging.
• pending_max N — Max allowed number of pending nonblocking connections. Default 100, minimum 1.
• pid — Return the process id of the running daemon.
• poll — Use poll for event management.
• prio — Use the priority based algorithm.
• no prio — Do not use the priority based algorithm.
• recent [N] — Shows which clients have connected in the last N seconds (default 300).
• roundrobin — Use round-robin server selection without client tracking
• no roundrobin
• select — Use select for event management.
• server N [ acl A | address A | port P | max M | hard H | blacklist T | weight W | prio P ] — Change acl, address, port, weight, priority and/or max connections for server N, or blacklist it for T seconds.
• servers — List address, port, weight, priority and max number of simultaneous connections for each remote server.
• socket N — Show to which connection socket N belongs.
• source IP — Set the local address to IP for upstream connections, i.e. where Pen connects to backend servers.
• ssl_ciphers CIPHERS — Choose list of available SSL ciphers, specified in the format described in https://www.openssl.org/docs/apps/ciphers.html.
• ssl_client_renegotiation_interval S — Allowing the client to request renegotiation is a potential denial of service vector. This command specifies the minimum number of seconds the client has to wait between requests for renegotiation requests. Default 3600 = effectively disabled.
• ssl_ocsp_response FILENAME — Specifies the location of a file containing a pre-fetched OCSP response. The file must be refreshed regularly by a cron job or similar and the ssl_ocsp_response command repeated to make Pen re-read the file..
• ssl_option OPTION — Manipulate SSL options. The available options are no_sslv2, no_sslv3, no_tlsv1, no_tlsv1.1, no_tlsv1.2, cipher_server_preference. Use the command multiple times to specify multiple options.
• ssl_sni_path PATH — This command enables the Server Name Indication TLS extension by specifying a directory where domain.key, domain.crt and domain.ca files can be found.
• status — Print status information in html format.
• stubborn — If the initial server selection is unavailable, close the client connection without trying another
• no stubborn
• tarpit_acl [N] — Used in DSR mode. If N is an existing access list, Pen will reply to ARP requests for IP addresses that match the access list, and reply with SYN+ACK to TCP SYN requests to these addresses. The result is that someone trying to scan a network will be slowed down by a large number of false positives. (trap them, bestie 🕸️)
• tcp_fastclose up|down|both|off — Close both sockets to upstream and downstream if one of them closes theirs. Default = off.
• tcp_nodelay — Set TCP_NODELAY on sockets, effectively turning off the Nagle algorithm.
• no tcp_nodelay — Do not set TCP_NODELAY on sockets. This is the default.
• timeout — Return current connect timeout in seconds.
• timeout N — Set connect timeout to N seconds.
• tracking N — Set tracking time, i.e. how long clients will be remembered. The default 0 will never expire clients based on time.
• transparent — On compatible platforms, use the client's address as source address in the connection to the backend server.
• no transparent — Use Pen's address as source address in the connection to the backend server.
• web_stats — Return file name of html status reports, if any.
• web_stats FILE — Set the name of html status reports.
• no web_stats — Do not generate html status reports.
• weight — Use weight for server selection.
• no weight — Do not use weight for server selection.
• write [FILE] — Write the current configuration into a file which can be used to start pen. If FILE is omitted, the configuration is written into pen's original configuration file.

bestie note: some of these are marked obsolete (block, delayed_forward) and some have defaults that will absolutely surprise you. read before you yeet 💅

💜 SEE ALSO 💜

• pen(1)

👑 AUTHOR 👑

Copyright (C) 2002-2015 Ulric Eriksson, <ulric@siag.nu>.

okay so that's the whole page, and yes you read all of it, we're so proud 🥹 this was the LOCAL section of the manual, for PENCTL(1) — go forth and control your load balancer, you absolute icon 🦋✨💖