Perlba...agement(3pm)

📦

version 1.80 · 6 versions

1.80 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing (latest)
1.80 · ubuntu stonking
1.80 · ubuntu jammy
1.80 · fedora 43
1.80 · fedora 44
1.80 · ubuntu resolute

, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

💖 Perlbal::Manual::Management(3pm) 💖

okay bestie, welcome to the Perlbal::Manual::Management page — it's a (3pm) manual from User Contributed Perl Documentation, and we're about to make managing Perlbal on-the-fly feel like a group chat with your favorite Unix bestie. 💅✨

NAME

Perlbal::Manual::Management — Managing Perlbal on-the-fly

VERSION

Perlbal 1.78. periodt.

DESCRIPTION

How to configure a Perlbal "management" service for on-the-fly configuration and debugging. it's giving remote control for your proxy vibes. 🦋

READ ME FIRST

Please read Perlbal::Manual::Configuration first for a better explanation on how to configure Perlbal. This document will make much more sense after reading that. fr fr, don't skip it. 📚

Setting up a management service

You can create a management service in the following way:

CREATE SERVICE mgmt
    SET role   = management
    SET listen = 127.0.0.1:16000
ENABLE mgmt

slay. now you have a management service listening on 127.0.0.1:16000. 💅

Consulting information with a browser

If you access the management service (in this case, 127.0.0.1 on port 16000) with a browser you'll reach a page with information on the services that are enabled. You're also able to click those services and reach further information on each of them. it's basically a lil dashboard, no cap. 🖥️✨

Managing Perlbal via telnet

If you telnet to the management service you get a connection that allows you manage your Perlbal's instance.

$ telnet 127.0.0.1 16000
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.

You now have access to several commands (which are case insensitive):

Admin Commands

create pool <name>, create service <name> — Creates a pool or a service. literally building new little hangout spots. 🎀 Examples:

create pool my_new_pool

create service my_new_service

disable <service> — Disables a service (stops listening). it's giving goodnight. 😴 Example:

disable my_service

Note that you can not disable "management" services. they're too powerful, bestie. 👑

enable <service> — Enables a service (starts listening). wake up bestie, we're listening again. 🌅 Example:

enable my_service

header <service> insert <header>:<value>, header <service> remove <header> — Inserts or removes headers from the request before they're passed on to the backend. it's giving header glow-up. ✨ When adding headers you must state the value:

header my_service insert x-myamazingheader:myamazingvalue

When removing headers you don't need the state any value, the header will be removed regardless of the value it holds:

header my_service remove Connection

Note: the usage of "x-" in the beginning of your header is not required, but the convention is that non-standard headers be prefixed with "x-". iykyk. 💅

load <plugin> — Loads a Perlbal plugin. plug it in, turn it on. 🔌 Example:

load AccessControl

plugins — Lists plugins. show me the plugins, bestie. 📋
pool <name> add <ip[:port]>, pool <name> remove <ip[:port]> — Allows you to add or remove nodes from a service. it's like managing your squad. 🫶 Examples:

pool add my_service 127.0.0.1:1337

pool remove my_service 127.0.0.1:1337

Note that adding a node that already exists or removing a non-existing node do not result in an error message. no drama, just vibes. 😌 Also note that the port number defaults to :80 if omitted.

reproxy_state — Dumps the state of reproxy status. it's giving reproxy receipts. 🧾 Example:

reproxy_state
SERVER max_reproxy_connections = 0

