back page: doc.lb-protocol.html, rendered:2003-05-18 11:23
 

Looky Server Commands

Table Of Content
 
1  General Format
 1.1  Responses
 1.2  Requests
2  Looky Server Protocol
 2.1  Assign or Release Consumers
 2.2  Resource Mangement
 2.3  Define Run-Time Data
 2.4  Display Data
 2.5  General Commands
 2.6  Master Commands
 2.7  Pool Control
Command Index
 
clear [cmd #3]
clear <pool> [cmd #2]
consume <pool> <consumer> [cmd #0]
couple <resource> (m) [cmd #10]
decouple <resource> (m) [cmd #11]
drop-resource <pool> <resource> (m) [cmd #8]
drop-resource <resource> (m) [cmd #9]
exit [cmd #27]
free <number> [cmd #5]
free <pool> <number> [cmd #4]
freeze <pool> <resource> [cmd #12]
halt [cmd #26]
help [cmd #30]
list-pool (!) [cmd #18]
list-resource (!) [cmd #19]
lock <pool> <resource> (M) [cmd #31]
lock <resource> (M) [cmd #32]
master [cmd #35]
print-consumer <consumer> (!) [cmd #25]
print-consumer <pool> <consumer> (!) [cmd #24]
print-pool (!) [cmd #21]
print-pool <pool> (!) [cmd #20]
print-resource <pool> <resource> (!) [cmd #22]
print-resource <resource> (!) [cmd #23]
release <pool> <consumer> [cmd #1]
save [cmd #29]
set-mode <mode> [cmd #39]
set-mode <pool> <mode> [cmd #38]
set-ratio <pool> <resource> <weight> (m) [cmd #16]
set-ratio <resource> <weight> (m) [cmd #17]
set-resource <pool> <resource> <quantity> (m) [cmd #6]
set-resource <resource> <quantity> (m) [cmd #7]
set-seed <method> [cmd #37]
set-seed <pool> <method> [cmd #36]
set-used <pool> <resource> <number> (m) [cmd #14]
set-used <resource> <number> (m) [cmd #15]
status [cmd #28]
unfreeze <pool> <resource> [cmd #13]
unlock <pool> <resource> (M) [cmd #33]
unlock <resource> (M) [cmd #34]


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

[cmd #0] 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.



[cmd #1] 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.



[cmd #2] clear <pool>

[cmd #3] clear

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.



[cmd #4] free <pool> <number>

[cmd #5] free <number>

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.

[cmd #6] set-resource <pool> <resource> <quantity>(m)

[cmd #7] 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.



[cmd #8] drop-resource <pool> <resource>(m)

[cmd #9] 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.



[cmd #10] couple <resource>(m)

[cmd #11] decouple <resource>(m)

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.



[cmd #12] freeze <pool> <resource>

[cmd #13] 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.

[cmd #14] set-used <pool> <resource> <number>(m)

[cmd #15] 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.



[cmd #16] set-ratio <pool> <resource> <weight>(m)

[cmd #17] 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.

[cmd #18] list-pool(!)

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 ]   




[cmd #19] list-resource(!)

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
}




[cmd #20] print-pool <pool>(!)

[cmd #21] print-pool(!)

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%)
   }
}




[cmd #22] print-resource <pool> <resource>(!)

[cmd #23] 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%
}




[cmd #24] print-consumer <pool> <consumer>(!)

[cmd #25] 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

[cmd #26] halt

The halt command terminates the looky server.



[cmd #27] exit

The exit command terminates the session with the looky server.



[cmd #28] status

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
}




[cmd #29] save

The save command flushes all changes done since the initial load of the configuration to disk to make this changes persistant.



[cmd #30] help

The help command sends a multiline reply with a short help.



2.6  Master Commands

[cmd #31] lock <pool> <resource>(M)

[cmd #32] lock <resource>(M)

[cmd #33] unlock <pool> <resource>(M)

[cmd #34] unlock <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.



[cmd #35] 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

[cmd #36] set-seed <pool> <method>

[cmd #37] set-seed <method>

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.



[cmd #38] set-mode <pool> <mode>

[cmd #39] set-mode <mode>

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.