software/apache-frontend/README.apache_frontend.txt

   1 apache_frontend
   2 ===============
   3
   4 Frontend system using Apache, allowing to rewrite and proxy URLs like
   5 myinstance.myfrontenddomainname.com to real IP/URL of myinstance.
   6
   7 apache_frontend works using the master instance / slave instance design.
   8 It means that a single main instance of Apache will be used to act as frontend
   9 for many slaves.
  10
  11 Software type
  12 =============
  13
  14 Apache frontend is available in 3 software types:
  15   * default : The standard way to use the apache frontend configuring everything with a few given parameters
  16   * custom-personal : This software type allow each slave to edit its apache configuration file
  17   * custom-group : This software type use a template given as a parameter on master instance to generate apache configuration for all slaves
  18   * replicate : This software type is set to replicate any kind of apache
  19
  20 About replicate frontend
  21 ========================
  22
  23 Slaves of the root instance (type "replicate") are sent as a parameter to requested frontends which will process them. The only difference is that they will then return the « would-be published information » to the root instance instead of publishing it. The root instance will then do a synthesis and publish the information to its slaves. The replicate instance only use 3 type of parameters for itself and will transmit the rest to requested frontends.
  24 These parameters are :
  25   * "-frontend-type" : the type to deploy frontends with. (default to 2)
  26   * "-frontend-quantity" : The quantity of frontends to request (default to "default")
  27   * "-sla-i-foo" : where "i" is the number of the concerned frontend (between 1 and "-frontend-quantity") and "foo" a sla parameter.
  28 ex:
  29 <parameter id="-frontend-quantity">3</parameter>
  30 <parameter id="-frontend-type">custom-personal</parameter>
  31 <parameter id="-sla-3-computer_guid">COMP-1234</parameter>
  32 will request the third frontend on COMP-1234. All frontends will be of software type "custom-personal".
  33
  34 Note: the way slaves are transformed to a parameter avoid modifying more than 3 lines in the frontend logic.
  35 Important NOTE: The way you ask for slave to a replicate frontend is the same as the one you would use for the software given in "-frontend-quantity". Do not forget to use "replicate" for software type. XXXXX So far it is not possible to do a simple request on a replicate frontend if you do not know the software_guid or other sla-parameter of the master instance. In fact we do not know yet the software type of the "requested" frontends. TO BE IMPLEMENTED
  36
  37 How to deploy a frontend server
  38 ===============================
  39
  40 This is to deploy an entire frontend server with a public IPv4.
  41 If you want to use an already deployed frontend to make your service available
  42 via ipv4, switch to the "Example" parts.
  43
  44 First, you will need to request a "master" instance of Apache Frontend with:
  45   * A "domain" parameter where the frontend will be available
  46   * A "public-ipv4" parameter to state which public IPv4 will be used
  47
  48 like::
  49   <?xml version='1.0' encoding='utf-8'?>
  50   <instance>
  51    <parameter id="domain">moulefrite.org</parameter>
  52    <parameter id="public-ipv4">xxx.xxx.xxx.xxx</parameter>
  53   </instance>
  54
  55 Then, it is possible to request many slave instances
  56 (currently only from slapconsole, UI doesn't work yet)
  57 of Apache Frontend, like::
  58   instance = request(
  59     software_release=apache_frontend,
  60     partition_reference='frontend2',
  61     shared=True,
  62     partition_parameter_kw={"url":"https://[1:2:3:4]:1234/someresource"}
  63   )
  64 Those slave instances will be redirected to the "master" instance,
  65 and you will see on the "master" instance the associated RewriteRules of
  66 all slave instances.
  67
  68 Finally, the slave instance will be accessible from:
  69 https://someidentifier.moulefrite.org.
  70
  71 About SSL
  72 =========
  73 Default and custom-personal software type can handle specific ssl for one slave instance.
  74 IMPORTANT: One apache can not serve more than One specific SSL VirtualHost and be compatible with obsolete browser (i.e.: IE8). See http://wiki.apache.org/httpd/NameBasedSSLVHostsWithSNI
  75
  76 #How to have custom configuration in frontend server
  77 #===================================================
  78 #
  79 #In your instance directory, you, as sysadmin, can directly edit two
  80 #configuration files that won't be overwritten by SlapOS to customize your
  81 #instance:
  82 #
  83 # * $PARTITION_PATH/srv/srv/apache-conf.d/apache_frontend.custom.conf
  84 # * $PARTITION_PATH/srv/srv/apache-conf.d/apache_frontend.virtualhost.custom.conf
  85 #
  86 #The first one is included in the end of the main apache configuration file.
  87 #The second one is included in the virtualhost of the main apache configuration file.
  88 #
  89 #SlapOS will jsut create those two files for you, then completely forget them.
  90 #
  91 #Note: make sure that the UNIX user of the instance has read access to those
  92 #files if you edit them.
  93
  94 Instance Parameters
  95 ===================
  96
  97 Master Instance Parameters
  98 --------------------------
  99
 100 domain
 101 ~~~~~~
 102 name of the domain to be used (example: mydomain.com). Subdomains of this
 103 domain will be used for the slave instances (example:
 104 instance12345.mydomain.com). It is then recommended to add a wildcard in DNS
 105 for the subdomains of the chosen domain like::
 106   *.mydomain.com. IN A 123.123.123.123
 107 Using the IP given by the Master Instance.
 108 "domain" is a mandatory Parameter.
 109
 110 public-ipv4
 111 ~~~~~~~~~~~
 112 Public ipv4 of the frontend (the one Apache will be indirectly listening to)
 113
 114 port
 115 ~~~~
 116 Port used by Apache. Optional parameter, defaults to 4443.
 117
 118 plain_http_port
 119 ~~~~~~~~~~~~~~~
 120 Port used by apache to serve plain http (only used to redirect to https).
 121 Optional parameter, defaults to 8080.
 122
 123 ip-read-limit
 124 ~~~~~~~~~~~~~
 125 Use to set IPReadLimit Parameter for antiloris.
 126 Optional parameter, defaults to 10.
 127
 128 apache_custom_http (custom-group)
 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130 Jinja template for apache virtualhost http configuration. It will be used by all slaves
 131
 132 apache_custom_https (custom-group)
 133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 134 Jinja template for apache virtualhost https configuration. It will be used by all slaves
 135
 136
 137 Slave Instance Parameters (default)
 138 -----------------------------------
 139
 140 url
 141 ~~~
 142 url of backend to use.
 143 "url" is a mandatory parameter.
 144 Example: http://mybackend.com/myresource
 145
 146 enable_cache
 147 ~~~~~
 148 Specify if slave instance should use a squid to connect to backend.
 149 Possible values: "true", "false".
 150 "enable_cache" is an optional parameter. Defaults to "false".
 151 Example: true
 152
 153 type
 154 ~~~~
 155 Specify if slave instance will redirect to a zope backend. If specified, Apache
 156 RewriteRule will use Zope's Virtual Host Daemon.
 157 Possible values: "zope", "default".
 158 "type" is an optional parameter. Defaults to "default".
 159 Example: zope
 160
 161 domain (former custom_domain)
 162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 163 Domain name to use as frontend. The frontend will be accessible from this domain.
 164 "domain" is an optional parameter. Defaults to
 165 [instancereference].[masterdomain].
 166 Example: www.mycustomdomain.com
 167
 168 https-only
 169 ~~~~~~~~~~
 170 Specify if website should be accessed using https only. If so, the frontend
 171 will redirect the user to https if accessed from http.
 172 Possible values: "true", "false".
 173 "https-only" is an optional parameter. Defaults to "false".
 174 Example: true
 175
 176 path
 177 ~~~~
 178 Only used if type is "zope".
 179
 180 Will append the specified path to the "VirtualHostRoot" of the zope's
 181 VirtualHostMonster.
 182
 183 "path" is an optional parameter, ignored if not specified.
 184 Example of value: "/erp5/web_site_module/hosting/"
 185
 186 Slave Instance Parameters (custom-personal)
 187 -------------------------------------------
 188
 189 apache_custom_https
 190 ~~~~~~~~~~~~~~~~~~~
 191 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.
 192 NOTE: If you want to use the cache, use the apache option "ProxyPreserveHost On"
 193
 194 apache_custom_http
 195 ~~~~~~~~~~~~~~~~~~
 196 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
 197 NOTE: If you want to use the cache, use the apache option "ProxyPreserveHost On"
 198
 199 url
 200 ~~~
 201 Necesarry to activate cache. url of backend to use.
 202 "url" is an optional parameter.
 203 Example: http://mybackend.com/myresource
 204
 205 domain
 206 ~~~~~~
 207 Necesarry to activate cache. The frontend will be accessible from this domain.
 208 "domain" is an optional parameter.
 209 Example: www.mycustomdomain.com
 210
 211 enable_cache
 212 ~~~~~~~~~~~~
 213 Necesarry to activate cache.
 214 "enable_cache" is an optional parameter.
 215
 216 ssl_key, ssl_crt, ssl_ca_crt, ssl_crs
 217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 218 SSL certificates of the slave.
 219 They are optional.
 220
 221 Functionalities for apache configuration:
 222 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"
 223   * cache_access : url of the cache. Should replace backend url in configuration to use the cache
 224   * error_log : path of the slave error log in order to log in a deferenciated file.
 225   * error_log : path of the slave access log in order to log in a deferenciated file.
 226   * ssl_key, ssl_crt, ssl_ca_crt, ssl_crs : path of the certificates given in slave instance parameters
 227
 228 Slave Instance Parameters (custom-group)
 229 ----------------------------------------
 230
 231 url
 232 ~~~
 233 Necesarry to activate cache. url of backend to use.
 234 "url" is an optional parameter.
 235 Example: http://mybackend.com/myresource
 236
 237 domain
 238 ~~~~~~
 239 Domain name to use as frontend. The frontend will be accessible from this domain.
 240 "domain" is an optional parameter necessary to activate cache. Defaults to
 241 [instancereference].[masterdomain].
 242 Example: www.mycustomdomain.com
 243
 244 The rest of the parameters are defined by templates given to the master and accessible by the slave_parameter dict in it.
 245
 246
 247 Examples
 248 ========
 249
 250 Here are some example of how to make your SlapOS service available through
 251 an already deployed frontend.
 252
 253 Simple Example (default)
 254 ------------------------
 255
 256 Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
 257 redirected and accessible from the proxy::
 258   instance = request(
 259     software_release=apache_frontend,
 260     software_type="RootSoftwareInstance",
 261     partition_reference='my frontend',
 262     shared=True,
 263     partition_parameter_kw={
 264         "url":"https://[1:2:3:4:5:6:7:8]:1234",
 265     }
 266   )
 267
 268
 269 Zope Example (default)
 270 ----------------------
 271
 272 Request slave frontend instance using a Zope backend so that
 273 https://[1:2:3:4:5:6:7:8]:1234 will be redirected and accessible from the
 274 proxy::
 275   instance = request(
 276     software_release=apache_frontend,
 277     software_type="RootSoftwareInstance",
 278     partition_reference='my frontend',
 279     shared=True,
 280     partition_parameter_kw={
 281         "url":"https://[1:2:3:4:5:6:7:8]:1234",
 282         "type":"zope",
 283     }
 284   )
 285
 286
 287 Advanced example (default)
 288 --------------------------
 289
 290 Request slave frontend instance using a Zope backend, with Varnish activated,
 291 listening to a custom domain and redirecting to /erp5/ so that
 292 https://[1:2:3:4:5:6:7:8]:1234/erp5/ will be redirected and accessible from
 293 the proxy::
 294   instance = request(
 295     software_release=apache_frontend,
 296     software_type="RootSoftwareInstance",
 297     partition_reference='my frontend',
 298     shared=True,
 299     partition_parameter_kw={
 300         "url":"https://[1:2:3:4:5:6:7:8]:1234",
 301         "enable_cache":"true",
 302         "type":"zope",
 303         "path":"/erp5",
 304         "domain":"mycustomdomain.com",
 305     }
 306   )
 307
 308 Simple Example (custom-personal)
 309 --------------------------------
 310
 311 Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
 312   instance = request(
 313     software_release=apache_frontend,
 314     software_type="RootSoftwareInstance",
 315     partition_reference='my frontend',
 316     shared=True,
 317     software_type="custom-personal",
 318     partition_parameter_kw={
 319         "url":"https://[1:2:3:4:5:6:7:8]:1234",
 320
 321         "apache_custom_https":'
 322   ServerName www.example.org
 323   ServerAlias example.org
 324   ServerAdmin geronimo@example.org
 325   SSLEngine on
 326   SSLProxyEngine on
 327   # Rewrite part
 328   ProxyVia On
 329   ProxyPreserveHost On
 330   ProxyTimeout 600
 331   RewriteEngine On
 332   RewriteRule ^/(.*) https://[1:2:3:4:5:6:7:8]:1234/$1 [L,P]',
 333
 334         "apache_custom_http":'
 335   ServerName www.example.org
 336   ServerAlias www.example.org
 337   ServerAlias example.org
 338   ServerAdmin geronimo@example.org
 339   SSLProxyEngine on
 340   # Rewrite part
 341   ProxyVia On
 342   ProxyPreserveHost On
 343   ProxyTimeout 600
 344   RewriteEngine On
 345   # Remove "Secure" from cookies, as backend may be https
 346   Header edit Set-Cookie "(?i)^(.+);secure$" "$1"
 347   # Not using HTTPS? Ask that guy over there.
 348   # Dummy redirection to https. Note: will work only if https listens
 349   # on standard port (443).
 350   RewriteRule ^/(.*) https://[1:2:3:4:5:6:7:8]:1234/$1 [L,P],
 351     }
 352   )
 353
 354 Simple Cache Example (custom-personal)
 355 --------------------------------
 356
 357 Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
 358   instance = request(
 359     software_release=apache_frontend,
 360     software_type="RootSoftwareInstance",
 361     partition_reference='my frontend',
 362     shared=True,
 363     software_type="custom-personal",
 364     partition_parameter_kw={
 365         "url":"https://[1:2:3:4:5:6:7:8]:1234",
 366         "domain": "www.example.org",
 367         "enable_cache": "True",
 368
 369         "apache_custom_https":'
 370   ServerName www.example.org
 371   ServerAlias www.example.org
 372   ServerAlias example.org
 373   ServerAdmin geronimo@example.org
 374   SSLEngine on
 375   SSLProxyEngine on
 376   # Rewrite part
 377   ProxyVia On
 378   ProxyPreserveHost On
 379   ProxyTimeout 600
 380   RewriteEngine On
 381   RewriteRule ^/(.*) %(cache_access)s/$1 [L,P]',
 382
 383         "apache_custom_http":'
 384   ServerName www.example.org
 385   ServerAlias www.example.org
 386   ServerAlias example.org
 387   ServerAdmin geronimo@example.org
 388   SSLProxyEngine on
 389   # Rewrite part
 390   ProxyVia On
 391   ProxyPreserveHost On
 392   ProxyTimeout 600
 393   RewriteEngine On
 394
 395   # Remove "Secure" from cookies, as backend may be https
 396   Header edit Set-Cookie "(?i)^(.+);secure$" "$1"
 397
 398   # Not using HTTPS? Ask that guy over there.
 399   # Dummy redirection to https. Note: will work only if https listens
 400   # on standard port (443).
 401   RewriteRule ^/(.*) %(cache_access)s/$1 [L,P],
 402     }
 403   )
 404
 405
 406 Advanced example (custom-personal)
 407 ----------------------------------
 408
 409 Request slave frontend instance using custom apache configuration, willing to use cache and ssl certificates.
 410 listening to a custom domain and redirecting to /erp5/ so that
 411 https://[1:2:3:4:5:6:7:8]:1234/erp5/ will be redirected and accessible from
 412 the proxy::
 413   instance = request(
 414     software_release=apache_frontend,
 415     software_type="RootSoftwareInstance",
 416     partition_reference='my frontend',
 417     shared=True,
 418     software_type="custom-personal",
 419     partition_parameter_kw={
 420         "url":"https://[1:2:3:4:5:6:7:8]:1234",
 421         "enable_cache":"true",
 422         "type":"zope",
 423         "path":"/erp5",
 424         "domain":"example.org",
 425
 426         "apache_custom_https":'
 427   ServerName www.example.org
 428   ServerAlias www.example.org
 429   ServerAdmin example.org
 430   SSLEngine on
 431   SSLProxyEngine on
 432   SSLProtocol -ALL +SSLv3 +TLSv1
 433   SSLHonorCipherOrder On
 434   SSLCipherSuite RC4-SHA:HIGH:!ADH
 435   # Use personal ssl certificates
 436   SSLCertificateFile %(ssl_crt)s
 437   SSLCertificateKeyFile %(ssl_key)s
 438   SSLCACertificateFile %(ssl_ca_crt)s
 439   SSLCertificateChainFile %(ssl_ca_crt)s
 440   # Configure personal logs
 441   ErrorLog "%(error_log)s"
 442   LogLevel info
 443   LogFormat "%%h %%l %%{REMOTE_USER}i %%t \"%%r\" %%>s %%b \"%%{Referer}i\" \"%%{User-Agent}i\" %%D" combined
 444   CustomLog "%(access_log)s" combined
 445   # Rewrite part
 446   ProxyVia On
 447   ProxyPreserveHost On
 448   ProxyTimeout 600
 449   RewriteEngine On
 450   # Redirect / to /index.html
 451   RewriteRule ^/$ /index.html [R=302,L]
 452   # Use cache
 453   RewriteRule ^/(.*) %(cache_access)s/VirtualHostBase/https/www.example.org:443/erp5/VirtualHostRoot/$1 [L,P]',
 454
 455     "apache_custom_http":'
 456   ServerName www.example.org
 457   ServerAlias www.example.org
 458   ServerAlias example.org
 459   ServerAdmin geronimo@example.org
 460   SSLProxyEngine on
 461   # Rewrite part
 462   ProxyVia On
 463   ProxyPreserveHost On
 464   ProxyTimeout 600
 465   RewriteEngine On
 466   # Configure personal logs
 467   ErrorLog "%(error_log)s"
 468   LogLevel info
 469   LogFormat "%%h %%l %%{REMOTE_USER}i %%t \"%%r\" %%>s %%b \"%%{Referer}i\" \"%%{User-Agent}i\" %%D" combined
 470   CustomLog "%(access_log)s" combined
 471   # Remove "Secure" from cookies, as backend may be https
 472   Header edit Set-Cookie "(?i)^(.+);secure$" "$1"
 473   # Not using HTTPS? Ask that guy over there.
 474   # Dummy redirection to https. Note: will work only if https listens
 475   # on standard port (443).
 476   RewriteRule ^/(.*)$ https://%%{SERVER_NAME}%%{REQUEST_URI}',
 477
 478     "ssl_key":"-----BEGIN RSA PRIVATE KEY-----
 479 XXXXXXX..........XXXXXXXXXXXXXXX
 480 -----END RSA PRIVATE KEY-----",
 481     "ssl_crt":'-----BEGIN CERTIFICATE-----
 482 XXXXXXXXXXX.............XXXXXXXXXXXXXXXXXXX
 483 -----END CERTIFICATE-----',
 484     "ssl_ca_crt":'-----BEGIN CERTIFICATE-----
 485 XXXXXXXXX...........XXXXXXXXXXXXXXXXX
 486 -----END CERTIFICATE-----',
 487     "ssl_csr":'-----BEGIN CERTIFICATE REQUEST-----
 488 XXXXXXXXXXXXXXX.............XXXXXXXXXXXXXXXXXX
 489 -----END CERTIFICATE REQUEST-----',
 490     }
 491   )
 492
 493 Notes
 494 =====
 495
 496 It is not possible with slapos to listen to port <= 1024, because process are
 497 not run as root.
 498
 499 Solution 1 (IPv4 only)
 500 ----------------------
 501
 502 It is a good idea then to go on the node where the instance is
 503 and set some iptables rules like (if using default ports)::
 504
 505   iptables -t nat -A PREROUTING -p tcp -d {public_ipv4} --dport 443 -j DNAT --to-destination {listening_ipv4}:4443
 506   iptables -t nat -A PREROUTING -p tcp -d {public_ipv4} --dport 80 -j DNAT --to-destination {listening_ipv4}:8080
 507
 508 Where {public ip} is the public IP of your server, or at least the LAN IP to where your NAT will forward to.
 509 {listening ip} is the private ipv4 (like 10.0.34.123) that the instance is using and sending as connection parameter.
 510
 511 Solution 2 (IPv6 only)
 512 ----------------------
 513
 514 It is also possible to directly allow the service to listen on 80 and 443 ports using the following command:
 515
 516   setcap 'cap_net_bind_service=+ep' /opt/slapgrid/$APACHE_FRONTEND_SOFTWARE_RELEASE_MD5/parts/apache-2.2/bin/httpd
 517
 518 Then specify in the instance parameters "port" and "plain_http_port" to be 443 and 80, respectively.