crossroads.conf(7) - Linux man page

e-tunity

Name

crossroads.conf - Crossroads configuration

Synopsis

This manpage describes the configuration of Crossroads, normally the file /etc/crossroads.conf. Crossroads can however be started with a flag -c to overrule this name.

Description

The configuration that crossroads uses is normally stored in the file /etc/crossroads.conf. This location can be overruled using the command line flag CW-c.

This section explains the syntax of the configuration file, and what all settings do.

General language elements

This section describes the general elements of the crossroads configuration language.

Empty lines and comments

Empty lines are of course allowed in the configuration. Crossroads recognizes three formats of comment:

o
C-style, between CW/* and CW*/,
o
C++-style, starting with CW// and ending with the end of the text line.

Simply choose your favorite editor and use the comment that 'looks best'.\ (I favor C or C++ comment. My favorite editor emacs can be put in CWcmode and nicely highlight what's comment and what's not. And as a bonus it will auto-indent the configuration!)

Preprocessor directives

Similar to C or C++, the Crossroads grammar knows CW#include and CW#define. Both directives must start at the first column of the line (ie., the CW# sign must occur at the leftmost line position).

o
CW#include CW"filenameCW" includes the stated file name at the place of the statement.
o
CW#define SYMBOL DEFINITION defines SYMBOL as placeholder for DEFINITION.

For example, one may use the configuration: 

#define SERVICEPORT 80
service web {
    port SERVICEPORT;
    .
    . /* More statements follow here */
    .
}
The CWport statement is then read as CWport 80.

The statement CW#define can also be very nicely used when trying out Crossroads configurations. Crossroads has a statement CWverbosity CWtrue that causes debugging information to be logged. Once a configuration has proven to work, you'll most likely want CWverbosity CWfalse so that overhead due to logging is avoided. This can be easily implemented using CW#define: 

/* Set DEBUG to true or false;
 * true   is for testing purposes,
 * false  is for production */
#define DEBUG true
service web {
    verbosity DEBUG;
    .
    . /* More statements follow here */
    .
}
Keywords, numbers, identifiers, generic strings

In a configuration file, statements are identified by keywords, which are reserved words. The list of the keywords of the Crossroads grammar is: CWservice CWport CWverbosity CWmaxconnections CWtype CWany CWhttp CWbackend CWserver CWbindto CWconnectiontimeout CWon CWoff CWdispatchmode CWroundrobin CWrandom CWbyduration CWbysize CWbyconnections CWbyorder CWbyclientip CWover CWdecay CWrevivinginterval CWcheckinterval CWretries CWshmkey CWweight CWonstart CWonfail CWbacklog CWthroughputlog CWtrafficlog CWstickycookie CWaddclientheader CWsetclientheader CWappendclientheader CWaddserverheader CWsetserverheader CWappendserverheader CWallowfrom CWdenyfrom CWallowfile CWdenyfile CWexternalhandler CWuseraccount CWonend CWheaderinspection CWdeep CWshallow CWstate CWavailable CWunavailable CWdown

Many keywords require an identifier as the argument. E.g, a service has a unique name, which must start with a letter or underscore, followed by zero or more letters, underscores, or digits. E.g., in the statement CWservice myservice, the keyword is CWservice and the identifier is CWmyservice.

Other keywords require a numeric argument. Crossroads knows only non-negative integer numbers, as in CWport 8000. Here, CWport is the keyword and CW8000 is the number.

Yet other keywords require 'generic strings', such as hostname specifications or system commands. Such generic strings contain any characters (including white space) up to the terminating statement character CW;. If a string must contain a semicolon, then it must be enclosed in single or double quotes:

o
CWThis is a string; is a string that starts at CWT and ends with CWg
o
CW"This is a string"; is the same, the double quotes are not necessary
o
CW"This is ; a string"; has double quotes to protect the inner ;

