[Initialization] Pound 2.8a initialization

Signed-off-by: Emilio <[email protected]>

	new file:   CHANGELOG
	new file:   FAQ
	new file:   GPL.txt
	new file:   Makefile.in
	new file:   README
	new file:   apuntes.txt
	new file:   config.c
	new file:   config.guess
	new file:   config.h.in
	new file:   config.sub
	new file:   configure
	new file:   dh2048.pem
	new file:   http.c
	new file:   install-sh
	new file:   pound.8
	new file:   pound.c
	new file:   pound.h
	new file:   poundctl.8
	new file:   poundctl.c
	new file:   stamp-h1
	new file:   svc.c
	new file:   version.c
	new file:   z2_2_5_1.py
	new file:   z2_2_6_1.py

FAQ

@@ -0,0 +1,395 @@
+FREQUENTLY ASKED QUESTIONS
+
+1. General
+==========
+
+1.1 Will Pound run my Web application?
+
+    No. Pound is a proxy, not a Web server - it does not deliver content by
+    itself. It is just the middle-man between a client and a server.
+
+1.2 Will Pound make my server go faster?
+
+    No. Pound is just a proxy - no caching of any kind takes place. Pound
+    IS able to distribute requests between several back-end servers, thus
+    allowing for faster overall response times, but it won't speed-up a
+    single Web sever.
+
+1.3 Will Pound make my server more secure?
+
+    Probably yes. Pound has its own checks on the validity of HTTP requests
+    and often catches malicious requests that are used to attack Web servers.
+
+1.4 Can I use Pound to change/rewrite/redirect requests?
+
+    No. Pound tries to be as transparent as possible - ideally a client
+    should not be aware that there is anything between itself and the actual
+    Web server. A limited form of redirect is available - see the man page.
+
+1.5 Can I use Pound to deny certain requests?
+
+    Yes. Pound has a rather good mechanism for classifying requests and it
+    can deny/reject certain requests based on URL and/or header content.
+
+
+2. Configuration, Compilation and Installation
+==============================================
+
+2.1 I try to compile and it fails on "needs OpenSSL with thread support"
+
+    Pound is a multi-threaded program and it needs an OpenSSL library
+    compiled with thread support (optional in the OpenSSL configuration and
+    absent in some default installations, such as *BSD). If your default
+    library does not support threads you must install a thread-enabled
+    version.
+
+2.2 Pound compiles correctly but crashes on *BSD
+
+    On some of the newer versions of *BSD (FreeBSD 5.x, OpenBSD 3.x) the
+    Pound autoconf may not correctly recognize the threading library. Add
+    manually to the generated Makefile the option -DNEED_STACK in the
+    CFLAGS.
+
+2.3 I want to run Pound with daemon-tools but it goes to background
+
+    You need to configure Pound for non-daemon operations: add "Daemon 0"
+    to the config file.
+
+2.4 Pound runs OK but some normal requests are rejected with "bad URL"
+
+    Pound checks the requested URLs quite thoroughly and rejects malformed
+    or illegal URLs - or at least illegal according to the RFCs. See the
+    man page for details.
+
+2.5 Pound runs OK but I get a "pthread_create" error message
+
+    You may be hitting the system limit on the number of processes. On
+    systems that implement threads as processes (as Linux does) you should
+    make sure that the Pound process has permission to start a sufficient
+    number of processes.
+
+    In some rare cases you may be running into the system limit on the
+    number of threads. Check your system details for the value of
+    PTHREAD_THREADS_MAX. If needed you must recompile the threads library
+    with a higher value.
+
+2.6 What resources does Pound need/use?
+
+    That depends very much on your system. On some systems, such as Linux
+    and System V (AIX, HP-UX, etc), threads are implemented as processes,
+    which means you must allow enough processes to run. On other systems,
+    such as *BSD, where threads are implemented in user space (in-process),
+    you should make sure that Pound can use sufficient memory for all the
+    threads and that the process is allowed to use enough file descriptors
+    (2 per active connection). Finally, on systems that implement threads
+    natively, such as Solaris, you need to make sure that enough threads
+    and open file descriptors are allowed.
+
+2.7 Is NPTL supported?
+
+    Theoretically Pound will work with any POSIX-compliant threads package.
+    In practice some of the newer NPTL implementations still have some
+    bugs. At least on Linux running Pound with LD_ASSUME_KERNEL=2.4.19
+    may be helpful.
+
+
+3. Virtual Hosts
+================
+
+3.1 How do I redirect specific virtual hosts to specific back-ends?
+
+    Make the virtual host mandatory in the UrlGroup. For example, to have
+    all requests to www.a.com go to 192.168.0.10 and all requests for
+    www.b.com go to 192.168.0.20, define
+
+        Service
+            HeadRequire "Host:.*www.a.com.*"
+            BackEnd
+                Address 192.168.0.10
+                Port    80
+            End
+        End
+
+        Service
+            HeadRequire "Host:.*www.b.com.*"
+            BackEnd
+                Address 192.168.0.20
+                Port    80
+            End
+        End
+
+    in your config file.
+
+3.2 How do I redirect requests to specific back-ends based on the client
+    address?
+
+    You can do it easier via the packet filter you use. If you insist on
+    having Pound do it use a combination of port redirection and separate
+    instances of Pound for each port. For example, assume you want intranet
+    clients (on 192.168.100.0/24) to use the server at 192.168.1.10 and
+    external clients go to 192.168.1.20. Do the following:
+
+        - redirect requests from 192.168.100.0/24 to port 8080
+
+            pf: rdr on rl0 from 192.168.100.0/24 to 192.168.100.1 port 80 \
+                -> localhost port 8080
+
+            netfilter: iptables -t nat -A PREROUTING -p tcp \
+                -s 192.168.100.0/24 --dport 80 -i eth0 -j DNAT \
+                --to localhost:8080
+
+        - redirect requests from anywhere else to port 8081
+
+            pf: rdr on rl0 from any to 192.168.100.1 port 80 \
+                -> localhost port 8081
+
+            netfilter: iptables -t nat -A PREROUTING -p tcp \
+                --dport 80 -i eth0 -j DNAT --to localhost:8081
+
+        - have a Pound listener on port 8080 and sending the
+          requests to 192.168.1.10
+
+        - have a Pound listener on port 8081 and sending the
+          requests to 192.168.1.20
+
+3.3 What happens when my server replies with a redirect?
+
+    Depending on configuration, Pound can watch for redirect replies from back-ends
+    and change them to the correct address. In order for this to happen the
+    following conditions must be met:
+
+    - Pound has "Check30x 1"
+    - the back-end replies with a redirect. The address of that URL resolves to
+      the same address as the one Pound is listening on or the address of the
+      back-end itself.
+
+    This feature is commonly used when Pound serves as a HTTPS wrapper,
+    as the backend redirect to "Location: http://x.y.com" is rewritten as
+    "Location: https://x.y.com".
+
+
+4. HTTPS
+========
+
+4.1 Can I have Pound force HTTPS connections to certain URLs/back-ends?
+
+    Yes - define a Service with a Redirect back-end.
+
+4.2 How can I do virtual hosting with HTTPS?
+
+    The simple answer is that neither you, nor anybody else can, due to a
+    limitation of the HTTPS protocol. In its simplest form an HTTPS (SSL)
+    connection goes through the following stages:
+
+    - negotiation: the client contacts the server, receives a certificate
+      from it, and negotiates the protocol details (cipher parameters, etc).
+
+    - authentication: the client checks that the certificate received matches
+      the server it wanted and validates that the certificate is correct as
+      attested by some certificate authority.
+
+    - request/response: normal HTTP, encrypted in transit.
+
+    As you can see the certificate is sent before any request was received.
+    Unfortunately, the first request specifies the virtual host that the
+    client would like to talk to - and it may not match the server name in
+    the certificate.
+
+4.3 Pound does not start with message "can't read private key"
+
+    The file you specify in the ListenHTTPS directive must contain both the
+    server certificate and the private key to it in PEM format. See the man
+    page for SSL_CTX_use_PrivateKey_file(3) for details.
+
+4.4 How can a back-end know that the connection is via HTTPS?
+
+    Pound can add a header for incoming requests indicating that they were
+    received via HTTPS. See the details on AddHeader in the man page.
+
+4.5 HTTPS connections fail when Pound runs chrooted
+
+    The OpenSSL library requires access to /dev/urandom for its random seed.
+    The normal device is not accessible in a jail root. You should add a
+    link to the device to make it accessible. On Linux this would be:
+
+        mknod /var/pound/dev/urandom c 1 9
+
+    assuming that /var/pound is the root jail.
+
+4.6 How can I force a back-end to generate the correct URL with HTTPS
+
+    There is no simple answer to this question - each server and application
+    have their own way of doing things. If your server does not use absolute
+    paths then all is well - things will run out of the box. However if some
+    frames, images, links or a base tag are generated with an absolute path
+    you must find a way to force the generation with https://.
+
+4.7 How can I find out about the client certificate in my application?
+
+    For requests via HTTPS connections Pound can add the details of the
+    client certificate as headers to each and every request it passes to
+    the back-end. See the details on HTTPSHeaders in the man page.
+
+4.8 Can Pound use my crypto accelerator hardware?
+
+    Pound supports the OpenSSL engine architecture. If your crypto card is
+    supported by OpenSSL then it is supported by Pound. See the SSLEngine
+    directive in the man page.
+
+4.9 Can Pound use HTTPS back-end servers?
+
+    Yes, but that is not always a very good idea. Such a setup would essentially
+    make Pound into a "man-in-the-middle" program. Even worse, the certificates
+    on the back-end would become meaningless - they are seen only by Pound.
+
+
+5. Session tracking
+===================
+
+5.1 Can I have session tracking based on URL and/or Cookie?
+
+    Pound can track sessions based on client IP address, a cookie, an URL
+    parameter or BasicAuthentication. These options are mutually exclusive -
+    only one of them can be used per UrlGroup.
+
+5.2 When does a session expire?
+
+    A session is kept for the specified number of seconds. If during this
+    time no new request was received the session is discarded.
+
+5.3 Does Pound create/track its own sessions?
+
+    No. Pound does not add anything to the requests or the responses - it
+    uses the tokens generated by the back-end servers exclusively.
+
+
+6. Logging
+==========
+
+6.1 Can I use Webalizer on Pound log files?
+
+    Yes. If you use LogLevel 3 or 4 Pound uses one of the standard log
+    formats that are recognized by applications such as Webalizer. You will
+    have to remove the time-stamp generated by the syslog - see cut(1) for
+    details.
+
+6.2 How do I log the original client address in the back-end log?
+
+    Pound adds the X-Forwarded-for header with the original client address
+    to every request. Use it for your logs on the back-end servers.
+
+6.3 How can I separate the Pound log from other syslog messages?
+
+    If you use the syslog facility you can configure it to send the pound
+    messages to a separate file. You may want to separate by severity as
+    well - normal log messages use LOG_INFO, everything else is not request
+    information. See syslogd(8) for details on how to configure it.
+
+6.4 How can I separate error messages from normal log messages?
+
+    If you use syslog: normal requests are logged at LOG_INFO, everything
+    else is higher.
+
+    If you run without syslog: normal request logging to stdout, everything
+    else to stderr.
+
+6.5 Why does Pound not log anything when chrooted?
+
+    On some systems you need access to /dev/log in order to use the syslog(8)
+    facility. Create/link the device as needed in the root jail you use.
+
+6.6 Why can't Pound log directly to a file?
+
+    This is a security requirement. As things stand, Pound does not write at
+    all to the disk. The existing tools - such as syslog - allow all the
+    flexibility one could wish for.
+
+    If you absolutely must you can try the patches from Shinji Tanaka (see
+    http://www.hatena-inc.co.jp/~stanaka/pound/ for details).
+
+
+7. WebDAV
+=========
+
+7.1 I compiled Pound with DAV support but it still rejects the requests
+
+    You also need to define "WebDAV 1" in your config file, and (depending on
+    your server or application) "xHTTP 1" as well.
+
+7.3 Can I use Pound as a front-end for Subversion?
+
+    Yes. You may have some problems with using it via HTTPS, but HTTP should
+    work.
+
+
+8. Zope
+=======
+
+8.1 What configurations is Pound most helpful for?
+
+    If you have several servers running on top of a ZEO server, Pound will
+    allow you to load-balance between them (BTW, this was the original
+    motivation for developing Pound). Pound also makes for a very good,
+    light-weight front-end for a single Zope - exposing the Zope Web-server
+    directly on the big, bad Internet is not a very good idea.
+
+8.2 Can I have virtual hosts in Zope without Apache?
+
+    Yes. Despite persistent rumors, the Virtual Host Monster works perfectly
+    well on its own (dark incantations at midnight under the shade of the
+    cross-shaped oak branch are NOT required). All you need to do is to
+    add a VHM in the Zope root, click on the Mappings tab and add whatever
+    hosts you need.
+
+8.3 Can I have HTTPS for Zope?
+
+    Yes. Pound will happily pass SSL requests to Zope. You have three possible
+    methods to force Zope to generate responses with the https:// prefix:
+
+    - if all you need is a specific area to be accessible only through HTTPS
+      you can add a SiteRoot with the correct name.
+
+    - alternately the Pound distribution includes patches for z2.py that
+      include a new -y flag for a "https://" port.
+
+    - finally, for version 2.7 or later you can set it in zope.conf.
+
+8.4 Can I force HTTPS for certain areas in Zope?
+
+    Yes. Add a check for the SSL-specific headers in the dtml_header or
+    whatever equivalent you use. See the details on HTTPSHeaders in the man
+    page.
+
+
+9. Miscellaneous/MS
+===================
+
+9.1 IE fails to connect to Pound via HTTPS
+
+    Define the ciphers to be
+
+        "ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL"
+
+    in the config file. We have had reports of IE problems with other
+    ciphers.
+
+9.2 IE has big delays in getting replies from Pound
+
+    Try a shorter Client timeout. IE uses exactly 4 sockets, and as long as
+    they stay open it won't do anything else. A short Client value will
+    force the socket(s) to be closed earlier, thus avoiding annoying waits.
+
+9.3 I try to run MS OWA and Pound rejects the requests
+
+    Make sure you configured Pound with --enable-msdav. Make sure you
+    included "WebDAV 1" in the config file. Pray that MS would adhere to
+    some known standard. Repeat as necessary.
+
+9.4 How can I force OWA to accept HTTPS requests?
+
+    Make sure to define
+
+        AddHeader   "Front-End-Https: on"
+
+    in the config file. This will force OWA to generate the responses with
+    the correct protocol.