5 1. [Overview - What is the apache module?](#overview)
6 2. [Module Description - What does the module do?](#module-description)
7 3. [Setup - The basics of getting started with apache](#setup)
8 * [Beginning with apache - Installation](#beginning-with-apache)
9 * [Configure a virtual host - Basic options for getting started](#configure-a-virtual-host)
10 4. [Usage - The classes and defined types available for configuration](#usage)
11 * [Classes and Defined Types](#classes-and-defined-types)
12 * [Class: apache](#class-apache)
13 * [Defined Type: apache::custom_config](#defined-type-apachecustom_config)
14 * [Class: apache::default_mods](#class-apachedefault_mods)
15 * [Defined Type: apache::mod](#defined-type-apachemod)
16 * [Classes: apache::mod::*](#classes-apachemodname)
17 * [Class: apache::mod::alias](#class-apachemodalias)
18 * [Class: apache::mod::event](#class-apachemodevent)
19 * [Class: apache::mod::geoip](#class-apachemodgeoip)
20 * [Class: apache::mod::info](#class-apachemodinfo)
21 * [Class: apache::mod::pagespeed](#class-apachemodpagespeed)
22 * [Class: apache::mod::php](#class-apachemodphp)
23 * [Class: apache::mod::ssl](#class-apachemodssl)
24 * [Class: apache::mod::status](#class-apachemodstatus)
25 * [Class: apache::mod::expires](#class-apachemodexpires)
26 * [Class: apache::mod::wsgi](#class-apachemodwsgi)
27 * [Class: apache::mod::fcgid](#class-apachemodfcgid)
28 * [Class: apache::mod::negotiation](#class-apachemodnegotiation)
29 * [Class: apache::mod::deflate](#class-apachemoddeflate)
30 * [Class: apache::mod::reqtimeout](#class-apachemodreqtimeout)
31 * [Class: apache::mod::security](#class-modsecurity)
32 * [Class: apache::mod::version](#class-apachemodversion)
33 * [Defined Type: apache::vhost](#defined-type-apachevhost)
34 * [Parameter: `directories` for apache::vhost](#parameter-directories-for-apachevhost)
35 * [SSL parameters for apache::vhost](#ssl-parameters-for-apachevhost)
36 * [Defined Type: apache::fastcgi::server](#defined-type-fastcgi-server)
37 * [Virtual Host Examples - Demonstrations of some configuration options](#virtual-host-examples)
38 * [Load Balancing](#load-balancing)
39 * [Defined Type: apache::balancer](#defined-type-apachebalancer)
40 * [Defined Type: apache::balancermember](#defined-type-apachebalancermember)
41 * [Examples - Load balancing with exported and non-exported resources](#examples)
42 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
44 * [Public Classes](#public-classes)
45 * [Private Classes](#private-classes)
46 * [Defined Types](#defined-types)
47 * [Public Defined Types](#public-defined-types)
48 * [Private Defined Types](#private-defined-types)
49 * [Templates](#templates)
50 6. [Limitations - OS compatibility, etc.](#limitations)
51 7. [Development - Guide for contributing to the module](#development)
52 * [Contributing to the apache module](#contributing)
53 * [Running tests - A quick guide](#running-tests)
57 The apache module allows you to set up virtual hosts and manage web services with minimal effort.
61 Apache is a widely-used web server, and this module provides a simplified way of creating configurations to manage your infrastructure. This includes the ability to configure and manage a range of different virtual host setups, as well as a streamlined way to install and configure Apache modules.
65 **What apache affects:**
67 * configuration files and directories (created and written to)
68 * **WARNING**: Configurations that are *not* managed by Puppet will be purged.
69 * package/service/configuration files for Apache
73 * `/etc/make.conf` on FreeBSD and Gentoo
74 * depends on module 'gentoo/puppet-portage' for Gentoo
76 ###Beginning with Apache
78 To install Apache with the default parameters
84 The defaults are determined by your operating system (e.g. Debian systems have one set of defaults, and RedHat systems have another, as do FreeBSD and Gentoo systems). These defaults work well in a testing environment, but are not suggested for production. To establish customized parameters
88 default_mods => false,
89 default_confd_files => false,
93 ###Configure a virtual host
95 Declaring the `apache` class creates a default virtual host by setting up a vhost on port 80, listening on all interfaces and serving `$apache::docroot`.
101 To configure a very basic, name-based virtual host
104 apache::vhost { 'first.example.com':
106 docroot => '/var/www/first',
110 *Note:* The default priority is 15. If nothing matches this priority, the alphabetically first name-based vhost is used. This is also true if you pass a higher priority and no names match anything else.
112 A slightly more complicated example, changes the docroot owner/group from the default 'root'
115 apache::vhost { 'second.example.com':
117 docroot => '/var/www/second',
118 docroot_owner => 'third',
119 docroot_group => 'third',
123 To set up a virtual host with SSL and default SSL certificates
126 apache::vhost { 'ssl.example.com':
128 docroot => '/var/www/ssl',
133 To set up a virtual host with SSL and specific SSL certificates
136 apache::vhost { 'fourth.example.com':
138 docroot => '/var/www/fourth',
140 ssl_cert => '/etc/ssl/fourth.example.com.cert',
141 ssl_key => '/etc/ssl/fourth.example.com.key',
145 Virtual hosts listen on '*' by default. To listen on a specific IP address
148 apache::vhost { 'subdomain.example.com':
151 docroot => '/var/www/subdomain',
155 To set up a virtual host with a wildcard alias for the subdomain mapped to a same-named directory, for example: `http://example.com.loc` to `/var/www/example.com`
158 apache::vhost { 'subdomain.loc':
161 virtual_docroot => '/var/www/%-2+',
162 docroot => '/var/www',
163 serveraliases => ['*.loc',],
167 To set up a virtual host with suPHP
170 apache::vhost { 'suphp.example.com':
172 docroot => '/home/appuser/myphpapp',
173 suphp_addhandler => 'x-httpd-php',
174 suphp_engine => 'on',
175 suphp_configpath => '/etc/php5/apache2',
176 directories => { path => '/home/appuser/myphpapp',
177 'suphp' => { user => 'myappuser', group => 'myappgroup' },
182 To set up a virtual host with WSGI
185 apache::vhost { 'wsgi.example.com':
187 docroot => '/var/www/pythonapp',
188 wsgi_application_group => '%{GLOBAL}',
189 wsgi_daemon_process => 'wsgi',
190 wsgi_daemon_process_options => {
193 display-name => '%{GROUP}',
195 wsgi_import_script => '/var/www/demo.wsgi',
196 wsgi_import_script_options =>
197 { process-group => 'wsgi', application-group => '%{GLOBAL}' },
198 wsgi_process_group => 'wsgi',
199 wsgi_script_aliases => { '/' => '/var/www/demo.wsgi' },
203 Starting in Apache 2.2.16, HTTPD supports [FallbackResource](https://httpd.apache.org/docs/current/mod/mod_dir.html#fallbackresource), a simple replacement for common RewriteRules.
206 apache::vhost { 'wordpress.example.com':
208 docroot => '/var/www/wordpress',
209 fallbackresource => '/index.php',
213 Please note that the 'disabled' argument to FallbackResource is only supported since Apache 2.2.24.
215 See a list of all [virtual host parameters](#defined-type-apachevhost). See an extensive list of [virtual host examples](#virtual-host-examples).
219 ###Classes and Defined Types
221 This module modifies Apache configuration files and directories and purges any configuration not managed by Puppet. Configuration of Apache should be managed by Puppet, as non-Puppet configuration files can cause unexpected failures.
223 It is possible to temporarily disable full Puppet management by setting the [`purge_configs`](#purge_configs) parameter within the base `apache` class to 'false'. This option should only be used as a temporary means of saving and relocating customized configurations. See the [`purge_configs` parameter](#purge_configs) for more information.
227 The apache module's primary class, `apache`, guides the basic setup of Apache on your system.
229 You can establish a default vhost in this class, the `vhost` class, or both. You can add additional vhost configurations for specific virtual hosts using a declaration of the `vhost` type.
231 **Parameters within `apache`:**
233 #####`allow_encoded_slashes`
235 This sets the server default for the [`AllowEncodedSlashes` declaration](http://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes) which modifies the responses to URLs with `\` and `/` characters. The default is undefined, which omits the declaration from the server configuration and select the Apache default setting of `Off`. Allowed values are: `on`, `off` or `nodecode`.
237 #####`apache_version`
239 Configures the behavior of the module templates, package names, and default mods by setting the Apache version. Default is determined by the class `apache::version` using the OS family and release. It should not be configured manually without special reason.
243 Changes the location of the configuration directory the main configuration file is placed in. Defaults to '/etc/httpd/conf' on RedHat, '/etc/apache2' on Debian, '/usr/local/etc/apache22' on FreeBSD, and '/etc/apache2' on Gentoo.
247 Changes the location of the configuration directory your custom configuration files are placed in. Defaults to '/etc/httpd/conf' on RedHat, '/etc/apache2/conf.d' on Debian, '/usr/local/etc/apache22' on FreeBSD, and '/etc/apache2/conf.d' on Gentoo.
251 Overrides the template used for the main apache configuration file. Defaults to 'apache/httpd.conf.erb'.
253 *Note:* Using this parameter is potentially risky, as the module has been built for a minimal configuration file with the configuration primarily coming from conf.d/ entries.
255 #####`default_charset`
257 If defined, the value will be set as `AddDefaultCharset` in the main configuration file. It is undefined by default.
259 #####`default_confd_files`
261 Generates default set of include-able Apache configuration files under `${apache::confd_dir}` directory. These configuration files correspond to what is usually installed with the Apache package on a given platform.
265 Sets up Apache with default settings based on your OS. Valid values are 'true', 'false', or an array of mod names.
267 Defaults to 'true', which includes the default [HTTPD mods](https://github.com/puppetlabs/puppetlabs-apache/blob/master/manifests/default_mods.pp).
269 If false, it only includes the mods required to make HTTPD work, and any other mods can be declared on their own.
271 If an array, the apache module includes the array of mods listed.
273 #####`default_ssl_ca`
275 The default certificate authority, which is automatically set to 'undef'. This default works out of the box but must be updated with your specific certificate information before being used in production.
277 #####`default_ssl_cert`
279 The default SSL certification, which is automatically set based on your operating system ('/etc/pki/tls/certs/localhost.crt' for RedHat, '/etc/ssl/certs/ssl-cert-snakeoil.pem' for Debian, '/usr/local/etc/apache22/server.crt' for FreeBSD, and '/etc/ssl/apache2/server.crt' for Gentoo). This default works out of the box but must be updated with your specific certificate information before being used in production.
281 #####`default_ssl_chain`
283 The default SSL chain, which is automatically set to 'undef'. This default works out of the box but must be updated with your specific certificate information before being used in production.
285 #####`default_ssl_crl`
287 The default certificate revocation list to use, which is automatically set to 'undef'. This default works out of the box but must be updated with your specific certificate information before being used in production.
289 #####`default_ssl_crl_path`
291 The default certificate revocation list path, which is automatically set to 'undef'. This default works out of the box but must be updated with your specific certificate information before being used in production.
293 #####`default_ssl_crl_check`
295 Sets the default certificate revocation check level via the [SSLCARevocationCheck directive](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcarevocationcheck), which is automatically set to 'undef'. This default works out of the box but must be specified when using CRLs in production. Only applicable to Apache 2.4 or higher, the value is ignored on older versions.
297 #####`default_ssl_key`
299 The default SSL key, which is automatically set based on your operating system ('/etc/pki/tls/private/localhost.key' for RedHat, '/etc/ssl/private/ssl-cert-snakeoil.key' for Debian, '/usr/local/etc/apache22/server.key' for FreeBSD, and '/etc/ssl/apache2/server.key' for Gentoo). This default works out of the box but must be updated with your specific certificate information before being used in production.
301 #####`default_ssl_vhost`
303 Sets up a default SSL virtual host. Defaults to 'false'. If set to 'true', sets up the following vhost:
306 apache::vhost { 'default-ssl':
310 scriptalias => $scriptalias,
311 serveradmin => $serveradmin,
312 access_log_file => "ssl_${access_log_file}",
316 SSL vhosts only respond to HTTPS queries.
320 (Apache httpd 2.2 only) MIME content-type that will be sent if the server cannot determine a type in any other way. This directive has been deprecated in Apache httpd 2.4, and only exists there for backwards compatibility of configuration files.
324 Sets up a default virtual host. Defaults to 'true', set to 'false' to set up [customized virtual hosts](#configure-a-virtual-host).
328 Changes the location of the default [Documentroot](https://httpd.apache.org/docs/current/mod/core.html#documentroot). Defaults to '/var/www/html' on RedHat, '/var/www' on Debian, '/usr/local/www/apache22/data' on FreeBSD, and '/var/www/localhost/htdocs' on Gentoo.
330 #####`error_documents`
332 Enables custom error documents. Defaults to 'false'.
336 Changes the group that Apache will answer requests as. The parent process will continue to be run as root, but resource accesses by child processes will be done under this group. By default, puppet will attempt to manage this group as a resource under `::apache`. If this is not what you want, set [`manage_group`](#manage_group) to 'false'. Defaults to the OS-specific default user for apache, as detected in `::apache::params`.
340 Changes the base location of the configuration directories used for the apache service. This is useful for specially repackaged HTTPD builds, but might have unintended consequences when used in combination with the default distribution packages. Defaults to '/etc/httpd' on RedHat, '/etc/apache2' on Debian, '/usr/local/etc/apache22' on FreeBSD, and '/etc/apache2' on Gentoo.
344 Enables persistent connections.
346 #####`keepalive_timeout`
348 Sets the amount of time the server waits for subsequent requests on a persistent connection. Defaults to '15'.
350 #####`max_keepalive_requests`
352 Sets the limit of the number of requests allowed per connection when KeepAlive is on. Defaults to '100'.
356 Specifies the location where apache module files are stored. It should not be configured manually without special reason.
360 Sets the file name for the module loadfile. Should be in the format \*.load. This can be used to set the module load order.
364 Changes the verbosity level of the error log. Defaults to 'warn'. Valid values are 'emerg', 'alert', 'crit', 'error', 'warn', 'notice', 'info', or 'debug'.
368 Define additional [LogFormats](https://httpd.apache.org/docs/current/mod/mod_log_config.html#logformat). This is done in a Hash:
371 $log_formats = { vhost_common => '%v %h %l %u %t \"%r\" %>s %b' }
374 There are a number of predefined LogFormats in the httpd.conf that Puppet writes out:
377 LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
378 LogFormat "%h %l %u %t \"%r\" %>s %b" common
379 LogFormat "%{Referer}i -> %U" referer
380 LogFormat "%{User-agent}i" agent
383 If your `$log_formats` contains one of those, they will be overwritten with **your** definition.
387 Changes the directory where Apache log files for the virtual host are placed. Defaults to '/var/log/httpd' on RedHat, '/var/log/apache2' on Debian, '/var/log/apache22' on FreeBSD, and '/var/log/apache2' on Gentoo.
391 Overrides the mode the default logroot directory is set to ($::apache::logroot). Defaults to undef. Do NOT give people write access to the directory the logs are stored
392 in without being aware of the consequences; see http://httpd.apache.org/docs/2.4/logs.html#security for details.
396 Setting this to 'false' stops the group resource from being created. This is for when you have a group, created from another Puppet module, you want to use to run Apache. Without this parameter, attempting to use a previously established group would result in a duplicate resource error.
400 Setting this to 'false' stops the user resource from being created. This is for instances when you have a user, created from another Puppet module, you want to use to run Apache. Without this parameter, attempting to use a previously established user would result in a duplicate resource error.
404 Changes the location of the configuration directory your Apache modules configuration files are placed in. Defaults to '/etc/httpd/conf.d' for RedHat, '/etc/apache2/mods-available' for Debian, '/usr/local/etc/apache22/Modules' for FreeBSD, and '/etc/apache2/modules.d' on Gentoo.
408 Determines which MPM is loaded and configured for the HTTPD process. Valid values are 'event', 'itk', 'peruser', 'prefork', 'worker', or 'false'. Defaults to 'prefork' on RedHat, FreeBSD and Gentoo, and 'worker' on Debian. Must be set to 'false' to explicitly declare the following classes with custom parameters:
410 * `apache::mod::event`
412 * `apache::mod::peruser`
413 * `apache::mod::prefork`
414 * `apache::mod::worker`
416 *Note:* Switching between different MPMs on FreeBSD is possible but quite difficult. Before changing `$mpm_module` you must uninstall all packages that depend on your currently-installed Apache.
418 #####`package_ensure`
420 Allows control over the package ensure attribute. Can be 'present','absent', or a version string.
424 Changes the name of the file containing Apache ports configuration. Default is `${conf_dir}/ports.conf`.
428 Removes all other Apache configs and vhosts, defaults to 'true'. Setting this to 'false' is a stopgap measure to allow the apache module to coexist with existing or otherwise-managed configuration. It is recommended that you move your configuration entirely to resources within this module.
430 #####`purge_vhost_configs`
432 If `vhost_dir` != `confd_dir`, this controls the removal of any configurations that are not managed by Puppet within `vhost_dir`. It defaults to the value of `purge_configs`. Setting this to false is a stopgap measure to allow the apache module to coexist with existing or otherwise unmanaged configurations within `vhost_dir`
436 Makes Apache use the Linux kernel sendfile to serve static files. Defaults to 'On'.
440 Sets the server administrator. Defaults to 'root@localhost'.
444 Sets the server name. Defaults to `fqdn` provided by Facter.
448 Sets the root directory in which the server resides. Defaults to '/etc/httpd' on RedHat, '/etc/apache2' on Debian, '/usr/local' on FreeBSD, and '/var/www' on Gentoo.
450 #####`server_signature`
452 Configures a trailing footer line under server-generated documents. More information about [ServerSignature](http://httpd.apache.org/docs/current/mod/core.html#serversignature). Defaults to 'On'.
456 Controls how much information Apache sends to the browser about itself and the operating system. More information about [ServerTokens](http://httpd.apache.org/docs/current/mod/core.html#servertokens). Defaults to 'OS'.
458 #####`service_enable`
460 Determines whether the HTTPD service is enabled when the machine is booted. Defaults to 'true'.
462 #####`service_ensure`
464 Determines whether the service should be running. Valid values are 'true', 'false', 'running', or 'stopped' when Puppet should manage the service. Any other value sets ensure to 'false' for the Apache service, which is useful when you want to let the service be managed by some other application like Pacemaker. Defaults to 'running'.
468 Name of the Apache service to run. Defaults to: 'httpd' on RedHat, 'apache2' on Debian and Gentoo, and 'apache22' on FreeBSD.
470 #####`service_manage`
472 Determines whether the HTTPD service state is managed by Puppet . Defaults to 'true'.
474 #####`service_restart`
476 Determines whether the HTTPD service restart command should be anything other than the default managed by Puppet. Defaults to undef.
481 Controls how TRACE requests per RFC 2616 are handled. More information about [TraceEnable](http://httpd.apache.org/docs/current/mod/core.html#traceenable). Defaults to 'On'.
485 Changes the location of the configuration directory your virtual host configuration files are placed in. Defaults to 'etc/httpd/conf.d' on RedHat, '/etc/apache2/sites-available' on Debian, '/usr/local/etc/apache22/Vhosts' on FreeBSD, and '/etc/apache2/vhosts.d' on Gentoo.
489 Changes the user that Apache will answer requests as. The parent process will continue to be run as root, but resource accesses by child processes will be done under this user. By default, puppet will attept to manage this user as a resource under `::apache`. If this is not what you want, set [`manage_user`](#manage_user) to 'false'. Defaults to the OS-specific default user for apache, as detected in `::apache::params`.
493 The name of the Apache package to install. This is automatically detected in `::apache::params`. You might need to override this if you are using a non-standard Apache package, such as those from Red Hat's software collections.
495 ####Defined Type: `apache::custom_config`
497 Allows you to create custom configs for Apache. The configuration files are only added to the Apache confd dir if the file is valid. An error is raised during the Puppet run if the file is invalid and `$verify_config` is `true`.
500 apache::custom_config { 'test':
505 **Parameters within `apache::custom_config`:**
509 Specify whether the configuration file is present or absent. Defaults to 'present'. Valid values are 'present' and 'absent'.
513 The directory to place the configuration file in. Defaults to `$::apache::confd_dir`.
517 The content of the configuration file. Only one of `$content` and `$source` can be specified.
521 The priority of the configuration file, used for ordering. Defaults to '25'.
523 Pass priority `false` to omit the priority prefix in file names.
527 The source of the configuration file. Only one of `$content` and `$source` can be specified.
529 #####`verify_command`
531 The command to use to verify the configuration file. It should use a fully qualified command. Defaults to '/usr/sbin/apachectl -t'. The `$verify_command` is only used if `$verify_config` is `true`. If the `$verify_command` fails, the configuration file is deleted, the Apache service is not notified, and an error is raised during the Puppet run.
535 Boolean to specify whether the configuration file should be validated before the Apache service is notified. Defaults to `true`.
537 ####Class: `apache::default_mods`
539 Installs default Apache modules based on what OS you are running.
542 class { 'apache::default_mods': }
545 ####Defined Type: `apache::mod`
547 Used to enable arbitrary Apache HTTPD modules for which there is no specific `apache::mod::[name]` class. The `apache::mod` defined type also installs the required packages to enable the module, if any.
550 apache::mod { 'rewrite': }
551 apache::mod { 'ldap': }
554 ####Classes: `apache::mod::[name]`
556 There are many `apache::mod::[name]` classes within this module that can be declared using `include`:
559 * `alias`(see [`apache::mod::alias`](#class-apachemodalias) below)
561 * `auth_cas`* (see [`apache::mod::auth_cas`](#class-apachemodauthcas) below)
579 * `event`(see [`apache::mod::event`](#class-apachemodevent) below)
593 * `pagespeed` (see [`apache::mod::pagespeed`](#class-apachemodpagespeed) below)
597 * `php` (requires [`mpm_module`](#mpm_module) set to `prefork`)
611 * `shib`* (see [`apache::mod::shib`](#class-apachemodshib) below)
613 * `ssl`* (see [`apache::mod::ssl`](#class-apachemodssl) below)
614 * `status`* (see [`apache::mod::status`](#class-apachemodstatus) below)
619 * `wsgi` (see [`apache::mod::wsgi`](#class-apachemodwsgi) below)
622 Modules noted with a * indicate that the module has settings and, thus, a template that includes parameters. These parameters control the module's configuration. Most of the time, these parameters do not require any configuration or attention.
624 The modules mentioned above, and other Apache modules that have templates, cause template files to be dropped along with the mod install. The module will not work without the template. Any module without a template installs the package but drops no files.
626 ###Class: `apache::mod::alias`
628 Installs and manages the alias module.
630 Full Documentation for alias is available from [Apache](https://httpd.apache.org/docs/current/mod/mod_alias.html).
632 To disable directory listing for the icons directory:
634 class { 'apache::mod::alias':
635 icons_options => 'None',
639 ####Class: `apache::mod::event`
641 Installs and manages mpm_event module.
643 Full Documentation for mpm_event is available from [Apache](https://httpd.apache.org/docs/current/mod/event.html).
645 To configure the event thread limit:
648 class {'apache::mod::event':
649 $threadlimit => '128',
653 ####Class: `apache::mod::auth_cas`
655 Installs and manages mod_auth_cas. The parameters `cas_login_url` and `cas_validate_url` are required.
657 Full documentation on mod_auth_cas is available from [JASIG](https://github.com/Jasig/mod_auth_cas).
659 ####Class: `apache::mod::geoip`
661 Installs and manages mod_geoip.
663 Full documentation on mod_geoip is available from [MaxMind](http://dev.maxmind.com/geoip/legacy/mod_geoip2/).
665 These are the default settings:
668 class {'apache::mod::geoip':
670 $db_file => '/usr/share/GeoIP/GeoIP.dat',
676 The parameter `db_file` can be a single directory or a hash of directories.
678 ####Class: `apache::mod::info`
680 Installs and manages mod_info which provides a comprehensive overview of the server configuration.
682 Full documentation for mod_info is available from [Apache](https://httpd.apache.org/docs/current/mod/mod_info.html).
684 These are the default settings:
687 $allow_from = ['127.0.0.1','::1'],
688 $apache_version = $::apache::apache_version,
689 $restrict_access = true,
692 To set the addresses that are allowed to access /server-info add the following:
695 class {'apache::mod::info':
704 To disable the access restrictions add the following:
707 class {'apache::mod::info':
708 restrict_access => false,
712 It is not recommended to leave this set to false though it can be very useful for testing. For this reason, you can insert this setting in your normal code to temporarily disable the restrictions like so:
715 class {'apache::mod::info':
716 restrict_access => false, # false disables the block below
725 ####Class: `apache::mod::pagespeed`
727 Installs and manages mod_pagespeed, which is a Google module that rewrites web pages to reduce latency and bandwidth.
729 This module does *not* manage the software repositories needed to automatically install the
730 mod-pagespeed-stable package. The module does however require that the package be installed,
731 or be installable using the system's default package provider. You should ensure that this
732 pre-requisite is met or declaring `apache::mod::pagespeed` causes the Puppet run to fail.
734 These are the defaults:
737 class { 'apache::mod::pagespeed':
738 inherit_vhost_config => 'on',
739 filter_xhtml => false,
740 cache_path => '/var/cache/mod_pagespeed/',
741 log_dir => '/var/log/pagespeed',
742 memcache_servers => [],
743 rewrite_level => 'CoreFilters',
744 disable_filters => [],
745 enable_filters => [],
746 forbid_filters => [],
747 rewrite_deadline_per_flush_ms => 10,
748 additional_domains => undef,
749 file_cache_size_kb => 102400,
750 file_cache_clean_interval_ms => 3600000,
751 lru_cache_per_process => 1024,
752 lru_cache_byte_limit => 16384,
753 css_flatten_max_bytes => 2048,
754 css_inline_max_bytes => 2048,
755 css_image_inline_max_bytes => 2048,
756 image_inline_max_bytes => 2048,
757 js_inline_max_bytes => 2048,
758 css_outline_min_bytes => 3000,
759 js_outline_min_bytes => 3000,
760 inode_limit => 500000,
761 image_max_rewrites_at_once => 8,
762 num_rewrite_threads => 4,
763 num_expensive_rewrite_threads => 4,
764 collect_statistics => 'on',
765 statistics_logging => 'on',
766 allow_view_stats => [],
767 allow_pagespeed_console => [],
768 allow_pagespeed_message => [],
769 message_buffer_size => 100000,
770 additional_configuration => { }
774 Full documentation for mod_pagespeed is available from [Google](http://modpagespeed.com).
776 ####Class: `apache::mod::php`
778 Installs and configures mod_php. The defaults are OS-dependant.
780 Overriding the package name:
782 class {'::apache::mod::php':
783 package_name => "php54-php",
784 path => "${::apache::params::lib_path}/libphp54-php5.so",
788 Overriding the default configuartion:
790 class {'::apache::mod::php':
791 source => 'puppet:///modules/apache/my_php.conf',
797 class {'::apache::mod::php':
798 template => 'apache/php.conf.erb',
805 class {'::apache::mod::php':
807 AddHandler php5-script .php
808 AddType text/html .php',
811 ####Class: `apache::mod::shib`
813 Installs the [Shibboleth](http://shibboleth.net/) module for Apache which allows the use of SAML2 Single-Sign-On (SSO) authentication by Shibboleth Identity Providers and Shibboleth Federations. This class only installs and configures the Apache components of a Shibboleth Service Provider (a web application that consumes Shibboleth SSO identities). The Shibboleth configuration can be managed manually, with Puppet, or using a [Shibboleth Puppet Module](https://github.com/aethylred/puppet-shibboleth).
815 Defining this class enables the Shibboleth specific parameters in `apache::vhost` instances.
817 ####Class: `apache::mod::ssl`
819 Installs Apache SSL capabilities and uses the ssl.conf.erb template. These are the defaults:
822 class { 'apache::mod::ssl':
823 ssl_compression => false,
824 ssl_cryptodevice => 'builtin',
825 ssl_options => [ 'StdEnvVars' ],
826 ssl_cipher => 'HIGH:MEDIUM:!aNULL:!MD5',
827 ssl_honorcipherorder => 'On',
828 ssl_protocol => [ 'all', '-SSLv2', '-SSLv3' ],
829 ssl_pass_phrase_dialog => 'builtin',
830 ssl_random_seed_bytes => '512',
831 ssl_sessioncachetimeout => '300',
835 To *use* SSL with a virtual host, you must either set the`default_ssl_vhost` parameter in `::apache` to 'true' or set the `ssl` parameter in `apache::vhost` to 'true'.
837 ####Class: `apache::mod::status`
839 Installs Apache mod_status and uses the status.conf.erb template. These are the defaults:
842 class { 'apache::mod::status':
843 allow_from => ['127.0.0.1','::1'],
844 extended_status => 'On',
845 status_path => '/server-status',
852 ####Class: `apache::mod::expires`
854 Installs Apache mod_expires and uses the expires.conf.erb template. These are the defaults:
857 class { 'apache::mod::expires':
858 expires_active => true,
859 expires_default => undef,
860 expires_by_type => undef,
867 `expires_by_type` is an array of Hashes, describing a set of types and their expire times:
870 class { 'apache::mod::expires':
872 { 'text/json' => 'access plus 1 month' },
873 { 'text/html' => 'access plus 1 year' },
878 ####Class: `apache::mod::wsgi`
880 Enables Python support in the WSGI module. To use, simply `include 'apache::mod::wsgi'`.
882 For customized parameters, which tell Apache how Python is currently configured on the operating system,
885 class { 'apache::mod::wsgi':
886 wsgi_socket_prefix => "\${APACHE_RUN_DIR}WSGI",
887 wsgi_python_home => '/path/to/venv',
888 wsgi_python_path => '/path/to/venv/site-packages',
892 To specify an alternate mod\_wsgi package name to install and the name of the module .so it provides,
893 (e.g. a "python27-mod\_wsgi" package that provides "python27-mod_wsgi.so" in the default module directory):
896 class { 'apache::mod::wsgi':
897 wsgi_socket_prefix => "\${APACHE_RUN_DIR}WSGI",
898 wsgi_python_home => '/path/to/venv',
899 wsgi_python_path => '/path/to/venv/site-packages',
900 package_name => 'python27-mod_wsgi',
901 mod_path => 'python27-mod_wsgi.so',
905 If ``mod_path`` does not contain "/", it will be prefixed by the default module path
906 for your OS; otherwise, it will be used literally.
908 More information about [WSGI](http://modwsgi.readthedocs.org/en/latest/).
910 ####Class: `apache::mod::fcgid`
912 Installs and configures mod_fcgid.
914 The class makes no effort to list all available options, but rather uses an options hash to allow for ultimate flexibility:
917 class { 'apache::mod::fcgid':
919 'FcgidIPCDir' => '/var/run/fcgidsock',
920 'SharememPath' => '/var/run/fcgid_shm',
921 'AddHandler' => 'fcgid-script .fcgi',
926 For a full list op options, see the [official mod_fcgid documentation](https://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html).
928 It is also possible to set the FcgidWrapper per directory per vhost. You must ensure the fcgid module is loaded because there is no auto loading.
931 include apache::mod::fcgid
932 apache::vhost { 'example.org':
933 docroot => '/var/www/html',
935 path => '/var/www/html',
937 command => '/usr/local/bin/fcgiwrapper',
943 See [FcgidWrapper documentation](https://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html#fcgidwrapper) for more information.
945 ####Class: `apache::mod::negotiation`
947 Installs and configures mod_negotiation. If there are not provided any
948 parameter, default apache mod_negotiation configuration is done.
951 class { '::apache::mod::negotiation':
952 force_language_priority => 'Prefer',
953 language_priority => [ 'es', 'en', 'ca', 'cs', 'da', 'de', 'el', 'eo' ],
957 **Parameters within `apache::mod::negotiation`:**
959 #####`force_language_priority`
961 A string that sets the `ForceLanguagePriority` option. Defaults to `Prefer Fallback`.
963 #####`language_priority`
965 An array of languages to set the `LanguagePriority` option of the module.
967 ####Class: `apache::mod::deflate`
969 Installs and configures mod_deflate. If no parameters are provided, a default configuration is applied.
972 class { '::apache::mod::deflate':
973 types => [ 'text/html', 'text/css' ],
975 'Input' => 'instream',
983 An array of mime types to be deflated.
987 A hash where the key represents the type and the value represents the note name.
990 ####Class: `apache::mod::reqtimeout`
992 Installs and configures mod_reqtimeout. Defaults to recommended apache
993 mod_reqtimeout configuration.
996 class { '::apache::mod::reqtimeout':
997 timeouts => ['header=20-40,MinRate=500', 'body=20,MinRate=500'],
1001 ####Class: `apache::mod::version`
1003 This wrapper around mod_version warns on Debian and Ubuntu systems with Apache httpd 2.4
1004 about loading mod_version, as on these platforms it's already built-in.
1007 include '::apache::mod::version'
1012 A string or an array that sets the `RequestReadTimeout` option. Defaults to
1013 `['header=20-40,MinRate=500', 'body=20,MinRate=500']`.
1016 ####Class: `apache::mod::security`
1018 Installs and configures mod_security. Defaults to enabled and running on all
1022 include '::apache::mod::security'
1027 Name of package to install containing crs rules
1031 Directory to install the modsec configuration and activated rules links into
1033 #####`activated_rules`
1035 Array of rules from the modsec_crs_path to activate by symlinking to
1036 ${modsec_dir}/activated_rules.
1038 #####`allowed_methods`
1040 HTTP methods allowed by mod_security
1042 #####`content_types`
1044 Content-types allowed by mod_security
1046 #####`restricted_extensions`
1048 Extensions prohibited by mod_security
1050 #####`restricted_headers`
1052 Headers restricted by mod_security
1055 ####Defined Type: `apache::vhost`
1057 The Apache module allows a lot of flexibility in the setup and configuration of virtual hosts. This flexibility is due, in part, to `vhost` being a defined resource type, which allows it to be evaluated multiple times with different parameters.
1059 The `vhost` defined type allows you to have specialized configurations for virtual hosts that have requirements outside the defaults. You can set up a default vhost within the base `::apache` class, as well as set a customized vhost as default. Your customized vhost (priority 10) will be privileged over the base class vhost (15).
1061 The `vhost` defined type uses `concat::fragment` to build the configuration file, so if you want to inject custom fragments for pieces of the configuration not supported by default by the defined type, you can add a custom fragment. For the `order` parameter for the custom fragment, the `vhost` defined type uses multiples of 10, so any order that isn't a multiple of 10 should work.
1064 apache::vhost { "example.com":
1065 docroot => '/var/www/html',
1068 concat::fragment { "example.com-my_custom_fragment":
1069 target => '25-example.com.conf',
1071 content => '# my custom comment',
1075 If you have a series of specific configurations and do not want a base `::apache` class default vhost, make sure to set the base class `default_vhost` to 'false'.
1079 default_vhost => false,
1083 **Parameters within `apache::vhost`:**
1087 Specifies whether `*_access.log` directives (`*_file`,`*_pipe`, or `*_syslog`) should be configured. Setting the value to 'false' chooses none. Defaults to 'true'.
1089 #####`access_log_file`
1091 Sets the `*_access.log` filename that is placed in `$logroot`. Given a vhost, example.com, it defaults to 'example.com_ssl.log' for SSL vhosts and 'example.com_access.log' for non-SSL vhosts.
1093 #####`access_log_pipe`
1095 Specifies a pipe to send access log messages to. Defaults to 'undef'.
1097 #####`access_log_syslog`
1099 Sends all access log messages to syslog. Defaults to 'undef'.
1101 #####`access_log_format`
1103 Specifies the use of either a LogFormat nickname or a custom format string for the access log. Defaults to 'combined'. See [these examples](http://httpd.apache.org/docs/current/mod/mod_log_config.html).
1105 #####`access_log_env_var`
1107 Specifies that only requests with particular environment variables be logged. Defaults to 'undef'.
1109 #####`add_default_charset`
1111 Sets [AddDefaultCharset](http://httpd.apache.org/docs/current/mod/core.html#adddefaultcharset), a default value for the media charset, which is added to text/plain and text/html responses.
1115 Determines whether the vhost creates a Listen statement. The default value is 'true'.
1117 Setting `add_listen` to 'false' stops the vhost from creating a Listen statement, and this is important when you combine vhosts that are not passed an `ip` parameter with vhosts that *are* passed the `ip` parameter.
1119 #####`use_optional_includes`
1121 Specifies if for apache > 2.4 it should use IncludeOptional instead of Include for `additional_includes`. Defaults to 'false'.
1123 #####`additional_includes`
1125 Specifies paths to additional static, vhost-specific Apache configuration files. Useful for implementing a unique, custom configuration not supported by this module. Can be an array. Defaults to '[]'.
1129 Passes a list of hashes to the vhost to create Alias, AliasMatch, ScriptAlias or ScriptAliasMatch directives as per the [mod_alias documentation](http://httpd.apache.org/docs/current/mod/mod_alias.html). These hashes are formatted as follows:
1133 { aliasmatch => '^/image/(.*)\.jpg$',
1134 path => '/files/jpg.images/$1.jpg',
1136 { alias => '/image',
1137 path => '/ftp/pub/image',
1139 { scriptaliasmatch => '^/cgi-bin(.*)',
1140 path => '/usr/local/share/cgi-bin$1',
1142 { scriptalias => '/nagios/cgi-bin/',
1143 path => '/usr/lib/nagios/cgi-bin/',
1145 { alias => '/nagios',
1146 path => '/usr/share/nagios/html',
1151 For `alias`, `aliasmatch`, `scriptalias` and `scriptaliasmatch` to work, each needs a corresponding context, such as `<Directory /path/to/directory>` or `<Location /some/location/here>`. The directives are created in the order specified in the `aliases` parameter. As described in the [`mod_alias` documentation](http://httpd.apache.org/docs/current/mod/mod_alias.html), more specific `alias`, `aliasmatch`, `scriptalias` or `scriptaliasmatch` parameters should come before the more general ones to avoid shadowing.
1153 *Note*: Using the `aliases` parameter is preferred over the `scriptaliases` parameter since here the order of the various alias directives among each other can be controlled precisely. Defining ScriptAliases using the `scriptaliases` parameter means *all* ScriptAlias directives will come after *all* Alias directives, which can lead to Alias directives shadowing ScriptAlias directives. This is often problematic, for example in case of Nagios.
1155 *Note:* If `apache::mod::passenger` is loaded and `PassengerHighPerformance => true` is set, then Alias might have issues honoring the `PassengerEnabled => off` statement. See [this article](http://www.conandalton.net/2010/06/passengerenabled-off-not-working.html) for details.
1157 #####`allow_encoded_slashes`
1159 This sets the [`AllowEncodedSlashes` declaration](http://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes) for the vhost, overriding the server default. This modifies the vhost responses to URLs with `\` and `/` characters. The default is undefined, which omits the declaration from the server configuration and select the Apache default setting of `Off`. Allowed values are: `on`, `off` or `nodecode`.
1163 Specifies the list of things Apache blocks access to. The default is an empty set, '[]'. Currently, the only option is 'scm', which blocks web access to .svn, .git and .bzr directories.
1165 #####`custom_fragment`
1167 Passes a string of custom configuration directives to be placed at the end of the vhost configuration. Defaults to 'undef'.
1169 #####`default_vhost`
1171 Sets a given `apache::vhost` as the default to serve requests that do not match any other `apache::vhost` definitions. The default value is 'false'.
1175 See the [`directories` section](#parameter-directories-for-apachevhost).
1177 #####`directoryindex`
1179 Sets the list of resources to look for when a client requests an index of the directory by specifying a '/' at the end of the directory name. [DirectoryIndex](http://httpd.apache.org/docs/current/mod/mod_dir.html#directoryindex) has more information. Defaults to 'undef'.
1184 [DocumentRoot](http://httpd.apache.org/docs/current/mod/core.html#documentroot)
1185 directive, which identifies the directory Apache serves files from. Required.
1187 #####`docroot_group`
1189 Sets group access to the docroot directory. Defaults to 'root'.
1191 #####`docroot_owner`
1193 Sets individual user access to the docroot directory. Defaults to 'root'.
1197 Sets access permissions of the docroot directory. Defaults to 'undef'.
1199 #####`manage_docroot`
1201 Whether to manage to docroot directory at all. Defaults to 'true'.
1205 Specifies whether `*_error.log` directives should be configured. Defaults to 'true'.
1207 #####`error_log_file`
1209 Points to the `*_error.log` file. Given a vhost, example.com, it defaults to 'example.com_ssl_error.log' for SSL vhosts and 'example.com_access_error.log' for non-SSL vhosts.
1211 #####`error_log_pipe`
1213 Specifies a pipe to send error log messages to. Defaults to 'undef'.
1215 #####`error_log_syslog`
1217 Sends all error log messages to syslog. Defaults to 'undef'.
1219 #####`error_documents`
1221 A list of hashes which can be used to override the [ErrorDocument](https://httpd.apache.org/docs/current/mod/core.html#errordocument) settings for this vhost. Defaults to '[]'. Example:
1224 apache::vhost { 'sample.example.net':
1225 error_documents => [
1226 { 'error_code' => '503', 'document' => '/service-unavail' },
1227 { 'error_code' => '407', 'document' => 'https://example.com/proxy/login' },
1234 Specifies if the vhost file is present or absent. Defaults to 'present'.
1236 #####`fallbackresource`
1238 Sets the [FallbackResource](http://httpd.apache.org/docs/current/mod/mod_dir.html#fallbackresource) directive, which specifies an action to take for any URL that doesn't map to anything in your filesystem and would otherwise return 'HTTP 404 (Not Found)'. Valid values must either begin with a / or be 'disabled'. Defaults to 'undef'.
1242 Adds lines to replace, merge, or remove response headers. See [Header](http://httpd.apache.org/docs/current/mod/mod_headers.html#header) for more information. Can be an array. Defaults to 'undef'.
1246 Sets the IP address the vhost listens on. Defaults to listen on all IPs.
1250 Enables an [IP-based](http://httpd.apache.org/docs/current/vhosts/ip-based.html) vhost. This parameter inhibits the creation of a NameVirtualHost directive, since those are used to funnel requests to name-based vhosts. Defaults to 'false'.
1254 Configures [ITK](http://mpm-itk.sesse.net/) in a hash. Keys can be:
1257 * `assignuseridexpr`
1258 * `assigngroupidexpr`
1261 * `limituidrange` (Linux 3.5.0 or newer)
1262 * `limitgidrange` (Linux 3.5.0 or newer)
1264 Usage typically looks like:
1267 apache::vhost { 'sample.example.net':
1268 docroot => '/path/to/directory',
1271 group => 'somegroup',
1278 Specifies the location of the virtual host's logfiles. Defaults to '/var/log/<apache log location>/'.
1280 #####`$logroot_ensure`
1282 Determines whether or not to remove the logroot directory for a virtual host. Valid values are 'directory', or 'absent'.
1286 Overrides the mode the logroot directory is set to. Defaults to undef. Do NOT give people write access to the directory the logs are stored
1287 in without being aware of the consequences; see http://httpd.apache.org/docs/2.4/logs.html#security for details.
1291 Specifies the verbosity of the error log. Defaults to 'warn' for the global server configuration and can be overridden on a per-vhost basis. Valid values are 'emerg', 'alert', 'crit', 'error', 'warn', 'notice', 'info' or 'debug'.
1293 ######`modsec_body_limit`
1295 Configures the maximum request body size (in bytes) ModSecurity will accept for buffering
1297 ######`modsec_disable_vhost`
1299 Boolean. Only valid if apache::mod::security is included. Used to disable mod_security on an individual vhost. Only relevant if apache::mod::security is included.
1301 ######`modsec_disable_ids`
1303 Array of mod_security IDs to remove from the vhost. Also takes a hash allowing removal of an ID from a specific location.
1306 apache::vhost { 'sample.example.net':
1307 modsec_disable_ids => [ 90015, 90016 ],
1312 apache::vhost { 'sample.example.net':
1313 modsec_disable_ids => { '/location1' => [ 90015, 90016 ] },
1317 ######`modsec_disable_ips`
1319 Array of IPs to exclude from mod_security rule matching
1321 #####`no_proxy_uris`
1323 Specifies URLs you do not want to proxy. This parameter is meant to be used in combination with [`proxy_dest`](#proxy_dest).
1325 #####`no_proxy_uris_match`
1327 This directive is equivalent to `no_proxy_uris`, but takes regular expressions.
1329 #####`proxy_preserve_host`
1331 Sets the [ProxyPreserveHost Directive](http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypreservehost). true Enables the Host: line from an incoming request to be proxied to the host instead of hostname . false sets this option to off (default).
1333 #####`proxy_error_override`
1335 Sets the [ProxyErrorOverride Directive](http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxyerroroverride). This directive controls whether apache should override error pages for proxied content. This option is off by default.
1339 Sets the [Options](http://httpd.apache.org/docs/current/mod/core.html#options) for the specified virtual host. Defaults to '['Indexes','FollowSymLinks','MultiViews']', as demonstrated below:
1342 apache::vhost { 'site.name.fdqn':
1344 options => ['Indexes','FollowSymLinks','MultiViews'],
1348 *Note:* If you use [`directories`](#parameter-directories-for-apachevhost), 'Options', 'Override', and 'DirectoryIndex' are ignored because they are parameters within `directories`.
1352 Sets the overrides for the specified virtual host. Accepts an array of [AllowOverride](http://httpd.apache.org/docs/current/mod/core.html#allowoverride) arguments. Defaults to '[none]'.
1354 #####`passenger_app_root`
1356 Sets [PassengerRoot](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerAppRoot), the location of the Passenger application root if different from the DocumentRoot.
1358 #####`passenger_app_env`
1360 Sets [PassengerAppEnv](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerAppEnv), the environment for the Passenger application. If not specifies, defaults to the global setting or 'production'.
1362 #####`passenger_ruby`
1364 Sets [PassengerRuby](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerRuby) on this virtual host, the Ruby interpreter to use for the application.
1366 #####`passenger_min_instances`
1368 Sets [PassengerMinInstances](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerMinInstances), the minimum number of application processes to run.
1370 #####`passenger_start_timeout`
1372 Sets [PassengerStartTimeout](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#_passengerstarttimeout_lt_seconds_gt), the timeout for the application startup.
1374 #####`passenger_pre_start`
1376 Sets [PassengerPreStart](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerPreStart), the URL of the application if pre-starting is required.
1378 #####`php_flags & values`
1380 Allows per-vhost setting [`php_value`s or `php_flag`s](http://php.net/manual/en/configuration.changes.php). These flags or values can be overwritten by a user or an application. Defaults to '{}'.
1382 #####`php_admin_flags & values`
1384 Allows per-vhost setting [`php_admin_value`s or `php_admin_flag`s](http://php.net/manual/en/configuration.changes.php). These flags or values cannot be overwritten by a user or an application. Defaults to '{}'.
1388 Sets the port the host is configured on. The module's defaults ensure the host listens on port 80 for non-SSL vhosts and port 443 for SSL vhosts. The host only listens on the port set in this parameter.
1392 Sets the relative load-order for Apache HTTPD VirtualHost configuration files. Defaults to '25'.
1394 If nothing matches the priority, the first name-based vhost is used. Likewise, passing a higher priority causes the alphabetically first name-based vhost to be used if no other names match.
1396 *Note:* You should not need to use this parameter. However, if you do use it, be aware that the `default_vhost` parameter for `apache::vhost` passes a priority of '15'.
1398 Pass priority `false` to omit the priority prefix in file names.
1402 Specifies the destination address of a [ProxyPass](http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass) configuration. Defaults to 'undef'.
1406 Specifies an array of `path => URI` for a [ProxyPass](http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass) configuration. Defaults to 'undef'. Optionally parameters can be added as an array.
1409 apache::vhost { 'site.name.fdqn':
1412 { 'path' => '/a', 'url' => 'http://backend-a/' },
1413 { 'path' => '/b', 'url' => 'http://backend-b/' },
1414 { 'path' => '/c', 'url' => 'http://backend-a/c', 'params' => {'max'=>20, 'ttl'=>120, 'retry'=>300}},
1415 { 'path' => '/l', 'url' => 'http://backend-xy',
1416 'reverse_urls' => ['http://backend-x', 'http://backend-y'] },
1417 { 'path' => '/d', 'url' => 'http://backend-a/d',
1418 'params' => { 'retry' => '0', 'timeout' => '5' }, },
1419 { 'path' => '/e', 'url' => 'http://backend-a/e',
1420 'keywords' => ['nocanon', 'interpolate'] },
1421 { 'path' => '/f', 'url' => 'http://backend-f/',
1422 'setenv' => ['proxy-nokeepalive 1','force-proxy-request-1.0 1']},
1427 `reverse_urls` is optional and can be an array or a string. It is useful when used with `mod_proxy_balancer`.
1428 `params` is an optional parameter. It allows to provide the ProxyPass key=value parameters (Connection settings).
1429 `setenv` is optional and is an array to set environment variables for the proxy directive, for details see http://httpd.apache.org/docs/current/mod/mod_proxy.html#envsettings
1431 #####`proxy_dest_match`
1433 This directive is equivalent to proxy_dest, but takes regular expressions, see [ProxyPassMatch](http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassmatch) for details.
1435 #####`proxy_dest_reverse_match`
1437 Allows you to pass a ProxyPassReverse if `proxy_dest_match` is specified. See [ProxyPassReverse](http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassreverse) for details.
1439 #####`proxy_pass_match`
1441 This directive is equivalent to proxy_pass, but takes regular expressions, see [ProxyPassMatch](http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassmatch) for details.
1443 #####`rack_base_uris`
1445 Specifies the resource identifiers for a rack configuration. The file paths specified are listed as rack application roots for [Phusion Passenger](http://www.modrails.com/documentation/Users%20guide%20Apache.html#_railsbaseuri_and_rackbaseuri) in the _rack.erb template. Defaults to 'undef'.
1447 #####`redirect_dest`
1449 Specifies the address to redirect to. Defaults to 'undef'.
1451 #####`redirect_source`
1453 Specifies the source URIs that redirect to the destination specified in `redirect_dest`. If more than one item for redirect is supplied, the source and destination must be the same length, and the items are order-dependent.
1456 apache::vhost { 'site.name.fdqn':
1458 redirect_source => ['/images','/downloads'],
1459 redirect_dest => ['http://img.example.com/','http://downloads.example.com/'],
1463 #####`redirect_status`
1465 Specifies the status to append to the redirect. Defaults to 'undef'.
1468 apache::vhost { 'site.name.fdqn':
1470 redirect_status => ['temp','permanent'],
1474 #####`redirectmatch_regexp` & `redirectmatch_status` & `redirectmatch_dest`
1476 Determines which server status should be raised for a given regular expression and where to forward the user to. Entered as arrays. Defaults to 'undef'.
1479 apache::vhost { 'site.name.fdqn':
1481 redirectmatch_status => ['404','404'],
1482 redirectmatch_regexp => ['\.git(/.*|$)/','\.svn(/.*|$)'],
1483 redirectmatch_dest => ['http://www.example.com/1','http://www.example.com/2'],
1487 #####`request_headers`
1489 Modifies collected [request headers](http://httpd.apache.org/docs/current/mod/mod_headers.html#requestheader) in various ways, including adding additional request headers, removing request headers, etc. Defaults to 'undef'.
1492 apache::vhost { 'site.name.fdqn':
1494 request_headers => [
1495 'append MirrorID "mirror 12"',
1503 Creates URL rewrite rules. Expects an array of hashes, and the hash keys can be any of 'comment', 'rewrite_base', 'rewrite_cond', 'rewrite_rule' or 'rewrite_map'. Defaults to 'undef'.
1505 For example, you can specify that anyone trying to access index.html is served welcome.html
1508 apache::vhost { 'site.name.fdqn':
1510 rewrites => [ { rewrite_rule => ['^index\.html$ welcome.html'] } ]
1514 The parameter allows rewrite conditions that, when true, execute the associated rule. For instance, if you wanted to rewrite URLs only if the visitor is using IE
1517 apache::vhost { 'site.name.fdqn':
1521 comment => 'redirect IE',
1522 rewrite_cond => ['%{HTTP_USER_AGENT} ^MSIE'],
1523 rewrite_rule => ['^index\.html$ welcome.html'],
1529 You can also apply multiple conditions. For instance, rewrite index.html to welcome.html only when the browser is Lynx or Mozilla (version 1 or 2)
1532 apache::vhost { 'site.name.fdqn':
1536 comment => 'Lynx or Mozilla v1/2',
1537 rewrite_cond => ['%{HTTP_USER_AGENT} ^Lynx/ [OR]', '%{HTTP_USER_AGENT} ^Mozilla/[12]'],
1538 rewrite_rule => ['^index\.html$ welcome.html'],
1544 Multiple rewrites and conditions are also possible
1547 apache::vhost { 'site.name.fdqn':
1551 comment => 'Lynx or Mozilla v1/2',
1552 rewrite_cond => ['%{HTTP_USER_AGENT} ^Lynx/ [OR]', '%{HTTP_USER_AGENT} ^Mozilla/[12]'],
1553 rewrite_rule => ['^index\.html$ welcome.html'],
1556 comment => 'Internet Explorer',
1557 rewrite_cond => ['%{HTTP_USER_AGENT} ^MSIE'],
1558 rewrite_rule => ['^index\.html$ /index.IE.html [L]'],
1561 rewrite_base => /apps/,
1562 rewrite_rule => ['^index\.cgi$ index.php', '^index\.html$ index.php', '^index\.asp$ index.html'],
1564 { comment => 'Rewrite to lower case',
1565 rewrite_cond => ['%{REQUEST_URI} [A-Z]'],
1566 rewrite_map => ['lc int:tolower'],
1567 rewrite_rule => ['(.*) ${lc:$1} [R=301,L]'],
1573 Refer to the [`mod_rewrite` documentation](http://httpd.apache.org/docs/current/mod/mod_rewrite.html) for more details on what is possible with rewrite rules and conditions.
1577 Defines a directory of CGI scripts to be aliased to the path '/cgi-bin', for example: '/usr/scripts'. Defaults to 'undef'.
1579 #####`scriptaliases`
1581 *Note*: This parameter is deprecated in favour of the `aliases` parameter.
1583 Passes an array of hashes to the vhost to create either ScriptAlias or ScriptAliasMatch statements as per the [`mod_alias` documentation](http://httpd.apache.org/docs/current/mod/mod_alias.html). These hashes are formatted as follows:
1588 alias => '/myscript',
1589 path => '/usr/share/myscript',
1592 aliasmatch => '^/foo(.*)',
1593 path => '/usr/share/fooscripts$1',
1596 aliasmatch => '^/bar/(.*)',
1597 path => '/usr/share/bar/wrapper.sh/$1',
1600 alias => '/neatscript',
1601 path => '/usr/share/neatscript',
1606 The ScriptAlias and ScriptAliasMatch directives are created in the order specified. As with [Alias and AliasMatch](#aliases) directives, more specific aliases should come before more general ones to avoid shadowing.
1610 Specifies the email address Apache displays when it renders one of its error pages. Defaults to 'undef'.
1612 #####`serveraliases`
1614 Sets the [ServerAliases](http://httpd.apache.org/docs/current/mod/core.html#serveralias) of the site. Defaults to '[]'.
1618 Sets the servername corresponding to the hostname you connect to the virtual host at. Defaults to the title of the resource.
1622 Used by HTTPD to set environment variables for vhosts. Defaults to '[]'.
1627 apache::vhost { 'setenv.example.com':
1628 setenv => ['SPECIAL_PATH /foo/bin'],
1634 Used by HTTPD to conditionally set environment variables for vhosts. Defaults to '[]'.
1636 #####`suphp_addhandler`, `suphp_configpath`, & `suphp_engine`
1638 Set up a virtual host with [suPHP](http://suphp.org/DocumentationView.html?file=apache/CONFIG).
1640 `suphp_addhandler` defaults to 'php5-script' on RedHat and FreeBSD, and 'x-httpd-php' on Debian and Gentoo.
1642 `suphp_configpath` defaults to 'undef' on RedHat and FreeBSD, and '/etc/php5/apache2' on Debian and Gentoo.
1644 `suphp_engine` allows values 'on' or 'off'. Defaults to 'off'
1646 To set up a virtual host with suPHP
1649 apache::vhost { 'suphp.example.com':
1651 docroot => '/home/appuser/myphpapp',
1652 suphp_addhandler => 'x-httpd-php',
1653 suphp_engine => 'on',
1654 suphp_configpath => '/etc/php5/apache2',
1655 directories => { path => '/home/appuser/myphpapp',
1656 'suphp' => { user => 'myappuser', group => 'myappgroup' },
1663 Enables name-based virtual hosting. If no IP is passed to the virtual host, but the vhost is assigned a port, then the vhost name is 'vhost_name:port'. If the virtual host has no assigned IP or port, the vhost name is set to the title of the resource. Defaults to '*'.
1665 #####`virtual_docroot`
1667 Sets up a virtual host with a wildcard alias subdomain mapped to a directory with the same name. For example, 'http://example.com' would map to '/var/www/example.com'. Defaults to 'false'.
1670 apache::vhost { 'subdomain.loc':
1673 virtual_docroot' => '/var/www/%-2+',
1674 docroot => '/var/www',
1675 serveraliases => ['*.loc',],
1679 #####`wsgi_daemon_process`, `wsgi_daemon_process_options`, `wsgi_process_group`, `wsgi_script_aliases`, & `wsgi_pass_authorization`
1681 Set up a virtual host with [WSGI](https://code.google.com/p/modwsgi/).
1683 `wsgi_daemon_process` sets the name of the WSGI daemon. It is a hash, accepting [these keys](http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIDaemonProcess.html), and it defaults to 'undef'.
1685 `wsgi_daemon_process_options` is optional and defaults to 'undef'.
1687 `wsgi_process_group` sets the group ID the virtual host runs under. Defaults to 'undef'.
1689 `wsgi_script_aliases` requires a hash of web paths to filesystem .wsgi paths. Defaults to 'undef'.
1691 `wsgi_pass_authorization` the WSGI application handles authorisation instead of Apache when set to 'On'. For more information see [here] (http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIPassAuthorization.html). Defaults to 'undef' where apache sets the defaults setting to 'Off'.
1693 `wsgi_chunked_request` enables support for chunked requests. Defaults to 'undef'.
1695 To set up a virtual host with WSGI
1698 apache::vhost { 'wsgi.example.com':
1700 docroot => '/var/www/pythonapp',
1701 wsgi_daemon_process => 'wsgi',
1702 wsgi_daemon_process_options =>
1705 display-name => '%{GROUP}',
1707 wsgi_process_group => 'wsgi',
1708 wsgi_script_aliases => { '/' => '/var/www/demo.wsgi' },
1709 wsgi_chunked_request => 'On',
1713 ####Parameter `directories` for `apache::vhost`
1715 The `directories` parameter within the `apache::vhost` class passes an array of hashes to the vhost to create [Directory](http://httpd.apache.org/docs/current/mod/core.html#directory), [File](http://httpd.apache.org/docs/current/mod/core.html#files), and [Location](http://httpd.apache.org/docs/current/mod/core.html#location) directive blocks. These blocks take the form, '< Directory /path/to/directory>...< /Directory>'.
1717 The `path` key sets the path for the directory, files, and location blocks. Its value must be a path for the 'directory', 'files', and 'location' providers, or a regex for the 'directorymatch', 'filesmatch', or 'locationmatch' providers. Each hash passed to `directories` **must** contain `path` as one of the keys.
1719 The `provider` key is optional. If missing, this key defaults to 'directory'. Valid values for `provider` are 'directory', 'files', 'location', 'directorymatch', 'filesmatch', or 'locationmatch'. If you set `provider` to 'directorymatch', it uses the keyword 'DirectoryMatch' in the Apache config file.
1721 General `directories` usage looks something like
1724 apache::vhost { 'files.example.net':
1725 docroot => '/var/www/files',
1727 { 'path' => '/var/www/files',
1728 'provider' => 'files',
1729 'deny' => 'from all'
1735 *Note:* At least one directory should match the `docroot` parameter. After you start declaring directories, `apache::vhost` assumes that all required Directory blocks will be declared. If not defined, a single default Directory block is created that matches the `docroot` parameter.
1737 Available handlers, represented as keys, should be placed within the `directory`, `files`, or `location` hashes. This looks like
1740 apache::vhost { 'sample.example.net':
1741 docroot => '/path/to/directory',
1742 directories => [ { path => '/path/to/directory', handler => value } ],
1746 Any handlers you do not set in these hashes are considered 'undefined' within Puppet and are not added to the virtual host, resulting in the module using their default values. Supported handlers are:
1750 Sets [AddHandler](http://httpd.apache.org/docs/current/mod/mod_mime.html#addhandler) directives, which map filename extensions to the specified handler. Accepts a list of hashes, with `extensions` serving to list the extensions being managed by the handler, and takes the form: `{ handler => 'handler-name', extensions => ['extension']}`.
1753 apache::vhost { 'sample.example.net':
1754 docroot => '/path/to/directory',
1756 { path => '/path/to/directory',
1757 addhandlers => [{ handler => 'cgi-script', extensions => ['.cgi']}],
1765 Sets an [Allow](http://httpd.apache.org/docs/2.2/mod/mod_authz_host.html#allow) directive, which groups authorizations based on hostnames or IPs. **Deprecated:** This parameter is being deprecated due to a change in Apache. It only works with Apache 2.2 and lower. You can use it as a single string for one rule or as an array for more than one.
1768 apache::vhost { 'sample.example.net':
1769 docroot => '/path/to/directory',
1771 { path => '/path/to/directory',
1772 allow => 'from example.org',
1778 ######`allow_override`
1780 Sets the types of directives allowed in [.htaccess](http://httpd.apache.org/docs/current/mod/core.html#allowoverride) files. Accepts an array.
1783 apache::vhost { 'sample.example.net':
1784 docroot => '/path/to/directory',
1786 { path => '/path/to/directory',
1787 allow_override => ['AuthConfig', 'Indexes'],
1793 ######`auth_basic_authoritative`
1795 Sets the value for [AuthBasicAuthoritative](https://httpd.apache.org/docs/current/mod/mod_auth_basic.html#authbasicauthoritative), which determines whether authorization and authentication are passed to lower level Apache modules.
1797 ######`auth_basic_fake`
1799 Sets the value for [AuthBasicFake](http://httpd.apache.org/docs/current/mod/mod_auth_basic.html#authbasicfake), which statically configures authorization credentials for a given directive block.
1801 ######`auth_basic_provider`
1803 Sets the value for [AuthBasicProvider] (http://httpd.apache.org/docs/current/mod/mod_auth_basic.html#authbasicprovider), which sets the authentication provider for a given location.
1805 ######`auth_digest_algorithm`
1807 Sets the value for [AuthDigestAlgorithm](http://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestalgorithm), which selects the algorithm used to calculate the challenge and response hashes.
1809 ######`auth_digest_domain`
1811 Sets the value for [AuthDigestDomain](http://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestdomain), which allows you to specify one or more URIs in the same protection space for digest authentication.
1813 ######`auth_digest_nonce_lifetime`
1815 Sets the value for [AuthDigestNonceLifetime](http://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestnoncelifetime), which controls how long the server nonce is valid.
1817 ######`auth_digest_provider`
1819 Sets the value for [AuthDigestProvider](http://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestprovider), which sets the authentication provider for a given location.
1821 ######`auth_digest_qop`
1823 Sets the value for [AuthDigestQop](http://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestqop), which determines the quality-of-protection to use in digest authentication.
1825 ######`auth_digest_shmem_size`
1827 Sets the value for [AuthAuthDigestShmemSize](http://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestshmemsize), which defines the amount of shared memory allocated to the server for keeping track of clients.
1829 ######`auth_group_file`
1831 Sets the value for [AuthGroupFile](https://httpd.apache.org/docs/current/mod/mod_authz_groupfile.html#authgroupfile), which sets the name of the text file containing the list of user groups for authorization.
1835 Sets the value for [AuthName](http://httpd.apache.org/docs/current/mod/mod_authn_core.html#authname), which sets the name of the authorization realm.
1837 ######`auth_require`
1839 Sets the entity name you're requiring to allow access. Read more about [Require](http://httpd.apache.org/docs/current/mod/mod_authz_host.html#requiredirectives).
1843 Sets the value for [AuthType](http://httpd.apache.org/docs/current/mod/mod_authn_core.html#authtype), which guides the type of user authentication.
1845 ######`auth_user_file`
1847 Sets the value for [AuthUserFile](http://httpd.apache.org/docs/current/mod/mod_authn_file.html#authuserfile), which sets the name of the text file containing the users/passwords for authentication.
1849 ######`custom_fragment`
1851 Pass a string of custom configuration directives to be placed at the end of the directory configuration.
1854 apache::vhost { 'monitor':
1858 path => '/path/to/directory',
1859 custom_fragment => '
1860 <Location /balancer-manager>
1861 SetHandler balancer-manager
1865 <Location /server-status>
1866 SetHandler server-status
1878 Sets a [Deny](http://httpd.apache.org/docs/2.2/mod/mod_authz_host.html#deny) directive, specifying which hosts are denied access to the server. **Deprecated:** This parameter is being deprecated due to a change in Apache. It only works with Apache 2.2 and lower. You can use it as a single string for one rule or as an array for more than one.
1881 apache::vhost { 'sample.example.net':
1882 docroot => '/path/to/directory',
1884 { path => '/path/to/directory',
1885 deny => 'from example.org',
1891 ######`error_documents`
1893 An array of hashes used to override the [ErrorDocument](https://httpd.apache.org/docs/current/mod/core.html#errordocument) settings for the directory.
1896 apache::vhost { 'sample.example.net':
1898 { path => '/srv/www',
1899 error_documents => [
1900 { 'error_code' => '503',
1901 'document' => '/service-unavail',
1909 ######`geoip_enable`
1911 Sets the [GeoIPEnable](http://dev.maxmind.com/geoip/legacy/mod_geoip2/#Configuration) directive.
1912 Note that you must declare `class {'apache::mod::geoip': }` before using this directive.
1915 apache::vhost { 'first.example.com':
1916 docroot => '/var/www/first',
1918 { path => '/var/www/first',
1919 geoip_enable => true,
1927 Adds lines for [Header](http://httpd.apache.org/docs/current/mod/mod_headers.html#header) directives.
1930 apache::vhost { 'sample.example.net':
1931 docroot => '/path/to/directory',
1933 path => '/path/to/directory',
1934 headers => 'Set X-Robots-Tag "noindex, noarchive, nosnippet"',
1939 ######`index_options`
1941 Allows configuration settings for [directory indexing](http://httpd.apache.org/docs/current/mod/mod_autoindex.html#indexoptions).
1944 apache::vhost { 'sample.example.net':
1945 docroot => '/path/to/directory',
1947 { path => '/path/to/directory',
1948 directoryindex => 'disabled', # this is needed on Apache 2.4 or mod_autoindex doesn't work
1949 options => ['Indexes','FollowSymLinks','MultiViews'],
1950 index_options => ['IgnoreCase', 'FancyIndexing', 'FoldersFirst', 'NameWidth=*', 'DescriptionWidth=*', 'SuppressHTMLPreamble'],
1956 ######`index_order_default`
1958 Sets the [default ordering](http://httpd.apache.org/docs/current/mod/mod_autoindex.html#indexorderdefault) of the directory index.
1961 apache::vhost { 'sample.example.net':
1962 docroot => '/path/to/directory',
1964 { path => '/path/to/directory',
1965 order => 'Allow,Deny',
1966 index_order_default => ['Descending', 'Date'],
1972 ######`index_style_sheet`
1974 Sets the [IndexStyleSheet](http://httpd.apache.org/docs/current/mod/mod_autoindex.html#indexstylesheet) which adds a CSS stylesheet to the directory index.
1977 apache::vhost { 'sample.example.net':
1978 docroot => '/path/to/directory',
1980 { path => '/path/to/directory',
1981 options => ['Indexes','FollowSymLinks','MultiViews'],
1982 index_options => ['FancyIndexing'],
1983 index_style_sheet => '/styles/style.css',
1991 Lists the [Options](http://httpd.apache.org/docs/current/mod/core.html#options) for the given Directory block.
1994 apache::vhost { 'sample.example.net':
1995 docroot => '/path/to/directory',
1997 { path => '/path/to/directory',
1998 options => ['Indexes','FollowSymLinks','MultiViews'],
2006 Sets the order of processing Allow and Deny statements as per [Apache core documentation](http://httpd.apache.org/docs/2.2/mod/mod_authz_host.html#order). **Deprecated:** This parameter is being deprecated due to a change in Apache. It only works with Apache 2.2 and lower.
2009 apache::vhost { 'sample.example.net':
2010 docroot => '/path/to/directory',
2012 { path => '/path/to/directory',
2013 order => 'Allow,Deny',
2019 ######`passenger_enabled`
2021 Sets the value for the [PassengerEnabled](http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerEnabled) directory to 'on' or 'off'. Requires `apache::mod::passenger` to be included.
2024 apache::vhost { 'sample.example.net':
2025 docroot => '/path/to/directory',
2027 { path => '/path/to/directory',
2028 passenger_enabled => 'on',
2034 *Note:* Be aware that there is an [issue](http://www.conandalton.net/2010/06/passengerenabled-off-not-working.html) using the PassengerEnabled directive with the PassengerHighPerformance directive.
2036 ######`php_value` and `php_flag`
2038 `php_value` sets the value of the directory, and `php_flag` uses a boolean to configure the directory. Further information can be found [here](http://php.net/manual/en/configuration.changes.php).
2040 ######`php_admin_value` and `php_admin_flag`
2042 `php_admin_value` sets the value of the directory, and `php_admin_flag` uses a boolean to configure the directory. Further information can be found [here](http://php.net/manual/en/configuration.changes.php).
2047 Sets a `Satisfy` directive as per the [Apache Core documentation](http://httpd.apache.org/docs/2.2/mod/core.html#satisfy). **Deprecated:** This parameter is being deprecated due to a change in Apache. It only works with Apache 2.2 and lower.
2050 apache::vhost { 'sample.example.net':
2051 docroot => '/path/to/directory',
2053 { path => '/path/to/directory',
2062 Sets a `SetHandler` directive as per the [Apache Core documentation](http://httpd.apache.org/docs/2.2/mod/core.html#sethandler). An example:
2065 apache::vhost { 'sample.example.net':
2066 docroot => '/path/to/directory',
2068 { path => '/path/to/directory',
2069 sethandler => 'None',
2077 Creates URL [`rewrites`](#rewrites) rules in vhost directories. Expects an array of hashes, and the hash keys can be any of 'comment', 'rewrite_base', 'rewrite_cond', or 'rewrite_rule'.
2080 apache::vhost { 'secure.example.net':
2081 docroot => '/path/to/directory',
2083 { path => '/path/to/directory',
2084 rewrites => [ { comment => 'Permalink Rewrites',
2087 { rewrite_rule => [ '^index\.php$ - [L]' ]
2089 { rewrite_cond => [ '%{REQUEST_FILENAME} !-f',
2090 '%{REQUEST_FILENAME} !-d',
2092 rewrite_rule => [ '. /index.php [L]' ],
2100 ***Note*** If you include rewrites in your directories make sure you are also including `apache::mod::rewrite`. You may also want to consider setting the rewrites using the `rewrites` parameter in `apache::vhost` rather than setting the rewrites in the vhost directories.
2102 ######`shib_request_setting`
2104 Allows an valid content setting to be set or altered for the application request. This command takes two parameters, the name of the content setting, and the value to set it to.Check the Shibboleth [content setting documentation](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPContentSettings) for valid settings. This key is disabled if `apache::mod::shib` is not defined. Check the [`mod_shib` documentation](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-Server/VirtualHostOptions) for more details.
2107 apache::vhost { 'secure.example.net':
2108 docroot => '/path/to/directory',
2110 { path => '/path/to/directory',
2111 shib_require_setting => 'requiresession 1',
2112 shib_use_headers => 'On',
2118 ######`shib_use_headers`
2120 When set to 'On' this turns on the use of request headers to publish attributes to applications. Valid values for this key is 'On' or 'Off', and the default value is 'Off'. This key is disabled if `apache::mod::shib` is not defined. Check the [`mod_shib` documentation](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-Server/VirtualHostOptions) for more details.
2124 String or list of [SSLOptions](https://httpd.apache.org/docs/current/mod/mod_ssl.html#ssloptions), which configure SSL engine run-time options. This handler takes precedence over SSLOptions set in the parent block of the vhost.
2127 apache::vhost { 'secure.example.net':
2128 docroot => '/path/to/directory',
2130 { path => '/path/to/directory',
2131 ssl_options => '+ExportCertData',
2133 { path => '/path/to/different/dir',
2134 ssl_options => [ '-StdEnvVars', '+ExportCertData'],
2142 A hash containing the 'user' and 'group' keys for the [suPHP_UserGroup](http://www.suphp.org/DocumentationView.html?file=apache/CONFIG) setting. It must be used with `suphp_engine => on` in the vhost declaration, and can only be passed within `directories`.
2145 apache::vhost { 'secure.example.net':
2146 docroot => '/path/to/directory',
2148 { path => '/path/to/directory',
2150 { user => 'myappuser',
2151 group => 'myappgroup',
2158 ####SSL parameters for `apache::vhost`
2160 All of the SSL parameters for `::vhost` default to whatever is set in the base `apache` class. Use the below parameters to tweak individual SSL settings for specific vhosts.
2164 Enables SSL for the virtual host. SSL vhosts only respond to HTTPS queries. Valid values are 'true' or 'false'. Defaults to 'false'.
2168 Specifies the SSL certificate authority. Defaults to 'undef'.
2172 Specifies the SSL certification. Defaults are based on your OS: '/etc/pki/tls/certs/localhost.crt' for RedHat, '/etc/ssl/certs/ssl-cert-snakeoil.pem' for Debian, '/usr/local/etc/apache22/server.crt' for FreeBSD, and '/etc/ssl/apache2/server.crt' on Gentoo.
2176 Specifies [SSLProtocol](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol). Expects an array of accepted protocols. Defaults to 'all', '-SSLv2', '-SSLv3'.
2180 Specifies [SSLCipherSuite](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslciphersuite). Defaults to 'HIGH:MEDIUM:!aNULL:!MD5'.
2182 #####`ssl_honorcipherorder`
2184 Sets [SSLHonorCipherOrder](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslhonorcipherorder), which is used to prefer the server's cipher preference order. Defaults to 'On' in the base `apache` config.
2186 #####`ssl_certs_dir`
2188 Specifies the location of the SSL certification directory. Defaults to '/etc/ssl/certs' on Debian, '/etc/pki/tls/certs' on RedHat, '/usr/local/etc/apache22' on FreeBSD, and '/etc/ssl/apache2' on Gentoo.
2192 Specifies the SSL chain. Defaults to 'undef'. (This default works out of the box, but it must be updated in the base `apache` class with your specific certificate information before being used in production.)
2196 Specifies the certificate revocation list to use. Defaults to 'undef'. (This default works out of the box but must be updated in the base `apache` class with your specific certificate information before being used in production.)
2200 Specifies the location of the certificate revocation list. Defaults to 'undef'. (This default works out of the box but must be updated in the base `apache` class with your specific certificate information before being used in production.)
2202 #####`ssl_crl_check`
2204 Sets the certificate revocation check level via the [SSLCARevocationCheck directive](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcarevocationcheck), defaults to 'undef'. This default works out of the box but must be specified when using CRLs in production. Only applicable to Apache 2.4 or higher; the value is ignored on older versions.
2208 Specifies the SSL key. Defaults are based on your operating system: '/etc/pki/tls/private/localhost.key' for RedHat, '/etc/ssl/private/ssl-cert-snakeoil.key' for Debian, '/usr/local/etc/apache22/server.key' for FreeBSD, and '/etc/ssl/apache2/server.key' on Gentoo. (This default works out of the box but must be updated in the base `apache` class with your specific certificate information before being used in production.)
2210 #####`ssl_verify_client`
2212 Sets the [SSLVerifyClient](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslverifyclient) directive, which sets the certificate verification level for client authentication. Valid values are: 'none', 'optional', 'require', and 'optional_no_ca'. Defaults to 'undef'.
2215 apache::vhost { 'sample.example.net':
2217 ssl_verify_client => 'optional',
2221 #####`ssl_verify_depth`
2223 Sets the [SSLVerifyDepth](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslverifydepth) directive, which specifies the maximum depth of CA certificates in client certificate verification. Defaults to 'undef'.
2226 apache::vhost { 'sample.example.net':
2228 ssl_verify_depth => 1,
2234 Sets the [SSLOptions](http://httpd.apache.org/docs/current/mod/mod_ssl.html#ssloptions) directive, which configures various SSL engine run-time options. This is the global setting for the given vhost and can be a string or an array. Defaults to 'undef'.
2239 apache::vhost { 'sample.example.net':
2241 ssl_options => '+ExportCertData',
2248 apache::vhost { 'sample.example.net':
2250 ssl_options => [ '+StrictRequire', '+ExportCertData' ],
2254 #####`ssl_proxyengine`
2256 Specifies whether or not to use [SSLProxyEngine](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxyengine). Valid values are 'true' and 'false'. Defaults to 'false'.
2258 ####Defined Type: FastCGI Server
2260 This type is intended for use with mod_fastcgi. It allows you to define one or more external FastCGI servers to handle specific file types.
2265 apache::fastcgi::server { 'php':
2266 host => '127.0.0.1:9000',
2269 faux_path => '/var/www/php.fcgi',
2270 fcgi_alias => '/php.fcgi',
2271 file_type => 'application/x-httpd-php'
2275 Within your virtual host, you can then configure the specified file type to be handled by the fastcgi server specified above.
2278 apache::vhost { 'www':
2280 custom_fragment => 'AddType application/x-httpd-php .php'
2287 The hostname or IP address and TCP port number (1-65535) of the FastCGI server.
2291 The number of seconds of FastCGI application inactivity allowed before the request is aborted and the event is logged (at the error LogLevel). The inactivity timer applies only as long as a connection is pending with the FastCGI application. If a request is queued to an application, but the application doesn't respond (by writing and flushing) within this period, the request is aborted. If communication is complete with the application but incomplete with the client (the response is buffered), the timeout does not apply.
2295 Force a write to the client as data is received from the application. By default, mod_fastcgi buffers data in order to free the application as quickly as possible.
2299 `faux_path` does not have to exist in the local filesystem. URIs that Apache resolves to this filename are handled by this external FastCGI application.
2303 A unique alias. This is used internally to link the action with the FastCGI server.
2307 The MIME-type of the file to be processed by the FastCGI server.
2309 ###Virtual Host Examples
2311 The apache module allows you to set up pretty much any configuration of virtual host you might need. This section addresses some common configurations, but look at the [Tests section](https://github.com/puppetlabs/puppetlabs-apache/tree/master/tests) for even more examples.
2313 Configure a vhost with a server administrator
2316 apache::vhost { 'third.example.com':
2318 docroot => '/var/www/third',
2319 serveradmin => 'admin@example.com',
2325 Set up a vhost with aliased servers
2328 apache::vhost { 'sixth.example.com':
2330 'sixth.example.org',
2331 'sixth.example.net',
2334 docroot => '/var/www/fifth',
2340 Configure a vhost with a cgi-bin
2343 apache::vhost { 'eleventh.example.com':
2345 docroot => '/var/www/eleventh',
2346 scriptalias => '/usr/lib/cgi-bin',
2352 Set up a vhost with a rack configuration
2355 apache::vhost { 'fifteenth.example.com':
2357 docroot => '/var/www/fifteenth',
2358 rack_base_uris => ['/rackapp1', '/rackapp2'],
2364 Set up a mix of SSL and non-SSL vhosts at the same domain
2368 apache::vhost { 'first.example.com non-ssl':
2369 servername => 'first.example.com',
2371 docroot => '/var/www/first',
2374 #The SSL vhost at the same domain
2375 apache::vhost { 'first.example.com ssl':
2376 servername => 'first.example.com',
2378 docroot => '/var/www/first',
2385 Configure a vhost to redirect non-SSL connections to SSL
2388 apache::vhost { 'sixteenth.example.com non-ssl':
2389 servername => 'sixteenth.example.com',
2391 docroot => '/var/www/sixteenth',
2392 redirect_status => 'permanent',
2393 redirect_dest => 'https://sixteenth.example.com/'
2395 apache::vhost { 'sixteenth.example.com ssl':
2396 servername => 'sixteenth.example.com',
2398 docroot => '/var/www/sixteenth',
2405 Set up IP-based vhosts on any listen port and have them respond to requests on specific IP addresses. In this example, we set listening on ports 80 and 81. This is required because the example vhosts are not declared with a port parameter.
2408 apache::listen { '80': }
2409 apache::listen { '81': }
2412 Then we set up the IP-based vhosts
2415 apache::vhost { 'first.example.com':
2417 docroot => '/var/www/first',
2420 apache::vhost { 'second.example.com':
2422 docroot => '/var/www/second',
2429 Configure a mix of name-based and IP-based vhosts. First, we add two IP-based vhosts on 10.0.0.10, one SSL and one non-SSL
2432 apache::vhost { 'The first IP-based vhost, non-ssl':
2433 servername => 'first.example.com',
2437 docroot => '/var/www/first',
2439 apache::vhost { 'The first IP-based vhost, ssl':
2440 servername => 'first.example.com',
2444 docroot => '/var/www/first-ssl',
2449 Then, we add two name-based vhosts listening on 10.0.0.20
2452 apache::vhost { 'second.example.com':
2455 docroot => '/var/www/second',
2457 apache::vhost { 'third.example.com':
2460 docroot => '/var/www/third',
2464 If you want to add two name-based vhosts so that they answer on either 10.0.0.10 or 10.0.0.20, you **MUST** declare `add_listen => 'false'` to disable the otherwise automatic 'Listen 80', as it conflicts with the preceding IP-based vhosts.
2467 apache::vhost { 'fourth.example.com':
2469 docroot => '/var/www/fourth',
2470 add_listen => false,
2472 apache::vhost { 'fifth.example.com':
2474 docroot => '/var/www/fifth',
2475 add_listen => false,
2481 ####Defined Type: `apache::balancer`
2483 `apache::balancer` creates an Apache balancer cluster. Each balancer cluster needs one or more balancer members, which are declared with [`apache::balancermember`](#defined-type-apachebalancermember).
2485 One `apache::balancer` defined resource should be defined for each Apache load balanced set of servers. The `apache::balancermember` resources for all balancer members can be exported and collected on a single Apache load balancer server using exported resources.
2487 **Parameters within `apache::balancer`:**
2491 Sets the balancer cluster's title. This parameter also sets the title of the conf.d file.
2495 Configures key-value pairs as [ProxySet](http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxyset) lines. Accepts a hash, and defaults to '{}'.
2497 #####`collect_exported`
2499 Determines whether or not to use exported resources. Valid values 'true' and 'false', defaults to 'true'.
2501 If you statically declare all of your backend servers, you should set this to 'false' to rely on existing declared balancer member resources. Also make sure to use `apache::balancermember` with array arguments.
2503 If you wish to dynamically declare your backend servers via [exported resources](http://docs.puppetlabs.com/guides/exported_resources.html) collected on a central node, you must set this parameter to 'true' in order to collect the exported balancer member resources that were exported by the balancer member nodes.
2505 If you choose not to use exported resources, all balancer members will be configured in a single Puppet run. If you are using exported resources, Puppet has to run on the balanced nodes, then run on the balancer.
2507 ####Defined Type: `apache::balancermember`
2509 Defines members of [mod_proxy_balancer](http://httpd.apache.org/docs/current/mod/mod_proxy_balancer.html), which sets up a balancer member inside a listening service configuration block in etc/apache/apache.cfg on the load balancer.
2511 **Parameters within `apache::balancermember`:**
2515 Sets the title of the resource. This name also sets the name of the concat fragment.
2517 #####`balancer_cluster`
2519 Sets the Apache service's instance name. This must match the name of a declared `apache::balancer` resource. Required.
2523 Specifies the URL used to contact the balancer member server. Defaults to 'http://${::fqdn}/'.
2527 An array of [options](http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#balancermember) to be specified after the URL. Accepts any key-value pairs available to [ProxyPass](http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass).
2531 To load balance with exported resources, export the `balancermember` from the balancer member
2534 @@apache::balancermember { "${::fqdn}-puppet00":
2535 balancer_cluster => 'puppet00',
2536 url => "ajp://${::fqdn}:8009"
2537 options => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],
2541 Then, on the proxy server, create the balancer cluster
2544 apache::balancer { 'puppet00': }
2547 To load balance without exported resources, declare the following on the proxy
2550 apache::balancer { 'puppet00': }
2551 apache::balancermember { "${::fqdn}-puppet00":
2552 balancer_cluster => 'puppet00',
2553 url => "ajp://${::fqdn}:8009"
2554 options => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],
2558 Then declare `apache::balancer` and `apache::balancermember` on the proxy server.
2560 If you need to use ProxySet in the balancer config
2563 apache::balancer { 'puppet01':
2564 proxy_set => {'stickysession' => 'JSESSIONID'},
2574 * [`apache`](#class-apache): Guides the basic setup of Apache.
2575 * `apache::dev`: Installs Apache development libraries. (*Note:* On FreeBSD, you must declare `apache::package` or `apache` before `apache::dev`.)
2576 * [`apache::mod::[name]`](#classes-apachemodname): Enables specific Apache HTTPD modules.
2580 * `apache::confd::no_accf`: Creates the no-accf.conf configuration file in conf.d, required by FreeBSD's Apache 2.4.
2581 * `apache::default_confd_files`: Includes conf.d files for FreeBSD.
2582 * `apache::default_mods`: Installs the Apache modules required to run the default configuration.
2583 * `apache::package`: Installs and configures basic Apache packages.
2584 * `apache::params`: Manages Apache parameters.
2585 * `apache::service`: Manages the Apache daemon.
2589 ####Public Defined Types
2591 * `apache::balancer`: Creates an Apache balancer cluster.
2592 * `apache::balancermember`: Defines members of [mod_proxy_balancer](http://httpd.apache.org/docs/current/mod/mod_proxy_balancer.html).
2593 * `apache::listen`: Based on the title, controls which ports Apache binds to for listening. Adds [Listen](http://httpd.apache.org/docs/current/bind.html) directives to ports.conf in the Apache HTTPD configuration directory. Titles take the form '<port>', '<ipv4>:<port>', or '<ipv6>:<port>'.
2594 * `apache::mod`: Used to enable arbitrary Apache HTTPD modules for which there is no specific `apache::mod::[name]` class.
2595 * `apache::namevirtualhost`: Enables name-based hosting of a virtual host. Adds all [NameVirtualHost](http://httpd.apache.org/docs/current/vhosts/name-based.html) directives to the `ports.conf` file in the Apache HTTPD configuration directory. Titles take the form '\*', '*:<port>', '\_default_:<port>, '<ip>', or '<ip>:<port>'.
2596 * `apache::vhost`: Allows specialized configurations for virtual hosts that have requirements outside the defaults.
2598 ####Private Defined Types
2600 * `apache::peruser::multiplexer`: Enables the [Peruser](http://www.freebsd.org/cgi/url.cgi?ports/www/apache22-peruser-mpm/pkg-descr) module for FreeBSD only.
2601 * `apache::peruser::processor`: Enables the [Peruser](http://www.freebsd.org/cgi/url.cgi?ports/www/apache22-peruser-mpm/pkg-descr) module for FreeBSD only.
2602 * `apache::security::file_link`: Links the activated_rules from apache::mod::security to the respective CRS rules on disk.
2606 The Apache module relies heavily on templates to enable the `vhost` and `apache::mod` defined types. These templates are built based on Facter facts around your operating system. Unless explicitly called out, most templates are not meant for configuration.
2612 The `apache::vhost::WSGIImportScript` parameter creates a statement inside the VirtualHost which is unsupported on older versions of Apache, causing this to fail. This will be remedied in a future refactoring.
2616 The `apache::mod::passenger` and `apache::mod::proxy_html` classes are untested since repositories are missing compatible packages.
2620 The `apache::mod::passenger` class is untested as the repository does not have packages for EL7 yet. The fact that passenger packages aren't available also makes us unable to test the `rack_base_uri` parameter in `apache::vhost`.
2624 This module is CI tested on Centos 5 & 6, Ubuntu 12.04 & 14.04, Debian 7, and RHEL 5, 6 & 7 platforms against both the OSS and Enterprise version of Puppet.
2626 The module contains support for other distributions and operating systems, such as FreeBSD, Gentoo and Amazon Linux, but is not formally tested on those and regressions can occur.
2628 ###SELinux and Custom Paths
2630 If you are running with SELinux in enforcing mode and want to use custom paths for your `logroot`, `mod_dir`, `vhost_dir`, and `docroot`, you need to manage the context for the files yourself.
2632 Something along the lines of:
2635 exec { 'set_apache_defaults':
2636 command => 'semanage fcontext -a -t httpd_sys_content_t "/custom/path(/.*)?"',
2637 path => '/bin:/usr/bin/:/sbin:/usr/sbin',
2638 require => Package['policycoreutils-python'],
2640 package { 'policycoreutils-python': ensure => installed }
2641 exec { 'restorecon_apache':
2642 command => 'restorecon -Rv /apache_spec',
2643 path => '/bin:/usr/bin/:/sbin:/usr/sbin',
2644 before => Class['Apache::Service'],
2645 require => Class['apache'],
2648 host { 'test.server': ip => '127.0.0.1' }
2649 file { '/custom/path': ensure => directory, }
2650 file { '/custom/path/include': ensure => present, content => '#additional_includes' }
2651 apache::vhost { 'test.server':
2652 docroot => '/custom/path',
2653 additional_includes => '/custom/path/include',
2657 You need to set the contexts using `semanage fcontext` not `chcon` because `file {...}` resources reset the context to the values in the database if the resource isn't specifying the context.
2661 In order to use this module on FreeBSD, you *must* use apache24-2.4.12 (www/apache24) or newer.
2667 Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
2669 We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
2671 Read the complete module [contribution guide](https://docs.puppetlabs.com/forge/contributing.html)
2675 This project contains tests for both [rspec-puppet](http://rspec-puppet.com/) and [beaker-rspec](https://github.com/puppetlabs/beaker-rspec) to verify functionality. For in-depth information please see their respective documentation.
2684 bundle exec rake spec
2685 bundle exec rspec spec/acceptance
2686 RS_DEBUG=yes bundle exec rspec spec/acceptance
2693 bundle install --without system_tests
2694 bundle exec rake spec