NAME

VERSION

DESCRIPTION

READ ME FIRST

Setting up a management service

    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:

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

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