1Perlbal::Manual::ManageUmseenrt(C3o)ntributed Perl DocumPeenrtlabtailo:n:Manual::Management(3)
2
3
4

NAME

6       Perlbal::Manual::Management - Managing Perlbal on-the-fly
7
8   VERSION
9       Perlbal 1.78.
10
11   DESCRIPTION
12       How to configure a Perlbal "management" service for on-the-fly
13       configuration and debugging.
14
15   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
20   Setting up a management service
21       You can create a management service in the following way:
22
23           CREATE SERVICE mgmt
24               SET role   = management
25               SET listen = 127.0.0.1:16000
26           ENABLE mgmt
27
28       Consulting information with a browser
29
30       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
35       Managing Perlbal via telnet
36
37       If you telnet to the management service you get a connection that
38       allows you manage your Perlbal's instance.
39
40           $ telnet 127.0.0.1 16000
41           Trying 127.0.0.1...
42           Connected to 127.0.0.1.
43           Escape character is '^]'.
44
45       You now have access to several commands (which are case insensitive):
46
47       Admin Commands
48
49       create pool <name>
50       create service <name>
51           Creates a pool or a service.
52
53               create pool my_new_pool
54
55               create service my_new_service
56
57       disable <service>
58           Disables a service (stops listening).
59
60               disable my_service
61
62           Note that you can not disable "management" services.
63
64       enable <service>
65           Enables a service (starts listening).
66
67               enable my_service
68
69       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
74           When adding headers you must state the value:
75
76               header my_service insert x-myamazingheader:myamazingvalue
77
78           When removing headers you don't need the state any value, the
79           header will be removed regardless of the value it holds:
80
81               header my_service remove Connection
82
83           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
87       load <plugin>
88           Loads a Perlbal plugin.
89
90               load AccessControl
91
92       plugins
93           Lists plugins
94
95       pool <name> add <ip[:port]>
96       pool <name> remove <ip[:port]>
97           Allows you to add or remove nodes from a service.
98
99               pool add my_service 127.0.0.1:1337
100
101               pool remove my_service 127.0.0.1:1337
102
103           Note that adding a node that already exists or removing a non-
104           existing node do not result in an error message.
105
106           Also note that the port number defaults to :80 if omitted.
107
108       reproxy_state
109           Dumps the state of reproxy status.
110
111               reproxy_state
112               SERVER max_reproxy_connections = 0
113
114       server <param> = <value>
115           Sets a server parameter, where param is one of:
116
117           •       max_reproxy_connections = <value>
118
119                   Maximum number of concurrent connections to the backends.
120
121           •       max_reproxy_connections("ip") = <value>
122
123                   Maximum number of concurrent connections to one specific
124                   backend.
125
126           •       max_connections = <value>
127
128                   Sets the value of "RLIMIT_NOFILE" (maximum number of open
129                   files for this process).
130
131                   Requires BSD::Resource. Also, Perlbal must be run under a
132                   superuser.
133
134           •       nice_level = <value>
135
136                   Sets the "nice" level for the process.
137
138           •       aio_mode = <value>
139
140                   One of "none", "linux" for Linux::AIO, or "ioaio" for
141                   IO::AIO.
142
143                   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
148           •       aio_threads = <value>
149
150                   Number of child threads doing disk IO. Use between 2 and
151                   50.
152
153           •       track_obj = <value>
154
155                   Developer option to track objects.
156
157           •       pidfile = <value>
158
159                   Filename to write pidfile to (no pidfile if not specified).
160
161           •       crash_backtrace = <value>
162
163                   1 or 0 indicating whether to perform a backtrace while the
164                   server is crashing.
165
166       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
170           Setting the file to autoload nodes from (Perlbal will periodically
171           check the file for updates):
172
173               SET my_pool nodefile = /path/to/file
174
175           Unsetting the file to autoload nodes from (note that this does not
176           remove current members):
177
178               SET my_pool nodefile = none
179
180           "undef", "null", "" and '' are interpreted just like "none".
181
182           Note that manually modifying the pool (via POOL ADD or POOL REMOVE)
183           will disable the periodic checking of the nodefile.
184
185           Setting the load balancing method:
186
187               SET pool balance_method = 'random'
188
189           Yes, we do realize that "random" is the only method currently
190           available, but hey.
191
192       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
196           See Perlbal::Manual::LoadBalancer, Perlbal::Manual::ReverseProxy
197           and Perlbal::Manual::WebServer for the list of available
198           parameters.
199
200       show service [<service_name>]
201       show pool [<pool_name>]
202           List all services:
203
204               show service
205
206           Show details of a service:
207
208               show service my_service
209
210           Lists all pools, nodes and services using them:
211
212               show pool
213
214           Show the members of a pool:
215
216               show pool my_pool
217
218       shutdown [graceful]
219           Shuts down the server (you'll also lose your telnet session).
220
221           Can be used instantly, killing all active connections:
222
223               shutdown
224
225           Using the parameter "graceful" listening sockets are closed and
226           perlbal stays alive until clients bleed off.
227
228               shutdown graceful
229
230       unload <plugin>
231           Unloads a plugin.
232
233               unload AccessControl
234
235       use <service>
236       use <pool>
237           Sets the implied service or pool for future operations.
238
239           For instance, after:
240
241               use my_pool
242
243           You can just type:
244
245               pool add 127.0.0.1:6000
246
247           Note that creating a service or pool also sets it as the implied
248           service.
249
250       xs
251       xs [enable <module>]
252       xs [disable <module>]
253           Show status of XS modules loaded:
254
255               xs
256
257           Turn on an already-loaded XS module:
258
259               xs enable module_name
260
261           Turn off an already-loaded XS module:
262
263               xs disable module_name
264
265       Diagnostic Commands
266
267       aio Shows Perlbal::AIO stats.
268
269       backends
270           Lists the open connections to the backends.
271
272               backends
273               127.0.0.1:3080 1
274               127.0.0.1:3081 2
275
276           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
280       dumpconfig
281           Shows the current configuration for each service.
282
283           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
287       fd  Shows the maximum number of file descriptors and how many are
288           currently in use.
289
290               fd
291               max 1024
292               cur 8
293
294       gladiator
295           Requires Devel::Gladiator.
296
297           Iterate's Perl's internal memory structures and can be used to
298           enumerate all the currently live SVs.
299
300           This can be used to hunt leaks and to profile memory usage.
301
302       help
303           Displays the list of available commands.
304
305       leaks
306       leaks <code>
307           Iterates over active objects.
308
309           If an argument is specified, it is treated as code with $_ being
310           the reference to the object.
311
312           Shows objects that might have been leaked.
313
314       mime
315           Lists known mime types.
316
317               mime
318               css text/css
319               doc application/msword
320               ...
321
322       node <ip[:port]>
323           Dumps information on a specific node.
324
325               node 127.0.0.1:8181
326               127.0.0.1:8181 attempts 10
327               127.0.0.1:8181 lastattempt 1290461126
328
329           Calling "node" with a parameter is the same as calling "nodes".
330
331       nodes
332           Dumps information on all nodes.
333
334               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
343       noverify
344           Shows the amount of time left for each node marked as noverify.
345
346           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
352               noverify
353               127.0.0.1:8081 42
354
355           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
358           If the time is a negative value it means that the "OPTIONS" command
359           will be issued before the next request.
360
361       obj Shows objects count in scope.
362
363           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
367       pending
368           Shows pending backend connections by service, node, and age.
369
370       proc
371           Shows CPU usage, current time, pid, and total requests processed.
372
373       prof on
374       prof off
375       prof data
376           Enables/disables profiling or dumps profile data.
377
378       queues
379           Shows status of all queues (normal, high priority and low priority)
380           for all enabled services.
381
382               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
390       reload <plugin_name>
391           Reloads a plugin that supports reloading.
392
393       socks [all]
394       socks summary
395           Lists all sockets or shows a summary of the sockets (by default
396           lists all sockets).
397
398               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
404               socks summary
405                   1 Perlbal::ClientManage
406                   2 Perlbal::TCPListener
407               Aggregate write buffer: 0.0k
408                           Open files: 0
409
410       state changes
411           Lists recent state changes of requests.
412
413           For instance, while a request is being processed this command may
414           issue something like:
415
416               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
421           And as soon as the request is processed:
422
423               state changes
424               Perlbal::BackendHTTP=HASH(0x12d75f30): connecting, bored, sending_req, wait_res, xfer_res, closed
425               closed 1
426
427           Note: This functionality depends on the environment variable
428           "PERLBAL_TRACK_STATES" being set to a true value.
429
430       states
431       states <service>
432           Shows how many sockets of which type and in which state currently
433           exist for all services.
434
435               states
436               Perlbal::ClientProxy draining_res 1
437
438           If a service is specified, shows the information for that service
439           only.
440
441               states ws
442               Perlbal::BackendHTTP wait_res 1
443               Perlbal::ClientProxy wait_res 1
444
445       track
446           Dumps objects tracked, sorted by age.
447
448               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
456           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
459               server track_obj = 1
460               OK
461
462       uptime
463       version
464           Shows the time the server was started, the current uptime and
465           Perlbal's version.
466
467       varsize
468           Debug management command to track size of internal data structures.
469
470               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
476       verbose on
477       verbose off
478           Turns verbose mode on or off.
479
480               verbose on
481               load AccessControl
482               OK
483               verbose off
484               load AccessControl
485               verbose on
486               OK
487               load AccessControl
488               OK
489
490           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
494   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
499       Some alternatives to authentication are commonly employed:
500
501       •   specifying the address as being 127.0.0.1 means that no one outside
502           the machine can telnet to the management service;
503
504       •   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
508   SEE ALSO
509       Perlbal::Manual::Configuration, Perlbal::Manual::Debugging.
510
511
512
513perl v5.38.0                      2023-07-19    Perlbal::Manual::Management(3)