1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
.TH PEN 1 LOCAL
.SH NAME
pen
.SH SYNOPSIS
.B pen
[-b sec] [-c N] [-e host:port] [-t sec] [-x N] [-j dir] [-u user] [-l logfile] [-p file ] [-w file] [-C port] [-Hadfhnrs] [host:]port h1[:p1[:maxc1]] [h2[:p2[:maxc2]]] ...
.SH EXAMPLE
pen 80 www1:8000:10 www2:80:10 www3
Here three servers cooperate in a web server farm. Host www1 runs its
web server on port 8000 and accepts a maximum of 10 simultaneous connections.
Host www2 runs on port 80 and accepts 10 connections. Finally, www3 runs
its web server on port 80 and allows an unlimited number of simultaneous
connections.
.SH DESCRIPTION
.I Pen
is a load balancer for tcp based protocols such as
http or smtp. It allows several servers to appear as one to the
outside and automatically detects servers that are down and distributes
clients among the available servers. This gives high availability and
scalable performance.
The load balancing algorithm keeps track of clients and will try to
send them back to the server they visited the last time. The client
table has a number of slots (default 2048, settable through command-line
arguments). When the table is full, the least recently used one will
be thrown out to make room for the new one.
This is superior to a simple round-robin algorithm, which sends a client
that connects repeatedly to different servers. Doing so breaks
applications that maintain state between connections in the server,
including most modern web applications.
When pen detects that a server is unavailable, it scans for another
starting with the server after the most recently used one. That way
we get load balancing and "fair" failover for free.
Correctly configured, pen can ensure that a server farm is always
available, even when individual servers are brought down for maintenance
or reconfiguration. The final single point of failure, pen itself,
can be eliminated by running pen on several servers, using vrrp to
decide which is active.
Sending pen a USR1 signal will make it print some useful statistics on stderr,
even if debugging is disabled. If pen is running in the background (i.e.
without the -f option), syslog is used rather than stderr. If the
-w option is used, the statistics is saved in HTML format in the
given file.
Sending pen a HUP signal will make it close and reopen the logfile,
if logging is enabled. Rotate the log like this (assuming pen.log
is the name of the logfile):
mv pen.log pen.log.1
kill -HUP `cat <pidfile>`
where <pidfile> is the file containing pen's process id, as written by the -p option.
Sending pen a TERM signal will make it exit cleanly, closing the
log file and all open sockets.
.SH OPTIONS
.TP
-C \fIport\fR
Specifies a control port where the load balancer listens for commands.
.TP
-H
Adds X-Forwarded-For header to http requests.
.TP
-a
Used in conjunction with -dd to get communication dumps in ascii
rather than hexadecimal format.
.TP
-b \fIsec\fR
Servers that do not respond are blacklisted, i.e. excluded from the
server selection algorithm, for the specified number of seconds (default 30).
.TP
-c \fIN\fR
Max number of clients (default 2048).
.TP
-d
Debugging (repeat -d for more). The output goes to stderr if we are running
in the foreground (see -f) and to syslog (facility user, priority
debug) otherwise.
.TP
-e \fIhost:port\fR
host:port specifies the emergency server to contact if all regular
servers become unavailable.
.TP
-f
Stay in foreground.
.TP
-h
Use a hash on the client IP address for the initial server selection.
This makes it more predictable where clients will be connected.
.TP
-j \fIdir\fR
Run in a chroot environment.
.TP
-l \fIfile\fR
Turn on logging.
.TP
-n
Nonblocking.
.TP
-p \fIfile\fR
Write the pid of the running daemon to \fIfile\fR.
.TP
-r
Go straight into round-robin server selection without looking up
which server a client used the last time.
.TP
-s
Stubborn server selection: if the initial choice is unavailable, the
client connection is closed without trying another server.
.TP
-t \fIsec\fR
Connect timeout in seconds (default 5).
.TP
-u \fIuser\fR
Run as a different user.
.TP
-x \fIN\fR
Max number of simultaneous connections (default 256).
.TP
-w \fIfile\fR
File for status reports in HTML format.
.TP
host:port
The local address and port pen listens to. By default pen listens to
all local addresses.
.TP
h1:p1:soft:hard
The address, port and maximum number of simultaneous connections for
a remote server. By default, the port is the same as the local port,
and the soft limit on the number of connections is unlimited. The hard
limit is used for clients which have accessed the server before.
.SH LIMITATIONS
Pen runs in a single process, and opens two sockets for each connection.
Depending on kernel configuration, pen can run out of file descriptors.
.SH SEE ALSO
dwatch(1), mergelogs(1), webresolve(1)
.SH AUTHOR
Copyright (C) 2001-2002 Ulric Eriksson, <ulric@siag.nu>.
.SH ACKNOWLEDGEMENTS
In part inspired by balance by Thomas Obermair.
|