server <param> = <value> — Sets a server parameter, where param is one of:
- max_reproxy_connections = <value> — Maximum number of concurrent connections to the backends. don't overwhelm the backends, bestie. 🛑
- max_reproxy_connections("ip") = <value> — Maximum number of concurrent connections to one specific backend. one backend at a time, okay? 🎯
- max_connections = <value> — Sets the value of "RLIMIT_NOFILE" (maximum number of open files for this process). Requires BSD::Resource. Also, Perlbal must be run under a superuser. root energy required. 👑
- nice_level = <value> — Sets the "nice" level for the process. be nice, or don't. 😇
- aio_mode = <value> — One of "none", "linux" for Linux::AIO, or "ioaio" for IO::AIO. This controls how disk IO is done asynchronously. Highly recommended to use Linux::AIO or IO::AIO for webserving or reproxying files. For purely reverse proxy or only reproxying URLs, none is fine. it's giving async disk tea. 🍵
- aio_threads = <value> — Number of child threads doing disk IO. Use between 2 and 50. not too many, not too few. ⚖️
- track_obj = <value> — Developer option to track objects. for the devs, iykyk. 👩‍💻
- pidfile = <value> — Filename to write pidfile to (no pidfile if not specified). where the pid lives. 🏠
- crash_backtrace = <value> — 1 or 0 indicating whether to perform a backtrace while the server is crashing. crash detective mode. 🕵️‍♀️
set [<pool_name>] <param> = <value> — Sets a property on a pool. If the pool was just created, specifying the pool name is optional. flexible, we love that. 💅 Setting the file to autoload nodes from (Perlbal will periodically check the file for updates):

SET my_pool nodefile = /path/to/file

Unsetting the file to autoload nodes from (note that this does not remove current members):

SET my_pool nodefile = none

"undef", "null", "" and '' are interpreted just like "none". same vibe, different spelling. ✨ Note that manually modifying the pool (via POOL ADD or POOL REMOVE) will disable the periodic checking of the nodefile. so don't touch it manually if you want autoload. 🙈 Setting the load balancing method:

SET pool balance_method = 'random'

Yes, we do realize that "random" is the only method currently available, but hey. it's giving random is the moment. 🎲

set [<service_name>] <param> = <value> — Sets a property on a service. If the service was just created, specifying the service name is optional. See Perlbal::Manual::LoadBalancer, Perlbal::Manual::ReverseProxy and Perlbal::Manual::WebServer for the list of available parameters. go read those for the full menu. 📖
show service [<service_name>], show pool [<pool_name>] — List all services:

show service

Show details of a service:

show service my_service

Lists all pools, nodes and services using them:

show pool

Show the members of a pool:

show pool my_pool

it's giving inspection era. 🔍

