1Perlbal::Manual::ManageUmseenrt(C3o)ntributed Perl DocumPeenrtlabtailo:n:Manual::Management(3)
2
6 Perlbal::Manual::Management - Managing Perlbal on-the-fly
7 VERSION
9 Perlbal 1.78.
10 DESCRIPTION
12 How to configure a Perlbal "management" service for on-the-fly
13 configuration and debugging.
14 READ ME FIRST
16 Please read Perlbal::Manual::Configuration first for a better
17 explanation on how to configure Perlbal. This document will make much
18 more sense after reading that.
19 Setting up a management service
21 You can create a management service in the following way:
22 CREATE SERVICE mgmt
24 SET role = management
25 SET listen = 127.0.0.1:16000
26 ENABLE mgmt
27 Consulting information with a browser
29 If you access the management service (in this case, 127.0.0.1 on port
31 16000) with a browser you'll reach a page with information on the
32 services that are enabled. You're also able to click those services and
33 reach further information on each of them.
34 Managing Perlbal via telnet
36 If you telnet to the management service you get a connection that
38 allows you manage your Perlbal's instance.
39 $ telnet 127.0.0.1 16000
41 Trying 127.0.0.1...
42 Connected to 127.0.0.1.
43 Escape character is '^]'.
44 You now have access to several commands (which are case insensitive):
46 Admin Commands
48 create pool <name>
50 create service <name>
51 Creates a pool or a service.
52 create pool my_new_pool
54 create service my_new_service
56 disable <service>
58 Disables a service (stops listening).
59 disable my_service
61 Note that you can not disable "management" services.
63 enable <service>
65 Enables a service (starts listening).
66 enable my_service
68 header <service> insert <header>:<value>
70 header <service> remove <header>
71 Inserts or removes headers from the request before they're passed
72 on to the backend.
73 When adding headers you must state the value:
75 header my_service insert x-myamazingheader:myamazingvalue
77 When removing headers you don't need the state any value, the
79 header will be removed regardless of the value it holds:
80 header my_service remove Connection
82 Note: the usage of "x-" in the beginning of your header is not
84 required, but the convention is that non-standard headers be
85 prefixed with "x-".
86 load <plugin>
88 Loads a Perlbal plugin.
89 load AccessControl
91 plugins
93 Lists plugins
94 pool <name> add <ip[:port]>
96 pool <name> remove <ip[:port]>
97 Allows you to add or remove nodes from a service.
98 pool add my_service 127.0.0.1:1337
100 pool remove my_service 127.0.0.1:1337
102 Note that adding a node that already exists or removing a non-
104 existing node do not result in an error message.
105 Also note that the port number defaults to :80 if omitted.
107 reproxy_state
109 Dumps the state of reproxy status.
110 reproxy_state
112 SERVER max_reproxy_connections = 0
113 server <param> = <value>
115 Sets a server parameter, where param is one of:
116 · max_reproxy_connections = <value>
118 Maximum number of concurrent connections to the backends.
120 · max_reproxy_connections("ip") = <value>
122 Maximum number of concurrent connections to one specific
124 backend.
125 · max_connections = <value>
127 Sets the value of "RLIMIT_NOFILE" (maximum number of open
129 files for this process).
130 Requires BSD::Resource. Also, Perlbal must be run under a
132 superuser.
133 · nice_level = <value>
135 Sets the "nice" level for the process.
137 · aio_mode = <value>
139 One of "none", "linux" for Linux::AIO, or "ioaio" for
141 IO::AIO.
142 This controls how disk IO is done asynchronously. Highly
144 recommended to use Linux::AIO or IO::AIO for webserving or
145 reproxying files. For purely reverse proxy or only
146 reproxying URLs, none is fine.
147 · aio_threads = <value>
149 Number of child threads doing disk IO. Use between 2 and
151 50.
152 · track_obj = <value>
154 Developer option to track objects.
156 · pidfile = <value>
158 Filename to write pidfile to (no pidfile if not specified).
160 · crash_backtrace = <value>
162 1 or 0 indicating whether to perform a backtrace while the
164 server is crashing.
165 set [<pool_name>] <param> = <value>
167 Sets a property on a pool. If the pool was just created, specifying
168 the pool name is optional.
169 Setting the file to autoload nodes from (Perlbal will periodically
171 check the file for updates):
172 SET my_pool nodefile = /path/to/file
174 Unsetting the file to autoload nodes from (note that this does not
176 remove current members):
177 SET my_pool nodefile = none
179 "undef", "null", "" and '' are interpreted just like "none".
181 Note that manually modifying the pool (via POOL ADD or POOL REMOVE)
183 will disable the periodic checking of the nodefile.
184 Setting the load balancing method:
186 SET pool balance_method = 'random'
188 Yes, we do realize that "random" is the only method currently
190 available, but hey.
191 set [<service_name>] <param> = <value>
193 Sets a property on a service. If the service was just created,
194 specifying the service name is optional.
195 See Perlbal::Manual::LoadBalancer, Perlbal::Manual::ReverseProxy
197 and Perlbal::Manual::WebServer for the list of available
198 parameters.
199 show service [<service_name>]
201 show pool [<pool_name>]
202 List all services:
203 show service
205 Show details of a service:
207 show service my_service
209 Lists all pools, nodes and services using them:
211 show pool
213 Show the members of a pool:
215 show pool my_pool
217 shutdown [graceful]
219 Shuts down the server (you'll also lose your telnet session).
220 Can be used instantly, killing all active connections:
222 shutdown
224 Using the parameter "graceful" listening sockets are closed and
226 perlbal stays alive until clients bleed off.
227 shutdown graceful
229 unload <plugin>
231 Unloads a plugin.
232 unload AccessControl
234 use <service>
236 use <pool>
237 Sets the implied service or pool for future operations.
238 For instance, after:
240 use my_pool
242 You can just type:
244 pool add 127.0.0.1:6000
246 Note that creating a service or pool also sets it as the implied
248 service.
249 xs
251 xs [enable <module>]
252 xs [disable <module>]
253 Show status of XS modules loaded:
254 xs
256 Turn on an already-loaded XS module:
258 xs enable module_name
260 Turn off an already-loaded XS module:
262 xs disable module_name
264 Diagnostic Commands
266 aio Shows Perlbal::AIO stats.
268 backends
270 Lists the open connections to the backends.
271 backends
273 127.0.0.1:3080 1
274 127.0.0.1:3081 2
275 In the above example, there are 3 open connections (they may be
277 being used or they may simply be open according to the value of
278 "connect_ahead").
279 dumpconfig
281 Shows the current configuration for each service.
282 If a service uses a plugin that supports "dumpconfig", that
284 plugin's configuration is also dumped (see "dumpconfig" under
285 Perlbal::Manual::Plugins for more information).
286 fd Shows the maximum number of file descriptors and how many are
288 currently in use.
289 fd
291 max 1024
292 cur 8
293 gladiator
295 Requires Devel::Gladiator.
296 Iterate's Perl's internal memory structures and can be used to
298 enumerate all the currently live SVs.
299 This can be used to hunt leaks and to profile memory usage.
301 help
303 Displays the list of available commands.
304 leaks
306 leaks <code>
307 Iterates over active objects.
308 If an argument is specified, it is treated as code with $_ being
310 the reference to the object.
311 Shows objects that might have been leaked.
313 mime
315 Lists known mime types.
316 mime
318 css text/css
319 doc application/msword
320 ...
321 node <ip[:port]>
323 Dumps information on a specific node.
324 node 127.0.0.1:8181
326 127.0.0.1:8181 attempts 10
327 127.0.0.1:8181 lastattempt 1290461126
328 Calling "node" with a parameter is the same as calling "nodes".
330 nodes
332 Dumps information on all nodes.
333 nodes
335 127.0.0.1:8181 attempts 10
336 127.0.0.1:8181 lastattempt 1290461126
337 127.0.0.1:8081 connects 19
338 127.0.0.1:8081 lastconnect 1290461127
339 127.0.0.1:8081 attempts 19
340 127.0.0.1:8081 responsecodes 200 11
341 127.0.0.1:8081 lastattempt 1290461127
342 noverify
344 Shows the amount of time left for each node marked as noverify.
345 If the "verify_backend" parameter is set to a true value, perlbal
347 tries to send an "OPTIONS" command to a node before sending it the
348 actual client request. If the node doesn't support the "OPTIONS"
349 command, the node is added to an internal hash so that an "OPTIONS"
350 command is not issued for new requests during the next 60 seconds.
351 noverify
353 127.0.0.1:8081 42
354 In the above example, node 127.0.0.1:8081 is on that list and still
356 has 42 seconds until an "OPTIONS" command is tried again.
357 If the time is a negative value it means that the "OPTIONS" command
359 will be issued before the next request.
360 obj Shows objects count in scope.
362 The environment variable "DEBUG_OBJ" must be set to a true value
364 (see "Environment Variables" under Perlbal::Manual::Configuration
365 for more information).
366 pending
368 Shows pending backend connections by service, node, and age.
369 proc
371 Shows CPU usage, current time, pid, and total requests processed.
372 prof on
374 prof off
375 prof data
376 Enables/disables profiling or dumps profile data.
377 queues
379 Shows status of all queues (normal, high priority and low priority)
380 for all enabled services.
381 queues
383 service_mywebsite-normal.age 1
384 service_mywebsite-normal.count 8
385 service_mywebsite-highpri.age 0
386 service_mywebsite-highpri.count 0
387 service_mywebsite-lowpri.age 0
388 service_mywebsite-lowpri.count 0
389 reload <plugin_name>
391 Reloads a plugin that supports reloading.
392 socks [all]
394 socks summary
395 Lists all sockets or shows a summary of the sockets (by default
396 lists all sockets).
397 socks
399 fd age
400 3 748s Perlbal::ClientManage(R): open to 85.245.86.253:52248
401 4 1003s Perlbal::TCPListener(R): open: listening on 82.102.30.112:80 for service 'ws'
402 6 1003s Perlbal::TCPListener(R): open: listening on 0.0.0.0:60000 for service 'mgmt'
403 socks summary
405 1 Perlbal::ClientManage
406 2 Perlbal::TCPListener
407 Aggregate write buffer: 0.0k
408 Open files: 0
409 state changes
411 Lists recent state changes of requests.
412 For instance, while a request is being processed this command may
414 issue something like:
415 state changes
417 Perlbal::ClientProxy=HASH(0x12d7ec28): reading_headers, wait_backend, backend_req_sent, wait_res
418 Perlbal::BackendHTTP=HASH(0x12d75f30): connecting, bored, sending_req, wait_res
419 wait_res 2
420 And as soon as the request is processed:
422 state changes
424 Perlbal::BackendHTTP=HASH(0x12d75f30): connecting, bored, sending_req, wait_res, xfer_res, closed
425 closed 1
426 Note: This functionality depends on the environment variable
428 "PERLBAL_TRACK_STATES" being set to a true value.
429 states
431 states <service>
432 Shows how many sockets of which type and in which state currently
433 exist for all services.
434 states
436 Perlbal::ClientProxy draining_res 1
437 If a service is specified, shows the information for that service
439 only.
440 states ws
442 Perlbal::BackendHTTP wait_res 1
443 Perlbal::ClientProxy wait_res 1
444 track
446 Dumps objects tracked, sorted by age.
447 track
449 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
450 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
451 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
452 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
453 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
454 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
455 For this to work you must have the environment variable "DEBUG_OBJ"
457 set to a true value and the server option "track_obj" on:
458 server track_obj = 1
460 OK
461 uptime
463 version
464 Shows the time the server was started, the current uptime and
465 Perlbal's version.
466 varsize
468 Debug management command to track size of internal data structures.
469 varsize
471 svc-ws-bored_backends [] 2
472 svc-ws-pending_connects {} 2
473 {127.0.0.1:3080} =
474 {127.0.0.1:3081} = Perlbal::BackendHTTP=HASH(0x1cfd2490)
475 verbose on
477 verbose off
478 Turns verbose mode on or off.
479 verbose on
481 load AccessControl
482 OK
483 verbose off
484 load AccessControl
485 verbose on
486 OK
487 load AccessControl
488 OK
489 Yes, verbose mode only activates the printing of an OK message upon
491 completion of some commands such as "load". Errors are displayed
492 regardless of verbose status.
493 CAVEAT
495 Note that this functionality doesn't implement any sort of
496 authentication. If you can telnet to the address you specify, you can
497 access the information and change things on the fly.
498 Some alternatives to authentication are commonly employed:
500 · specifying the address as being 127.0.0.1 means that no one outside
502 the machine can telnet to the management service;
503 · setting the management address as a private IP available only
505 through a VPN, for instance, will allow you to manage these
506 accesses on the VPN instead.
507 SEE ALSO
509 Perlbal::Manual::Configuration, Perlbal::Manual::Debugging.
510perl v5.32.0 2020-07-27 Perlbal::Manual::Management(3)