Finally, an argument can be a 'boolean' value. Crossroads knows CWtrue, CWfalse, CWyes, CWno, CWon, CWoff. The keywords CWtrue, CWyes and CWon all mean the same and can be used interchangeably; as can the keywords CWfalse, CWno and CWoff.

Service definitions

Service definitions are blocks in the configuration file that state what is for each service. A service definition starts with CWservice, followed by a unique identifier, and by statements in CW{ and CW}. For example: 

// Definition of service 'www':
service www {
    ...
    ... // statements that define the
    ... // service named 'www'
    ...
}
The configuration file can contain many service blocks, as long as the identifying names differ. The following list shows possible statements. Each statement must end with a semicolon, except for the CWbackend statement, which has is own block (more on this later).

port - Specifying the listen port

Description:
The CWport statement defines to which TCP port a service 'listens'. E.g. CWport 8000 says that this service will accept connections on port 8000.
Multiple services in one configuration cannot use the same port
number, unless they both bind to specific (and different) IP addresses. See also the CWbindto statement.
Syntax:
CWport number
Default:
There is no default. This is a required setting.

type - Defining the service type

Description:
The CWtype statement defines how crossroads handles the stated service. There are currently two types: CWany and CWhttp. The type CWany means that crossroads doesn't interpret the contents of a TCP stream, but only distributes streams over back ends. The type CWhttp means that crossroads has to analyze what's in the messages, does magical HTTP header tricks, and so on -- all to ensure that multiple connections are treated as one session, or that the back end is notified of the client's IP address.
Unless you really need such special features, use the type CWany (the
default), even for HTTP protocols.
Syntax:
CWtype specifier, where specifier is CWany or CWhttp
Default:
CWany

headerinspection - are all HTTP headers inspected

Description:
The CWheaderinspection directive defines whether Crossroads must inspect all HTTP headers that are seen on one TCP connection, or only the first ones. There are two possible values for this directive: CWdeep and CWshallow. In CWdeep mode, all information that is seen on the TCP link is monitored and parsed, and all HTTP header blocks are analyzed and subject to directives such as CWaddclientheader. In CWshallow mode, only the first header block that the server sends, and the first header block that forms the server's answer, are analyzed.
Syntax:
CWheaderinspection specifier, where specifier is CWdeep or CWshallow
Default:
CWdeep

bindto - Binding to a specific IP address

Description:
The CWbindto statement is used in situations where crossroads should only listen to the stated port at a given IP address. E.g., CWbindto 127.0.0.1 causes crossroads to 'bind' the service only to the local IP address. Network connections from other hosts won't be serviced. By default, crossroads binds a service to all presently active IP addresses at the invoking host.
Syntax:
CWbindto address, where address is a numeric IP address, such as 127.0.0.1, or the keyword CWany.
Default:
CWany

verbosity - Controlling debug output

Description:
Verbosity statements come in two forms: CWverbosity on or CWverbosity off. When 'on', log messages to CW/var/log/messages are generated that show what's going on.\ (Actually, the messages go to CWsyslog(3), using facility CWLOG_DAEMON and priority CWLOG_INFO. In most (Linux) cases this will mean: output to CW/var/log/messages. On Mac OSX the messages go to CW/var/log/system.log.) The keyword CWverbose is an alias for CWverbosity.
Syntax:
CWverbosity setting or CWverbose setting, where setting is CWtrue, CWyes or CWon to turn verbosity on; or CWfalse, CWno, CWoff to turn it off.
Default:
CWoff

dispatchmode - How are back ends selected