shutdown [graceful] — Shuts down the server (you'll also lose your telnet session). bye bye telnet, bye bye server. 😭 Can be used instantly, killing all active connections:

shutdown

Using the parameter "graceful" listening sockets are closed and perlbal stays alive until clients bleed off.

shutdown graceful

graceful is the polite way to dip. 🫡

unload <plugin> — Unloads a plugin. take it out, we're done. 🚪 Example:

unload AccessControl

use <service>, use <pool> — Sets the implied service or pool for future operations. it's giving set it and forget it. 💅 For instance, after:

use my_pool

You can just type:

pool add 127.0.0.1:6000

Note that creating a service or pool also sets it as the implied service. so it's lowkey automatic. ✨

xs, xs [enable <module>], xs [disable <module>] — Show status of XS modules loaded:

xs

Turn on an already-loaded XS module:

xs enable module_name

Turn off an already-loaded XS module:

xs disable module_name

XS modules, but make it manageable. 🧚

Diagnostic Commands

aio — Shows Perlbal::AIO stats. 📊
backends — Lists the open connections to the backends. Example:

backends
127.0.0.1:3080 1
127.0.0.1:3081 2

In the above example, there are 3 open connections (they may be being used or they may simply be open according to the value of "connect_ahead"). three connections, just vibing. 🌈

dumpconfig — Shows the current configuration for each service. If a service uses a plugin that supports "dumpconfig", that plugin's configuration is also dumped (see "dumpconfig" under Perlbal::Manual::Plugins for more information). config dump, but make it thorough. 📝
fd — Shows the maximum number of file descriptors and how many are currently in use. Example:

fd
max 1024
cur 8

file descriptors: max 1024, cur 8. plenty of room. 🏠

gladiator — Requires Devel::Gladiator. Iterate's Perl's internal memory structures and can be used to enumerate all the currently live SVs. This can be used to hunt leaks and to profile memory usage. memory gladiator arena. ⚔️
help — Displays the list of available commands. when in doubt, help. 🆘
leaks, leaks <code> — Iterates over active objects. If an argument is specified, it is treated as code with $_ being the reference to the object. Shows objects that might have been leaked. leak hunt. 🕵️‍♀️
mime — Lists known mime types. Example:

mime
css text/css
doc application/msword
...

mime types, the OG content types. 🎀

node <ip[:port]> — Dumps information on a specific node. Example:

node 127.0.0.1:8181
127.0.0.1:8181 attempts 10
127.0.0.1:8181 lastattempt 1290461126

Calling "node" with a parameter is the same as calling "nodes". same energy. ✨

nodes — Dumps information on all nodes. Example:

nodes
127.0.0.1:8181 attempts 10
127.0.0.1:8181 lastattempt 1290461126
127.0.0.1:8081 connects 19
127.0.0.1:8081 lastconnect 1290461127
127.0.0.1:8081 attempts 19
127.0.0.1:8081 responsecodes 200 11
127.0.0.1:8081 lastattempt 1290461127

all the nodes, all the tea. 🍵

noverify — Shows the amount of time left for each node marked as noverify. If the "verify_backend" parameter is set to a true value, perlbal tries to send an "OPTIONS" command to a node before sending it the actual client request. If the node doesn't support the "OPTIONS" command, the node is added to an internal hash so that an "OPTIONS" command is not issued for new requests during the next 60 seconds. Example:

noverify
127.0.0.1:8081 42

In the above example, node 127.0.0.1:8081 is on that list and still has 42 seconds until an "OPTIONS" command is tried again. If the time is a negative value it means that the "OPTIONS" command will be issued before the next request. negative time, immediate vibe check. ⏳

obj — Shows objects count in scope. The environment variable "DEBUG_OBJ" must be set to a true value (see "Environment Variables" under Perlbal::Manual::Configuration for more information). object counting era. 🔢
pending — Shows pending backend connections by service, node, and age. pending connections, the waiting room. 🪑
proc — Shows CPU usage, current time, pid, and total requests processed. proc says: here's the CPU, time, pid, and request count. 📈
prof on, prof off, prof data — Enables/disables profiling or dumps profile data. profiling: on, off, or data. 🎛️
queues — Shows status of all queues (normal, high priority and low priority) for all enabled services. Example:

queues
service_mywebsite-normal.age 1
service_mywebsite-normal.count 8
service_mywebsite-highpri.age 0
service_mywebsite-highpri.count 0
service_mywebsite-lowpri.age 0
service_mywebsite-lowpri.count 0

queues: normal, high priority, low priority. the whole priority spectrum. 🌈

reload <plugin_name> — Reloads a plugin that supports reloading. reload goes brrr. 🔄
socks [all], socks summary — bestie, this one lists all your sockets, or gives you a lil summary of them. By default it lists all of them (so socks alone = socks all, iykyk). ✨

socks
   fd    age
    3   748s Perlbal::ClientManage(R): open to 85.245.86.253:52248
    4  1003s Perlbal::TCPListener(R): open: listening on 82.102.30.112:80 for service 'ws'
    6  1003s Perlbal::TCPListener(R): open: listening on 0.0.0.0:60000 for service 'mgmt'

socks summary
    1 Perlbal::ClientManage
    2 Perlbal::TCPListener
Aggregate write buffer: 0.0k
            Open files: 0

that Open files: 0 is giving "my fd table is immaculate" 💅

state changes — shows you the recent state changes of requests. 🦋

So like, while a request is mid-processing, this command might spit out something like:

state changes
Perlbal::ClientProxy=HASH(0x12d7ec28): reading_headers, wait_backend, backend_req_sent, wait_res
Perlbal::BackendHTTP=HASH(0x12d75f30): connecting, bored, sending_req, wait_res
wait_res 2

And the literal second the request finishes processing:

state changes
Perlbal::BackendHTTP=HASH(0x12d75f30): connecting, bored, sending_req, wait_res, xfer_res, closed
closed 1

Note: this whole functionality is lowkey dependent on the environment variable PERLBAL_TRACK_STATES being set to a true value. No env var, no state changes, periodt. 😭

states, states <service> — shows how many sockets of which type and in which state currently exist, for all services. 🌸

states
Perlbal::ClientProxy draining_res 1

If you pass a service, it shows you the info for that service only:

states ws
Perlbal::BackendHTTP wait_res 1
Perlbal::ClientProxy wait_res 1

track — dumps the objects being tracked, sorted by age. ⭐

track
15s Perlbal::HTTPHeaders=HASH(0x1a043a50): Perlbal::HTTPHeaders::clone, Perlbal::BackendHTTP::assign_client, Perlbal::Service::register_boredom, Perlbal::BackendHTTP::event_write, Danga::Socket::EpollEventLoop, (eval), Perlbal::run
15s Perlbal::HTTPHeaders=HASH(0x19594fe0): Perlbal::HTTPHeaders::new, Perlbal::Socket::read_headers, Perlbal::Socket::read_response_headers, Perlbal::BackendHTTP::event_read_waiting_options, Perlbal::BackendHTTP::event_read, Danga::Socket::EpollEventLoop, (eval), Perlbal::run
15s Perlbal::HTTPHeaders=HASH(0x1a043d80): Perlbal::HTTPHeaders::new, Perlbal::Socket::read_headers, Perlbal::Socket::read_response_headers, Perlbal::BackendHTTP::event_read, Danga::Socket::EpollEventLoop, (eval), Perlbal::run
15s Perlbal::BackendHTTP=HASH(0x1a044608): Perlbal::BackendHTTP::new, Perlbal::Service::spawn_backends, Perlbal::Service::note_bad_backend_connect, Perlbal::BackendHTTP::event_err, Danga::Socket::EpollEventLoop, (eval), Perlbal::run
15s Perlbal::BackendHTTP=HASH(0x1a042588): Perlbal::BackendHTTP::new, Perlbal::Service::spawn_backends, Perlbal::Service::note_bad_backend_connect, Perlbal::BackendHTTP::verify_failure, Perlbal::BackendHTTP::event_read_waiting_options, Perlbal::BackendHTTP::event_read, Danga::Socket::EpollEventLoop, (eval), Perlbal::run
15s Perlbal::BackendHTTP=HASH(0x1a044488): Perlbal::BackendHTTP::new, Perlbal::Service::spawn_backends, Perlbal::Service::request_backend_connection, Perlbal::ClientProxy::request_backend, Perlbal::ClientProxy::handle_request, Perlbal::ClientProxy::event_read, Danga::Socket::EpollEventLoop, (eval), Perlbal::run

For this to even work you need the environment variable DEBUG_OBJ set to a true value and the server option track_obj turned on, like so:

server track_obj = 1
OK

two keys to the same door, bestie. both or nothing. 🔑

uptime, version — shows the time the server was started, the current uptime, and Perlbal's version. Three-for-one, iconic. 👑
varsize — a debug management command to track the size of internal data structures. 🔥

varsize
svc-ws-bored_backends [] 2
svc-ws-pending_connects {} 2
  {127.0.0.1:3080}  =
  {127.0.0.1:3081}  = Perlbal::BackendHTTP=HASH(0x1cfd2490)

verbose on, verbose off — turns verbose mode on or off. 🎀

verbose on
load AccessControl
OK
verbose off
load AccessControl
verbose on
OK
load AccessControl
OK

Yes, fr fr — verbose mode only activates the printing of an OK message upon completion of some commands, such as load. Errors get displayed regardless of verbose status. Errors are not shy, bestie, they will find you. 💀

🫶 CAVEAT 🫶

Not me having to tell you this, but — this functionality doesn't implement any sort of authentication. If you can telnet to the address you specify, you can access the information and change things on the fly. That's the whole caveat, no cap. 😭

Some alternatives to authentication are commonly employed:

specifying the address as being 127.0.0.1 means that no one outside the machine can telnet to the management service; 🔒
setting the management address as a private IP available only through a VPN, for instance, will allow you to manage these accesses on the VPN instead. 🌈

🌸 SEE ALSO 🌸

Perlbal::Manual::Configuration, Perlbal::Manual::Debugging.

and that's the whole page, bestie 💖 this one came from perl v5.34.0 and it's dated 2022-06-28 — go forth and manage your sockets responsibly, mwah 🎀✨

📦 where this page comes from

debian bookworm: libperlbal-perl 1.80-4 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libperlbal-perl 1.80-4 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libperlbal-perl 1.80-4 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu questing: libperlbal-perl 1.80-4
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms