apache-frontend: Update documentation to match reality

software/apache-frontend/README.apache_frontend.txt

@@ -8,6 +8,13 @@ apache_frontend works using the master instance / slave instance design.
 It means that a single main instance of Apache will be used to act as frontend
 for many slaves.
 
+Software type
+=============
+
+Apache frontend is available in 3 software types:
+  * default : The standard way to use the apache frontend configuring everything with a few given parameters
+  * custom-personal : This software type allow each slave to edit its apache configuration file
+  * custom-group : This software type use a template given as a parameter on master instance to generate apache configuration for all slaves
 
 How to deploy a frontend server
 ===============================
@@ -44,23 +51,23 @@ Finally, the slave instance will be accessible from:
 https://someidentifier.moulefrite.org.
 
 
-How to have custom configuration in frontend server
-===================================================
-
-In your instance directory, you, as sysadmin, can directly edit two
-configuration files that won't be overwritten by SlapOS to customize your
-instance:
-
- * $PARTITION_PATH/srv/srv/apache-conf.d/apache_frontend.custom.conf
- * $PARTITION_PATH/srv/srv/apache-conf.d/apache_frontend.virtualhost.custom.conf
-
-The first one is included in the end of the main apache configuration file.
-The second one is included in the virtualhost of the main apache configuration file.
-
-SlapOS will jsut create those two files for you, then completely forget them.
-
-Note: make sure that the UNIX user of the instance has read access to those
-files if you edit them.
+#How to have custom configuration in frontend server
+#===================================================
+#
+#In your instance directory, you, as sysadmin, can directly edit two
+#configuration files that won't be overwritten by SlapOS to customize your
+#instance:
+#
+# * $PARTITION_PATH/srv/srv/apache-conf.d/apache_frontend.custom.conf
+# * $PARTITION_PATH/srv/srv/apache-conf.d/apache_frontend.virtualhost.custom.conf
+#
+#The first one is included in the end of the main apache configuration file.
+#The second one is included in the virtualhost of the main apache configuration file.
+#
+#SlapOS will jsut create those two files for you, then completely forget them.
+#
+#Note: make sure that the UNIX user of the instance has read access to those
+#files if you edit them.
 
 Instance Parameters
 ===================
@@ -78,6 +85,10 @@ for the subdomains of the chosen domain like::
 Using the IP given by the Master Instance.
 "domain" is a mandatory Parameter.
 
+public-ipv4
+~~~~~~~~~~~
+Public ipv4 of the frontend (the one Apache will be indirectly listening to)
+
 port
 ~~~~
 Port used by Apache. Optional parameter, defaults to 4443.
@@ -87,8 +98,17 @@ plain_http_port
 Port used by apache to serve plain http (only used to redirect to https).
 Optional parameter, defaults to 8080.
 
-Slave Instance Parameters
--------------------------
+apache_custom_http (custom-group)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Jinja template for apache virtualhost http configuration. It will be used by all slaves
+
+apache_custom_https (custom-group)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Jinja template for apache virtualhost https configuration. It will be used by all slaves
+
+
+Slave Instance Parameters (default)
+-----------------------------------
 
 url
 ~~~
@@ -98,10 +118,9 @@ Example: http://mybackend.com/myresource
 
 enable_cache
 ~~~~~
-Specify if slave instance should use a varnish / stunnel to connect to backend.
-Possible values: "true", "false".
-"enable_cache" is an optional parameter. Defaults to "false".
-Example: true
+Specify if slave instance should use a squid to connect to backend.
+Its presence in slave parameter enable the cache for the slave
+"enable_cache" is an optional parameter.
 
 type
 ~~~~
@@ -111,10 +130,10 @@ Possible values: "zope", "default".
 "type" is an optional parameter. Defaults to "default".
 Example: zope
 
