|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Looky Server Commands
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 FormatThe 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 ResponsesA 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:
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 RequestsA 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 ProtocolCommands 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
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.
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 MangementThis section provides commands to add, drop, couple and freeze resources.
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.
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.
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 DataThis section provides commands to manage resources run time data: it's 'have' and 'used' values.
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.
The set-ratio command increases or decreases the have value by a ratio by using the following equation: effective-have = have * ratioIf 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 DataAll 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%) } }
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% }
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
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. |