Configuration reference

Yxorp reads its configuration from an XML file at startup, and sets up it's internal representation of the configuration statements. While Yxorp is running, a new configuration file can be inserted into the running configuration; this may extend the configuration, but also replace parts of the original configuration. It is also possible to read the actual configuration from the running daemon.

Overview of the configuration file

The configuration statements are grouped; each group deals with a set of configuration items. These groups are:

• configlistener; this group deals with the TCP interface that is used to read or update the configuration in an active yxorp daemon;

• log; this group contains the statements that configure logging;

• listener; this group, that may occur more than once in a configuration, controls the proxy processing and sets the TCP ports that the yxorp daemon will listen to;

• rule; may occur multiple times and contains the rule programming language statements;

• threads; controls the settings that the yxorp daemon will use for worker threads;

• security; controls security settings;

• server; controls which (virtual or real) servers yxorp can send requests to;

• virtualserver; controls the groupings of servers that are used as loadbalancing or failover pools;

• realserver; controls the settings of real servers that are mapped from a server definition or a virtualserver pool;

• globalconfiguration; controls which settings the yxorp daemon uses for things like timers, retry limits to connect to servers, headers to process, etc;

• basicauth; sets which userid/password combinations are recognized for local basic authentication processing;

• debug; controls filtering of debug output messages. If yxorp is built with debugging support enabled, these filters may be used to selectively show some message types.

Syntax of the configuration file

The configuration file should be formatted as follows:

<?xml version="1.0"?>
<yxorpconfig>
<log>
... logging settings
</log>
<configlistener>
... config listener settings
</configlistener>
<rule id=”name” type=”request”>
... rule code
</rule
</yxorpconfig>

Configuration file contents

The configuration file must start as follows:

<?xml version="1.0"?>
<yxorpconfig>

and end as follows:

</yxorpconfig>

The other contents of the configuration file depend on what Yxorp functions you want to use. These are described in the next sections.

Configuring listeners

Listeners are the end point for sessions between a client and Yxorp. For Yxorp to do any useful work, at least one listener must be created.

There are two types of listener, corresponding to the two types of proxy: dissecting and tunneling. The dissecting proxy completely takes a request apart, may run all kinds of scripts on each part of the request, and then reassembles it and forwards it to a server. In contrast, a tunnel proxy does not do any processing on a request, but just forwards it as-is to a server. Which type of proxy is chosen depends on the definition in the listener; a listener may invoke either type of proxy, but not both.

A listener is created by setting a <listener> tag in the configuration. The <listener> tag takes the following attributes:

Reconfiguring

All attributes on a listener can be reconfigured on-line. If the socket attributes (port and ipaddress) are changed, Yxorp will close the current socket and bind to a new socket with the new settings. If the new socket is in use on the operating system level, this might take an extended period of time; if sessions or programs are active on the new socket, the socket may not become available at all, causing Yxorp to keep retrying to bind to the socket.

Example

The following example creates a dissect listener for IPv4 on the HTTP port, that will bind to the localhost interface (and thus only accept requests sent to the localhost address):

<listener 
	id=”www” 
	type=”4” 
	mode=”dissect”
	ipaddress=”127.0.0.1” 
	port=”80” 
	rule=”wwwreq” 
	resprule=”wwwresp” 
	rejrule=”wwwrej”
/>

The next example will create a tunnel listener using IPv6 on the HTTPS port, and connect to an IPv4 server on address 1.2.3.4:

<listener 
	id=”www” 
	type=”6” 
	mode=”tunnel”
	ipaddress=”fe80::210:1100:0123:4567” 
	port=”443” 
	tunneldest=”1.2.3.4” 
	tunnelport=”443” 
/>

Configuring servers

Yxorp uses the servers listed in the configuration as an abstraction layer for servers. A server can either directly map to a real server, or map to a virtual server for load balancing. If no servers are available, a special rule type called the 'sorry rule' is executed.

A server is identified by the name taken from the Host: header, and thus, normally the same as the domain part of the URL that was requested. If rule code is used to modify the Host: header value, the changed value is used. If the value in the Host: header does not correspond to any server, the request is rejected (by executing a reject rule, if one is specified; or by the default reject actions).

A server is created by setting a <server> tag in the configuration. The <server> tag takes the following attributes:

Reconfiguring

All attributes on a server can be reconfigured on-line.

Example

The following example creates a server that will map requests for a domain name (Host: header value) of yxorp.sourceforge.net to a virtual server named “servergroup1”. If none of the servers in the group is available, the sorry rule “sorryrule-yxorp” is invoked.

<server 
	id=”yxorp.sourceforge.net” 
	virtualserver=”servergroup1”
	sorry=”sorryrule-yxorp”
/>

The following example creates a server that will map requests for a domain name (Host: header value) of yxorp.sourceforge.net to a real server named “bigserver”:

<server 
	id=”yxorp.sourceforge.net” 
	realserver=”bigserver”
	sorry=”sorryrule-yxorp”
/>

Configuring virtual servers

The configuration settings for a virtual server list which real servers may be used to process a request. The virtualserver configuration also determines the scheduling algorithm to be used for load balancing.

Real servers will be excluded from the load balancing if they are out-of-service. If one of the real servers has been set out-of-service automatically, is is possible to have the virtualserver schedule a request to it occasionally, to determine whether it has become available again. This mechanism is called “real server wakeup”. This should work without disruption; if Yxorp is not able to connect to a server, another server will be connected after a short timeout.

A virtual server is created by setting a <virtualserver> tag in the configuration. Inside the virtualserver tag , the <real> tags are used to list the real servers. The <virtualserver> tag takes the following attributes:

The <real> tag takes the following attributes:

Reconfiguring

All attributes on a virtualserver can be reconfigured on-line. The list of real servers will by default be replaced.

Example

The following example creates a virtual server that will load balance requests over a group of three real servers, using the roundrobin scheduling algorithm, and automatically retrying to inservice servers that may have become unavailable:

<virtualserver
	id=”servergroup1”
	schedule=”roundrobin”
	wakeup=”auto”
	wakeupfrequency=”100”
 >
	<real id=”server1” />
	<real id=”server2” />
	<real id=”server3” />
</virtualserver>

Configuring real servers

The configuration settings for a real server define the attributes of actual servers.

A real server may be set out-of-service automatically if it fails to respond to requests.

A real server is created by setting a <realserver> tag in the configuration. The <realserver> tag takes the following attributes:

Reconfiguring

All attributes on a real server can be reconfigured on-line.

Example

The following example creates a real server. The initial state of the real server is inservice, that is, the server is presumed to be able to process requests; the server is also set available, so it will immediately be scheduled.

<realserver
	id=”bigserver”
	port=”80”
	ipaddress=”10.1.0.117” 
	inservice=”yes”
	available=”yes”
/>

Configuring rules

Rules are small programs written in a special programming language. Each rule contains exactly one such program, which can deal with a request or response. The rule language itself is described in a separate chapter.

A rule begins with a <rule> tag, and ends with a </rule> tag. The text space in between these tags are assumed to be the program source. The rule program source is compiled when the configuration file is read; syntax errors will be reported. The configuration process will abort if serious errors are detected.

Since the configuration file uses XML, and the rule language uses text constructs that may not be valid in “plain” XML, it is sensible to enclose all rules in <![CDATA[ ... ]]> tags.

The <rule> tag takes the following attributes:

Reconfiguring

All parts of a rule may be reconfigured.

Example

<rule id=”example” type=”request”>
<![CDATA[
// rule source
   host: = “yxorp.sourceforge.net”;
]]>
</rule>

Configuring logging

Yxorp logs to files. Normal requests are logged to the access log; requests denied (either by a rule or by Yxorp code) are logged to the error log; and rule programs may log information to another log file, called the trace log. Debugging messages may either be logged to stdout, or to a file.

The log file names are set as attributes on the <log> tag in the configuration file.

The <log> tag takes the following attributes:

Log entries in the access and error logs are formatted from a printf-like format string. Any normal text in the format string is simply copied to the log; tokens starting with '%' are interpreted as field names, and substituted with the field value. The format strings are set as subtags enclosed in the log tag; the format strings are set in the text space. The format for the access log is set using the <access-fmt> subtag; the format of the error log is set using the <error-fmt> subtag.

The default access log format is as follows:

%clientip %clientport %nsstart %realserver \"%method %protocol%host%uri\" %statuscode %fromclient %toclient %toserver %fromserver %clientreqhdr %clientrsphdr %serverreqhdr %serverrsphdr %elapsed

The default error log format:

%requestnumber %clientip %clientiplookup %clientport %nsstart %realserver \"%method http://%host%uri\" %statuscode %fromclient %toclient %toserver %fromserver %clientreqhdr %clientrsphdr %serverreqhdr %serverrsphdr %elapsed %rejectreason

The following tokens are available for formatting:

Reconfiguring

All of the log settings may be reconfigured. If the log file names are changed in the new configuration, the active log file will be closed, and a new file with the changed name will be created (as yxorp tries to log a message, so using this mechanism to rotate logfiles must be used with caution since yxorp may not have closed the logfiles immediately upon reconfiguring).

Example

The following example will create three log files, and set the formatting for the access log and the error log:

<log accesslog=”/var/log/yxorpaccess” errorlog=”/var/log/yxorperror” tracelog=”/var/log/yxorptrace”>
	<access-fmt>%clientip %nsend %method %host %uri %statuscode 	</access-fmt>
	<error-fmt>%clientip %rejectreason”</error-fmt>
</log>

The following example, assuming a config snippet generated by a script running from cron, will “rotate” the access log file to a new, daily log file:

<log accesslog=”/var/log/yxorpaccess.2004-Feb-29” />

Configuring a configuration listener

The configuration listener is a special interface into an active Yxorp daemon. It allows the configuration of Yxorp to be changed while Yxorp is active.

Normally, the configuration listener should be bound to IP address 127.0.0.1 and port 7780. This is done by setting the <configlistener> tag in the configuration file. Setting the IP address to 127.0.0.1 is recommended, because of security reasons; only change this if you are sure you know all the consequences.

You can also choose not to run a configuration listener; this is inherently more secure, but also less flexible. If no configuration listener is active, the yxorpconfig command can not be used to reconfigure Yxorp, or to read the current configuration; also, all other commands like yxorpclientstate and yxorprealserver will not work without a configuration listener.

Disable the configuration listener by omitting the <configlistener> tag, or by explicitly setting the port number to zero.

There can only be one configlistener in an Yxorp daemon; any attempt to define more than one configlistener will overwrite the previous configuration attributes.

The <configlistener> tag takes the following attributes:

Reconfiguring

It is not possible to reconfigure the configlistener.

Example

The followin example shows how to configure the configuration listener to use IP address 127.0.0.1 and port number 7780:

<configlistener ipaddress=”127.0.0.1” port=”7780” />

Configuring threads

Yxorp uses a thread pool for processing the requests. The behaviour and size of the thread pool can be configured by the <thread> tag.

The <thread> tag takes the following attributes:

Not all threads in an Yxorp process are counted for the thread pool size: the debug/log system, and each listener have their own dedicated thread that is not part of the thread pool.

Reconfiguring

It is possible to reconfigure threads; however, reducing 'max' will not lower the number of active threads.

Example

<threads initial=”20” minfree=”2” max=”100” />

Configuring security

Yxorp runs with reduced privileges on Solaris and Linux. Normally, binding to a port number lower than 1024 requires the process to run as root. Yxorp can release the root privileges and set parts of the process to run as a lower-privileged user. The way this works has significantly changed since version 0.19, it is now implemented using capabilities (Linux) and privileges (Solaris). For other platforms, you will either have to run Yxorp as root, or use non-privileged ports only.

For both Linux and Solaris, all privileges except the ones necessary for Yxorp are released. For Linux, the only remaining privilege is “cap_net_bind_service”; for Solaris, it is “PRIV_NET_PRIVADDR”.

Besides this, it is also possible to change the userid and group that Yxorp will run as; this has the added effect of securing access to the file system.

Another security setting is “chroot”; if this is set, yxorp will change root to the specified directory.

The <security> tag takes the following attributes:

Reconfiguring

It is not possible to reconfigure security settings.

Example

<security user=”65535” group=”65535” />

Configuring basic authentication

Yxorp can store a table of basic authentication credentials in its configuration. Currently this is the only way, but it is foreseen that other tables may be available in a future version.

Note that basic authentication is not very secure. To recover userid and password from the encoded form is trivial. Don't use userid's and passwords you also use for other systems.

The <basicauth> tag takes the following attributes:

Reconfiguring

It is possible to reconfigure all basic authentication settings.

Example

<basicauth realm=”mystuff” userid=”baas” passwd=”notsosecure” />

Configuring global settings

Global configuration settings are (as the name implies) global within a daemon (and thus govern all processing for all listeners).

The <globalconfiguration> tag takes the following attributes:

The header table

Also in the globalconfiguration section is the table of accepted headers. Only headers that appear in this table are processed by yxorp, or made available in the rule language. The standard headers in RFC2616 are included by default. The header table can be changed by including “<header>” tags in the globalconfiguration section.

The <header> tag takes the following attributes:

Reconfiguring

All global settings can be reconfigured. However, header entries, once they are created, may be modified but not completely removed (you can still set that the header will not be accepted though).

Example

The example below sets global configuration values, and updates the header table with the (custom) header “Example:”, which will be called “bad_example:” in the scripting language, is accepted from a client but not from a server; the maximum length is 1 byte, and nonconformance will lead to the request being rejected.

<globalconfiguration
                    maxchunksize="16777216"
                    maxserverconnectionattempts="3"
                    writetoclienttimeout="15000"
                    readfromclienttimeout="15000"
                    maxrealserverconnectfailuresbeforeoutservice="4"
                    connectservertimeout="5000"
                    readfromservertimeout="15000"
                    writetoservertimeout="15000"
                    tunnelwritetoservertimeout="5000"
                    tunnelwritetoclienttimeout="5000"
                    tunnelconnecttimeout="5000"
                    clientstatecleanupinterval="30"
                    clientstatecleanupmaxage="900"
                    >
<header id=”Example”
        xlateid=”bad_example”
        maxlen=”1”
        client=”1”
        server=”0”
        reject=”1”
        check=”reduced”
/>

</globalconfiguration>