-custom_domain
-~~~~~~~~~~~~~
+domain (former custom_domain)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Domain name to use as frontend. The frontend will be accessible from this domain.
-"custom_domain" is an optional parameter. Defaults to
+"domain" is an optional parameter. Defaults to
 [instancereference].[masterdomain].
 Example: www.mycustomdomain.com
 
@@ -122,8 +141,8 @@ https-only
 ~~~~~~~~~~
 Specify if website should be accessed using https only. If so, the frontend
 will redirect the user to https if accessed from http.
-Possible values: "true", "false".
-This is an optional parameter. Defaults to false.
+Its presence in parameters enable its functionality.
+This is an optional parameter.
 
 path
 ~~~~
@@ -135,14 +154,73 @@ VirtualHostMonster.
 "path" is an optional parameter, ignored if not specified.
 Example of value: "/erp5/web_site_module/hosting/"
 
+Slave Instance Parameters (custom-personal)
+-------------------------------------------
+
+apache_custom_https
+~~~~~~~~~~~~~~~~~~~
+Raw apache configuration in python template format (i.e. write "%%" for one "%") for the slave listening to the https port. Its content will be templatified in order to access functionalities such as cache access, ssl certificates... The list is available above.
+
+apache_custom_http
+~~~~~~~~~~~~~~~~~~
+Raw apache configuration in python template format (i.e. write "%%" for one "%") for the slave listening to the http port. Its content will be templatified in order to access functionalities such as cache access, ssl certificates... The list is available above
+
+url
+~~~
+Necesarry to activate cache. url of backend to use.
+"url" is an optional parameter.
+Example: http://mybackend.com/myresource
+
+domain
+~~~~~~
+Necesarry to activate cache. The frontend will be accessible from this domain.
+"domain" is an optional parameter.
+Example: www.mycustomdomain.com
+
+enable_cache
+~~~~~~~~~~~~
+Necesarry to activate cache.
+"enable_cache" is an optional parameter.
+
+ssl_key, ssl_crt, ssl_ca_crt, ssl_crs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SSL certificates of the slave.
+They are optional.
+
+Functionalities for apache configuration:
+In the slave apache configuration you can use parameters that will be replaced during instanciation. They should be entered as python templates parameters ex:" %(parameter)s"
+  * cache_access : url of the cache. Should replace backend url in configuration to use the cache
+  * error_log : path of the slave error log in order to log in a deferenciated file.
+  * error_log : path of the slave access log in order to log in a deferenciated file.
+  * ssl_key, ssl_crt, ssl_ca_crt, ssl_crs : path of the certificates given in slave instance parameters
+
+Slave Instance Parameters (custom-group)
+----------------------------------------
+
+url
+~~~
+Necesarry to activate cache. url of backend to use.
+"url" is an optional parameter.
+Example: http://mybackend.com/myresource
+
+domain
+~~~~~~
+Domain name to use as frontend. The frontend will be accessible from this domain.
+"domain" is an optional parameter necessary to activate cache. Defaults to
+[instancereference].[masterdomain].
+Example: www.mycustomdomain.com
+
+The rest of the parameters are defined by templates given to the master and accessible by the slave_parameter dict in it.
+
+
 Examples
 ========
 
 Here are some example of how to make your SlapOS service available through
 an already deployed frontend.
 
-Simple Example
---------------
+Simple Example (default)
+------------------------
 
 Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
 redirected and accessible from the proxy::
@@ -157,8 +235,8 @@ redirected and accessible from the proxy::
   )
 
 
-Zope Example
-------------
+Zope Example (default)
+----------------------
 
 Request slave frontend instance using a Zope backend so that
 https://[1:2:3:4:5:6:7:8]:1234 will be redirected and accessible from the
@@ -175,8 +253,8 @@ proxy::
   )
 
 
-Advanced example
-----------------
+Advanced example (default)
+--------------------------
 
 Request slave frontend instance using a Zope backend, with Varnish activated,
 listening to a custom domain and redirecting to /erp5/ so that