Description:
The dispatch mode controls how crossroads selects a back end from
a list of active back ends. The below text shows the bare
syntax. See section ?? for a textual explanation.
The settings can be:
o
CWdispatchmode roundrobin: Simply the 'next in line' is chosen. E.g, when 3 back ends are active, then the usage series is 1, 2, 3, 1, 2, 3, and so on.
Roundrobin dispatching is the default method, when no
CWdispatchmode statement occurs.
o
CWdispatchmode random: Random selection. Probably only for stress testing, though when used with weights (see below) it is a good distributor of new connections too.
o
CWdispatchmode bysize [ over connections CW]: The next back end is the one that has transferred the least number of bytes. This selection mechanism assumes that the more bytes, the heavier the load.
The modifier CWover connections is optional. (The square
brackets shown above are not part of the statement but indicate optionality.) When given, the load is computed as an average of the last stated number of connections. When this modifier is absent, then the load is computed over all connections since startup.
o
CWdispatchmode byduration [ over connections CW]: The next back end is the one that served connections for the shortest time. This mechanism assumes that the longer the connection, the heavier the load.
o
CWdispatchmode byconnections: The next back end is the one with the least active connections. This mechanism assumes that each connection to a back end represents load. It is usable for e.g. database connections.
o
CWdispatchmode byorder: The first back end is selected every time, unless it's unavailable. In that case the second is taken, and so on.
o
CWdispatchmode byclientip: The client's IP address is 'hashed' into a number, which is used to pick a back end. The same client IP address will therefore always be dispatched to the same back end. When the back end of choice is down, CWdispatchmode byconnections is used.
o
CWdispatchmode externalhandler program arguments: This is a special mode, where an external program is delegated the responsibility to say which back end should be used next. In this case, Crossroads will call the external program, and this will of course be slower than one of the 'built-in' dispatch modes. However, this is the ultimate escape when custom-made dispatch modes are needed.
The dispatch mode that uses an CWexternalhandler is
discussed separately in section ??.
The selection algorithm is only used when clients are serviced that
aren't part of a sticky HTTP session. This is the case during:
o
all client requests of a service type CWany;
o
new sessions of a service type CWhttp.
When type CWhttp is in effect and a session is underway, then the
previously used back end is always selected -- regardless of dispatching mode.
Your 'right' dispatch mode will depend on the type of service. Given
the fact that crossroads doesn't know (and doesn't care) how to estimate load from a network traffic stream, you have to choose an appropriate dispatch mode to optimize load balancing. In most cases, CWroundrobin or CWbyconnections will do the job just fine.
Syntax:
CWdispatchmode mode (see above for the modes), optionally followed by CWover number, or when the mode is CWexternalhandler, followed by program.
Default:
CWroundrobin

revivinginterval - Back end wakeup calls

Description:
A reviving interval definition is used when Crossroads determines that a back end is temporarily unavailable. This will happen when:
o
The back end cannot be reached (network connection fails);
o
The network connection to the back end suddenly dies.
Once a reviving interval is set, Crossroads will periodically
check the unavailable back end(s) to see whether they have woken up.
An example of the definition is CWrevivinginterval 10. When this
reviving interval is given, crossroads will check each 10 seconds whether unavailable back ends have woken up yet.
Syntax:
o
CWrevivinginterval number;
o
CWrevivinginterval number CWexternalhandler
program arguments;
The first form connects to a back end server. If the connection
succeeds, then the back end is considered available. The second
form activates an external program (see section
?? for a description). The back end is marked
available if the program's exit status is zero.
Default:
0 (no wakeup calls)

checkinterval - Periodic back end checks

Description:
When a check interval is stated, Crossroads will periodically probe back ends to determine whether available back ends are still there, and to see whether unavailable back ends have woken up yet.
An example is CWcheckinterval 10. When this is stated,
Crossroads will probe all back ends each 10 seconds.
Syntax:
o
CWcheckinterval number;
o
CWcheckinterval number CWexternalhandler program arguments; The first form checks bhy connecting to the back end server. If the connection succeeds, then the back end is considered available; otherwise the back end is considered unavailable.
The second form activates an external program (see section
?? for a description). The back end is considered
available if the program's exit status is zero; otherwise it is considered unavailable.
Default:
0 (no periodic checks)

maxconnections - Limiting concurrent clients at service level

