forked from goochjj/pound
-
Notifications
You must be signed in to change notification settings - Fork 0
/
pound.8
executable file
·1232 lines (1219 loc) · 33.2 KB
/
pound.8
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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH POUND "8" "Jan 2010" "pound" "System Manager's Manual"
.SH NAME
pound \- HTTP/HTTPS reverse-proxy and load-balancer
.SH SYNOPSIS
.TP
.B pound
[\fI-v\fR]
[\fI-c\fR]
[\fI-V\fR]
[\fI-f config_file\fR]
[\fI-p pid_file\fR]
.SH DESCRIPTION
.PP
.B Pound
is a reverse-proxy load balancing server. It accepts requests from HTTP/HTTPS
clients and distributes them to one or more Web servers. The HTTPS requests are
decrypted and passed to the back-ends as plain HTTP.
.PP
If more than one back-end server is defined,
.B Pound
chooses one of them randomly, based on defined priorities. By default,
.B Pound
keeps track of associations between clients and back-end servers (sessions).
.SH GENERAL PRINCIPLES
.P
In general
.B Pound
needs three types of objects defined in order to function:
.IR listeners ,
.I services
and
.IR back-ends .
.TP
\fBListeners\fR
A
.I listener
is a definition of how
.B Pound
receives requests from the clients (browsers). Two types of
.I listeners
may be defined: regular HTTP
.I listeners
and HTTPS (HTTP over SSL/TLS)
.IR listeners .
At the very least a
.I listener
must define the address and port to listen on, with additional
requirements for HTTPS
.IR listeners .
.TP
\fBServices\fR
A
.I service
is the definition of how the requests are answered. The
.I services
may be defined within a
.I listener
or at the top level (global). When a request is received
.B Pound
attempts to match them to each
.I service
in turn, starting with the
.I services
defined in the
.I listener
itself and, if needed, continuing with the
.I services
defined at the global level. The
.I services
may define their own conditions as to which requests they can answer:
typically this involves certain URLs (images only, or a certain path)
or specific headers (such as the Host header). A
.I service
may also define a
.I session
mechanism: if defined future requests from a given client will always
be answered by the same
.IR back-end .
.TP
\fBBack-ends\fR
The
.I back-ends
are the actual servers for the content requested. By itself,
.B Pound
supplies no responses - all contents must be received from a "real"
web server. The
.I back-end
defines how the server should be contacted.
.IP
Three types of
.I back-ends
may be defined: a "regular"
.I back-end
which receives requests and returns responses, a "redirect"
.I back-end
in which case
.B Pound
will respond with a redirect response, without accessing any
.I back-end
at all, or an "emergency"
.I back-end
which will be used only if all other backends are "dead".
.IP
Multiple
.I back-ends
may be defined within a
.IR service ,
in which case
.B Pound
will load-balance between the available
.IR back-ends .
.IP
If a
.I back-end
fails to respond it will be considered "dead", in which case
.B Pound
will stop sending requests to it. Dead
.I back-ends
are periodically checked for availability, and once they respond again they
are "resurected" and requests are sent again their way. If no
.I back-ends
are available (none were defined, or all are "dead") then
.B Pound
will reply with "503 Service Unavailable", without checking additional
.IR services .
.IP
The connection between
.B Pound
and the
.I back-ends
is always via HTTP, regardless of the actual protocol used between
.B Pound
and the client.
.SH OPTIONS
Options available (see also below for configuration file options):
.TP
\fB\-v\fR
Verbose mode: error messages will be sent to stdout even if
.B Pound
was configured to log to syslog. This applies only to startup messages, before
.B Pound
puts itself in the background. Normal operational messages will still go to syslog.
.TP
\fB\-V\fR
Print version:
.B Pound
will exit immediately after printing the current version and configuration flags.
.TP
\fB\-c\fR
Check only:
.B Pound
will exit immediately after parsing the configuration file. This may be used for
running a quick syntax check before actually activating a server.
.TP
\fB\-f\fR config_file
Location of the configuration file (see below for a full description of the format).
Default:
.I /usr/local/etc/pound.cfg
.TP
\fB\-p\fR pid_file
Location of the pid file.
.B Pound
will write its own pid into this file. Normally this is used for shell
scripts that control starting and stopping of the daemon.
Default:
.I /var/run/pound.pid
.PP
In general, any number of back-end servers may be specified. Use the priority to
affect the load distribution among unequal-performance servers.
.PP
One (or more) copies of
.B Pound
should be started at boot time. Use "big iron" if you expect heavy loads: while
.B Pound
is as light-weight as I know how to make it, with a lot of simultaneous requests it
will use quite a bit of CPU and memory. Multiple CPUs are your friend.
.SH "CONFIGURATION FILE"
Each line in the file is considered a complete configuration directive. The directives
are case-insensitive. Empty lines or lines starting in '#' are ignored. There are three
types of directives:
.B global
directives (they affect the settings for the entire program instance),
.B listener
directives (they define which requests
.B Pound
will listen for), and
.B service
directives (they affect only a specific group of requests).
.SH "GLOBAL DIRECTIVES"
Global directives may appear anywhere within the configuration file, though it is
customary for them to be at the start. They may appear in any order.
.TP
\fBUser\fR "user_name"
Specify the user
.B Pound
will run as (must be defined in \fI/etc/passwd\fR).
.TP
\fBGroup\fR "group_name"
Specify the group
.B Pound
will run as (must be defined in \fI/etc/group\fR).
.TP
\fBRootJail\fR "directory_path_and_name"
Specify the directory that
.B Pound
will chroot to at runtime. Please note that OpenSSL requires access to /dev/urandom,
so make sure you create a device by that name, accessible from the root jail
directory.
.B Pound
may also require access to
.I /dev/syslog
or similar.
.TP
\fBDaemon\fR 0|1
Have
.B Pound
run in the foreground (if 0) or as a daemon (if 1). By default
.B Pound
runs as a daemon (detaches itself from the controlling terminal and
puts itself in the background). By specifying this option you can force
.B Pound
to work like a regular process. Useful for debugging or if you want to
use something like \fIdaemontools\fR.
.TP
\fBThreads\fR nnn
How many worker threads
.B Pound
should use. Default: 128. Tune this parameter to improve performance.
If you set it too high,
.B Pound
will use a lot memory, and some CPU will be wasted on context switches.
If you set it too low requests may be served with some delay. Experiment
to find the optimal value for your installation.
.TP
\fBLogFacility\fR value
Specify the log facility to use.
.I value
(default: daemon) must be one of the symbolic facility names defined in
\fIsyslog.h\fR. This facility shall be used for logging. Using a - for
the facility name causes
.B Pound
to log to stdout/stderr.
.TP
\fBLogLevel\fR value
Specify the logging level: 0 for no logging, 1 (default) for regular
logging, 2 for extended logging (show chosen backend server as well),
3 for Apache-like format (Combined Log Format with Virtual Host), 4
(same as 3 but without the virtual host information) and 5 (same as 4
but with information about the
.I Service
and
.I BackEnd
used).
This value can be overridden for specific listeners.
.TP
\fBIgnoreCase\fR 0|1
Ignore case when matching URLs (default: 0). This value can be
overridden for specific services.
.TP
\fBDynScale\fR 0|1
Enable or disable the dynamic rescaling code (default: 0). If enabled
.B Pound
will periodically try to modify the back-end priorities in order to
equalise the response times from the various back-ends.
This value can be overridden for specific services.
.TP
\fBAlive\fR value
Specify how often
.B Pound
will check for resurected back-end hosts (default: 30 seconds). In
general, it is a good idea to set this as low as possible - it
will find resurected hosts faster. However, if you set it too
low it will consume resources - so beware.
.TP
\fBClient\fR value
Specify for how long
.B Pound
will wait for a client request (default: 10 seconds). After this
long has passed without the client sending any data
.B Pound
will close the connection. Set it higher if your clients
time-out on a slow network or over-loaded server, lower if you
start getting DOS attacks or run into problems with IE clients.
This value can be overridden for specific listeners.
.TP
\fBTimeOut\fR value
How long should
.B Pound
wait for a response from the back-end (in seconds). Default: 15 seconds.
This value can be overridden for specific back-ends.
.TP
\fBConnTO\fR value
How long should
.B Pound
wait for a connection to the back-end (in seconds). Default: the
.B TimeOut
value. This value can be overridden for specific back-ends.
.TP
\fBGrace\fR value
How long should
.B Pound
continue to answer existing connections after a receiving and INT or HUP
signal (default: 30 seconds). The configured listeners are closed
immediately. You can bypass this behaviour by stopping
.B Pound
with a TERM or QUIT signal, in which case the program exits without any
delay.
.TP
\fBSSLEngine\fR "name"
Use an OpenSSL hardware acceleration card called \fIname\fR. Available
only if OpenSSL-engine is installed on your system.
.TP
\fBControl\fR "/path/to/socket"
Set the control socket path. If not defined
.B Pound
does not listen for any commands. The commands may be issued by using
the
.I poundctl(8)
program.
.TP
\fBInclude\fR "/path/to/file"
Include the file as though it were part of the configuration file.
.TP
\fBAnonymise\fR
Replace the last byte of the client address with 0 for logging purposes.
Default: log the client address in full.
.SH "HTTP Listener"
An HTTP listener defines an address and port that
.B Pound
will listen on for HTTP requests. All configuration directives enclosed
between
.I ListenHTTP
and
.I End
are specific to a single HTTP listener. At the very least you must specify
and address and a port for each listener. The following directives are
available:
.TP
\fBAddress\fR address
The address that
.B Pound
will listen on. This can be a numeric IP address, or a symbolic host name
that must be resolvable at run-time. This is a
.B mandatory
parameter. The address 0.0.0.0 may be used as an alias for 'all available
addresses on this machine', but this practice is strongly discouraged, as
it will interfere with the rewriting mechanisms (see below).
.TP
\fBPort\fR port
The port number that
.B Pound
will listen on. This is a
.B mandatory
parameter.
.TP
\fBxHTTP\fR value
Defines which HTTP verbs are accepted. The possible values are:
.IP
.I 0
(default) accept only standard HTTP requests (GET, POST, HEAD).
.IP
.I 1
additionally allow extended HTTP requests (PUT, DELETE).
.IP
.I 2
additionally allow standard WebDAV verbs (LOCK, UNLOCK, PROPFIND,
PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY,
CHECKOUT, MERGE, REPORT).
.IP
.I 3
additionally allow MS extensions WebDAV verbs (SUBSCRIBE, UNSUBSCRIBE,
NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT).
.IP
.I 4
additionally allow MS RPC extensions verbs (RPC_IN_DATA, RPC_OUT_DATA).
.TP
\fBClient\fR value
Override the global
.I Client
time-out value.
.TP
\fBCheckURL\fR "pattern to match"
Define a pattern that must be matched by each request sent to this
listener. A request that does not match is considered to be illegal.
By default
.B Pound
accepts all requests (i.e. the pattern is ".*"), but you are free to
limit it to something more reasonable. Please note that this applies
only to the request path -
.B Pound
will still check that the request is syntactically correct.
.TP
\fBErr414\fR "filename"
A file with the text to be displayed if an Error 414 occurs.
Default: "Request URI is too long.".
.TP
\fBErr500\fR "filename"
A file with the text to be displayed if an Error 500 occurs.
Default: "An internal server error occurred. Please try again later.".
.TP
\fBErr501\fR "filename"
A file with the text to be displayed if an Error 501 occurs.
Default: "This method may not be used.".
.TP
\fBErr503\fR "filename"
A file with the text to be displayed if an Error 503 occurs.
Default: "The service is not available. Please try again later.".
.TP
\fBMaxRequest\fR nnn
Request maximal size. All requests will be limited to these many bytes. If
a request contains more data than allowed an error 414 is returned. Default:
unlimited.
.TP
\fBHeadRemove\fR "header pattern"
Remove certain headers from the incoming requests. All occurences of the
matching specified header will be removed. Please note that this filtering
is done prior to other checks (such as \fIHeadRequire\fR or \fIHeadDeny\fR),
so you should not try to check for these headers in later matches. Multiple
directives may be specified in order to remove more than one header, and
the header itself may be a regular pattern (though this should be used with
caution).
.TP
\fBAddHeader\fR "header: to add"
Add the defined header to the request passed to the back-end server. The header
is added verbatim. Use multiple \fIAddHeader\fR directives if you need to add more
than one header.
.TP
\fBRewriteLocation\fR 0|1|2
If 1 force
.B Pound
to change the Location: and Content-location: headers in responses. If they
point to the back-end itself or to the listener (but with the wrong protocol)
the response will be changed to show the virtual host in the request. Default:
1 (active). If the value is set to 2 only the back-end address is compared;
this is useful for redirecting a request to an HTTPS listener on
the same server as the HTTP listener.
.TP
\fBRewriteDestination\fR 0|1
If 1 force
.B Pound
to change the Destination: header in requests. The header is changed to point
to the back-end itself with the correct protocol. Default: 0.
.TP
\fBLogLevel\fR value
Override the global
.I LogLevel
value.
.TP
\fBService\fR [ "name" ]
This defines a private service (see below for service definition syntax). This
service will be used only by this listener. The service may be optionally
named, with the name showing in the
.I poundctl
listings.
.SH "HTTPS Listener"
An HTTPS listener defines an address and port that
.B Pound
will listen on for HTTPS requests. All configuration directives enclosed
between
.I ListenHTTPS
and
.I End
are specific to a single HTTPS listener. At the very least you must specify
and address, a port and a server certificate for each listener. All directives
defined for HTTP listeners are applicable to HTTPS listeners as well. The
following additional directives are also available:
.TP
\fBCert\fR "certificate file"
Specify the server certificate. The
.I certificate file
is the file containing the certificate, possibly a certificate chain and the signature
for this server. This directive is
.B mandatory
for HTTPS listeners.
.IP
Please note that multiple
.I Cert
directives are allowed if your OpenSSL version supports SNI. In such cases,
the first directive is the default certificate, with additional certificates
used if the client requests them.
.IP
The ordering of the directives is important: the first certificate where the CN
matches the client request will be used, so put your directives in the
most-specific-to-least specific order (i.e. wildcard certificates
.B after
host-specific certificates).
.IP
.I Cert
directives
.B must
precede all other SSL-specific directives.
.TP
\fBClientCert\fR 0|1|2|3 depth
Ask for the client's HTTPS certificate: 0 - don't ask (default), 1 - ask,
2 - ask and fail if no certificate was presented, 3 - ask but do not verify.
.I Depth
is the depth of verification for a client certificate (up to 9). The default
depth limit is 9, allowing for the peer certificate and additional 9 CA
certificates that must be verified.
.TP
\fBCiphers\fR "acceptable:cipher:list"
This is the list of ciphers that will be accepted by the SSL connection; it is a
string in the same format as in OpenSSL
.I ciphers(1)
and
.I SSL_CTX_set_cipher_list(3).
.TP
\fBSSLHonorCipherOrder\fR 0|1
If this value is 1, the server will broadcast a preference to use \fBCiphers\fR in
the order supplied in the \fBCiphers\fR directive. If the value is 0, the server
will treat the Ciphers list as the list of Ciphers it will accept, but no preference
will be indicated. Default value is 0.
.TP
\fBSSLAllowClientRenegotiation\fR 0|1|2
If this value is 0, client initiated renegotiation will be disabled. This will
mitigate DoS exploits based on client renegotiation, regardless of the patch status
of clients and servers related to "Secure renegotiation". If the value is 1, secure
renegotiation is supported. If the value is 2, insecure renegotiation is supported,
with unpatched clients. \fBThis can lead to a DoS and a Man in the Middle attack!\fR
The default value is 0.
.TP
\fBCAlist\fR "CAcert_file"
Set the list of "trusted" CA's for this server. The CAcert_file is a file containing
a sequence of CA certificates (PEM format). The names of the defined CA certificates
will be sent to the client on connection.
.TP
\fBVerifyList\fR "Verify_file"
Set the CA (Certificate Authority). The Verify_file is a file that contains the CA
root certificates (in PEM format).
.IP
.IR "Please note":
there is an important difference between the CAlist and the VerifyList. The
CAlist tells the client (browser) which client certificates it should send. The
VerifyList defines which CAs are actually used for the verification of the
returned certificate.
.TP
\fBCRLlist\fR "CRL_file"
Set the CRL (Certificate Revocation List) file. The CRL_file is a file that contains
the CRLs (in PEM format).
.TP
\fBNoHTTPS11\fR 0|1|2
Behave like an HTTP/1.0 server for HTTPS clients. If this value is
0 disable the check. If the value is 1 do not allow multiple
requests on SSL connections. If the value is 2 (default) disable multiple
requests on SSL connections only for MSIE clients. Required
work-around for a bug in certain versions of IE.
.SH "Service"
A service is a definition of which back-end servers
.B Pound
will use to reply to incoming requests. A service may be defined as part
of a listener (in which case it will be used only by that listener), or
globally (which makes it available to all listeners).
.B Pound
will always try the private services in the order defined, followed by
the global ones.
.P
All configuration directives enclosed between
.I Service
and
.I End
are specific to a single service. The following directives are available:
.TP
\fBURL\fR "pattern"
Match the incoming request. If a request fails to match than this service
will be skipped and next one tried. If all services fail to match
.B Pound
returns an error. You may define multiple
.I URL
conditions per service. If no
.I URL
was defined then all requests match. The matching is by default case-sensitive,
but this can be overridden by specifying
.B IgnoreCase 1
.TP
\fBIgnoreCase\fR 0|1
Override the global
.B IgnoreCase
setting.
.TP
\fBHeadRequire\fR "pattern"
The request must contain at least on header matching the given pattern.
Multiple
.I HeadRequire
directives may be defined per service, in which case all of them must
be satisfied.
.TP
\fBHeadDeny\fR "pattern"
The request may
.B not
contain any header matching the given pattern. Multiple
.I HeadDeny
directives may be defined per service, in which case all of them must be satisfied.
.IP
.IR "Please note":
if the listener defined a
.I HeadRemove
directive, the matching headers are removed
.B before
the service matching is attempted.
.TP
\fBDynScale\fR 0|1
Enable or disable dynamic rescaling for the current service. This value will
override the value globally defined.
.TP
\fBDisabled\fR 0|1
Start
.B Pound
with this service disabled (1) or enabled (0). If started as disabled, the
service can be later enabled with
.I poundctl
(8).
.TP
\fBBackEnd\fR
Directives enclosed between a
.I BackEnd
and
the following
.I End
directives define a single back-end server (see below for details). You may define
multiple back-ends per service, in which case
.B Pound
will attempt to load-balance between them.
.TP
\fBRedirect\fR [code] "url"
This is a special type of back-end. Instead of sending the request to a back-end
.B Pound
replies immediately with a redirection to the given URL. You may define multiple
redirectors in a service, as well as mixing them with regular back-ends.
.IP
The address the client is redirected to is determined by the actual
.I url
you specify: if it is a "pure" host (i.e. with no path) then the client will be
redirected to the host you specified, with the original request path appended. If
your
.I url
does contain a path then the request path is ignored.
.IP
Examples: if you specified
.br
.br
Redirect "http://abc.example"
.br
.br
and the client requested
.I http://xyz/a/b/c
then it will be redirected to
.IR "http://abc.example/a/b/c",
but if you specified
.br
.br
Redirect "http://abc.example/index.html"
.br
.br
it will be sent to
.IR "http://abc.example/index.html".
.IP
.IR "Technical note":
in an ideal world
.B Pound
should reply with a "307 Temporary Redirect" status. Unfortunately, that is not
yet supported by all clients (in particular HTTP 1.0 ones), so
.B Pound
currently replies by default with a "302 Found" instead. You may override this
behaviour by specifying the code to be used (301, 302 or 307).
.TP
\fBEmergency\fR
Directives enclosed between an
.I Emergency
and
the following
.I End
directives define an emergency back-end server (see below for details). You may define
only one emergency server per service, which
.B Pound
will attempt to use if all backends are down.
.TP
\fBSession\fR
Directives enclosed between a
.I Session
and
the following
.I End
directives define a session-tracking mechanism for the current service. See below
for details.
.SH "BackEnd"
A back-end is a definition of a single back-end server
.B Pound
will use to reply to incoming requests. All configuration directives enclosed between
.I BackEnd
and
.I End
are specific to a single service. The following directives are available:
.TP
\fBAddress\fR address
The address that
.B Pound
will connect to. This can be a numeric IP address, or a symbolic host name
that must be resolvable at run-time. If the name cannot be resolved to a valid
address,
.B Pound
will assume that it represents the path for a Unix-domain socket. This is a
.B mandatory
parameter.
.TP
\fBPort\fR port
The port number that
.B Pound
will connect to. This is a
.B mandatory
parameter for non Unix-domain back-ends.
.TP
\fBHTTPS\fR [ "cert" ]
The back-end is using HTTPS. If the optional parameter
.I cert
is specified,
.B Pound
will present this certificate to the back-end.
.TP
\fBPriority\fR val
The priority of this back-end (between 1 and 9, 5 is default). Higher priority
back-ends will be used more often than lower priority ones, so you should
define higher priorities for more capable servers.
.TP
\fBTimeOut\fR val
Override the global
.I TimeOut
value.
.TP
\fBConnTO\fR val
Override the global
.I ConnTO
value.
.TP
\fBHAport\fR [ address ] port
A port (and optional address) to be used for server function checks. See below
the "High Availability" section for a more detailed discussion. By default
.B Pound
uses the same address as the back-end server, but you may use a separate address
if you wish. This directive applies only to non Unix-domain servers.
.TP
\fBDisabled\fR 0|1
Start
.B Pound
with this back-end disabled (1) or enabled (0). If started as disabled, the
back-end can be later enabled with
.I poundctl
(8).
.SH "Emergency"
The emergency server will be used once all existing back-ends are "dead".
All configuration directives enclosed between
.I Emergency
and
.I End
are specific to a single service. The following directives are available:
.TP
\fBAddress\fR address
The address that
.B Pound
will connect to. This can be a numeric IP address, or a symbolic host name
that must be resolvable at run-time. If the name cannot be resolved to a valid
address,
.B Pound
will assume that it represents the path for a Unix-domain socket. This is a
.B mandatory
parameter.
.TP
\fBPort\fR port
The port number that
.B Pound
will connect to. This is a
.B mandatory
parameter for non Unix-domain back-ends.
.SH "Session"
Defines how a service deals with possible HTTP sessions. All configuration
directives enclosed between
.I Session
and
.I End
are specific to a single service. Once a sessions is identified,
.B Pound
will attempt to send all requests within that session to the same back-end
server.
.PP
The following directives are available:
.TP
\fBType\fR IP|BASIC|URL|PARM|COOKIE|HEADER
What kind of sessions are we looking for: IP (the client address), BASIC (basic
authentication), URL (a request parameter), PARM (a URI parameter), COOKIE (a
certain cookie), or HEADER (a certain request header).
This is a
.B mandatory
parameter.
.TP
\fBTTL\fR seconds
How long can a session be idle (in seconds). A session that has been idle for
longer than the specified number of seconds will be discarded.
This is a
.B mandatory
parameter.
.TP
\fBID\fR "name"
The session identifier. This directive is permitted only for sessions of type
URL (the name of the request parameter we need to track), COOKIE (the name of
the cookie) and HEADER (the header name).
.PP
See below for some examples.
.SH HIGH-AVAILABILITY
.B Pound
attempts to keep track of active back-end servers, and will temporarily disable
servers that do not respond (though not necessarily dead: an overloaded server
that
.B Pound
cannot establish a connection to will be considered dead). However, every
.I Alive
seconds, an attempt is made to connect to the dead servers in case they have become
active again. If this attempt succeeds, connections will be initiated to them again.
.PP
In general it is a good idea to set this time interval as low as is consistent with
your resources in order to benefit from resurected servers at the earliest possible
time. The default value of 30 seconds is probably a good choice.
.PP
The clients that happen upon a dead backend server will just receive a
.I "503 Service Unavailable"
message.
.PP
The
.I HAport
parameter specifies an additional port (and optionally an address)
that is used only for viability checks: if this port is specified in a
.I BackEnd
directive,
.B Pound
will attempt periodically (every
.I Alive
seconds) to connect to this port. If the port does not respond the server is considered dead.
.B "It never makes sense to have the"
.I HAport
.B "identical to the main back-end port:"
this would only generate extra, unncecessary activity (CPU, network traffic) for no good
reason whatsoever. The
.I HAport
is meant for applications that offer an additional health monitoring port or for installations
that wish to take servers off-line in a controlled manner.
.PP
By default the address of the
.I HAport
health monitor is the same as that of the
back-end server. You may specify a different address though, for example if you have
a monitoring program running on another host.
.SH HTTPS HEADERS
If a client browser connects to
.B Pound
via HTTPS and if it presents a client certificate
.B Pound
adds the following headers to the request it issues to the server:
.TP
\fBX-SSL-Subject\fR
Details about the certificate owner.
.TP
\fBX-SSL-Issuer\fR
Details about the certificate issuer (Certificate Authority).
.TP
\fBX-SSL-notBefore\fR
Starting date of certificate validity.
.TP
\fBX-SSL-notAfter\fR
Ending date of certificate validity.
.TP
\fBX-SSL-serial\fR
Certificate serial number (decimal).
.TP
\fBX-SSL-cipher\fR
The cipher currently in use.
.TP
\fBX-SSL-certificate\fR
The full client certificate (PEM-format multi-line)
.PP
It is the application's responsibility to actually use these
headers - Pound just passes this information without checking
it in any way (except for signature and encryption correctness).
.SH SECURITY
.PP
In general,
.B Pound
does not read or write to the hard-disk. The exceptions are reading the configuration file
and (possibly) the server certificate file(s) and error message(s), which are opened read-only
on startup, read,
and closed, and the pid file which is opened on start-up, written to and immediately closed.
Following this there is no disk access whatsoever, so using a RootJail directive is only
for extra security bonus points.
.PP
.B Pound
tries to sanitise all HTTP/HTTPS requests: the request itself, the headers and the contents
are checked for conformance to the RFC's and only valid requests are passed to the back-end
servers. This is not absolutely fool-proof - as the recent Apache problem with chunked
transfers demonstrated. However, given the current standards, this is the best that can
be done - HTTP is an inherently weak protocol.
.SH ADDITIONAL NOTES
.B Pound
uses the system log for messages (default facility LOG_DAEMON). The format is very similar to
other web servers, so that if you want to use a log tool:
.TP
fgrep pound /var/log/messages | your_log_tool
.PP
Translating HTTPS to HTTP is an iffy proposition: no client information is passed to
the server itself (certificates, etc) and the backend server may be misled if it
uses absolute URLs. A patch for \fIZope\fR is included in the distribution to address
this issue - for other Web servers you are on your own. May the source be with you.
.PP
.B Pound
deals with (and sanitizes) HTTP/1.1 requests. Thus even if you have an HTTP/1.0 server,
a single connection to an HTTP/1.1 client is kept, while the connection to the back-end
server is re-opened as necessary.
.PP
.B Pound
attempts to resolve the names of the hosts that appear in various requests and/or responses.
That means it need a functioning resolver of some kind (be it /etc/hosts, DNS or something
else).
.SH EXAMPLES
To translate HTTPS requests to a local HTTP server (assuming your network address
is 123.123.123.123):
.IP
ListenHTTPS
.br
Address 1.2.3.4
.br
Port 443
.br
Cert "/etc/pound/server.pem"
.br
.br
Service
.br
BackEnd
.br
Address 127.0.0.1
.br
Port 80
.br
End
.br
End
.br
End
.PP
To distribute the HTTP/HTTPS requests to three Web servers, where the third one
is a newer and faster machine:
.IP
ListenHTTP
.br
Address 123.123.123.123
.br
Port 80
.br
End
.br
ListenHTTPS
.br
Address 1.2.3.4
.br
Port 443
.br
Cert "/etc/pound/server.pem"
.br
End
.br
.br
Service
.br
BackEnd
.br
Address 192.168.0.10
.br
Port 80
.br
End
.br
BackEnd
.br
Address 192.168.0.11
.br
Port 80
.br
End
.br
BackEnd
.br
Address 192.168.0.12
.br
Port 80
.br
Priority 3
.br
End