NAME¶
Perlbal::Manual::Management - Managing Perlbal on-the-fly
VERSION¶
Perlbal 1.78.
DESCRIPTION¶
How to configure a Perlbal "management" service for on-the-fly
configuration and debugging.
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.
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
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.
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.
create pool my_new_pool
create service my_new_service
- disable <service>
- Disables a service (stops listening).
disable my_service
Note that you can not disable "management" services.
- enable <service>
- Enables a service (starts listening).
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.
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-".
- load <plugin>
- Loads a Perlbal plugin.
load AccessControl
- plugins
- Lists plugins
- pool <name> add <ip[:port]>
- pool <name> remove <ip[:port]>
- Allows you to add or remove nodes from a service.
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.
Also note that the port number defaults to :80 if omitted.
- reproxy_state
- Dumps the state of reproxy status.
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.
- •
- max_reproxy_connections("ip") = <value>
Maximum number of concurrent connections to one specific backend.
- •
- 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.
- •
- nice_level = <value>
Sets the "nice" level for the process.
- •
- 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.
- •
- aio_threads = <value>
Number of child threads doing disk IO. Use between 2 and 50.
- •
- track_obj = <value>
Developer option to track objects.
- •
- pidfile = <value>
Filename to write pidfile to (no pidfile if not specified).
- •
- crash_backtrace = <value>
1 or 0 indicating whether to perform a backtrace while the server is
crashing.
- set [<pool_name>] <param> = <value>
- Sets a property on a pool. If the pool was just created,
specifying the pool name is optional.
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".
Note that manually modifying the pool (via POOL ADD or POOL REMOVE) will
disable the periodic checking of the nodefile.
Setting the load balancing method:
SET pool balance_method = 'random'
Yes, we do realize that "random" is the only method currently
available, but hey.
- 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.
- 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
- shutdown [graceful]
- Shuts down the server (you'll also lose your telnet
session).
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
- unload <plugin>
- Unloads a plugin.
unload AccessControl
- use <service>
- use <pool>
- Sets the implied service or pool for future operations.
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.
- 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
Diagnostic Commands
- aio
- Shows Perlbal::AIO stats.
- backends
- Lists the open connections to the backends.
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").
- 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).
- fd
- Shows the maximum number of file descriptors and how many
are currently in use.
fd
max 1024
cur 8
- 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.
- help
- Displays the list of available commands.
- 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.
- mime
- Lists known mime types.
mime
css text/css
doc application/msword
...
- node <ip[:port]>
- Dumps information on a specific node.
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".
- nodes
- Dumps information on all nodes.
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
- 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.
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.
- 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).
- pending
- Shows pending backend connections by service, node, and
age.
- proc
- Shows CPU usage, current time, pid, and total requests
processed.
- prof on
- prof off
- prof data
- Enables/disables profiling or dumps profile data.
- queues
- Shows status of all queues (normal, high priority and low
priority) for all enabled services.
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
- reload <plugin_name>
- Reloads a plugin that supports reloading.
- socks [all]
- socks summary
- Lists all sockets or shows a summary of the sockets (by
default lists all sockets).
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
- state changes
- Lists recent state changes of requests.
For instance, while a request is being processed this command may issue
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 as soon as the request is processed:
state changes
Perlbal::BackendHTTP=HASH(0x12d75f30): connecting, bored, sending_req, wait_res, xfer_res, closed
closed 1
Note: This functionality depends on the environment variable
"PERLBAL_TRACK_STATES" being set to a true value.
- 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 a service is specified, shows the information for that service only.
states ws
Perlbal::BackendHTTP wait_res 1
Perlbal::ClientProxy wait_res 1
- track
- Dumps objects 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 work you must have the environment variable
"DEBUG_OBJ" set to a true value and the server option
"track_obj" on:
server track_obj = 1
OK
- uptime
- version
- Shows the time the server was started, the current uptime
and Perlbal's version.
- varsize
- Debug management command to track 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, verbose mode only activates the printing of an OK message upon
completion of some commands such as "load". Errors are displayed
regardless of verbose status.
CAVEAT¶
Note that 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.
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.