Description:
The maximum number of connections is specified using CWmaxconnections. There is one argument; the number of concurrent established connections that may be active within one service.
'Throttling' the number of connections is a way of preventing Denial of
Service (DOS) attacks. Without a limit, numerous network connections may spawn so many server instances, that the service ultimately breaks down and becomes unavailable.
Syntax:
CWmaxconnections number, where the number specifies the maximum of concurrent connections to the service.
Default:
0, meaning that all connections will be accepted.

backlog - The TCP Back Log size

Description:
The TCP back log size is a number that controls how many 'waiting' network connections may be queued, before a client simply cannot connect. The syntax is e.g. CWbacklog 5 to cause crossroads to have 5 waiting connections for 1 active connection. The backlog queue shouldn't be too high, or clients will experience timeouts before they can actually connect. The queue shouldn't be too small either, because clients would be simply rejected. Your mileage may vary.
Syntax:
CWbacklog number
Default:
0, which takes the operating system's default value for socket back log size.

shmkey - Shared Memory Access

Description:
Different Crossroads invocations must 'know' of each others activity. E.g, CWcrossroad status must be able to get to the actual state information of all running services. This is internally implemented through shared memory, which is reserved using a key.
Normally crossroads will supply a shared memory key, based on the
service name. In situations where this conflicts with existing keys (of other programs, having their own keys), you may supply a chosen value.
The actual key value doesn't matter much, as long as it's unique
and as long as each invocation of crossroads uses it.
Syntax:
CWshmkey number
Default:
0, which means that crossroads will 'guess' its own key, based on the service name.

allow* and deny* - Allowing or denying connections

Description:
Crossroads can allow or deny connections based on the IP address of a client. There are four directives that are relevant: CWallowfrom, CWallowfile, CWdenyfrom and CWdenyfile.
When using CWallowfrom and
CWdenyfrom then the IP addresses to allow or deny connections are stated in /etc/crossroads.conf. When using CWallowfile and CWdenyfile the allow or deny connections are stated in a separate file.
When CWallow* directives are used, then all connections are denied
unless they match the stated allowed IP's. When CWdeny* directives are used, then all connections are allowed unless they match the stated disallowed IP's. When denying and allowing is both used, then the Crossroads checks the deny list first.
The statements CWallowfrom and CWdenyfrom are followed by a
list of filter specifications. The statements CWallowfile and CWdenyfile are followed by a filename; Crossroads will read filter specifications from those external files. In both cases, Crossroads obtains filter specifications and places them in its lists of allowed or denied IP addresses. The difference between specifying filters in /etc/crossroads.conf or in external files, is that Crossroads will reload the external files when it receives signal 1 (CWSIGHUP), as in CWkillall -1 crossroads.
The filter specifications must obey the following syntax: they
are series of space-separated strings, consisting of up to four numbers ranging from 0 to 255 and separated by a decimal sign. Optionally a slash follows, with a bitmask which is also a decimal number. For example, CW127.0.0/24 10/8 192.168.2.1 is a setting that consists of three specifiers.
This is probably best explained by a few examples:
o
CWallowfrom 10/8; will allow connections from CW10.*.*.* (a full Class A network). The mask CW/8 means that the first 8 bits of the number (ie., only the CW10) are significant. On the last 3 positions of the IP address, all numbers are allowed. Given this directive, client connections from e.g. 10.1.1.1 and 10.2.3.4 will be allowed.
o
CWallowfrom 10.3/16; will allow all IP addresses that start with CW10.3. The first 16 bits (i.e., the first 2 numbers) are significant, the rest doesn't matter.
o
CWallowfrom 10.3.1/16; is the same as above. The third byte of the IP address is superfluous because the netmask specifies that only the first 16 bits (2 numbers) are taken into account.
o
CWallowfrom 10.3.1.15; allows traffic from only the specified IP address. There is no bitmask; all four numbers are relevant.
o
CWallowfrom 10.3.1.15 10.2/16; allows traffic from one IP address CW10.3.1.15 or from a complete Class B network CW10.2.*.*
o
CWallowfile /tmp/myfile.txt; in combination with a file CW/tmp/myfile.txt, with the contents CW10.3.1.15 10.2/16, is the same as above.
When using ttt(allowfrom) and CWdenyfrom, separate specifiers
can be stated in one statement (separated by whitespace), or the whole statement can be repeated. E.g., the following two alternatives have the same effect:
/* Alternative 1: */allowfrom 10/8 192.168.1/24;/* Alternative 2: */allowfrom 10/8;allowfrom 192.168.1.24;Syntax:
o
CWallowfrom filter-specificication(s)
o
CWdenyfrom filter-specificication(s)
o
CWallowfile filename
o
CWdenyfile filename
Default:
In absence of these statements, all client IP's are accepted.

