Looky Server Commands
 | Table Of Content | |
| Command Index | |
The  server uses a very simple TCP protocol. A command is
passed by a single request line. The server replies by a response
more or less human readable. The following document provides a
listing of all those commands.
BTW: Geeks use telnet to the looky server and try 'help'. Wimps
stay tuned on this document ...
1 General Format
The general format is a request/response format. A request
is a single command line that is passed to the server. The
response is sent back immediatly. A response may be
single-lined or multi-lined.
1.1 Responses
A response has the following syntax:
LOOKY/<version> <rc-code> 'OK|ERR' (':'<parameterlist>)::?
( <any>::*
<empty-line> )::?
The <parameterlist> has the following format:
<key> '=' <value>(',' <key> '=' <value>)::*
<value> is escaped using '\' as meta character. Use '\c' to
pass a ',', '\\' to pass a '\', '\n', '\s', '\t', '\r' to pass
named whitespace character.
Values passed by <parameterlist> are called
'parameter'. The <key> is the parameter name. The < value> is the parameter value. The following parameters are defined:
| multiline |
the multiline parameter is set to 'yes' if response is a
multiline response |
| message |
the message parameter is used to pass any kind of human
readable text |
| resource |
The resource parameter is used to return the name of a
resource |
| date |
The date parameter is used to return a timepoint. |
The <rc-code> is a 3 digit code to pass the error code. A
positive result is indicated by an 'OK', a negative result is
indicated by an 'ERR'.
A multiline response is flagged by parameter 'mutliline' with value
'yes'. Each multiline response is terminated by a single empty
line (just \r\n).
1.2 Requests
A request consists of a single line. The request is splitted by
white space into a <command> and a list of <args>:
<request> ::= <i-prefix> <command> ( <args> )::*
An additional <i-prefix> may be added. Currently only a '!'
is supported.
If a '!' <i-prefix> is added to a command, the reply will
be a native binary format, which is parsed directly by Looky's perl
libaries.
2 Looky Server Protocol
Commands may be restricted to master (m) or may be only available in
master mode (M). This is indicated with flags in the command description.
2.1 Assign or Release Consumers
| consume <pool> <consumer> |
|
The consume command requires a resource in a pool for a
consumer. The command uses parameter <pool> to
select the pool and and parameter <consumer> to select the
consumer.
If the command's response is OK, the caller gets a <resource>
parameter naming the assigned resource and a <date> parameter
naming the timepoint, when the resource gets automaticly freed by
looky's latency timer.
If the command's response is ERR, the caller gets no resource.
| release <pool> <consumer> |
|
The release command releases a required resource in a pool
for a consumer. The command uses the argument <pool> to select
the pool and and the argument <consumer> to select the
consumer. The command does the opposite of consume command.
The command's response is always OK. The fact that a specific resource
was never assigned to the given consumer in the given pool is completely ignored.
The clear command releases all assigned resources or all assigned
resources of a specific pool. The command uses the argument
<pool> to select the pool.
The command's response is OK if no parameter <pool> was set or
if the pool given by the argument exists.
The command's response is ERR if the pool named by the argument
<pool> does not exist.
The free command releases n assigned resources or n
assigned resources of a specific pool. The command uses the argument
<number> to provide the number of resources to be
released. The command uses an optional argument <pool> to
select a specific pool.
The command's response is ERR if the pool set by the argument
<pool> does not exist or the number of resources to be
released <number> is negative.
2.2 Resource Mangement
This section provides commands to add, drop, couple and freeze
resources.
| set-resource <pool> <resource> <quantity> | (m) |
|
| set-resource <resource> <quantity> | (m) |
|
The set-resource command defines or modifies the session quantity
of a resource in a pool or in all pools. The command uses the
argument <resource> to select the resource and the argument
<quantity> to select the number of sessions hosted by the
resource. The argument <pool> is optional. If not set, the
command is applied to all pools.
The command may either create, increase or decrease the number of
sessions of a given resource. NB: if the command is applied on a
coupled resource, the resources of all pools are set, despite the
fact if the argument <resource> is set or not.
The command's response is ERR, if the argument <pool> was set to
an undefined pool. If the argument <number> is negative or
null, the command has no effect.
The command's response is also ERR, if the looky server is mastered and
command is not applied by the master.
| drop-resource <pool> <resource> | (m) |
|
| drop-resource <resource> | (m) |
|
The drop-resource command removes a resource from a pool or from
all pools. The command uses the argument <resource> to name
the resource to be dropped. The argument <pool> is optional. If
not set, the command is applied to all pools.
The command's response is ERR, if the arguments <pool> or
<resource> were set to an undefined pool or resource.
The command's response is also ERR, if the looky server is mastered and
command is not applied by the master.
The couple / decouple command selects whether a given resource is a
shared or a coupled resource. The command uses the argument
<resource> to name the resource to be changed.
The command's response is ERR, if the argument <resource> was set
to an undefined resource.
The command's response is also ERR, if the looky server is mastered and
command is not applied by the master.
| unfreeze <pool> <resource> |
|
The freeze / unfreeze command freezes or unfreezes a given
resource. The command uses the argument <resource> to
name the resource to be changed.
The command's response is ERR, if the argument <resource> was set
to an undefined resource.
The command's response is also ERR, if the looky server is mastered and
command is not applied by the master.
2.3 Define Run-Time Data
This section provides commands to manage resources run time data:
it's 'have' and 'used' values.
| set-used <pool> <resource> <number> | (m) |
|
| set-used <resource> <number> | (m) |
|
The set-used command sets the number of effectivly used sessions of
a resource in a pool or in all pools. The command overrules looky
servers view of number of distributed sessions.
The command uses the argument <resource> to name the resource
to be changed and the argument <number> to set the number of
sessions. The argument <pool> is optional. If the argument is set
the operation is done for a specific pool. If the argument is not set,
the number of sessions is set for the resource in all pools.
The command's response is ERR, if the argument <resource> was set
to an undefined resource or the argument <pool> was set to an
undefined pool.
The command's response is also ERR, if the looky server is mastered and
command is not applied by the master.
| set-ratio <pool> <resource> <weight> | (m) |
|
| set-ratio <resource> <weight> | (m) |
|
The set-ratio command increases or decreases the have value by a
ratio by using the following equation:
effective-have = have * ratio
If a ratio is set to a value > 1, the have (more precise the
effective-have) value is increased. If ratio is set to a value < 1,
the have value is decreased.
The command uses the argument <resource> to name the resource
to be changed and the argument <weight> to set the
ratio. The argument <pool> is optional. If the argument is set the
operation is done for a specific pool. If the argument is not set, the
ratio is set for the resource in all pools.
The command's response is ERR, if the argument <resource> was set
to an undefined resource, the argument <pool> was set to an
undefined pool or the argument <weight> has a value <= 0.
The command's response is also ERR, if the looky server is mastered and
command is not applied by the master.
2.4 Display Data
All commands in this section may take an <i-prefix> '!' to get
binary data.
The list-pool command returns a multi line response with a list
of all defined pools.
Example:
list-pool
LOOKY/1.0 201 OK:multiline=yes
pool-list = [ admin, sales ]
The list-resource command returns a multi line response with a list
of all defined resources with a status indicating if a resource is
coupled or shared.
Example:
list-resource
LOOKY/1.0 201 OK:multiline=yes
resource-list = {
100.1.4.128 = shared
100.1.4.129 = coupled
100.1.4.130 = shared
}
The print-pool command returns a multi line response with detailed
information about a specific pool or about all pools. The command uses the optional
argument <pool> to select a pool.
The command returns ERR if the given pool does not exist.
Example:
print-pool sales
LOOKY/1.0 201 OK:multiline=yes
pool sales {
started = yes
latency = 3600 sec
max-pool-size = 700
auto-max = on
seed = weighted
current = 0
resource = #3 {
#000 100.1.4.129: have=200(200), used=0(0) (0%)
#001 100.1.4.130: have=300(300), used=0(0) (0%)
#002 100.1.4.128: have=200(200), used=0(0) (0%)
}
}
| print-resource <pool> <resource> | (!) |
|
| print-resource <resource> | (!) |
|
The print-resource command returns a multi line response with
detailed information about a resource in a specfic pool or in all
pools. The command uses argument <resource> to select the
resource of interest. The command uses the optional argument
<pool> to select the pool.
The command returns ERR if the given pool or resource does not exist.
Example:
print-resource 100.1.4.130
LOOKY/1.0 201 OK:multiline=yes
admin/100.1.4.130 = undef
resource sales/100.1.4.130 = {
consumer = {
}
status = -
have = {
given = 300
ratio = 1.0000
effective = 300
}
used = {
counted = 0
offset = 0
effective = 0
}
usage = 0%
}
| print-consumer <pool> <consumer> | (!) |
|
| print-consumer <consumer> | (!) |
|
The print-consumer command returns a multi line response with
information about a named consumer in a specfic pool or in all
pools. The command uses the argument <consumer> to depict the
name of the consumer. The command uses the optional argument
<pool> to select the pool.
The command returns ERR if the given consumer or pool does not exist.
Example:
print-consumer oliver
LOOKY/1.0 201 OK:multiline=yes
consumer admin/oliver = undef
consumer sales/oliver = {
resource = 100.1.4.130
last-contact = 2003-04-18 / 11:20:26 (0)
}
2.5 General Commands
The halt command terminates the looky server.
The exit command terminates the session with the looky server.
The status command returns status information about the looky
server and the current session with the looky server (e.g. if you
are master or not)
Example
status
LOOKY/1.0 201 OK:multiline=yes
status = {
dirty = 0
uptime = 1.33 min
have-master = 0
version = balancer/1.6 (1.0.5) (2003-04-20)
you-are-master = 0
}
The save command flushes all changes done since the initial load of
the configuration to disk to make this changes persistant.
The help command sends a multiline reply with a short help.
2.6 Master Commands
| lock <pool> <resource> | (M) |
|
| unlock <pool> <resource> | (M) |
|
The lock/unlock command locks or unlocks a resource in a pool or in
all pools. Both commands use the argument <resource> to select
the resource. Both commands use the optional argument <pool>
to select the pool.
Both command's response is ERR, if the argument <resource> was
set to an undefined resource.
Both command's response is also ERR, if the looky server is not
mastered or the server is mastered and the command is not applied by
the master.
The master command masteres the server. The master mode is
automaticly removed if the mastering session terminates.
The command's response is ERR, if the server is already mastered.
2.7 Pool Control
The set-seed command defines the seed method for a pool or
all pools.
The command uses the argument <method> to name the
seed. Accepted values are 'parallel', 'serial', 'weighted' and
'minimal'. The argument <pool> is optional. If the argument is set
the operation is done for a specific pool. If argument is not set,
the seed is set for all pools.
The command's response is ERR, if the argument <pool> was set to an
undefined pool.
The set-mode command defines the distribute mode of a
pool or all pools.
The command uses the argument <mode> to name the
mode. Accepted values are 'sticky', 'queued', and 'queued-DD',
where DD is an literal number. The argument <pool> is
optional. If the argument is set the operation is done for a specific
pool. If the argument is not set, the distribute mode is set for all
pools.
The command's response is ERR, if the argument <pool> was set to an
undefined pool.
|
|
commands LB