| back | page: doc.configuration.html, rendered:2003-05-18 11:23 |
Looky Configuration
 | Configuration Key Index | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
The
system reads out a single configuration file. This
file is searched for on disk by all components. Because looky is a
distributed system, you may have copies of the same configuration
file on several machines.
This document provides a brief overview about all configuration keys.
1 General
1.1 Configuration File
Looky components are searching for the configuration file called looky.conf. The file is searched for at the following locations in the given order:- ./looky.conf
- /etc/looky.conf
- /etc/looky/looky.conf
Most looky components support an command line option -c <filename> to run from an individual configuration.
NB: You cannot set an command line option -c for CGI applications.
Because the most relevant looky component (looky balancer client) is a CGI application, you cannot build your system on an individual location of the file looky.conf.
The command line option -c is indented for a temporary test of a specific configuration, but not for a long time solution.
1.2 File Syntax
Puritists get the whole syntax from this grammar ...<<file>> ::= ( <comment> | <space> | <conf> ) "\n" ;
<comment> ::= '#' <any>::* ;
<space> ::= [ \s\t\v]::* ;
<conf> ::= <key> ':' <value> ;
<key> ::= [^:]::+ ;
<value> ::= <simple-value> | <value-with-ref> ;
<simple-value ::= <any>::* ;
<value-with-ref> ::= '#{' <ref>::{ [^}]::* } '}' <any>::* ;;
... others stay tuned on this:
Each line of the file looky.conf is either a comment, a space line or a configuration line. A comment line starts with a '#' character. A space line consists only of white space. All other lines are configuration lines. Comment and space lines are ignored but preserved (e.g. while writing this file)
A configuration line is splitted by first colon ':' character into a <key> and a <value>. The <key> names the configuration entry. The <value> provides the configuration value.
If a <key> is defined twice, the last definition will overwrite all previous ones. There is no way to add a colon into <key>.
The <value> may start with a reference to an already defined <key> using a #{<ref>} definition: <ref> provides the name of the referred <key>. The <ref> is replaced by referred <key>'s <value>.
Example:
# This is a comment
#
my-server:http://my.domain.com/looky-error
# ----- some configuration key
#
redirect.error.invalid-url:#{my-server}/invalid.html
redirect.error.no-resource-url:#{my-server}/no-resource.html
redirect.error.no-server-url:#{my-server}/no-server.html
Attention: Be careful with spaces at the end of a configuration line: these spaces are part of the configuration key's value (!)
(We should change this in on our next releases ...)
1.3 Complete Example
Please find here: [Example File Looky.Conf] a complete example of a looky.conf file.1.4 Datatypes
Each value of a looky configuration key has a specific syntax. To avoid duplication of information, this document (!) uses datatypes to explain this syntax. If a specific configuration key uses a syntax explained in this section it is printed next to key's name in square brackets.1.4.1 Boolean
A boolean value is either '1', '0', 'yes' or 'no'. For no reason we do not support a 'true' or a 'false'.1.4.2 Number
A number is a non empty sequence of digit characters.1.4.3 Domain-Or-Ip
A domain-or-ip syntax may be either a valid dns-name, an ip-address in dot-syntax (192.1.2.3), the specific value localhost or the specific value anyA domain-or-ip value defines an interface to be bound by looky components.
1.4.4 Authmask
An Authmask is a combination of a <subnet> and a <mask>. An Authmask is used to define a set of ip addresses (by an ip range).An Authmask value has the following syntax:
<authmask> ::= <subnet>#<mask> | '*' ;Both <subnet> and
An ip-address <addr> matches an authmask value if the formula
((<addr> & <mask>) == <subnet>)becomes true.
<subnet> may also be a valid dns entry or just localhost.
Authmask value may be '*' as an abbreviation for all matching 0.0.0.0#0.0.0.0 expressions.
Example:
192.2.0.0#255.255.0.0 is a valid expression matching ip address 192.2.3.1 but not 39.3.22.1.
1.4.5 Time-Period
A time-period is used to define a time period in seconds, minutes, hours or days.A time-period is combination of a number and a time suffix to define scale. If no suffix is given, the number is seen as seconds.
A 'min' suffix depicts minutes, a 'hour' suffix depicts hours. A 'day' suffix depicts days. Suffixes may be abbreviated to 'm', 'h' or 'd'.
Example:
1.2d are 1 1/5 days. 34min are 34 minutes or 34 * 60 seconds.
1.4.6 Denoter
A denoter is a string that is part of an additional configuration key. The denoter may consist of all characters but not of a colon ':', a comma ',', a percent '%' or a dollar '$'.To avoid problems with future releases of looky, you should only use letters, digits, dots, underlines and dashes for this.
1.4.7 List:x
The list datatype is a compositive datatype: the 'x' may be replaced by all other datatypes listed above. E.g. 'list:denoter' or 'list:Authmask'.A list is a sequence of values with a comma ',' as delimiter. Space is significant!
Example:
pool.list:sales,adminThe key pool.list defines a list with two elements: sales and admin.
2 Looky Configuration
The following section provides all configuration keys used by the system. Keys are sorted in logical sections. Keys
tagged with a big O are optional keys with a default value. Keys
tagged with a big M are mandatory keys. If a mandatory key is not
defined, looky components will crash.
2.1 Network, ACL
|
The configuration key address defines the ip-address / interface that is used by the looky server to binding. If the key is not set, the server will bind on any interface.
The key is also consulted by looky balancer clients (LBC) to create a TCP connection to the looky server.
|
The configuration key port defines the TCP port that is used by the looky server for listening. If key is not set, the server will listen on port '4040'.
The key is also consulted by looky balancer clients (LBC) to create a TCP connection to the looky server.
|
The configuration key order defines the order how looky server evaluates ACL configuration keys allow and deny. The value of this key is either 'allow,deny' or 'deny,allow'
The key influences the default access and how ip-sets which are defined by the configuration keys allow and deny are evaluated.
| order | default | subsets |
|---|---|---|
| allow,deny | access denied | deny is a subset of allow |
| deny,allow | access granted | allow is a subset of deny |
If the configuration key order has the value 'allow,deny', Looky clients have to get grants by ACL 'allow' and must not be excluded by ACL 'deny'.
If the configuration key order has the value 'deny,allow', Looky clients have to be excluded by ACL 'deny' but if so, they may get grants by ACL 'allow'.
|
The configuration key allow defines a list of authmask expressions. A looky balancer client with an ip-address matching one of the authmasks sets has access to the looky server.
|
The configuration key deny defines a list of authmask expressions. A looky balancer client with an ip-address matching one of the authmasks sets has no access to the looky server.
Example
# ----- network and ACL # address:any port:4040 order:allow,deny allow:localhost deny:
2.2 Set-Up Log
|
The configuration key log.only-bootstrap selects if looky server's log is limited to bootstrap phase (~ parse configuration and allocate system resource) or not.
You should set this key to 'no' only in the set-up phase of your looky system. Once it is stable, the information written after bootstrap phase is rather of no interest.
|
The configuration key log.dump-pools selects if looky server's log parses the pool configuration or not.
You should set this key to 'yes' to check which configuration was read from the configuration file during start time. (for administrators sake :-)
Example:
# ----- set-up log # log.only-bootstrap:yes log.dump-pools:yes
2.3 Reorganization
The looky server needs to do a reorganization of allocated resources (free idle consumers) from time to time.
|
The configuration key reorg-time defines a time period of inactivity (no client requests) until a reorganization is enforced.
|
The configuration key reorg-calls defines the maximum number of client requests until a reorganization is enforced.
Example:
# ----- reorganization timers # reorg-calls:1000 reorg-time:2h
2.4 Set-Up Pools
|
The configuration key pool.list defines a list of available #(TERM:pool)s. The key is mandatory: if not set, the looky components won't be started.
2.4.1 Default Pool Values
|
The configuration key pool.seed-method defines the default seed method for all pools. The following values are allowed for this key: 'serial', 'parallel', 'weighted' and 'minimal'. If other values are set, the seed-method is set to 'parallel'.
The default seed method is used for a pool <pn>, if no pool.<pn>.seed-method key is set.
|
The configuration key pool.distribute-mode defines the default distribute mode for all pools. The following values are allowed for this key: 'sticky', 'queued' and 'queued-NNN', where NNN is sequence of digits.
The default distribute mode is used for a pool <pn>, if no pool.<pn>.distribute-mode key is set.
|
The configuration key pool.latency-time defines the default latency time for all pools.
The default latency time is used for a pool <pn>, if no pool.<pn>.latency-time key is set.
|
The configuration key pool.quantity defines the default session quantity of all pools.
The default quantity is used for a pool <pn>, if no pool.<pn>.resource.quantity key is set.
2.4.2 Set-Up Pool
2.4.2.1 Pool Characteristics
|
The configuration key pool.<pn>.seed-method defines the seed method for the pool <pn>.
If the key is not set, the pool <pn> uses default seed method.
|
The configuration key pool.<pn>.distribute-mode defines the distribute mode for the pool <pn>.
If the key is not set, the pool <pn> uses default distribute mode.
|
The configuration key pool.<pn>.latency-time defines the latency time for the pool <pn>.
If the key is not set, the pool <pn> uses default latency time.
2.4.2.2 Pool Resources
|
The configuration key pool.<pn>.resource.list assigns a list of resources to a pool <pn>. The key is mandatory and must be set. If the key is not set, the looky server will crash.
The list defines the order number of a resource in a pool < p>: if a resource <x> is defined at position <i> in that list, the resource <x> has order number <i> within that pool <p>.
|
The configuration key pool.<pn>.resource.quantity defines the default resource quantity in the pool <pn>. If the key is set, the default quantity, as defined by configuration key pool.quantity, is overwritten for the pool <pn>.
|
The configuration key pool.<pn>.resource.<rn>.quantity defines the session quantity of the resource <rn> in a pool <pn>.
Example:
# ----- define pools # pool.list:sales,admin # ----- define pool defaults # pool.seed-method:weighted pool.distribute-mode:queued pool.latency-time:2min pool.quantity:100 # ----- set-up pool sales # pool.sales.resource.list:100.1.4.129,100.1.4.128,100.1.4.130 pool.sales.latency-time:5min pool.sales.resource.quantity:200 pool.sales.resource.100.1.4.130.quantity:300 # ----- set-up pool admin # pool.admin.resource.list:100.1.4.129,100.1.4.128
This example defines the following pools/resources:
| pool | data | resources | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| sales |
|
|
||||||||||||||||||
| admin |
|
|
2.5 Set-Up Resource
|
The configuration key resource.coupled.list defines a list of all resources that are coupled. Resources not listed in this list (but used in pools) are automaticly treated as shared resources.
2.5.1 Default Characteristics
Warning: The keys defined in this section may be changed in next release.
|
The configuration key resource.load.opt defines the default optimal load value for all resources. The value is used, if no configuration key resource.<rname>.load.opt exists for a specific resource <rname>.
|
The configuration key resource.load.max defines the default maximum load value for all resources. The value is used, if no configuration key resource.<rname>.load.max exists for a specific resource <rname>.
|
The configuration key resource.quantity.max defines the default maximum quantity for all resources. The value is used, if no configuration key resource.<rname>.load.max exists for a specific resource <rname>.
If the key is not defined, the default maximum quantity is computed using the configuration key resource.quantity.max.factor
|
The configuration key resource.quantity.max.factor defines a ratio value, that is used to estimate a default maximum quantity.
The ratio is multiplied by overall quantity (shared resources are a sum of all individual quantities, coupled resources have just one quantity) to get the default maximum quantity. E.g. a ratio of 1.1 will lead to a maximum of 110%.
2.5.2 Characteristics
Warning: The keys defined in this section may be changed in next release.
|
The configuration key resource.<rname>.load.opt defines the optimal load value for resource <rname>.
|
The configuration key resource.<rname>.load.max defines the maximal load value for the resource <rname>.
|
The configuration key resource.<rname>.quantity.max defines the maximum quantity for the resource <rname>.
Example:
# ----- define coupled resources # resource.coupled.list:100.1.4.130 resource.load.opt:2 resource.load.max:4 resource.quantity.max.factor:1.2
2.6 Redirection
You should read document redirection first to understand this section.2.6.1 Error Urls
|
The configuration key redirect.error.invalid-url defines an URL sent to the consumer if the consumers URL is invalid and cannot be parsed correctly.
|
The configuration key redirect.error.no-resource-url defines an URL sent to the consumer if no resource was found for the consumer.
|
The configuration key redirect.error.no-server-url defines an URL sent to the consumer if the looky balancer client was not able to bind on a looky server. (this is down for some reasons ...)
2.6.2 Resource Urls
|
The configuration key redirect is the default URL sent to the consumer if a resource was found in the addressed pool. The key is used for a pool <pn>, if the configuration key redirect.<pn> is not defined.
The URL is highly magic and may contain the following ctags:
| %{resource} | resource as assigned from looky server |
| %{consumer} | consumer name as computed by compute consumer expression |
| %{pool} | pool name as computed by compute pool expression |
| %{path} | path as computed by transient path expression |
| %{query} | query part of URL as computed by transient query expression |
| %{url} | original URL sent by consumer. |
| %{url/scheme} | schema part of original URL sent by consumer |
| %{url/path} | path part of original URL sent by consumer |
| %{url/query} | query part of original URL sent by consumer |
| %{url/fragment} | fragment part of original URL sent by consumer |
|
The configuration key redirect.<pn> defines the URL sent to the consumer if a resource was found for the consumer in the addressed pool. The URL is highly magic and may contain the same ctags as defined for configuration key redirect
|
The configuration key compute.pool is a pseudo function expression to compute the pool name of a request from a given URL, environement or by constant expression. The following expressions are defined.
| path/<segment-id> | Compute pool by path part of URL sent by consumer. <segment-id> is an index into path segments. (first = 0, last = -1) |
| query/<parameter-name> | Compute path by query part of URL sent by consumer. <parameter-name> is the name of the CGI parameter providing the pool. |
| const/<any> | Use a constant pool name <any>. This is quite helpfull if you don't like to support several pools. |
| env/<key> | Get pool name from environment. <key> is the name of the environment variable providing the pool name. |
|
The configuration key compute.consumer is a pseudo function expression to compute consumers name out of a request from given URL, environment or by constant expression.
compute.consumer uses the same expressions as compute.pool with one exception: use const/- to enforce a generic consumer name (e.g. if you haven't got any)
|
The configuration key transient.path is a pseudo function which extracts parts of original path to be inserted into the redirect URL.
Valid functions are defined by the following syntax:
<<transient.path>> ::= <all> | <range> ; <all> ::= '*' ; <range> ::= <offset> | <offset> '/' <len> ; <offset> ::= <number> ; <len> ::= <number> ; <number> ::= [0-9]::+ ;;
If transient.path is set to '*', the complete path is assigned to ctag %{path} in the redirect pattern. If transient.path is set to <offset>/<len>, the expression defines a slice in the path segment with <offset> and <len>. <len> may be omitted.
|
The configuration key transient.query is a pseudo function which extracts parts of the original query to be assigned to ctag %{query} in the redirect pattern.
Valid functions are defined by the following syntax:
<<transient.path>> ::= <all> | <positive-list> | <negative-list>;
<all> ::= '*' ;
<negative-list> ::= '-' ',' <positive-list> ;
<positive-list-list> ::= <parameter-name>
( ',' <parameter-name> )::* ;;
If transient.query is set to '*', the complete query part is assigned to ctag %{query}.
If transient.query is set to a list of <parameter-name>s, the list defines those CGI parameters, that are assigned to ctag %{query}.
If first <parameter-name> is a single dash '-', a negative list is defined. A negative list depicts those parameters that are not transient.
Example:
# ----- redirection
#
redirect.error.invalid-url:http://my.server.net/invalid-url
redirect.error.no-resource-url:http://my.server.net/no-resource
redirect.error.no-server-url:http://my.server.net/no-server
compute.pool:path/0
compute.consumer:const/-
transient.path:1
transient.query:*
redirect:http://%{resource}/%{path}%{url/query:?%{url/query}}%{url/fra\
\gment:#%{url/fragment}}
#
2.7 CGI Redirector
Keys defined in the following section are only used by Looky Balancer Client CGI.
|
The configuration key cgi.use.frames defines whether the looky balancer client CGI provides a 'frame' reply or a 'redirect' reply: if the key is set to a true value, a frame reply is used.
|
The configuration key cgi.frame-title defines the title of the frame HTML response the looky balancer client CGI is returning in case the 'reply-in-frames' mode is activated.
Example:
# ----- CGI client # cgi.use-frames:yes cgi.frame-title:Powered By Looky!
2.8 Controller
2.8.1 Network, ACL
The looky controller processes has a similar set of configuration keys like the looky server: there is just a 'controller' prefix.
|
The configuration key controller.address defines the ip-address / interface that is used by the looky controller for binding. If key is not set, the controller will bind on interface 'any'.
The key is also consulted by looky probe clients (LPC) and Looky observer (LO) to create a TCP connection to the looky controller server.
|
The configuration key controller.port defines the TCP port that is used by the looky controller server for listening. If key is not set, the server will listen on port '4041'.
The key is also consulted by looky probe clients (LPC) and looky observer (LO) to create a TCP connection to the looky controller server.
|
The configuration key controller.order defined the order how looky controller evals ACL configuration keys controller.allow and controller.deny. The value of this key is either 'allow,deny' or 'deny,allow'
See configuration key order for more information about this.
|
The configuration key controller.allow defines a list of authmask expressions. A looky probe client with an ip-address matching one of the authmasks sets has access to the looky controller.
|
The configuration key controller.deny defines a list of authmask expressions. A looky probe client with an ip-address matching one of the authmasks sets has no access to the looky controller.
Example
# ----- network and ACL # controller.address:any controller.port:4041 controller.order:allow,deny controller.allow:100.1.4.0#255.255.255.0 controller.deny:
2.8.2 Set-Up Controlling
|
The configuration key controller.period defines the length of a controller period. (this is the time period, where the controller collects data)
|
The configuration key controller.history-depth defines the size of history data that is stored in memory by looky controller for administrational use.
Warning: Don't set this value to a high number: this will cause a very big process and a very slow administration process.
2.8.3 Controller Set-Up Log
|
The configuration key controller.log.only-bootstrap selects whether looky server's log is limited to bootstrap phase (~ parse configuration and allocate system resource) or not.
|
The configuration key controller.log.statistic-file activates the statistics log. If this parameter is not set, no statistics are written.
2.9 Web Interfaces
2.9.1 Set-Up Log
|
The configuration key web.balancer.log activates a log written by the looky component 'web balancer manager'. The log is written on STDERR <=> into Apache's error.log file.
|
The configuration key web.controller.log activates a log written by the looky component 'web controller manager'. The log is written on STDERR <=> into Apache's error.log file.
Example
# ----- setup web interface log # web.controller.log:no web.balancer.log:no