useraccount - Limiting the effective ID of external processes

Description:
Using the directive CWuseraccount, the effective user and group ID can be restricted. This comes into effect when Crossroads runs external commands, such as:
o
Hooks for CWonstart, CWonend or CWonfail;
o
External dispatchers, when CWdispatchmode externalhandler is in effect. Once a user name for external commands is specified, Crossroads assumes the associated user ID and group ID before running those commands.
Syntax:
CWuseraccount username
Default:
None; when unspecified, external commands are run with the ID that was in effect when Crossroads was started.

Backend definitions

Inside the service definitions as are described in the previous section, backend definitions must also occur. Backend definitions are started by the keyword CWbackend, followed by an identifier (the back end name) , and statements inside CW{ and CW}: 

service myservice {
    ...
    ... // statements that define the
    ... // service named 'myservice'
    ...
    backend mybackend {
        ...
        ... // statements that define the
        ... // backend named 'mybackend'
        ...
    }
}
Each service definition must have at least one backend definition. There may be more (and probably will, if you want balancing and fail over) as long as the backend names differ. The statements in the backend definition blocks are described in the following sections.

Some directives (CWstickycookie etc.) only have effect when Crossroads treats the network traffic as a stream of HTTP messages; i.e., when the service is declared with CWtype http. Incase of CWtype any, the HTTP-specific directives have no effect.

server - Specifying the back end address

Description:
Each back end must be identified by the network name (server name) where it is located. For example: CWserver 10.1.1.23, or CWserver web.mydomain.org. A TCP port specifier can follow the server name, as in CWserver web.mydomain.org:80. Note that resolved host names can be cached by Crossroads. (The DNS cache timeout can be controlled using the invocation flag CW-d.)
Syntax:
o
CWserver servername, where servername is a network name or IP address. In this case a separate CWport statement must be used to define the TCP port;
o
CWserver servername:port
Default:
There is no default. This is a required setting.

port - Specifying a back end port

Description:
Back ends must be known by their host name and a port. Both can be simultaneously specified in a CWserver statement. When the CWserver statement specifies a host name only, then a CWport statement must be used to specify the port.
Syntax:
CWport number
Default:
There is no default for the port. It must be specified either using CWserver or using CWport.

verbosity - Controlling verbosity at the back end level

Description:
Similar to CWservice specifications, a CWbackend can have its own verbosity (CWon or CWoff). When CWon, traffic to and fro this back end is reported.
Syntax:
o
CWverbosity setting, or
o
CWverbose setting, where setting is CWtrue, CWyes or CWon, or CWfalse, CWno, CWoff to turn it off.
Default:
CWoff

retries - Specifying allowed failures

Description:
Back ends that are 'flaky' or on a less reliable network can be marked as unavailable after not just one failure, but after e.g. three. You can use this configuration if you suspect that spurious errors cause otherwise 'good' back ends to be marked as unavailable, while they in fact still could be used.
Syntax:
CWretries number; where number is the threshold of bad connections. Once exceeded, Crossroads will mark a back end as unavailable.
Default:
1; a back end is assumed to be unavailable after the first bad connection.

