From 0f066115350ea9d1c4bd35e2687aff99c3af53f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Le=20Ninivin?= <cedric.leninivin@tiolive.com> Date: Fri, 24 May 2013 09:09:26 +0200 Subject: [PATCH] apache-frontend: Update documentation to match reality --- .../README.apache_frontend.txt | 338 ++++++++++++++++-- 1 file changed, 303 insertions(+), 35 deletions(-) diff --git a/software/apache-frontend/README.apache_frontend.txt b/software/apache-frontend/README.apache_frontend.txt index d4126b61d..05e12053c 100644 --- a/software/apache-frontend/README.apache_frontend.txt +++ b/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-----', } ) -- 2.30.9