Looky Configuration
 | Table Of Content | |
| 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 any
A 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 are 4 byte ip-address masks in
dot notation. <mask> is optional and may be obmitted. In
this case 255.255.255.255 is used as <mask>.
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,admin
The 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
| address [DOMAIN-OR-IP], 'any' | | O |
|
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'.
| allow [LIST:AUTHMASK], '' | | O |
|
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.
| deny [LIST:AUTHMASK], '' | | O |
|
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
| log.only-bootstrap [BOOLEAN], 'yes' | | O |
|
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.
| log.dump-pools [BOOLEAN], 'yes' | | O |
|
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.
| reorg-time [TIME-PERIOD], '3600' | | O |
|
The configuration key reorg-time defines a time period of
inactivity (no client requests) until a reorganization is enforced.
| reorg-calls [NUMBER], '500' | | O |
|
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
| pool.list [LIST:DENOTER] | | M |
|
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
| pool.seed-method, 'parallel' | | O |
|
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.
| pool.distribute-mode, 'sticky' | | O |
|
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.
| pool.latency-time [TIME-PERIOD], '1h' | | O |
|
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.
| pool.quantity [NUMBER], '1' | | O |
|
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
| pool.<pn>.seed-method, pool.seed-method | | O |
|
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.
| pool.<pn>.distribute-mode, pool.distribute-mode | | O |
|
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.
| pool.<pn>.latency-time [TIME-PERIOD], pool.latency-time | | O |
|
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
| pool.<pn>.resource.list [LIST:DENOTER] | | M |
|
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>.
| pool.<pn>.resource.quantity [NUMBER], pool.quantity | | O |
|
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>.
| pool.<pn>.resource.<rn>.quantity [NUMBER], pool.<pn>.resource.quantity | | O |
|
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 |
| seed method | weighted |
| distribute mode | queued |
| latency time | 5min |
|
| # | name | quantity |
|---|
| 1 | 100.1.4.129 | 200 |
| 2 | 100.1.4.128 | 200 |
| 3 | 100.1.4.130 | 300 |
|
| admin |
| seed method | weighted |
| distribute mode | queued |
| latency time | 2min |
|
| # | name | quantity |
|---|
| 1 | 100.1.4.129 | 100 |
| 2 | 100.1.4.128 | 100 |
|
2.5 Set-Up Resource
| resource.coupled.list [LIST:DENOTER], '' | | O |
|
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.
| resource.load.opt [NUMBER], '1' | | O, 1.0.5 |
|
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>.
| resource.load.max [NUMBER], resource.load.opt | | O, 1.0.5 |
|
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>.
| resource.quantity.max [NUMBER] | | O, 1.0.5 |
|
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
| resource.quantity.max.factor, '1' | | O, 1.0.5 |
|
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.
| resource.<rname>.load.opt [NUMBER], resource.load.opt | | O, 1.0.5 |
|
The configuration key resource.<rname>.load.opt
defines the optimal load value for resource <rname>.
| resource.<rname>.load.max [NUMBER], resource.load.max | | O, 1.0.5 |
|
The configuration key resource.<rname>.load.max
defines the maximal load value for the resource <rname>.
| resource.<rname>.quantity.max [NUMBER], resource.quantity.max | | O, 1.0.5 |
|
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
| redirect.error.invalid-url, '' | | O |
|
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.
| redirect.error.no-resource-url, '' | | O |
|
The configuration key redirect.error.no-resource-url
defines an URL sent to the consumer if no resource was found for the
consumer.
| redirect.error.no-server-url, '' | | O |
|
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
| redirect, 'http:://error.org/' | | O |
|
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 |
| redirect.<pn>, redirect | | O |
|
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
| compute.pool, 'query/pool' | | O |
|
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. |
| compute.consumer, 'query/consumer' | | O |
|
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/fragment:#%{url/fragment}}
#
2.7 CGI Redirector
Keys defined in the following section are only used by Looky Balancer
Client CGI.
| cgi.use-frames [BOOLEAN], 'yes' | | O, 1.0.5 |
|
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.
| cgi.frame-title [STRING], '' | | O, 1.0.5 |
|
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.
| controller.address [DOMAIN-OR-IP], 'any' | | O, 1.0.5 |
|
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.
| controller.port [NUMBER], '4040' | | O, 1.0.5 |
|
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.
| controller.order, 'allow,deny' | | O, 1.0.5 |
|
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.
| controller.allow [LIST:AUTHMASK], '' | | O, 1.0.5 |
|
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.
| controller.deny [LIST:AUTHMASK], '' | | O, 1.0.5 |
|
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
| controller.period [TIME-PERIOD], '360sec' | | O, 1.0.5 |
|
The configuration key controller.period defines the length
of a controller period. (this is the time period, where the
controller collects data)
| controller.history-depth [NUMBER], '20' | | O, 1.0.5 |
|
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
| controller.log.only-bootstrap [BOOLEAN], 'yes' | | O, 1.0.6 |
|
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.
| controller.log.statistic-file | | O, 1.0.6 |
|
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
| web.balancer.log [BOOLEAN], 'yes' | | O, 1.0.6 |
|
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.
| web.controller.log [BOOLEAN], 'yes' | | O, 1.0.6 |
|
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
|
|
configuration