weight - When a back end is more equal than others

Description:
To influence how backends are selected, a backend can specify its 'weight' in the process. The higher the weight, the less likely a back end will be chosen. The default is 1.
The weighing mechanism only applies to the dispatch modes
CWrandom, CWbyconnections, CWbysize and CWbyduration. The weight is in fact a penalty factor. E.g., if backend A has CWweight 2 and backend B has CWweight 1, then backend B will be selected all the time, until its usage parameter is twice as large as the parameter of A. Think of it as a 'sluggishness' statement.
Syntax:
CWweight number; the higher the number, the more 'sluggish' a back end is
Default:
1; all back ends have equal weight.

decay - Levelling out activity of a back end

Description:
To make sure that a 'spike' of activity doesn't influence the perceived load of a back end forever, you may specify a certain decay. E.g, the statement CWdecay 10 makes sure that the load that crossroads computes for this back end (be it in seconds or in bytes) is decreased by 10% each time that an other back end is hit. Decays are not applied to the count of concurrent connections.
This means that when a given back end is hit, then its usage data
of the transferred bytes and the connection duration are updated using the actual number of bytes and actual duration. However, when a different back end is hit, then the usage data are decreased by the specified decay.
Syntax:
CWdecay number, where number is a percentage that decreases the back end usage data when other back ends are hit.
Default:
0, meaning that no decay is applied to usage statistics.

state - Setting an initial back end state

Description:
Using the CWstate directive a back end can be 'primed' with an initial state. The keyword CWstate can be followed by CWavailable, CWunavailable or CWdown. Back ends marked CWunavailable are excluded as candidates, but are checked when a CWrevivinginterval or a CWcheckinterval is used. Back ends marked CWdown are excluded and never re-checked.
Syntax:
o
CWstate specifier CW;
o
where specifier is one of CWavailable, CWunavailable or CWdown
Default:
CWavailable, meaning that a back end is a candidate for initial dispatching.

onstart, onend, onfail - Action Hooks

Description:
The three directives CWonstart, CWonend and CWonfail can be specified to start system commands (external programs) when a connection to a back end starts, fails or ends:
o
CWonstart commands will be run when Crossroads successfully connects to a back end, and starts servicing;
o
CWonend commands will be run when a (previously established) connection stops;
o
CWonfail commands will be run when Crossroads tries to contact a back end to serve a client, but the back end can't be reached.
The format is always CWontype command. The command
is an external program, optionally followed by arguments. The command is expanded according to the following table:
o
CW%a is the availability of the current back end, when a current back end is established. CW%1a is the availability of the first back end (0 when unavailable, 1 if available); CW%2a is the availability of the second back end, and so on.
o
CW%b is the name of the current back end, when one is established. CW%1b is the name of the first back end, CW%2b of the second back end, and so on.
o
CW%e is the count of seconds since start of epoch (January 1st 1970 GMT). CW%60e is the count since start of epoch plus 60, so this is a 1 minute offset into the future.
o
CW%g is a "GMT-string" representation of the current time, in the format monthname, day year hh:mm:ss. This format is used in e.g. cookie expiry. CW%600g is the same representation but of a moment 600 seconds in the future (10 minutes).
o
CW%h is the host name of the current back end. CW%1h is the host name of the first back end, CW%2h of the second back end, and so on.
o
CW%p is the TCP port of the current back end. CW%1p is the TCP port of the first back end, CW%2p of the second back end, and so on.
o
CW%r is the IP address of the connecting client.
o
CW%s is the name of the current service that the client connected to.
o
CW%t is the current local time in ANSI format, in YYYY-MM-DD/hhh:mm:ss. CW%1800s is an ANSI stamp of a moment 1800 seconds in the future (half an hour).
o
CW%T is the current GMT time in ANSI format. CW%10T offsets this 10 seconds into the future.
o
CW%v is the Crossroads version.
o
CW%w is the weight factor of the current back end. CW%1w is the weight factor of the first back end, etc..
o
Any other chararacter following a CW% sign is taken literally; e.g. CW%z is just a z.
Syntax:
The syntax of the commands is as follows.
o
CWonstart commandline
o
CWonend commandline
o
CWonfail commandline
o
CWonsuccess commandline
Default:
There is no default. Normally no external programs are run upon connection, success or failure of a back end.

