Crossroads is a load balance and fail over utility for TCP based services. It is a daemon program running in user space, and features extensive configurability, polling of back ends using 'wakeup calls', detailed status reporting, 'hooks' for special actions when backend calls fail, and much more. Crossroads is service-independent: it is usable for HTTP(S), SSH, SMTP, DNS, etc.
Using this approach, crossroads serves as load balancer and fail over utility. Crossroads will very likely not be as reliable as hardware based balancers, since it always will require a server to run on. This server, in turn, may become a new Single Point of Failure (SPOS). However, in situations where cost efficiency is an issue, crossroads may be a good choice. Furthermore, crossroads can be deployed in situations where a hardware based balancing already exists and augmenting service reliability is needed. Or, crossroads may be run off a diskless system, which again improves reliability of the underlying hardware.
This document describes how to use crossroads, how to configure it in order to increase the reliability of your systems, and how to compile the program from its sources. This document is also available in PDF format.
As quick reference, here are some important URL's for Crossroads:
Crossroads is distributed as-is, without assumptions of fitness or usability. You are free to use crossroads to your liking. It's free, and as with everything that's free: there's also no warranty.
You are allowed to make modifications to the source code of crossroads, and you are allowed to (re)distribute crossroads, as long as you include this text, all sources, and if applicable: all your modifications, with each distribution.
While you are allowed to make any and all changes to the sources, I would appreciate hearing about them. If the changes concern new functionality or bugfixes, then I'll include them in a next release, stating full credits.
Throughout this document, the following terms are used: (Many more meanings of the terms will exist -- yes, I am aware of that. I'm using the terms here in a very strict sense.)
HTTP/1.0
500 Server Error then crossroads will see this as a
succesful session, though the user behind a browser may
think otherwise.
/etc/crossroads.conf (the default configuration file). It
supports a number of flags (e.g., to overrule the location of the
configuration file). The actual usage information is always obtained
by typing crossroads without any arguments. Crossroads then
displays the allowed arguments.
This section shows the basic usage.
crossroads start and crossroads stop are typical
actions that are run from system startup scripts. The
meaning is self-explanatory.
crossroads restart is a combination of the former
two. Beware that a restart may cause discontinuity in
service; it is just a shorthand for typing the 'stop' and
'start' actions after one another.
crossroad status reports on each running
service. Per service, the state of each back end is
reported.
crossroads tell service backend state is a
command line way of telling crossroads that a given back
end, of a given service, is in a given state. Normally
crossroads maintains state information itself, but by
using crossroads tell, a back end can be e.g. taken
'off line' for servicing.
crossroads services reports on the configured
services. In contrast to crossroads status, this
option only shows what's configured -- not what's up and
running. Therefore, crossroads services doesn't
report on back end states.
crossroads sampleconf shows a sample configuration on
screen. A good way of quicky viewing the configuration
file syntax, or of getting a start for your own
configuration /etc/crossroads.conf.
/etc/crossroads.conf. This location can be overruled using the
command line flag -c.
This section explains the syntax of the configuration file, and what all settings do.
This section describes the general elements of the crossroads configuration language.
3.1.1: Empty lines and comments
Empty lines are of course allowed in the configuration. Crossroads recognizes three formats of comment:
/* and */,
// and ending with the end
of the text line;
# 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 cmode and nicely highlight what's comment and what's
not. And as a bonus it will auto-indent the configuration!)
3.1.2: Keywords, numbers, identifiers, generic strings
In a configuration file, statements are identified by keywords,
such as service, verbosity. These are reserved words.
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 service myservice, the keyword is
service and the identifier is myservice.
Other keywords require a numeric argument. Crossroads knows only
non-negative integer numbers, as in port 8000. Here, port is
the keyword and 8000 is the number.
Yet other keywords require 'generic strings', such as hostname
specifications or system commands. Such generic strings contain any
characters up to the terminating statement character ;.
Finally, an argument can be a 'boolean' value. Crossroads knows
true, false, yes, no, on, off. The keywords
true, yes and on all mean the same and can be used
interchangeably; as can the keywords false, no and off.
Service definitions are blocks in the configuration file that
state what is for each service. A service definition starts with
service, followed by a unique identifier, and by statements in
{ and }. For example:
// Definition of service 'www':
service www {
...
... // statements that define the
... // service named 'www'
...
}
The following list shows possible stateements.
backend statement, which
has its own block).
port 8000 says that this service will accept
connections on port 8000.
port number ;
bindto 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.
bindto ip-address ;
192.168.1.45, or the keyword any
any
verbosity on or
verbosity off. When 'on', log messages to /var/log/messages
are generated that show what's going on.(Actually, the
messages go to syslog(3), using facility LOG_DAEMON and
priority LOG_INFO. In most (Linux) cases this will mean: output to
/var/log/messages.)
verbosity setting ;
true, yes or on to turn
verbosity on; or false, no, off to turn it off.
off.
dispatchmode 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
dispatchmode statement occurs.
dispatchmode random: Random selection. Probably only
for stress testing.
dispatchmode bysize [ over sessions ]:
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 over nsessions is optional. (The square
brackets shown above are not part of the statement but
indicate optionality.) When given,
the size load is computed over the last stated number of
sessions. When this modifier is absent, then the load is
computed over all sessions since startup.
dispatchmode byduration [ over sessions ]:
The next back end is the one
that served sessions for the shortest time. This mechanims
assumes that the longer the session, the heavier the load.
dispatchmode byorder: The first back end is selected
every time, unless it's unavailable. In that case the second
is taken, and so on.
The 'right' dispatch mode will depend on the type of service. Given
the fact that crossroads doesn't know (and doesn't care) what a stream
of network traffic means, you have to choose an appropriate dispatch
mode to optimize load balancing. Note that the dispatch mode is
totally irrelevant when your only concern is fail over. In most cases,
roundrobin will do the job just fine.
An example of the definition is revivinginterval 10. When this
reviving interval is given, crossroads will check each 10 seconds
whether unavailable back ends have woken up yet. A back end is
considered awake when a network connection to that back end can
succesfully be established.
revivinginterval number ;
maxclients. There is one argument; the number of concurrent
established sessions that may be active within one service.
'Throttling' the number of clients 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.
maxclient number ;
backlog 5 to cause crossroads
to have 5 waiting connections for 1 active session.
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.
backlog number ;
crossroad
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 port and bitwise or-ed with a magic number. In situations where this conflicts with existing keys (of other programs, having their own keys), you may supply a chosen value.
The syntax is e.g. shmkey 123456. The actual key value doesn't
matter much, as long as it's unique and as long as each invocation of
crossroads uses it.
shmkey number ;
sessiontimeout 300. This instructs crossroads to
consider a session where nothing has happened for 300 seconds as
'finished'. Crossroads will terminate the connection when this timeout
is exceeded.
sessiontimeout number ;
Inside the service definitions as are described in the previous
section, backend definitions must also occur. Backend definitions
are started by the keyword backend, followed by an identifier, and
defining statements inside { and }:
service myservice {
...
... // statements that define the
... // service named 'myservice'
...
backend mybackend {
...
... // statements that define the
... // backend named 'mybackend'
...
}
}
The backend definition statements are shown below.
server
10.1.1.23, or server web.mydomain.org.
server servername ;
server specifier, the port
definition is also required. It has one argument, the (numeric)
port number.
port number ;
service specifications, a
backend can have its own verbosity (on or off). When
on, traffic to and fro this back end is reported.
verbosity setting ;
true, yes or on to turn
verbosity on; or false, no, off to turn it off.
off.
maxclients statement for the overall service description.
The difference is that a maxclients statement at the level of
a service description avoids too many hits from the outside (DOS
prevention). A maxclients statement at the level of a back end
description makes sure that this particular back end doesn't get
overloaded.
maxclients number ;
The weighing mechanism only applies for dispatchmode bysize or
byduration. The weight is in fact a multiplier. E.g., if backend A has
weight 2 and backend B has weight 1, then backend B will
be selected all the time,
until its usage parameter is twice as large as the
parameter of A.
weight number ;
decay 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.
This means that when a given back end is hit, then its usage data is updated according to the session. However, when a different back end is hit, its usage is decreased by the specified decay.
decay number ;
onfailure and onsuccess. The argument to
the triggers is a system command that is executed when a session
with the back end either fails or succeeds.
onfailure commandline ; and
onsuccess commandline ;
trafficlog filename can
be issued. This causes the traffic to be dumped in hexadecimal
format to the stated filename.
Traffic sent by the client is prefixed by a C, traffic sent by
the back end is prefixed by a B. Below is a sample traffic
dump of a browser trying to get a HTML page. The server replies
that the page was not modified.
C 0000 47 45 54 20 68 74 74 70 3a 2f 2f 77 77 77 2e 63 GET http://www.c C 0010 73 2e 68 65 6c 73 69 6e 6b 69 2e 66 69 2f 6c 69 s.helsinki.fi/li C 0020 6e 75 78 2f 6c 69 6e 75 78 2d 6b 65 72 6e 65 6c nux/linux-kernel C 0030 2f 32 30 30 31 2d 34 37 2f 30 34 31 37 2e 68 74 /2001-47/0417.ht C 0040 6d 6c 20 48 54 54 50 2f 31 2e 31 0d 0a 43 6f 6e ml HTTP/1.1..Con C 0050 6e 65 63 74 69 6f 6e 3a 20 63 6c 6f 73 65 0d 0a nection: close.. . . etcetera . B 0000 48 54 54 50 2f 31 2e 30 20 33 30 34 20 4e 6f 74 HTTP/1.0 304 Not B 0010 20 4d 6f 64 69 66 69 65 64 0d 0a 44 61 74 65 3a Modified..Date: B 0020 20 54 75 65 2c 20 31 32 20 4a 75 6c 20 32 30 30 Tue, 12 Jul 200 B 0030 35 20 30 39 3a 34 39 3a 34 37 20 47 4d 54 0d 0a 5 09:49:47 GMT.. B 0040 43 6f 6e 74 65 6e 74 2d 54 79 70 65 3a 20 74 65 Content-Type: te B 0050 78 74 2f 68 74 6d 6c 3b 20 63 68 61 72 73 65 74 xt/html; charset . . etcetera . B 0110 6c 6f 73 65 0d 0a 0d 0a lose....
Turning on traffic dumps will significantly slow down crossroads.
trafficlog filename ;
Besides trafficlog, there is also a directive
throughputlog. This directive also takes one argument, a
filename. The file is appended, and the following information is
logged:
As an example, consider the following (the lines are shortened for brevity and prefixed by line numbers for clarity):
1 0015003 0000000000.0000000008 C GET http://gstreamer.freedesktop.o.. 2 0015003 0000000001.4294810978 B HTTP/1.1 200 OK..Age: 0..Date: Wed.. 3 0015003 0000000002.4294493517 B ia framework"></td></tr>.</table>... 4 0015004 0000000000.0000000014 C GET http://gstreamer.freedesktop.o.. 5 0015003 0000000002.4294544117 B .gif" border="0" width="2" height=.. 6 0015003 0000000002.4294553569 B 0" bgcolor="#CCCCCC" align="center.. 7 0015003 0000000002.4294560517 B class="gstnavside">Bug Lists</a><.. 8 0015003 0000000002.4294567088 B freedesktop.org/releases/gst-plugi.. 9 0015003 0000000002.4294574490 B g src="http://gstreamer.freedeskto.. 10 0015004 0000000000.0000365017 B HTTP/1.1 200 OK..Age: 0..Date: Wed.. 11 0015004 0000000000.0000477317 C GET http://gstreamer.freedesktop.o.. 12 0015005 0000000000.0000000009 C GET http://gstreamer.freedesktop.o.. 13 0015006 0000000000.0000000009 C GET http://gstreamer.freedesktop.o.. 14 0015003 0000000002.0000049267 C GET http://gstreamer.freedesktop.o.. 15 0015004 0000000000.0000710035 B HTTP/1.1 200 OK..Age: 0..Date: Wed..
This tells us that:
Summarizing, the throughput times of a client-back end connection
can be analyzed using the directive throughputlog. In a
real-world analysis, you'd probably want to write up a script to
analyze the output and to compute round trip times. Such scripts
are not (yet) included in Crossroads.
throughputlog filename ;
In order to tune your load balancing, you'll need to understand how
crossroads computes usage, how weighing works, and so on. In this
section we'll focus on dispatchmode bysize and dispatchmode
byduration only: the other dispatching types are self-explanatory.
As stated before, crossroads doesn't know 'what a service does' and how to judge whether a given back end is very busy or not. You must therefore give the right hints:
byduration is appropriate here.
bysize is apppropriate.
byduration can also be used when
network latency is an issue. E.g., if your balancer has back
ends that are geograpically distributed, then byduration
would be a good way to select well available back ends.
dispatchmode
byduration is not usable for interactive processes such as
SSH logins. Idle time of a
login adds to the duration, while causing (almost) no
load. Mode byduration should only be used for automated
processes that don't wait for user interaction (e.g., SOAP
calls and other HTTP requests).3.4.2: Averaging size and duration
The configuration statement dispatchmode bysize or byduration
allows an optional modifier over number, where the stated
number represents a session count. When this modifier is present, then
crossroads will use a moving average over the last n sessions to
compute duration and size figures.
In the real world you'll always want this modifier. E.g., consider two
back ends that are running for years now, and one of them is suddenly
overloaded and very busy. When the over modifier is absent, then
the sudden load will hardly show up in the usage figures -- it will
flatten out due to the large usage figures already stored in the years
of service.
In contrast, when e.g. over 3 is in effect, then a sudden load
does show up -- because it highly contributes to the average of three
sessions.
Decays are also only relevant when crossroads computes the 'next best back end' by size (bytes) or duration (seconds). E.g., imagine two back ends A and B, both averaged over say 3 sessions.
Now when back end A is suddenly hit by a large request (a 'spike'), its average would go up accordingly. But the back end would never again be used, unless B also received a similar spike, because A's 'usage data' would forever be larger than B's data.
For that reason, you should in real situations probably always specify a decay, so that the backend selection algorithm recovers from spikes. The below configuration illustrates this:
/* Definition of the service */
service soap {
/* Local TCP port */
port 8080;
/* We'll select back ends by the processing
* duration
*/
dispatchmode byduration over 3;
/* First back end: */
backend A {
/* Back end IP address and port */
server 10.1.1.1;
port 8080;
/* When this back end is NOT hit because
* the other one is less busy, then the
* usage parameters decay 10% per session
*/
decay 10;
}
/* Second back end: */
backend B {
server 10.1.1.2;
port 8080;
decay 10;
}
}
The back end modifier weight is useful in situations where your
back ends differ in respect to performance. E.g,. your back ends may
be geographically distributed, and you know that a given back end is
difficult to reach and often experiences network lag.
Or you may have one primary back end, a system with a fast CPU and enough memory, and a small fall-back back end, with a slow CPU and short on memory. In that case you know in advance that the second back end should be used only rarely.
In such cases you will know in advance that the best performing back ends
should be selected the most often. Here's where the weight
statement comes in: you can simply increase the weight of the back
ends with the least performance, so that they are selected less
frequently.
E.g., consider the following configuration:
service soap {
port 8080;
dispatchmode byduration over 3;
backend A {
server 10.1.1.1;
port 8080;
decay 20;
}
backend B {
server 10.1.1.2;
port 8080;
weight 2;
decay 10;
}
backend C {
server 10.1.1.3;
port 8080;
weight 4;
decay 5;
}
}
This will cause crossroads to select back ends by the processing time, averaging over the last three sessions. However, backend B will kick in only when its usage is half of the usage of A (back end B is probably only half as fast as A). Backend C will kick in only when its usage is a quarter of the usage of A, which is half of the usage of B (back end C is probably very weak, and just a fall-back system incase both A and B crash). Note also that A's usage data decay much faster than B's and C's.
3.4.5: Throttling the number of concurrent sessions
If you suspect that your service may occasionally receive 'spikes' of activity(which you should always assume), then it might be a good idea to protect your service by specifying a maximum number of concurrent sessions. This protection can be specified on two levels:
maxclients
100; states that the service as a whole will never
service more than 100 concurrent sessions. This means that
all your back ends will be protected from being
overloaded.
maxclients 10;
states that this particular back end will never have more
than 10 concurrent sessions; regardless of the overall
setting on the service level. This means that this
particular back end will be protected from being
overloaded (regardless of what other back ends may
experience).
Using the maxclients statement, combined with a back end selection
algorithm, allows very fine granularity. The maxclients statement
on the back end level is like a hand brake: even when you specify a
back end algorithm that would protect a given back end from being used
too much, a situation may occur where that back end is about to be
hit. A maxclients statement on the level of that back may then
protect it.
As a general hint, use crossroads sampleconf to view the most
up-to-date examples of configurations. The description below shows a
few examples too.
3.5.1: A load balancer for three webserver back ends
The following configuration example binds crossroads to port 80 of the current server, and distributes the load over three back ends. This configuration shows most of the possible settings.
service www {
/* Port on which we'll listen in this service: required. */
port 8000;
/* What IP address should this service listen? Default is 'any'.
* Alternatively you can state an explicit IP address, such as
* 127.0.0.1; that would bind the service only to 'localhost'. */
bindto any;
/* Verbose reporting or not. Default is off. */
verbosity on;
/* Dispatching mode, or: How to select a back end for an incoming
* request. Possible values:
* roundrobin: just the next back end in line
* random: like roundrobin, but at random to make things more
* confusing. Probably only good for testing.
* bysize: The backend that transferred the least nr of bytes
* is the next in line. As a modifier you can say e.g.
* bysize over 10, meaning that the 10 last sessions will
* be used to compute the transfer size, instead of all
* transfers.
* byduration: The backend that was active for the shortest time
* is the next in line. As a modifier you can say e.g.
* byduration of 10 to compute over the last 10 sessions.
* byorder: The first available back end is always taken.
*/
dispatchmode byduration over 5;
/* Interval at which we'll check whether a temporarily unavailable
* backend has woken up.
*/
revivinginterval 5;
/* TCP backlog of connections. Default is 0 (no backlog, one
* connection may be active).
*/
backlog 5;
/* For status reporting: a shared memory key. Default is the same
* as the port number, OR-ed by a magic number.
*/
shmkey 8000;
/* This controls when crossroads should consider a session as
* finished even when the TCP sockets weren't closed. This is to
* avoid hanging connections that don't do anything. NOTE THAT when
* crossroads cuts off a session due to timeout exceed, this is
* not marked as a failure, but as a success. Default is 0: no timeout.
*/
sessiontimeout 300;
/* The max number of allowed client sessions. When present, connections
* won't be accepted if the max is about to be exceeded. When
* absent, all connections will be accepted, which might be misused
* for a DOS attack.
*/
maxclients 300;
/* Now let's define a couple of back ends. Number 1: */
backend www_backend_1 {
/* The server and its port, the minimum configuration. */
server httpserver1;
port 9010;
/* The 'decay' of usage data of this back end. Only relevant
* when the whole service has 'dispatchmode bysize' or
* 'byduration'. The number is a percentage by which the usage
* parameter is decreased upon each session of an other back
* end.
*/
decay 10;
/* To see what's happening in /var/log/messages: */
verbosity on;
}
/* The second one: */
backend www_backend_2 {
/* Server and port */
server httpserver2;
port 9011;
/* Verbosity of reporting when this back end is active */
verbosity on;
/* Decay */
decay 10;
/* Event triggers for system commands upon succesful activation
* and upon failure.
*/
onsuccess echo 'success on backend 2' | mail root;
onfailure echo 'failure on backend 2' | mail root;
}
/* And yet another one.. this time we will dump the traffic
* to a trace file. Furthermore we don't want more than 10 concurrent
* sessions here. Note that there's also a total maxclients for the
* whole service.
*/
backend www_backend_3 {
server httpserver3;
verbosity on;
port 9000;
verbosity on;
decay 10;
trafficlog /tmp/backend.3.log;
maxclients 10;
}
}
3.5.2: A HTTP forwarder when travelling
As another example, here's my crossroads.conf that I use on my
Linux laptop. The problem that I face is that I need many HTTP proxy
configurations (at home, at customers' sites and so on) but I'm too
lazy to reconfigure browsers all the time.
Here's how it used to be before crossroads:
http://localhost:3128.
http://localhost:3129.
http://10.120.34.113:8080, because they have configured it
so.
http://localhost:8888.Here's how it works with a crossroads configuration:
http://localhost:8080 as the proxy. For all situations.
dispatchmode byorder. This
makes sure that once crossroads determines which
backend works, it will stick to it. This usage of
crossroads doesn't need to balance over more than one
back end.
bindto 127.0.0.1 makes sure
that requests from other interfaces than loopback
won't get serviced.
service HttpProxy {
port 8080;
bindto 127.0.0.1;
verbosity on;
dispatchmode byorder;
revivinginterval 15;
backend Charles {
server 127.0.0.1;
port 8888;
verbosity on;
}
backend CustomerProxy {
server 10.120.34.113;
port 8080;
verbosity on;
}
backend SshTunnel {
server 127.0.0.1;
port 3129;
}
backend LocalSquid {
server 127.0.0.1;
port 3128;
verbosity on;
}
}
As a final note, the commandline argument tell can be used to
influence crossroad's own detection mechanism of back end availability
detection. E.g., if in the above example the back ends SshTunnel
and LocalSquid are both active, then crossroads tell httpproxy
sshtunnel down will 'take down' the back end SshTunnel -- and
will automatically cause crossroads to switch to LocalSquid.
3.5.3: SSH login with enforced idle logout
The following example shows how crossroads 'throttles' SSH logins. Connections are accepted on port 22 (the normal SSH port) and forwards these to the actual SSH daemon which is running on port 2222.
Note the usage of the
sessiontimeout directive. This makes sure that users are logged
out after 10 minutes of inactivity. Note also the maxclients
setting, this makes sure that no more than 10 concurrent logins occur.
service Ssh {
port 22;
backlog 5;
maxclients 10;
sessiontimeout 600;
backend TrueSshDaemon {
server 127.0.0.1;
port 2222;
}
}
The benchmark was run on a system where the following was varied:
The crossroads configuration of the second alternative is shown below:
service HttpProxy {
port 8080;
verbosity on;
backend LocalSquid {
server 127.0.0.1;
port 3128;
verbosity on;
}
}
The results of this test are that crossroads causes a negligible delay, if it is statistically relevant at all. Without crossroads, the timing results are:
real 0m8.146s user 0m0.130s sys 0m0.253s
When using crossroads as a middle station, the results are:
real 0m9.481s user 0m0.141s sys 0m0.230s
The above shown results are quite favorable to crossroads. However, one should know that situations will exist where crossroads leans towards the 'worst case' scenario, causing up to 50% delay.
E.g., imagine a test where a wget command retrieves a
HTML document from an Apache server on localhost. Now we have
(almost) no overhead due to network throttling, hostname lookups and
so on. When this test would be run either with or without crossroads
in between, then theoretically, crossroads would cause a much larger
delay, because it has to read from the server, and then write the same
information to wget. Each read/write occurs twice when crossroads
sits in between.
This worst case scenario will however (fortunately) occur only very seldom in the real world:
The creation of crossroads requires:
sed, awk, Perl
(5.00 or better);
bison and flex;
Basically a Linux or Apple MacOSX box will do nicely once you make
sure that bison and flex are installed. To compile and install
crossroads, follow these steps.
crossroads-X.YY.tar.gz, where X.YY is
a version number.
tar
xzf crossroads-X.YY.tar.gz. The contents spill into a
subdirectory crossroads/.
etc/Makefile.def and verify that all
compilation settings are to your likings. The settings are
explained in the file. Note that the default distribution
of Makefile.def is suited for Linux or Apple MacOSX
systems.
On other
Unices, or on non-Unix systems, you must particularly pay
attention to SET_PROC_TITLE_BY.... When in doubt, comment out
all SET_PROC_TITLE... settings. Crossroads will work
nevertheless, but it won't show nice titles in ps listings.
make
local followed by make install. The latter step may have
to be done by the user root if the BINDIR setting of
etc/Makefile.def points to a root-owned directory.
cp doc/crossroads.html
htmldirectory/; where htmldirectory is the destination
directory for your HTML manuals;
cp doc/crossroads.pdf
pdfdirectory/; where pdfdirectory is the
destination directory for your PDF manuals;
cp doc/crossroads.man
manualdirectory/man1/crossroads.1, where
manualdirectory is e.g. /usr/man,
/usr/share, /usr/local/man,
/usr/local/share. Any possibility is valid, as
long as manualdirectory has a subdirectory
man1/;
gzip -c < doc/crossroads.man >
manualdirectory/man1/crossroads.1.gz.
Now that the binary is available on your system, you need to create a
suitable /etc/crossroads.conf. Use this manual or the output of
crossroads samplconf to get started.
Once you have the configuration ready, start crossroads with
crossroads start. Test the availability of your services and back
ends. Monitor how crossroads is doing with:
while [ 1 ] ; do
tput clear
crossroads status
sleep 3
done
Please note that depending on your system you might need
sleep 3s, i.e., with an s appended.
while [ 1 ] ; do
tput clear
ps ax | grep crossroads | grep -v grep
sleep 3
done
tail -f /var/log/messages.
Now thoroughly test the availability of your back ends through
crossroads. The status display will show an updated view of which back
ends are selected and how busy they are. The process list will show
which crossroads daemons are running. Finally, the tailing of
/var/log/messages shows what's going on -- especially if you have
verbosity true statements in the configuration.
Finally, you may want to create a boot-time startup script. The exact procedure depends on the used Unix flavor.
On SysV style systems, there's a startup script directory
/etc/init.d where bootscripts for all utilities are located.
You may have the chkconfig utility to automate the task of
inserting scripts into the boot sequence, but
otherwise the steps will resemble the following.
crossroads in /etc/init.d similar to the
following:
#!/bin/sh /usr/local/bin/crossroads -v $@
The stated directory /usr/local/bin must correspond with
the installation path. The flag -v causes the startup to
be more 'verbose'. However, once daemonized, the verbosity is
controlled by the appropriate statements in the configuration.
root> cd /etc/rc.d/rc3.d root> ln -s /etc/init.d/crossroads S99crossroads root> ln -s /etc/init.d/crossroads K99crossroads
This creates startup (S*) and stop (K*) links that
will be run when the system enters or leaves a given runlevel.
If your runlevel is 5, then the right cd command is to
/etc/rc.d/rc5.d. Alternatively, you can create the
symlinks in both runlevel directories.
On BSD style systems, daemons are booted directly from /etc/rc and
related scripts. Incase you have a file /etc/rc.local, edit it,
and add the statement:
/usr/local/bin/crossroads start
If your BSD system lacks /etc/rc.local, then you may need to start
Crossroads from /etc/rc. Your mileage may vary.