@@ -192,7 +270,197 @@ the proxy::
         "enable_cache":"true",
         "type":"zope",
         "path":"/erp5",
-        "custom_domain":"mycustomdomain.com",
+        "domain":"mycustomdomain.com",
+    }
+  )
+
+Simple Example (custom-personal)
+--------------------------------
+
+Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
+  instance = request(
+    software_release=apache_frontend,
+    software_type="RootSoftwareInstance",
+    partition_reference='my frontend',
+    shared=True,
+    software_type="custom-personal",
+    partition_parameter_kw={
+        "url":"https://[1:2:3:4:5:6:7:8]:1234",
+        "apache_custom_https":'
+  ServerName www.example.org
+  ServerAlias www.example.org
+  ServerAlias example.org
+  ServerAdmin geronimo@example.org
+
+  SSLEngine on
+  SSLProxyEngine on
+  # Rewrite part
+  ProxyVia On
+  ProxyPreserveHost On
+  ProxyTimeout 600
+  RewriteEngine On
+  RewriteRule ^/(.*) https://[1:2:3:4:5:6:7:8]:1234/$1 [L,P]',
+        "apache_custom_http":'
+  ServerName www.example.org
+  ServerAlias www.example.org
+  ServerAlias example.org
+  ServerAdmin geronimo@example.org
+  SSLProxyEngine on
+  # Rewrite part
+  ProxyVia On
+  ProxyPreserveHost On
+  ProxyTimeout 600
+  RewriteEngine On
+
+  # Remove "Secure" from cookies, as backend may be https
+  Header edit Set-Cookie "(?i)^(.+);secure$" "$1"
+
+  # Not using HTTPS? Ask that guy over there.
+  # Dummy redirection to https. Note: will work only if https listens
+  # on standard port (443).
+  RewriteRule ^/(.*) https://[1:2:3:4:5:6:7:8]:1234/$1 [L,P],
+    }
+  )
+
+Simple Cache Example (custom-personal)
+--------------------------------
+
+Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
+  instance = request(
+    software_release=apache_frontend,
+    software_type="RootSoftwareInstance",
+    partition_reference='my frontend',
+    shared=True,
+    software_type="custom-personal",
+    partition_parameter_kw={
+        "url":"https://[1:2:3:4:5:6:7:8]:1234",
+	"domain": "www.example.org",
+	"enable_cache": "True",
+        "apache_custom_https":'
+  ServerName www.example.org
+  ServerAlias www.example.org
+  ServerAlias example.org
+  ServerAdmin geronimo@example.org
+
+  SSLEngine on
+  SSLProxyEngine on
+  # Rewrite part
+  ProxyVia On
+  ProxyPreserveHost On
+  ProxyTimeout 600
+  RewriteEngine On
+  RewriteRule ^/(.*) %(cache_access)s/$1 [L,P]',
+        "apache_custom_http":'
+  ServerName www.example.org
+  ServerAlias www.example.org
+  ServerAlias example.org
+  ServerAdmin geronimo@example.org
+  SSLProxyEngine on
+  # Rewrite part
+  ProxyVia On
+  ProxyPreserveHost On
+  ProxyTimeout 600
+  RewriteEngine On
+
+  # Remove "Secure" from cookies, as backend may be https
+  Header edit Set-Cookie "(?i)^(.+);secure$" "$1"
+
+  # Not using HTTPS? Ask that guy over there.
+  # Dummy redirection to https. Note: will work only if https listens
+  # on standard port (443).
+  RewriteRule ^/(.*) %(cache_access)s/$1 [L,P],
+    }
+  )
+
+
+Advanced example (custom-personal)
+----------------------------------
+
+Request slave frontend instance using custom apache configuration, willing to use cache and ssl certificates.
+listening to a custom domain and redirecting to /erp5/ so that
+https://[1:2:3:4:5:6:7:8]:1234/erp5/ will be redirected and accessible from
+the proxy::
+  instance = request(
+    software_release=apache_frontend,
+    software_type="RootSoftwareInstance",
+    partition_reference='my frontend',
+    shared=True,
+    software_type="custom-personal",
+    partition_parameter_kw={
+        "url":"https://[1:2:3:4:5:6:7:8]:1234",
+        "enable_cache":"true",
+        "type":"zope",
+        "path":"/erp5",
+        "domain":"example.org",
+  	"apache_custom_https":'
+  ServerName www.example.org
+  ServerAlias www.example.org
+  ServerAdmin example.org
+  SSLEngine on
+  SSLProxyEngine on
+  SSLProtocol -ALL +SSLv3 +TLSv1
+  SSLHonorCipherOrder On
+  SSLCipherSuite RC4-SHA:HIGH:!ADH
+
+  # Use personal ssl certificates
+  SSLCertificateFile %(ssl_crt)s
+  SSLCertificateKeyFile %(ssl_key)s
+  SSLCACertificateFile %(ssl_ca_crt)s
+  SSLCertificateChainFile %(ssl_ca_crt)s
+
+  # Configure personal logs
+  ErrorLog "%(error_log)s"
+  LogLevel warn
+  LogFormat "%%h %%l %%{REMOTE_USER}i %%t \"%%r\" %%>s %%b \"%%{Referer}i\" \"%%{User-Agent}i\" %%D" combined
+  CustomLog "%(access_log)s" combined
+
+  # Rewrite part
+  ProxyVia On
+  ProxyPreserveHost On
+  ProxyTimeout 600
+  RewriteEngine On
+  # Redirect / to /index.html
+  RewriteRule ^/$ /index.html [R=302,L]
+  # Use cache
+  RewriteRule ^/(.*) %(cache_access)s/VirtualHostBase/https/www.example.org:443/erp5/VirtualHostRoot/$1 [L,P]',
+
+    "apache_custom_http":'
+  ServerName www.example.org
+  ServerAlias www.example.org
+  ServerAlias example.org
+  ServerAdmin geronimo@example.org
+  SSLProxyEngine on
+  # Rewrite part
+  ProxyVia On
+  ProxyPreserveHost On
+  ProxyTimeout 600
+  RewriteEngine On
+
+  # Configure personal logs
+  ErrorLog "%(error_log)s"
+  LogLevel warn
+  LogFormat "%%h %%l %%{REMOTE_USER}i %%t \"%%r\" %%>s %%b \"%%{Referer}i\" \"%%{User-Agent}i\" %%D" combined
+  CustomLog "%(access_log)s" combined
+
+  # Remove "Secure" from cookies, as backend may be https
+  Header edit Set-Cookie "(?i)^(.+);secure$" "$1"
+
+  # Not using HTTPS? Ask that guy over there.
+  # Dummy redirection to https. Note: will work only if https listens
+  # on standard port (443).
+  RewriteRule ^/(.*)$ https://%%{SERVER_NAME}%%{REQUEST_URI}',
+    "ssl_key":"-----BEGIN RSA PRIVATE KEY-----
+XXXXXXX..........XXXXXXXXXXXXXXX
+-----END RSA PRIVATE KEY-----",
+    "ssl_crt":'-----BEGIN CERTIFICATE-----
+XXXXXXXXXXX.............XXXXXXXXXXXXXXXXXXX
+-----END CERTIFICATE-----',
+    "ssl_ca_crt":'-----BEGIN CERTIFICATE-----
+XXXXXXXXX...........XXXXXXXXXXXXXXXXX
+-----END CERTIFICATE-----',
+    "ssl_csr":'-----BEGIN CERTIFICATE REQUEST-----
+XXXXXXXXXXXXXXX.............XXXXXXXXXXXXXXXXXX
+-----END CERTIFICATE REQUEST-----',
     }
   )