trafficlog and throughputlog - Debugging and Performance Aids

Description:
Two directives are available to log network traffic to files. They are CWtrafficlog and CWthroughputlog.
The CWtrafficlog statement causes all traffic to be logged in
hexadecimal format. Each line is prefixed by CWB or CWC, depending on whether the information was received from the back end or from the client.
The CWthroughputlog statement writes shorthand transmissions to
its log, accompanied by timings.
Syntax:
o
CWtrafficlog filename
o
CWthroughputlog filename
Default:
none

stickycookie - Back end selection with an HTTP cookie

Description:
The directive CWstickycookie value causes Crossroads to unpack clients' requests, to check for value in the cookies. When found, the message is routed to the back end having the appropriate CWstickycookie directive.
E.g., consider the following configuration:

service ... { ... backend one { ... stickycookie "BalancerID=first"; } backend two { ... stickycookie "BalancerID=second"; }}
When clients' messages contain cookies named CWBalancerID with
the value CWfirst, then such messages are routed to backend CWone. When the value is CWsecond then they are routed to the backend CWtwo.
There are basically to provide such cookies to a browser. First, a
back end can insert such a cookie into the HTTP response. E.g., the webserver of back end CWone might insert a cookie named CWBalancerID, having value CWfirst. Second, Crossroads can insert such cookies using a carefully crafted directive CWaddclientheader.
Syntax:
CWstickycookie cookievalue
Default:
There is no default.

HTTP Header Modification Directives

