1Perlbal::Manual::ManageUmseenrt(C3o)ntributed Perl DocumPeenrtlabtailo:n:Manual::Management(3)
2
3
4
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.32.0 2020-07-27 Perlbal::Manual::Management(3)