1 files changed, 93 insertions, 34 deletions

diff --git a/README b/README
index 30140c4..ca814ba 100644
--- a/README
+++ b/README
@@ -1,33 +1,34 @@
-Vmod_remoteip
-=============
+#+TITLE: vmod_remoteip: Deduce actial client IP address for Varnish Cache
 
-Overview
---------
+* Overview
 
-This modules is for Varnish Cache what mod_remoteip is for Apache. It
+This module is for Varnish Cache what =mod_remoteip= is for Apache. It
 determines the actual client IP address for the connection, using the
-useragent IP address list presented by a proxies or a load balancer
+useragent IP address list presented by a proxy or load balancer
 via the request headers and a preconfigred list of trusted IP
 addresses.  For example, if your Varnish server works behind a load
 balancer or yet another reverse proxy (such as pound or haproxy to
 handle the TLS connection), you can use this module to get the real
-incoming connection IP address from the "X-Forwarded-For" header.
+incoming connection IP address from the =X-Forwarded-For= header.
 
-Example
--------
+* Example
 
-An example of using this module:
+The following example VCL uses the client address deduced from the
+value of the =X-Forwarded-For= header to enable the code specific for
+hosts from the ACL "allowed":
 
+#+BEGIN_SRC vcl-script
   import std;
   import remoteip;
  
   sub vcl_init {
-      remoteip.init("192.0.2.1, 127.0.0.0/8");
+      // Register trusted proxy server addresses
+      remoteip.init("192.0.2.1, 127.0.0.1");
   }
 
   acl allowed {
-      "127.0.0.1";
-      ...
+      "203.0.113.1";
+      "192.0.2.10";
   }
 
   sub vcl_recv {
@@ -36,60 +37,118 @@ An example of using this module:
           ...
       }
   }
+#+END_SRC
 
-Installation
-------------
+* Installation
 
-In order to compile the package you need to have installed
-varnishd and varnishapi package.  The module has been tested with
-Varnish version 6.3.1.
+In order to compile the package you need the varnishd and varnishapi
+packages.  The module has been tested with Varnish version 6.3.1 and
+higher.  Python 3, [[https://sourceforge.net/projects/docutils][Docutils]] 
+and [[http://sphinx-doc.org][Sphinx]] are needed to build documentation.
+On Debian-based systems, this requires the =python3-docutils= and
+=python3-sphinx= packages.
 
-Supposing that condition is met, run:
+If these prerequisites are met, run:
 
+#+BEGIN_SRC shell-script
    ./configure
+#+END_SRC
 
-If your system offers Python versions 2.x and 3.x, it is quite often that
-version 2.x is used by default.  In that case, we recommend to explicitly
-require version 3.x, as shown in this example:
+If both Python versions 2.x and 3.x are installed on the system,
+chances are version 2 is used by default.  In that case, require
+version 3 explicitly, as shown in this example: 
 
+#+BEGIN_SRC shell-script
    ./configure PYTHON=python3
+#+END_SRC
    
 Otherwise, the configure script should be able to automatically find
 the necessary components.  In case it doesn't, tweak the configuration
-variables as necessary.  The most important one is PKG_CONFIG_PATH,
-which contains a path (in the UNIX sense) where the .pc files are
-located.  It should contain a directory where the 'varnishapi.pc' file
+variables as necessary.  The most important one is =PKG_CONFIG_PATH=,
+which contains a path (in the UNIX sense) where the =.pc= files are
+located.  It should contain a directory where the =varnishapi.pc= file
 lives.  Example usage:
 
+#+BEGIN_SRC shell-script
    ./configure PKG_CONFIG_PATH=/opt/varnish/lib/pkgconfig:$PKG_CONFIG_PATH
+#+END_SRC
 
-Please read the file INSTALL for a detailed discussion of available variables
+Please read the file =INSTALL= for a detailed discussion of available variables
 and command line options.
 
 Once configured, do
-
-  make
+ 
+#+BEGIN_SRC shell-script
+   make
+#+END_SRC
 
 This will build the module.  After this step you can optionally run
-'make test' to test the package.
+=make test= to test the package.
 
 Finally, run the following command as root:
 
+#+BEGIN_SRC shell-script
   make install
+#+END_SRC
 
-Documentation
--------------
+* Documentation
 
-The manual page vmod_remoteip(3) will be available after a successful
-install.  To read it without actually installing the module, run
-`man src/vmod_remoteip.3'.
+The manual page
+[[http://man.gnu.org.ua/manpage/?3+vmod_remoteip][vmod_remoteip(3)]] will
+be available after a successful install.  To read it without actually
+installing the module, run =man src/vmod_remoteip.3= .
 
 An online copy of the documentation is available from
 http://ps.gnu.org.ua/software/vmod-remoteip.
 
+* Downloads
+
+Source tarballs can be downloaded from
+https://download.gnu.org.ua/release/vmod-remoteip.
+
+The git repository is available at
+http://git.gnu.org.ua/cgit/vmod-remoteip.git.
+
+The project home page is
+https://puszcza.gnu.org.ua/projects/vmod-remoteip.
+
+* Copyright
+
+Copyright (C) 2020 Sergey Poznyakoff
+
+Permission is granted to anyone to make or distribute verbatim copies
+of this document as received, in any medium, provided that the
+copyright notice and this permission notice are preserved,
+thus giving the recipient permission to redistribute in turn.
+
+Permission is granted to distribute modified versions
+of this document, or of portions of it,
+under the above conditions, provided also that they
+carry prominent notices stating who last changed them.
+
 * Bug reporting
 
 Send bug reports and suggestions to <gray@gnu.org>
 
+* Document settings :noexport:
+
+Please ignore this section. It supplies the variables necessary for
+proper rendering of this document.
+
+:PROPERTIES:
+:VISIBILITY: folded
+:END:
+
+#+STARTUP: showall
+#+EXCLUDE_TAGS: noexport
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
+#+OPTIONS: ^:nil
+
+# Local Variables:
+# mode: org
+        # paragraph-separate: "[ ]*$"
+# version-control: never
+# End:
+