Description:
Crossroads understands the following header modification directives: CWaddclientheader, CWappendclientheader, CWsetclientheader, CWaddserverheader, CWappendserverheader, CWsetserverheader.
The directive names always consist of
ActionDestinationCWheader, where:
o
The action is CWadd, CWappend or CWinsert.
o
Action CWadd adds a header, even when headers with the same name already are present in an HTTP message. Adding headers is useful for e.g. CWSet-Cookie headers; a message may contain several of such headers.
o
Action CWappend adds a header if it isn't present yet in an HTTP message. If such a header is already present, then the value is appended to the pre-existing header. This is useful for e.g. CWVia headers. Imagine an HTTP message with a header CWVia: someproxy. Then the directive CWappendclientheader "Via: crossroads" will rewrite the header to CWVia: someproxy; crossroads.
o
Action CWset overwrites headers with the same name; or adds a new header if no pre-existing is found. This is useful for e.g. CWHost headers.
o
The destination is one of CWclient or CWserver. When the destination is CWserver, then Crossroads will apply such directives to HTTP messages that originate from the browser and are being forwarded to back ends. When the destination is CWclient, then Crossroads will apply such directives to backend responses that are shuttled to the browser.
The format of the directives is e.g. CWaddclientheader
"X-Processed-By: Crossroads". The directives expect one argument; a string, consisting of a header name, a colon, and a header value. As usual, the directive must end with a semicolon.
The header value may contain one of the following formatting
directives:
o
CW%a is the availability of the current back end, when a current back end is established. CW%1a is the availability of the first back end (0 when unavailable, 1 if available); CW%2a is the availability of the second back end, and so on.
o
CW%b is the name of the current back end, when one is established. CW%1b is the name of the first back end, CW%2b of the second back end, and so on.
o
CW%e is the count of seconds since start of epoch (January 1st 1970 GMT). CW%60e is the count since start of epoch plus 60, so this is a 1 minute offset into the future.
o
CW%g is a "GMT-string" representation of the current time, in the format monthname, day year hh:mm:ss. This format is used in e.g. cookie expiry. CW%600g is the same representation but of a moment 600 seconds in the future (10 minutes).
o
CW%h is the host name of the current back end. CW%1h is the host name of the first back end, CW%2h of the second back end, and so on.
o
CW%p is the TCP port of the current back end. CW%1p is the TCP port of the first back end, CW%2p of the second back end, and so on.
o
CW%r is the IP address of the connecting client.
o
CW%s is the name of the current service that the client connected to.
o
CW%t is the current local time in ANSI format, in YYYY-MM-DD/hhh:mm:ss. CW%1800s is an ANSI stamp of a moment 1800 seconds in the future (half an hour).
o
CW%T is the current GMT time in ANSI format. CW%10T offsets this 10 seconds into the future.
o
CW%v is the Crossroads version.
o
CW%w is the weight factor of the current back end. CW%1w is the weight factor of the first back end, etc..
o
Any other chararacter following a CW% sign is taken literally; e.g. CW%z is just a z.
The following examples show common uses of header modifications.
Enforcing session stickiness:
By combining CWstickycookie and CWaddclientheader, HTTP session stickiness is enforced. Consider the following configuration:
service ... { ... backend one { ... addclientheader "Set-Cookie: BalancerID=first; path=/"; stickycookie "BalancerID=first"; } backend two { ... addclientheader "Set-Cookie: BalancerID=second; path=/"; stickycookie "BalancerID=second"; }}
The first request of an HTTP session is balanced to either
backend CWone or CWtwo. The server response is enriched using CWaddclientheader with an appropriate cookie. A subsequent request from the same browser now has that cookie in place; and is therefore sent to the same back end where the its predecessors went.
The header which is sent to the client to inject a cookie, can
furthermore be expanded to specify a timeout:
addclientheader "Set-Cookie: BalancerID=second; path=/; expires=%1800g";
The format specifier CW%1800g outputs a GMT-string date 1800
seconds in the future (half an hour from now).
Hiding the server software version:
Many servers (e.g. Apache) advertize their version, as in CWServer: Apache 1.27. This potentially provides information to attackers. The following configuration hides such information:
service ... { ... backend one { ... setclientheader "Server: WWW-Server"; }}
Informing the server of the clients' IP address:
Since Crossroads sits 'in the middle' between a client and a back end, the back end perceives Crossroads as its client. The following sends the true clients' IP address to the server, in a header CWX-Real-IP:
service ... { ... backend one { ... setserverheader "X-Real-IP: %r"; }}
Keep-Alive Downgrading:
The directives CWsetclientheader and CWsetserverheader also play a key role in downgrading Keep-Alive connections to 'single-shot'. E.g., the following configuration makes sure that no Keep-Alive connections occur.
service ... { ... backend one { ... setserverheader "Connection: close"; setclientheader "Connection: close"; }}Syntax:
o
CWaddclientheader Headername: headervalue to add a header in the traffic towards the client, even when another header Headername exists;
o
CWappendclientheader Headername: headervalue to append headervalue to an existing header Headername in the traffic towards the client, or to add the whole header alltogether;
o
CWsetclientheader Headername: headervalue to overwrite an existing header in the traffic towards the client, or to add such a header;
o
CWaddserverheader Headername: headervalue to add a header in the traffic towards the server, even when another header Headername exists;
o
CWappendserverheader Headername: headervalue to append headervalue to an existing header Headername in the traffic towards the server, or to add the whole header alltogether;
o
CWsetserverheader Headername: headervalue to overwrite an existing header in the traffic towards the server, or to add such a header.
Default:
There is no default.

See Also

o
crossroads (1)
o
The full Crossroads documentation, in pdf and html format, distributed with the sources.

Author

Crossroads is written by Karel Kubat and is maintained by
Karel Kubat (karel@kubat.nl).