The default installation process (i.e. “configure;make;make install”) installs a configuration that demonstrates some of the things Yxorp can do. There are no complicated things necessary to run this configuration; it only needs a machine to run Yxorp and a machine (possibly the same) that runs browsers and can connect to the Yxorp machine.
The default configuration is also a starting point in this tutorial, which gives an overview of the things Yxorp can do.
This default configuration is described here in detail.
<?xml version="1.0"?> <yxorpconfig> <!-- Main yxorp configuration file --> <!-- where the log files go --> <log accesslog="/var/log/yxorpaccess" errorlog="/var/log/yxorperror" />
The first interesting line here is the <log> tag; it sets where the logfiles will go. Log formats are left at their defaults.
<!-- This is the tcp port the xml listener will run on --> <configlistener port="7780" ipaddress="127.0.0.1" />
The <configlistener> tag enables the configuration listener. This makes it possible to use online reconfiguration; i.e. you do not have to stop and restart Yxorp every time you make a change in the configuration. Also, the command “yxorpconfig -r” can be used to look at the actual configuration (including all defaults) that is running.
<!-- request rule that will check and modify a request -->
<rule id="rule1" type="request">
<![CDATA[
if (Host: ~/^[a-z\.]+$/) {
Host: = "yxorp.sourceforge.net";
} else if (Host: ~/^[0-9\.]+$/) {
reject("You are not allowed access through the IP address of this server");
} else {
Host: = "yxorp.sourceforge.net";
}
]]>
</rule>This <rule> tag defines the rule program that will be executed on receiving a request (to enable this, the rule must be referenced somewhere; usually this is done on the listener, so that any request comes in on the listener causes the rule to be run). The rule looks at the value of the Host: header; if it contains only letters and dots (as in most domain names), it changes the Host: header to “yxorp.sourceforge.net”. If however the Host: header contains numbers and dots (as in IP addresses), it rejects the request.
<!--the reject rule will be executed if something is wrong with the request--> <rule id="rule3" type="reject"> <![CDATA[ errorhtml="<html> <head> <title>Nicht Touchen, U only watchen das Blinkenlights!</title> </head> <body> <h1>Error "; errorhtml=concat(errorhtml, errorcode, " - ", rejectreason); errorhtml=concat(errorhtml, "</h1></body></html>"); Server: = "yxorp-x.x"; ]]> </rule>
This <rule> tag defines the reject rule, that is used whenever a request is rejected (either by the Yxorp code, or by the use of the reject function in a script). As with the request rule, it is normally set on the listener. This rule composes a customized error message by using special variables like errorhtml and errorcode. Note how the errorhtml variable is set; the string spans multiple lines.
<!-- the definitions for the listeners --> <listener id="test1" ipaddress="0.0.0.0" port="80" rule="rule1" rejrule="rule3" />
This bit defines the listener. Note especially the IP address; as it is set here, this will cause Yxorp to bind to all the available interfaces in the system. If you set a specific IP address, Yxorp will listen only on that address. Also note the rule settings; this sets the linking between the listener and the rules for the requests that come in on this listener.
<server id="yxorp.sourceforge.net" virtualserver="group1" /> <virtualserver id="group1" schedule="lru"> <real id="sf" /> </virtualserver> <realserver id="sf" ip="dns" inservice="yes" />
This bit defines what happens with the contents of the Host: header in a request. This value is first matched to a <server> definition. The one in this example maps to a <virtualserver> group (and will run a sorry rule if none of the servers in this group are available). The virtualserver group defines only one real server (so the schedule setting is superfluous). The last line defines the real server; note that it does not list an IP address but “dns”; this causes the Host: header to be resolved in DNS and contacted. This is useful for examples and testing, but do not use this for real, since it may have unintended consequences i.e. for security and performance. In this case it is very easy, because I don't have to update configurations and documentation if Sourceforge decide to change their IP addresses.
The complete configuration file for this example should have been installed by “make install” with the default configuration file name “yxorpconfig.xml”. you can also pick it up from http://yxorp.sourceforge.net/examples/yxorpconfig.xml
Start yxorp. Since release stable-1.23.2, the default is for yxorp to run as a daemon; if you give the command
yxorp
yxorp will start itself as a daemon process. If you want to stop the daemon, use the command
yxorp -K
or you can install one of the init.d scripts from the data directory and use your distribution's way of stopping and starting daemons.
If you want to look at lots of debugging output, and have debugging enabled in your build (the default for this is dependent whether or not you downloaded a development or stable release), you can set options like -X -ddddddd; this overrides the configured debug settings to show almost all output. You will need to define where the debug output goes with the <log> tag in the configuration, or run yxorp in the foreground with a command like
yxorp -N
If you did not change the default installation, and did not set -c <configfilename> as an option to yxorp, the configuration described in the paragraphs above should be active.
Verify it is working by pointing your favorite browser to http://localhost/ ; you should now get the Yxorp website that is really at http://yxorp.sourceforge.net/
In this step, we will merge the following bits in the active configuration:
<?xml version="1.0"?> <yxorpconfig> <!-- the definitions for the ssl listener --> <listener id="test1ssl" ipaddress="0.0.0.0" port="443" rule="rule1" rejrule="rule3" ssl="yes" certfile="yxorptest.pem" /> </yxorpconfig>
As you see above, this configuration snippet defines another listener, but with some added fields for SSL. The most important bit is the “ssl=yes” switch, that determines that this listener will actually expect SSL. The other important bit is the certfile definition; this is the filename that the certificate is stored in. Yxorp will try to read this file from the sysconfdir that has been set in by configure; usually this is something like /usr/local/etc or /etc.
The certificate should have been automatically generated during make install, but you can also use your own certificate.
The complete configuration file for this example is available in the Yxorp source tree in the data/examples directory, it is called add_ssl.xml. You can also pick it up from http://yxorp.sourceforge.net/examples/add_ssl.xml
If you stopped Yxorp after the step above, start it again. Apply the extra SSL configuration bits by running the command “yxorpconfig -c add_ssl.xml”.
Verify it is working by pointing your favorite browser to https://localhost/ . You should get a popup window from your browser about the certificate, since it is self-signed. Depending on your browser, you may also get a warning about nonsecure items on the page, this is because the Sourceforge logo on top of the Yxorp page is inserted with an absolute http URL, and thus is retrieved directly from the original Sourceforge site instead of being proxied by Yxorp.
A simple example of adding basic authentication is in the following configuration snippet:
<?xml version="1.0"?>
<yxorpconfig>
<rule id="rule1" type="request">
<![CDATA[
if (Host: ~/^[a-z\.]+$/) {
Host: = "yxorp.sourceforge.net";
} else if (Host: ~/^[0-9\.]+$/) {
reject("You are not allowed access through the IP address of this server");
} else {
Host: = "yxorp.sourceforge.net";
}
if (uri ~/^\/yxorpdoc.*$/) {
basic_auth_check("my-realm", "local");
}
]]>
</rule>
<basicauth realm=”my-realm” userid="aladdin" passwd="sesame" />
</yxorpconfig>Note that the source for rule1 is completely replaced. In the last if-statement, the regexp checks if the URI contains /yxorpdoc in the beginning; if it does, it will demand basic authentication by the function call to 'basic_auth_check("my-realm", "local")'. Basic_auth_check will reject the request if valid basic authentication credentials are not present in the request; thus, the reject rule we already had will be activated.
The basic authentication credentials that are accepted are defined in
<basicauth realm=”my-realm” userid="aladdin" passwd="sesame" />
The realm=”my-realm” portion in the definition must correspond to the first parameter in the basic_auth_check call. This allows you to define several “realms”, each of which may give access to different parts of your content. The userid/password combinations are unique within the same value of the realm, but not across realms; so the same userid and password may be defined multiple times in several realms.
If you stopped Yxorp after the step above, start it again. Apply the basic authentication configuration bits by running the command “yxorpconfig -c add_basicauth.xml”. Again, the file is in data/examples, or http://yxorp.sourceforge.net/examples/add_basicauth.xml
Verify it is working by pointing your favorite browser to http://localhost/ . This should work as before. Now point your browser at http://localhost/yxorpdoc-2.html and you should get a popup window asking for userid and password.
Now run the command “yxorpconfig -r”. This will read the complete configuration from Yxorp as it is currently active. You will see lots of configuration statements that were not in the files we've seen so far; these are defaults that Yxorp assumes.
Look for the line saying:
<basicauth realm=”my-realm” base64="YWxhZGRpbjpzZXNhbWU=" />
This is the internal representation that Yxorp uses for basic authentication credentials. Note that this is not any form of encryption (which would not make a lot of sense since basic authentication is not very secure), but the base64-encoded form of userid and password. You can specify either the base64 or userid/password forms in a configuration.
Some sites use other headers than those described in RFC2616 and later; also, Yxorp does not necessarily know about all headers in all RFC's (since there are lots). Yxorp discards headers it does not know about. If however you need one of these headers, you can add it to Yxorp's table of headers using the following example:
<?xml version="1.0"?>
<yxorpconfig>
<globalconfiguration>
<header id="X-Pad:" xlateid="X_Pad:" client="1" server="1" reject="0"
check="rfc2616-text" maxlen="80" />
</globalconfiguration>
</yxorpconfig>In this example, a header named “X-Pad” is added (this header is at the time of writing sent out by Sourceforge's project web servers, where Yxorp's website resides).
Refer to the configuration web pages for full detail on the settings that you can specify for a header. One thing to look at is the check parameter, which sets the character set that Yxorp will check the contents of the header to, and the reject parameter, which determines what will happen if a header does not conform to what Yxorp thinks it should.
Testing the effect of the change above is a bit harder than with the previous examples, since I'm not exactly clear on when Sourceforge's servers insert this header, and some browsers don't allow you to look at the headers. One definite way would be to trace the traffic between your browser and Yxorp with Ethereal, for example.
As before, apply the change by the command yxorpconfig -c add_headers.xml, find the file in data/examples or on http://yxorp.sourceforge.net/examples/add_headers.xml
To use load balancing, we need to add a second web server (i.e., a “real server”) to the configuration and setup the “virtualserver” to know about this second real server. How this is done is demonstrated by the following configuration snippet:
<?xml version="1.0"?> <yxorpconfig> <virtualserver id="group1" schedule="lru"> <real id="sf" /> <real id="sf2" /> </virtualserver> <realserver id="sf" ip="dns" inservice="yes" /> <realserver id="sf2" ip="dns" inservice="yes" /> </yxorpconfig>
Note that what this does is just duplicate the definition of the original real server. In a real example, you would obviously define different servers (otherwise, what's the point of load balancing), and use IP addresses instead of the “dns” testing shortcut.
Apply the change: yxorpconfig -c add_loadbalancing.xml from data/examples or http://yxorp.sourceforge.net/examples/add_loadbalancing.xml and access the site a couple of times via http://localhost/ . Then look at the access log file (usually in /var/log/yxorpaccess) and look for the realserver names in the log entries, these should look similar to these:
127.0.0.1 27340 [09/Jan/2006:17:39:17 +0100] sf "GET http://yxorp.sourceforge.net/yxorpdoc-2_html_m34ac0a87.png" 200 501 15874 546 15836 501 299 546 261 737 127.0.0.1 27342 [09/Jan/2006:17:39:17 +0100] sf2 "GET http://yxorp.sourceforge.net/yxorpdoc-2_html_m64bcb189.png" 200 501 17568 546 17530 501 299 546 261 753 127.0.0.1 27346 [09/Jan/2006:17:39:17 +0100] sf2 "GET http://yxorp.sourceforge.net/yxorpdoc-2_html_1cb9e497.png" 200 500 17250 545 17212 500 299 545 261 744 127.0.0.1 27344 [09/Jan/2006:17:39:17 +0100] sf "GET http://yxorp.sourceforge.net/yxorpdoc-2_html_m5fd42.png" 200 498 32706 543 32668 498 299 543 261 945
As you see, both realservers are scheduled.
You can now have a look at the realserver status with the yxorprealserver command, as follows:
# yxorprealserver -v sf : inservice available config sf2 : inservice available config #
Other options on the yxorprealserver command allow you to manually set a server out-of-service or unavailable:
# yxorprealserver -v -u sf sf : inservice unavailable config sf2 : inservice available config #
Note the difference between inservice and available; Yxorp can automatically set a realserver out-of-service if it fails to respond to a connection several times in a row (and Yxorp will also automatically set it inservice again if it responds to a new connection that is scheduled by the auto-wakeup mechanism). Yxorp will however not change the available/unavailable flag.
There is another difference between inservice and available, this has to do with sticky load balancing. See the example on that for a discussion.
One last thing to try with this setup is what happens if you set both realservers out-of-service. Note the ugly message a client gets in this case. This is where the sorry rule comes in.
If no servers in a virtualserver group are available, it is possible to let a sorry rule run. A sorry rule can generate a custom HTML page, as we did above with the reject rule. However, especially with a complex layout for a sorry page, this can be a lot of work, and another technique is possible that we will see in the example below:
<?xml version="1.0"?>
<yxorpconfig>
<rule id="sorryrule" type="sorry">
redirect("http://yxorp.sourceforge.net/noserver.html");
</rule>
<server id="yxorp.sourceforge.net" virtualserver="group1" sorry="sorryrule" />
</yxorpconfig>The sorry rule just generates a redirect (i.e., a 307 Temporary Redirect status code, with a Location: header set to http://yxorp.sourceforge.net/noserver.html.
Also note that the definition of the sorryrule is on the server level, not on the virtualserver. This is because it may be necessary to have a different sorry page for each server definition, even though these servers may share the virtualserver group.
As above, activate the file add_sorryrule.xml from data/examples or http://yxorp.sourceforge.net/examples/add_sorryrule.xml, then make sure both realservers are set out-of-service or unavailable, and then try http://localhost/ and if all has gone well, you should now be redirected to http://yxorp.sourceforge.net/noserver.html.
Sticky load balancing is the technique where many clients are distributed evenly over a group of servers, but each request from a specific client is always sent to the same server, i.e. the load balancer “remembers” the association between a client and a server. This is necessary if an application runs on the webservers that is not stateless, and there is no other means of sharing the state over the servers. If you want to share state on the web/application server level, or if you want sticky load balancing, is a discussion that goes rather far beyond the scope of this tutorial.
Yxorp can do sticky load balancing, however, the implementation has some drawbacks compared to straight load balancing; at least, the total throughput of Yxorp will decrease somewhat. Also, the table in which the state mapping is maintained may grow large, especially if someone is doing denial-of-service attacks on your site (or worse, targeted attacks tailored to let Yxorp's tables grow).
The way Yxorp keeps track of which client is which is by setting a session cookie. This cookie will normally be named “yxorpstate”, and will be valid until the end of the “session” (in most cases, this is the lifetime of the browser instance). The cookie value will be a randomly generated string like XL61DS0FPS4PLEDXUIBVIB8LLU301IZX1ZOB1WVWSOW9SWNMG2CEXGZFW6CQ1L.
The configuration changes to enable sticky load balancing are simple:
<?xml version="1.0"?> <yxorpconfig> <virtualserver id="group1" sticky="yes"> <real id="sf" /> <real id="sf2" /> </virtualserver> </yxorpconfig>
In fact, the only change this makes is the “sticky=yes” part.
Activate the configuration from http://yxorp.sourceforge.net/examples/add_sticky.xml or data/examples. Then, point your browser to http://localhost/ and cause a couple of hits.
Then, use the yxorpclientstate command as follows:
# yxorpclientstate <yxorpclientstate> <clientstate id="IQ3AHIIPFKEDO1SQUQ1H67CPX68NMFSUARUWQESXGEXGGQT9TU74DJYU92C7V0" clientip="127.0.0.1" sticky="1" lastactive="[09/Jan/2006:23:52:37 +0100]" hitcount="1" toclient="9850" fromclient="451" toserver="9850" fromserver="451" > <stickymap server="yxorp.sourceforge.net" realserver=sf2" /> </clientstate> <tablestats entries="1" tablebytesize="824" maxchainlength="1" tabletruncated="0" /> </yxorpclientstate> #
As you see, the value of the state cookie is linked to a lot of information. For this example, note the stickymap tag; this links requests for a certain server to a specific realserver.
This gets more complicated if you have more servers defined. Normally, the clients (browsers) will get a different state cookie for each server (or, rather, what the client thinks is a server). It is possible to use the same cookie for several servers by putting the servers in a cookie domain, see the setcookiedomain function call for details on this. If cookiedomains are used, the same cookie and state can be used for the servers sharing the domain (in this case you would see multiple stickymap tags in the same clientstate tag).
Client states are cleaned up automatically by Yxorp, see the global configuration settings.
Similar to the sorry rules we already saw, there is also the case in sticky load balancing when the mapped server is no longer available. In this case, Yxorp has a special rule called “stickyloss” that handles what happens with the request.
<?xml version="1.0"?>
<yxorpconfig>
<rule id="stickylossrule" type="stickyloss">
redirect("http://yxorp.sourceforge.net/stickyloss.html");
</rule>
<server id="yxorp.sourceforge.net" stickyloss="stickylossrule" />
</yxorpconfig>You would typically want a stickyloss rule to explain that clients have lost their state in an application, and need to retry to another server.
Activate the configuration from http://yxorp.sourceforge.net/examples/add_stickyloss.xml or data/examples. Use the yxorprealserver command to check if you need to restore the realservers to available and inservice after the experiments in the previous example. Then, point your browser to http://localhost/ and cause a couple of hits.
Then, use the yxorpclientstate command as follows:
# yxorpclientstate <yxorpclientstate> <clientstate id="PQJZNM51ELUXTKDNECCZQIRLC1ME0BZBALX68AWBLMKIE978NV22YEXWLWMKV4" clientip="127.0.0.1" sticky="1" lastactive="[10/Jan/2006:00:35:36 +0100]" hitcount="3" toclient="29584" fromclient="1763" toserver="29584" fromserver="1763" > <stickymap server="yxorp.sourceforge.net" realserver=sf" /> </clientstate> <tablestats entries="1" tablebytesize="824" maxchainlength="1" tabletruncated="0" /> </yxorpclientstate> #
Note the server that is mapped (in this case it is sf), and set it out-of service as follows:
# yxorprealserver -v -o sf sf : out-of-service available config sf2 : inservice available config #
and see what happens if you reload your browser (remember, it needs to be the same window as before, since Yxorp's state cookie should only be valid in a single browser instance). If everything is correct, nothing apparently has changed. Why? Because we just set the sf server out-of-service; it will not be eligible for new sticky mappings, or normal scheduling, but it will continue to serve for valid states.
Next, to see the stickylossrule in action, we will do:
# yxorprealserver -v -u sf sf : out-of-service unavailable config sf2 : inservice available config #
If you reload your browser again, you should now see the effect of the stickyloss rule.