Tosetupavirtualhostwithawildcardaliasforthesubdomainmappedtoadirectoryofthesamename,suchas'http://example.com.loc' mapped to `/var/www/example.com`, define the wildcard alias using the [`serveraliases`][] parameter and the document root with the [`virtual_docroot`][] parameter:
Tousethe[ProxySet](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxyset) directive on the balancer, use the [`proxy_set`](#proxy_set) parameter of `apache::balancer`:
Thebestsourceforunderstandingthe`mod_jk`parametersisthe[officialdocumentation](https://tomcat.apache.org/connectors-doc/reference/apache.html), except for \*file_content:
Installs and manages [`mod_passenger`][]. For Red Hat-based systems, ensure that you meet the minimum requirements described in the [passenger docs](https://www.phusionpassenger.com/library/install/apache/install/oss/el6/#step-1:-upgrade-your-kernel,-or-disable-selinux).
The current set of server configurations settings were taking directly from the [`Passenger Reference`](https://www.phusionpassenger.com/library/config/apache/reference/). Deprecation warning and removal failure messages can be enabled by setting the passenger_installed_version to
|rack_auto_detect|undef|RackAutoDetect|These options have been removed in version 4.0.0 as part of an optimization. You should use PassengerEnabled instead.|
|rack_autodetect|undef|n/a|see rack_auto_detect|
|rack_base_uri|undef|RackBaseURI|Deprecated in 3.0.0 in favor of PassengerBaseURI.|
|rails_allow_mod_rewrite|undef|RailsAllowModRewrite|This option doesn't do anything anymore in since version 4.0.0.|
|rails_app_spawner_idle_time|undef|RailsAppSpawnerIdleTime|This option has been removed in version 4.0.0, and replaced with PassengerMaxPreloaderIdleTime.|
|rails_auto_detect|undef|RailsAutoDetect|These options have been removed in version 4.0.0 as part of an optimization. You should use PassengerEnabled instead.|
|rails_framework_spawner_idle_time|undef|RailsFrameworkSpawnerIdleTime|This option is no longer available in version 4.0.0. There is no alternative because framework spawning has been removed altogether. You should use smart spawning instead.|
|rails_ruby|undef|RailsRuby|Deprecated in 3.0.0 in favor of PassengerRuby.|
|rails_spawn_method|undef|RailsSpawnMethod|Deprecated in 3.0.0 in favor of PassengerSpawnMethod.|
|rails_user_switching|undef|RailsUserSwitching|Deprecated in 3.0.0 in favor of PassengerUserSwitching.|
|wsgi_auto_detect|undef|WsgiAutoDetect|These options have been removed in version 4.0.0 as part of an optimization. You should use PassengerEnabled instead.|
##### Class: `apache::mod::ldap`
Installs and configures [`mod_ldap`][], and allows you to modify the
* `apache_version`: Specifies the installed Apache version.
Default: `undef`.
* `ldap_trusted_global_cert_file`: Specifies the path and file name of the trusted CA certificates to use when establishing SSL or TLS connections to an LDAP server.
* `ldap_trusted_global_cert_type`: Specifies the global trust certificate format.
Default: 'CA_BASE64'.
* `ldap_shared_cache_size`: Specifies the size, in bytes, of the shared memory cache.
* `ldap_cache_entries`: Specifies the maximum number of entries in the primary LDAP cache.
* `ldap_cache_ttl`: Specifies the time, in seconds, that cached items remain valid.
* `ldap_opcache_entries`: Specifies the number of entries used to cache LDAP compare operations.
* `ldap_opcache_ttl`: Specifies the time, in seconds, that entries in the operation cache remain valid.
* `package_name`: Specifies the custom package name.
Default: `undef`.
##### Class: `apache::mod::negotiation`
Installs and configures [`mod_negotiation`][].
**Parameters**:
* `force_language_priority`: Sets the `ForceLanguagePriority` option.
Values: A string.
Default: `Prefer Fallback`.
* `language_priority`: An [array][] of languages to set the `LanguagePriority` option of the module.
An SSL provider for Apache using the NSS crypto libraries.
**Parameters:**
- `transfer_log`: path to access.log
- `error_log`: path to error.log
- `passwd_file`: path to file used for NSSPassPhraseDialog directive
- `port`: SSL port. Defaults to 8443
##### Class: `apache::mod::pagespeed`
Installs and manages [`mod_pagespeed`][], a Google module that rewrites web pages to reduce latency and bandwidth.
Although this apache module requires the `mod-pagespeed-stable` package, Puppet **does not** manage the software repositories required to automatically install the package. If you declare this class when the package is either not installed or not available to your package manager, your Puppet run will fail.
> **Note:** Verify that your system is compatible with the latest Google Pagespeed requirements.
**Parameters**:
These parameters correspond to the module's directives. See the [module's documentation][`mod_pagespeed`] for details.
* `additional_configuration`: A hash of directive value pairs, or an array of lines to insert at the end of the pagespeed configuration. Default: '{ }'.
##### Class: `apache::mod::passenger`
Installs and configures `mod_passenger`.
>**Note**: The passenger module isn't available on RH/CentOS without providing the dependency packages provided by EPEL and the `mod_passengers` custom repository. See the `manage_repo` parameter above and [https://www.phusionpassenger.com/library/install/apache/install/oss/el7/]()
**Parameters**: [TODO: parameters were not listed (except `manage_repo`), so I pulled them out of the manifest. I need to know what these parameters do and what their values can be OR a link that points external documentation for the parameter mapping (as with mod_pagespeed above) <!--see also MODULES-4745-->]
* `manage_repo`: Whether to manage the phusionpassenger.com repository. Default: `true`.
* `mod_package`: Default: `undef`.
* `mod_package_ensure`: Default: `undef`.
* `mod_lib`: Default: `undef`.
* `mod_lib_path`: Default: `undef`.
* `mod_id`: Default: `undef`.
* `mod_path`: Default: `undef`.
##### Class: `apache::mod::proxy`
Installs `mod_proxy` and uses the `proxy.conf.erb` template to generate its configuration.
**Parameters within `apache::mod::proxy`**:
TODO: What do these parameters do?
- `allow_from`: Default: `undef`.
- `apache_version`: Default: `undef`.
- `package_name`: Default: `undef`.
- `proxy_requests`: Default: 'Off'.
- `proxy_via`: Default: 'On'.
##### Class: `apache::mod::proxy_balancer`
Installs and manages [`mod_proxy_balancer`][], which provides load balancing.
**Parameters**:
* `manager`: Determines whether to enable balancer manager support.
Default: `false`.
* `manager_path`: The server location of the balancer manager.
Default: '/balancer*manager'.
* `allow_from`: An [array][] of IPv4 or IPv6 addresses that can access `/balancer*manager`.
Default: ['127.0.0.1','::1'].
* `apache_version`: Apache's version number as a string, such as '2.2' or '2.4'.
Default: the value of [`$::apache::apache_version`][`apache_version`]. On Apache 2.4 or greater, `mod_slotmem_shm` is loaded.
##### Class: `apache::mod::php`
Installs and configures [`mod_php`][].
**Parameters**:
Default values for these parameters depend on your operating system. Most of this class's parameters correspond to `mod_php` directives; see the [module's documentation][`mod_php`] for details.
* `package_name`: Names the package that installs `mod_php`.
* `path`: Defines the path to the `mod_php` shared object (`.so`) file.
* `source`: Defines the path to the default configuration. Values include a `puppet:///` path.
* `template`: Defines the path to the `php.conf` template Puppet uses to generate the configuration file.
* `content`: Adds arbitrary content to `php.conf`.
##### Class: `apache::mod::proxy_html`
**Note**: There is no official package available for `mod_proxy_html`, so you must make it available outside of the apache module.
##### Class: `apache::mod::reqtimeout`
Installs and configures [`mod_reqtimeout`][].
**Parameters**
* `timeouts`: Sets the [`RequestReadTimeout`][] option.
Installs and enables the Apache module `mod_rewrite`.
##### Class: `apache::mod::shib`
Installs the [Shibboleth](http://shibboleth.net/) Apache module `mod_shib`, which enables SAML2 single sign-on (SSO) authentication by Shibboleth Identity Providers and Shibboleth Federations. Defining this class enables Shibboleth-specific parameters in `apache::vhost` instances.
This class installs and configures only the Apache components of a web application that consumes Shibboleth SSO identities. You can manage the Shibboleth configuration manually, with Puppet, or using a [Shibboleth Puppet Module](https://github.com/aethylred/puppet-shibboleth).
**Note**: The shibboleth module isn't available on RH/CentOS without providing dependency packages provided by Shibboleth's repositories. See [http://wiki.aaf.edu.au/tech-info/sp-install-guide]()
##### Class: `apache::mod::ssl`
Installs [Apache SSL features][`mod_ssl`] and uses the `ssl.conf.erb` template to generate its configuration. On most operating systems, this `ssl.conf` is placed in the module configuration directory. On Red Hat-based operating systems, this file is placed in `/etc/httpd/conf.d`, the same location in which the RPM stores the configuration.
To use SSL with a virtual host, you must either set the [`default_ssl_vhost`][] parameter in `::apache` to `true` **or** the [`ssl`][] parameter in [`apache::vhost`][] to `true`.
Installs [`mod_status`][] and uses the `status.conf.erb` template to generate its configuration.
**Parameters**:
* `allow_from`: An [array][] of IPv4 or IPv6 addresses that can access `/server-status`.
Default: ['127.0.0.1','::1'].
* `extended_status`: Determines whether to track extended status information for each request, via the [`ExtendedStatus`][] directive.
Values: 'Off', 'On'.
Default: 'On'.
* `status_path`: The server location of the status page.
Default: '/server-status'.
##### Class: `apache::mod::userdir`
Allows user-specific directories to be accessed using the `http://example.com/~user/` syntax. All parameters can be found in in the [official Apache documentation](https://httpd.apache.org/docs/2.4/mod/mod_userdir.html).
Installs [`mod_version`][] on many operating systems and Apache configurations.
If Debian and Ubuntu systems with Apache 2.4 are classified with `apache::mod::version`, Puppet warns that `mod_version` is built-in and can't be loaded.
##### Class: `apache::mod::security`
Installs and configures Trustwave's [`mod_security`][]. It is enabled and runs by default on all virtual hosts.
**Parameters**:
* `activated_rules`: An [array][] of rules from the `modsec_crs_path` or absolute to activate via symlinks.
* `allowed_methods`: A space*separated list of allowed HTTP methods.
Default: 'GET HEAD POST OPTIONS'.
* `content_types`: A list of one or more allowed [MIME types][MIME `content*type`].
* `secdefaultaction`: Configures the Mode of Operation, Self-Contained ('deny') or Collaborative Detection ('pass'), for the OWASP ModSecurity Core Rule Set.
Default: 'deny'. You can also set full values, such as "log,auditlog,deny,status:406,tag:'SLA 24/7'".
* `secpcrematchlimit`: Sets the number for the match limit in the PCRE library.
Default: 1500.
* `secpcrematchlimitrecursion`: Sets the number for the match limit recursion in the PCRE library.
Default: 1500.
* `logroot`: Configures the location of audit and debug logs.
Defaults to the Apache log directory (Redhat: `/var/log/httpd`, Debian: `/var/log/apache2`).
* `audit_log_releavant_status`: Configures which response status code is to be considered relevant for the purpose of audit logging.
Default: '^(?:5|4(?!04))'.
* `audit_log_parts`: Sets the sections to be put in the [audit log][].
Default: 'ABIJDEFHZ'.
* `anomaly_score_blocking`: Activates or deactivates the Collaborative Detection Blocking of the OWASP ModSecurity Core Rule Set.
Default: 'off'.
* `inbound_anomaly_threshold`: Sets the scoring threshold level of the inbound blocking rules for the Collaborative Detection Mode in the OWASP ModSecurity Core Rule Set.
Default: 5.
* `outbound_anomaly_threshold`: Sets the scoring threshold level of the outbound blocking rules for the Collaborative Detection Mode in the OWASP ModSecurity Core Rule Set.
Default: 4.
* `critical_anomaly_score`: Sets the scoring points of the critical severity level for the Collaborative Detection Mode in the OWASP ModSecurity Core Rule Set.
Default: 5.
* `error_anomaly_score`: Sets the scoring points of the error severity level for the Collaborative Detection Mode in the OWASP ModSecurity Core Rule Set.
Default: 4.
* `warning_anomaly_score`: Sets the scoring points of the warning severity level for the Collaborative Detection Mode in the OWASP ModSecurity Core Rule Set.
Default: 3.
* `notice_anomaly_score`: Sets the scoring points of the notice severity level for the Collaborative Detection Mode in the OWASP ModSecurity Core Rule Set.
Default: 2.
* `secrequestmaxnumargs`: Sets the Maximum number of arguments in the request.
Default: 255.
* `secrequestbodylimit`: Sets the maximum request body size ModSecurity accepts for buffering.
Default: '13107200'.
* `secrequestbodynofileslimit`: Sets the maximum request body size ModSecurity accepts for buffering, excluding the size of any files being transported in the request.
Default: '131072'.
* `secrequestbodyinmemorylimit`: Sets the maximum request body size that ModSecurity stores in memory.
Default: '131072'
##### Class: `apache::mod::wsgi`
Enables Python support via [`mod_wsgi`][].
**Parameters**:
* `mod_path`: Defines the path to the `mod_wsgi` shared object (`.so`) file.
Default: `undef`.
* If the `mod_path` parameter doesn't contain `/`, Puppet prefixes it with your operating system's default module path. Otherwise, Puppet follows it literally.
* `package_name`: Names the package that installs `mod_wsgi`.
Default: `undef`.
* `wsgi_python_home`: Defines the [`WSGIPythonHome`][] directive, such as '/path/to/venv'.
Values: A string specifying a path.
Default: `undef`.
* `wsgi_python_path`: Defines the [`WSGIPythonPath`][] directive, such as '/path/to/venv/site*packages'.
Values: A string specifying a path.
Default: `undef`.
* `wsgi_restrict_embedded`: Defines the [`WSGIRestrictEmbedded`][] directive, such as 'On'.
Values: On|Off|undef.
Default: undef.
* `wsgi_socket_prefix`: Defines the [`WSGISocketPrefix`][] directive, such as "\${APACHE\_RUN\_DIR}WSGI".
Default: `wsgi_socket_prefix` in [`apache::params`][].
The class's parameters correspond to the module's directives. See the [module's documentation][`mod_wsgi`] for details.
### Private Classes
#### Class: `apache::confd::no_accf`
Creates the `no-accf.conf` configuration file in `conf.d`, required by FreeBSD's Apache 2.4.
#### Class: `apache::default_confd_files`
Includes `conf.d` files for FreeBSD.
#### Class: `apache::default_mods`
Installs the Apache modules required to run the default configuration. See the `apache` class's [`default_mods`][] parameter for details.
#### Class: `apache::package`
Installs and configures basic Apache packages.
#### Class: `apache::params`
Manages Apache parameters for different operating systems.
#### Class: `apache::service`
Manages the Apache daemon.
#### Class: `apache::version`
Attempts to automatically detect the Apache version based on the operating system.
### Public defined types
#### Defined type: `apache::balancer`
Creates an Apache load balancing group, also known as a balancer cluster, using [`mod_proxy`][]. Each load balancing group needs one or more balancer members, which you can declare in Puppet with the [`apache::balancermember`][] defined type.
Declare one `apache::balancer` defined type for each Apache load balancing group. You can export `apache::balancermember` defined types for all balancer members and collect them on a single Apache load balancer server using [exported resources][].
**Parameters**:
##### `name`
Sets the title of the balancer cluster and name of the `conf.d` file containing its configuration.
##### `proxy_set`
Configures key-value pairs as [`ProxySet`][] lines. Values: a [hash][].
Default: '{}'.
##### `collect_exported`
Determines whether to use [exported resources][].
If you statically declare all of your backend servers, set this parameter to `false` to rely on existing, declared balancer member resources. Also, use `apache::balancermember` with [array][] arguments.
To dynamically declare backend servers via exported resources collected on a central node, set this parameter to `true` to collect the balancer member resources exported by the balancer member nodes.
If you don't use exported resources, a single Puppet run configures all balancer members. If you use exported resources, Puppet has to run on the balanced nodes first, then run on the balancer.
Boolean.
Default: `true`.
#### Defined type: `apache::balancermember`
Defines members of [`mod_proxy_balancer`][], which sets up a balancer member inside a listening service configuration block in the load balancer's `apache.cfg`.
**Parameters**:
##### `balancer_cluster`
**Required**.
Sets the Apache service's instance name, and must match the name of a declared [`apache::balancer`][] resource.
##### `url`
Specifies the URL used to contact the balancer member server.
Default: 'http://${::fqdn}/'.
##### `options`
Specifies an [array][] of [options](https://httpd.apache.org/docs/current/mod/mod_proxy.html#balancermember) after the URL, and accepts any key-value pairs available to [`ProxyPass`][].
Default: an empty array.
#### Defined type: `apache::custom_config`
Adds a custom configuration file to the Apache server's `conf.d` directory. If the file is invalid and this defined type's [`verify_config`][] parameter's value is `true`, Puppet throws an error during a Puppet run.
**Parameters**:
##### `ensure`
Specifies whether the configuration file should be present.
Values: 'absent', 'present'.
Default: 'present'.
##### `confdir`
Sets the directory in which Puppet places configuration files.
Default: the value of [`$::apache::confd_dir`][`confd_dir`].
##### `content`
Sets the configuration file's content. The `content` and [`source`][] parameters are exclusive of each other.
Default: `undef`
##### `filename`
Sets the name of the file under `confdir` in which Puppet stores the configuration.
Default: Filename generated from the `priority` parameter and the resource name.
##### `priority`
Sets the configuration file's priority by prefixing its filename with this parameter's numeric value, as Apache processes configuration files in alphanumeric order.
To omit the priority prefix in the configuration file's name, set this parameter to `false`.
Default: '25'.
##### `source`
Points to the configuration file's source. The [`content`][] and `source` parameters are exclusive of each other. TODO: is this required or does it have a default value?
Default: `undef`
##### `verify_command`
Specifies the command Puppet uses to verify the configuration file. Use a fully qualified command.
This parameter is used only if the [`verify_config`][] parameter's value is `true`. If the `verify_command` fails, the Puppet run deletes the configuration file and raises an error, but does not notify the Apache service.
Default: '/usr/sbin/apachectl -t'.
##### `verify_config`
Specifies whether to validate the configuration file before notifying the Apache service.
Boolean.
Default: `true`.
#### Defined type: `apache::fastcgi::server`
Defines one or more external FastCGI servers to handle specific file types. Use this defined type with [`mod_fastcgi`][FastCGI].
**Parameters**
##### `host`
Determines the FastCGI's hostname or IP address and TCP port number (1-65535).
Default: '127.0.0.1:9000'.
##### `timeout`
Sets the number of seconds a [FastCGI][] application can be inactive before aborting the request and logging the event 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.
Default: 15.
##### `flush`
Forces [`mod_fastcgi`][FastCGI] to 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.
Default: `false`.
##### `faux_path`
Apache has [FastCGI][] handle URIs that resolve to this filename. The path set in this parameter does not have to exist in the local filesystem.
Default: "/var/www/${name}.fcgi".
##### `alias`
Internally links actions with the FastCGI server. This alias must be unique.
Default: "/${name}.fcgi".
##### `file_type`
Sets the [MIME `content-type`][] of the file to be processed by the FastCGI server.
Default: 'application/x-httpd-php'.
#### Defined type: `apache::listen`
Adds [`Listen`][] directives to `ports.conf` in the Apache configuration directory that define the Apache server's or a virtual host's listening address and port. The [`apache::vhost`][] class uses this defined type, and titles take the form `<PORT>`, `<IPV4>:<PORT>`, or `<IPV6>:<PORT>`.
#### Defined type: `apache::mod`
Installs packages for an Apache module that doesn't have a corresponding [`apache::mod::<MODULE NAME>`][] class, and checks for or places the module's default configuration files in the Apache server's `module` and `enable` directories. The default locations depend on your operating system.
**Parameters**:
##### `package`
**Required**.
Names the package Puppet uses to install the Apache module.
Default: `undef`.
##### `package_ensure`
Determines whether Puppet ensures the Apache module should be installed.
Values: 'absent', 'present'.
Default: 'present'.
##### `lib`
Defines the module's shared object name. Do not configure manually without special reason.
Default: `mod_$name.so`.
##### `lib_path`
Specifies a path to the module's libraries. Do not manually set this parameter without special reason. The [`path`][] parameter overrides this value.
Default: The `apache` class's [`lib_path`][] parameter.
##### `loadfile_name`
Sets the filename for the module's [`LoadFile`][] directive, which can also set the module load order as Apache processes them in alphanumeric order.
Values: Filenames formatted `\*.load`.
Default: the resource's name followed by 'load', as in '$name.load'.
##### `loadfiles`
Specifies an array of [`LoadFile`][] directives.
Default: `undef`.
##### `path`
Specifies a path to the module. Do not manually set this parameter without a special reason.
Default: [`lib_path`][]/[`lib`][].
#### Defined type: `apache::namevirtualhost`
Enables [name-based virtual hosts][] and adds all related directives to the `ports.conf` file in the Apache HTTPD configuration directory. Titles can take the forms '\*', '\*:\<PORT\>', '\_default\_:\<PORT\>, '\<IP\>', or '\<IP\>:\<PORT\>'.
#### Defined type: `apache::vhost`
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 Apache to evaluate it multiple times with different parameters.
The `apache::vhost` defined type allows you to have specialized configurations for virtual hosts that have requirements outside the defaults. You can set up a default virtual host within the base `::apache` class, as well as set a customized virtual host as the default. Customized virtual hosts have a lower numeric [`priority`][] than the base class's, causing Apache to process the customized virtual host first.
The `apache::vhost` defined type uses `concat::fragment` to build the configuration file. To inject custom fragments for pieces of the configuration that the defined type doesn't inherently support, add a custom fragment.
For the custom fragment's `order` parameter, the `apache::vhost` defined type uses multiples of 10, so any `order` that isn't a multiple of 10 should work.
**Parameters**:
##### `access_log`
Determines whether to configure `*_access.log` directives (`*_file`,`*_pipe`, or `*_syslog`).
Boolean.
Default: `true`.
##### `access_log_env_var`
Specifies that only requests with particular environment variables be logged.
Default: `undef`.
##### `access_log_file`
Sets the filename of the `*_access.log` placed in [`logroot`][]. Given a virtual host---for instance, example.com---it defaults to 'example.com_ssl.log' for [SSL-encrypted][SSL encryption] virtual hosts and 'example.com_access.log' for unencrypted virtual hosts.
Default: `false`.
##### `access_log_format`
Specifies the use of either a [`LogFormat`][] nickname or a custom-formatted string for the access log.
Default: 'combined'.
##### `access_log_pipe`
Specifies a pipe where Apache sends access log messages.
Default: `undef`.
##### `access_log_syslog`
Sends all access log messages to syslog.
Default: `undef`.
##### `add_default_charset`
Sets a default media charset value for the [`AddDefaultCharset`][] directive, which is added to `text/plain` and `text/html` responses.
Default: `undef`.
##### `add_listen`
Determines whether the virtual host creates a [`Listen`][] statement.
Setting `add_listen` to `false` prevents the virtual host from creating a `Listen` statement. This is important when combining virtual hosts that aren't passed an `ip` parameter with those that are.
Boolean.
Default: `true`.
##### `use_optional_includes`
Specifies whether Apache uses the [`IncludeOptional`][] directive instead of [`Include`][] for `additional_includes` in Apache 2.4 or newer.
Boolean.
Default: `false`.
##### `additional_includes`
Specifies paths to additional static, virtual host-specific Apache configuration files. You can use this parameter to implement a unique, custom configuration not supported by this module.
Values: a string or [array][] of strings specifying paths.
Default: an empty array.
##### `aliases`
Passes a list of [hashes][hash] to the virtual host to create [`Alias`][], [`AliasMatch`][], [`ScriptAlias`][] or [`ScriptAliasMatch`][] directives as per the [`mod_alias`][] documentation.
For example:
``` puppet
aliases => [
{ aliasmatch => '^/image/(.*)\.jpg$',
path => '/files/jpg.images/$1.jpg',
},
{ alias => '/image',
path => '/ftp/pub/image',
},
{ scriptaliasmatch => '^/cgi-bin(.*)',
path => '/usr/local/share/cgi-bin$1',
},
{ scriptalias => '/nagios/cgi-bin/',
path => '/usr/lib/nagios/cgi-bin/',
},
{ alias => '/nagios',
path => '/usr/share/nagios/html',
},
],
```
For the `alias`, `aliasmatch`, `scriptalias` and `scriptaliasmatch` keys to work, each needs a corresponding context, such as `<Directory /path/to/directory>` or `<Location /some/location/here>`. Puppet creates the directives in the order specified in the `aliases` parameter. As described in the [`mod_alias`][] documentation, add more specific `alias`, `aliasmatch`, `scriptalias` or `scriptaliasmatch` parameters before the more general ones to avoid shadowing.
> **Note**: Use the `aliases` parameter instead of the `scriptaliases` parameter because you can precisely control the order of various alias directives. 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 often causes problems; for example, this could cause problems with Nagios.
If [`apache::mod::passenger`][] is loaded and `PassengerHighPerformance` is `true`, the `Alias` directive might not be able to honor the `PassengerEnabled => off` statement. See [this article](http://www.conandalton.net/2010/06/passengerenabled-off-not-working.html) for details.
##### `allow_encoded_slashes`
Sets the [`AllowEncodedSlashes`][] declaration for the virtual host, overriding the server default. This modifies the virtual host responses to URLs with `\` and `/` characters. Values: 'nodecode', 'off', 'on'. The default setting omits the declaration from the server configuration and selects the Apache default setting of 'Off'.
Default: `undef`
##### `block`
Specifies the list of things to which Apache blocks access. Valid option: 'scm', which blocks web access to `.svn`, `.git`, and `.bzr` directories.
Default: an empty [array][].
##### `cas_attribute_prefix`
Adds a header with the value of this header being the attribute values when SAML validation is enabled.
Defaults: The value set by [`apache::mod::auth_cas`][].
##### `cas_attribute_delimiter`
Sets the delimiter between attribute values in the header created by `cas_attribute_prefix`.
Default: The value set by [`apache::mod::auth_cas`][].
##### `cas_login_url`
Sets the URL to which the module redirects users when they attempt to access a CAS-protected resource and
don't have an active session.
Default: The value set by [`apache::mod::auth_cas`][].
##### `cas_scrub_request_headers`
Remove inbound request headers that may have special meaning within mod_auth_cas.
Default: The value set by [`apache::mod::auth_cas`][].
##### `cas_sso_enabled`
Enables experimental support for single sign out (may mangle POST data).
Default: The value set by [`apache::mod::auth_cas`][].
##### `cas_validate_saml`
Parse response from CAS server for SAML.
Default: The value set by [`apache::mod::auth_cas`][].
##### `cas_validate_url`
Sets the URL to use when validating a client-presented ticket in an HTTP query string.
Defaults to the value set by [`apache::mod::auth_cas`][].
##### `custom_fragment`
Passes a string of custom configuration directives to place at the end of the virtual host configuration.
Default: `undef`.
##### `default_vhost`
Sets a given `apache::vhost` defined type as the default to serve requests that do not match any other `apache::vhost` defined types.
Default: `false`.
##### `directories`
See the [`directories`](#parameter-directories-for-apachevhost) section.
##### `directoryindex`
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. See the [`DirectoryIndex`][] directive documentation for details.
Default: `undef`.
##### `docroot`
**Required**.
Sets the [`DocumentRoot`][] location, from which Apache serves files.
If `docroot` and [`manage_docroot`][] are both set to `false`, no [`DocumentRoot`][] will be set and the accompanying `<Directory /path/to/directory>` block will not be created.
Values: A string specifying a directory path.
##### `docroot_group`
Sets group access to the [`docroot`][] directory.
Values: A string specifying a system group.
Default: 'root'.
##### `docroot_owner`
Sets individual user access to the [`docroot`][] directory.
Values: A string specifying a user account.
Default: 'root'.
##### `docroot_mode`
Sets access permissions for the [`docroot`][] directory, in numeric notation.
Values: A string.
Default: `undef`.
##### `manage_docroot`
Determines whether Puppet manages the [`docroot`][] directory.
Boolean.
Default: `true`.
##### `error_log`
Specifies whether `*_error.log` directives should be configured.
Boolean.
Default: `true`.
##### `error_log_file`
Points the virtual host's error logs to a `*_error.log` file. If this parameter is undefined, Puppet checks for values in [`error_log_pipe`][], then [`error_log_syslog`][].
If none of these parameters is set, given a virtual host `example.com`, Puppet defaults to '$logroot/example.com_error_ssl.log' for SSL virtual hosts and '$logroot/example.com_error.log' for non-SSL virtual hosts.
Default: `undef`.
##### `error_log_pipe`
Specifies a pipe to send error log messages to.
This parameter has no effect if the [`error_log_file`][] parameter has a value. If neither this parameter nor `error_log_file` has a value, Puppet then checks [`error_log_syslog`][].
Default: `undef`.
##### `error_log_syslog`
Determines whether to send all error log messages to syslog.
This parameter has no effect if either of the [`error_log_file`][] or [`error_log_pipe`][] parameters has a value. If none of these parameters has a value, given a virtual host `example.com`, Puppet defaults to '$logroot/example.com_error_ssl.log' for SSL virtual hosts and '$logroot/example.com_error.log' for non-SSL virtual hosts.
Boolean.
Default: `undef`.
##### `error_documents`
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 virtual host.
Specifies if the virtual host is present or absent.
Values: 'absent', 'present'.
Default: 'present'.
##### `fallbackresource`
Sets the [FallbackResource](https://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)'. Values must either begin with a '/' or be 'disabled'.
Default: `undef`.
#####`fastcgi_idle_timeout`
If using fastcgi, this option sets the timeout for the server to respond.
Default: `undef`.
##### `file_e_tag`
Sets the server default for the [`FileETag`][] declaration, which modifies the response header field for static files.
Values: 'INode', 'MTime', 'Size', 'All', 'None'.
Default: `undef`, which uses Apache's default setting of 'MTime Size'.
##### `filters`
[Filters](https://httpd.apache.org/docs/current/mod/mod_filter.html) enable smart, context-sensitive configuration of output content filters.
Sets the [`ForceType`][] directive, which forces Apache to serve all matching files with a [MIME `content-type`][] matching this parameter's value.
#### `add_charset`
Lets Apache set custom content character sets per directory and/or file extension
##### `headers`
Adds lines to replace, merge, or remove response headers. See [Apache's mod_headers documentation](https://httpd.apache.org/docs/current/mod/mod_headers.html#header) for more information.
Values: A string or an array of strings.
Default: `undef`.
##### `ip`
Sets the IP address the virtual host listens on. By default, uses Apache's default behavior of listening on all IPs.
Values: A string or an array of strings.
Default: `undef`.
##### `ip_based`
Enables an [IP-based](https://httpd.apache.org/docs/current/vhosts/ip-based.html) virtual host. This parameter inhibits the creation of a NameVirtualHost directive, since those are used to funnel requests to name-based virtual hosts.
Default: `false`.
##### `itk`
Configures [ITK](http://mpm-itk.sesse.net/) in a hash.
Usage typically looks something like:
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
itk => {
user => 'someuser',
group => 'somegroup',
},
}
```
Values: a hash, which can include the keys:
* user + group
* `assignuseridexpr`
* `assigngroupidexpr`
* `maxclientvhost`
* `nice`
* `limituidrange` (Linux 3.5.0 or newer)
* `limitgidrange` (Linux 3.5.0 or newer)
Usage typically looks like:
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
itk => {
user => 'someuser',
group => 'somegroup',
},
}
```
Default: `undef`.
##### `jk_mounts`
Sets up a virtual host with 'JkMount' and 'JkUnMount' directives to handle the paths for URL mapping between Tomcat and Apache.
The parameter must be an array of hashes where each hash must contain the 'worker' and either the 'mount' or 'unmount' keys.
Usage typically looks like:
``` puppet
apache::vhost { 'sample.example.net':
jk_mounts => [
{ mount => '/*', worker => 'tcnode1', },
{ unmount => '/*.jpg', worker => 'tcnode1', },
],
}
```
Default: `undef`.
##### `keepalive`
Determines whether to enable persistent HTTP connections with the [`KeepAlive`][] directive for the virtual host. By default, the global, server-wide [`KeepAlive`][] setting is in effect.
Use the `keepalive_timeout` and `max_keepalive_requests` parameters to set relevant options for the virtual host.
Values: 'Off', 'On'.
Default: `undef`
##### `keepalive_timeout`
Sets the [`KeepAliveTimeout`] directive for the virtual host, which determines the amount of time to wait for subsequent requests on a persistent HTTP connection. By default, the global, server-wide [`KeepAlive`][] setting is in effect.
This parameter is only relevant if either the global, server-wide [`keepalive` parameter][] or the per-vhost `keepalive` parameter is enabled.
Default: `undef`
##### `max_keepalive_requests`
Limits the number of requests allowed per connection to the virtual host. By default, the global, server-wide [`KeepAlive`][] setting is in effect.
This parameter is only relevant if either the global, server-wide [`keepalive` parameter][] or the per-vhost `keepalive` parameter is enabled.
Default: `undef`.
##### `auth_kerb`
Enable [`mod_auth_kerb`][] parameters for a virtual host.
Usage typically looks like:
``` puppet
apache::vhost { 'sample.example.net':
auth_kerb => `true`,
krb_method_negotiate => 'on',
krb_auth_realms => ['EXAMPLE.ORG'],
krb_local_user_mapping => 'on',
directories => {
path => '/var/www/html',
auth_name => 'Kerberos Login',
auth_type => 'Kerberos',
auth_require => 'valid-user',
},
}
```
Related parameters follow the names of `mod_auth_kerb` directives:
- `krb_method_negotiate`: Determines whether to use the Negotiate method. Default: 'on'.
- `krb_method_k5passwd`: Determines whether to use password-based authentication for Kerberos v5. Default: 'on'.
- `krb_authoritative`: If set to 'off', authentication controls can be passed on to another module. Default: 'on'.
- `krb_auth_realms`: Specifies an array of Kerberos realms to use for authentication. Default: '[]'.
- `krb_local_user_mapping`: Strips @REALM from usernames for further use. Default: `undef`.
Boolean.
Default: `false`.
##### `krb_verify_kdc`
This option can be used to disable the verification tickets against local keytab to prevent KDC spoofing attacks.
Default: 'on'.
##### `krb_servicename`
Specifies the service name that will be used by Apache for authentication. Corresponding key of this name must be stored in the keytab.
Default: 'HTTP'.
##### `krb_save_credentials`
This option enables credential saving functionality.
Default is 'off'
##### `logroot`
Specifies the location of the virtual host's logfiles.
Default: '/var/log/<apache log location>/'.
##### `$logroot_ensure`
Determines whether or not to remove the logroot directory for a virtual host.
Values: 'directory', 'absent'.
Default: 'directory'.
##### `logroot_mode`
Overrides the mode the logroot directory is set to. Do *not* grant write access to the directory the logs are stored in without being aware of the consequences; for more information, see [Apache's log security documentation](https://httpd.apache.org/docs/2.4/logs.html#security).
Default: `undef`.
##### `logroot_owner`
Sets individual user access to the logroot directory.
Defaults to `undef`.
##### `logroot_group`
Sets group access to the [`logroot`][] directory.
Defaults to `undef`.
##### `log_level`
Specifies the verbosity of the error log.
Values: 'emerg', 'alert', 'crit', 'error', 'warn', 'notice', 'info' or 'debug'.
Default: 'warn' for the global server configuration. Can be overridden on a per-virtual host basis.
###### `modsec_body_limit`
Configures the maximum request body size (in bytes) ModSecurity accepts for buffering.
Values: An integer.
Default: `undef`.
###### `modsec_disable_vhost`
Disables [`mod_security`][] on a virtual host. Only valid if [`apache::mod::security`][] is included.
Boolean.
Default: `undef`.
###### `modsec_disable_ids`
Removes `mod_security` IDs from the virtual host.
Values: An array of `mod_security` IDs to remove from the virtual host. Also takes a hash allowing removal of an ID from a specific location.
These three parameters together determine how to send `mod_security` audit log ([SecAuditLog](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#SecAuditLog)).
* If `modsec_audit_log_file` is set, it is relative to [`logroot`][].
Default: `undef`.
* If `modsec_audit_log_pipe` is set, it should start with a pipe. Example '|/path/to/mlogc /path/to/mlogc.conf'.
Default: `undef`.
* If `modsec_audit_log` is `true`, given a virtual host---for instance, example.com---it defaults to 'example.com\_security\_ssl.log' for [SSL-encrypted][SSL encryption] virtual hosts and 'example.com\_security.log' for unencrypted virtual hosts.
Default: `false`.
If none of those parameters are set, the global audit log is used (''/var/log/httpd/modsec\_audit.log''; Debian and derivatives: ''/var/log/apache2/modsec\_audit.log''; others: ).
##### `no_proxy_uris`
Specifies URLs you do not want to proxy. This parameter is meant to be used in combination with [`proxy_dest`](#proxy_dest).
Default: [].
##### `no_proxy_uris_match`
This directive is equivalent to [`no_proxy_uris`][], but takes regular expressions.
Default: [].
##### `proxy_preserve_host`
Sets the [ProxyPreserveHost Directive](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypreservehost).
Setting this parameter to `true` enables the `Host:` line from an incoming request to be proxied to the host instead of hostname. Setting it to `false` sets this directive to 'Off'.
Boolean.
Default: `false`.
##### `proxy_add_headers`
Sets the [ProxyAddHeaders Directive](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxyaddheaders).
This parameter controlls whether proxy-related HTTP headers (X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server) get sent to the backend server.
Boolean.
Default: `false`.
##### `proxy_error_override`
Sets the [ProxyErrorOverride Directive](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxyerroroverride). This directive controls whether Apache should override error pages for proxied content.
Boolean.
Default: `false`.
##### `options`
Sets the [`Options`][] for the specified virtual host. For example:
> **Note**: If you use the [`directories`][] parameter of [`apache::vhost`][], 'Options', 'Override', and 'DirectoryIndex' are ignored because they are parameters within `directories`.
Sets the overrides for the specified virtual host. Accepts an array of [AllowOverride](https://httpd.apache.org/docs/current/mod/core.html#allowoverride) arguments.
Default: '[none]'.
##### `passenger_app_root`
Sets [PassengerRoot](https://www.phusionpassenger.com/library/config/apache/reference/#passengerapproot), the location of the Passenger application root if different from the DocumentRoot.
Values: A string specifying a path.
Default: `undef`.
##### `passenger_app_env`
Sets [PassengerAppEnv](https://www.phusionpassenger.com/library/config/apache/reference/#passengerappenv), the environment for the Passenger application. If not specified, defaults to the global setting or 'production'.
Values: A string specifying the name of the environment.
Default: `undef`.
##### `passenger_log_file`
By default, Passenger log messages are written to the Apache global error log. With [PassengerLogFile](https://www.phusionpassenger.com/library/config/apache/reference/#passengerlogfile), you can configure those messages to be logged to a different file. This option is only available since Passenger 5.0.5.
Values: A string specifying a path.
Default: `undef`.
##### `passenger_log_level`
This option allows to specify how much information should be written to the log file. If not set, [PassengerLogLevel](https://www.phusionpassenger.com/library/config/apache/reference/#passengerloglevel) will not show up in the configuration file and the defaults are used.
Default: Passenger versions less than 3.0.0: '0'; 5.0.0 and later: '3'.
##### `passenger_ruby`
Sets [PassengerRuby](https://www.phusionpassenger.com/library/config/apache/reference/#passengerruby), the Ruby interpreter to use for the application, on this virtual host.
Default: `undef`.
##### `passenger_min_instances`
Sets [PassengerMinInstances](https://www.phusionpassenger.com/library/config/apache/reference/#passengermininstances), the minimum number of application processes to run.
sengermaxrequests), the maximum number of requests an application process will process.
##### `passenger_max_instances_per_app`
Sets [PassengerMaxInstancesPerApp](https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxinstancesperapp), the maximum number of application processes that may simultaneously exist for a single application.
Default: `undef`.
##### `passenger_start_timeout`
Sets [PassengerStartTimeout](https://www.phusionpassenger.com/library/config/apache/reference/#passengerstarttimeout), the timeout for the application startup.
##### `passenger_pre_start`
Sets [PassengerPreStart](https://www.phusionpassenger.com/library/config/apache/reference/#passengerprestart), the URL of the application if pre-starting is required.
##### `passenger_user`
Sets [PassengerUser](https://www.phusionpassenger.com/library/config/apache/reference/#passengeruser), the running user for sandboxing applications.
##### `passenger_high_performance`
Sets the [`PassengerHighPerformance`](https://www.phusionpassenger.com/library/config/apache/reference/#passengerhighperformance) parameter.
Values: `true`, `false`.
Default: `undef`.
##### `passenger_nodejs`
Sets the [`PassengerNodejs`](https://www.phusionpassenger.com/library/config/apache/reference/#passengernodejs), the NodeJS interpreter to use for the application, on this virtual host.
##### `passenger_sticky_sessions`
Sets the [`PassengerStickySessions`](https://www.phusionpassenger.com/library/config/apache/reference/#passengerstickysessions) parameter.
Boolean.
Default: `undef`.
##### `passenger_startup_file`
Sets the [`PassengerStartupFile`](https://www.phusionpassenger.com/library/config/apache/reference/#passengerstartupfile) path. This path is relative to the application root.
##### `php_flags & values`
Allows per-virtual host 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.
Default: '{}'.
##### `php_admin_flags & values`
Allows per-virtual host 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.
Default: '{}'.
##### `port`
Sets the port the host is configured on. The module's defaults ensure the host listens on port 80 for non-SSL virtual hosts and port 443 for SSL virtual hosts. The host only listens on the port set in this parameter.
##### `priority`
Sets the relative load-order for Apache HTTPD VirtualHost configuration files.
If nothing matches the priority, the first name-based virtual host is used. Likewise, passing a higher priority causes the alphabetically first name-based virtual host to be used if no other names match.
> **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'.
To omit the priority prefix in file names, pass a priority of `false`.
Default: '25'.
##### `proxy_dest`
Specifies the destination address of a [ProxyPass](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass) configuration.
Default: `undef`.
##### `proxy_pass`
Specifies an array of `path => URI` values for a [ProxyPass](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass) configuration. Optionally, parameters can be added as an array.
* `reverse_urls`. *Optional.* This setting is useful when used with `mod_proxy_balancer`. Values: an array or string.
* `reverse_cookies`. *Optional.* Sets `ProxyPassReverseCookiePath` and `ProxyPassReverseCookieDomain`.
* `params`. *Optional.* Allows for ProxyPass key-value parameters, such as connection settings.
* `setenv`. *Optional.* Sets [environment variables](https://httpd.apache.org/docs/current/mod/mod_proxy.html#envsettings) for the proxy directive. Values: array.
##### `proxy_dest_match`
This directive is equivalent to [`proxy_dest`][], but takes regular expressions, see [ProxyPassMatch](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassmatch) for details.
##### `proxy_dest_reverse_match`
Allows you to pass a ProxyPassReverse if [`proxy_dest_match`][] is specified. See [ProxyPassReverse](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassreverse) for details.
##### `proxy_pass_match`
This directive is equivalent to [`proxy_pass`][], but takes regular expressions, see [ProxyPassMatch](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassmatch) for details.
##### `rack_base_uris`
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.
Default: `undef`.
#####`passenger_base_uris`
Used to specify that the given URI is a Phusion Passenger-served application. The file paths specified are listed as passenger application roots for [Phusion Passenger](https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerBaseURI) in the _passenger_base_uris.erb template.
Default: `undef`.
##### `redirect_dest`
Specifies the address to redirect to.
Default: `undef`.
##### `redirect_source`
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.
Modifies collected [request headers](https://httpd.apache.org/docs/current/mod/mod_headers.html#requestheader) in various ways, including adding additional request headers, removing request headers, and so on.
Default: `undef`.
``` puppet
apache::vhost { 'site.name.fdqn':
…
request_headers => [
'append MirrorID "mirror 12"',
'unset MirrorID',
],
}
```
##### `rewrites`
Creates URL rewrite rules. Expects an array of hashes.
Values: Hash keys that are any of 'comment', 'rewrite_base', 'rewrite_cond', 'rewrite_rule' or 'rewrite_map'.
Default: `undef`.
For example, you can specify that anyone trying to access index.html is served welcome.html
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
``` puppet
apache::vhost { 'site.name.fdqn':
…
rewrites => [
{
comment => 'redirect IE',
rewrite_cond => ['%{HTTP_USER_AGENT} ^MSIE'],
rewrite_rule => ['^index\.html$ welcome.html'],
},
],
}
```
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)
Refer to the [`mod_rewrite` documentation][`mod_rewrite`] for more details on what is possible with rewrite rules and conditions.
##### `rewrite_inherit`
Determines whether the virtual host inherits global rewrite rules.
Default: `false`.
Rewrite rules may be specified globally (in `$conf_file` or `$confd_dir`) or inside the virtual host `.conf` file. By default, virtual hosts do not inherit global settings. To activate inheritance, specify the `rewrites` parameter and set `rewrite_inherit` parameter to `true`:
``` puppet
apache::vhost { 'site.name.fdqn':
…
rewrites => [
<rules>,
],
rewrite_inherit => `true`,
}
```
> **Note**: The `rewrites` parameter is **required** for this to have effect
Apache activates global `Rewrite` rules inheritance if the virtual host files contains the following directives:
``` ApacheConf
RewriteEngine On
RewriteOptions Inherit
```
Refer to the [official `mod_rewrite` documentation](https://httpd.apache.org/docs/2.2/mod/mod_rewrite.html), section "Rewriting in Virtual Hosts".
##### `scriptalias`
Defines a directory of CGI scripts to be aliased to the path '/cgi-bin', such as '/usr/scripts'.
Default: `undef`.
##### `scriptaliases`
> **Note**: This parameter is deprecated in favor of the `aliases` parameter.
Passes an array of hashes to the virtual host to create either ScriptAlias or ScriptAliasMatch statements per the [`mod_alias` documentation][`mod_alias`].
``` puppet
scriptaliases => [
{
alias => '/myscript',
path => '/usr/share/myscript',
},
{
aliasmatch => '^/foo(.*)',
path => '/usr/share/fooscripts$1',
},
{
aliasmatch => '^/bar/(.*)',
path => '/usr/share/bar/wrapper.sh/$1',
},
{
alias => '/neatscript',
path => '/usr/share/neatscript',
},
]
```
The ScriptAlias and ScriptAliasMatch directives are created in the order specified. As with [Alias and AliasMatch](#aliases) directives, specify more specific aliases before more general ones to avoid shadowing.
##### `serveradmin`
Specifies the email address Apache displays when it renders one of its error pages.
Default: `undef`.
##### `serveraliases`
Sets the [ServerAliases](https://httpd.apache.org/docs/current/mod/core.html#serveralias) of the site.
Default: '[]'.
##### `servername`
Sets the servername corresponding to the hostname you connect to the virtual host at.
Default: the title of the resource.
##### `setenv`
Used by HTTPD to set environment variables for virtual hosts.
Default: '[]'.
Example:
``` puppet
apache::vhost { 'setenv.example.com':
setenv => ['SPECIAL_PATH /foo/bin'],
}
```
##### `setenvif`
Used by HTTPD to conditionally set environment variables for virtual hosts.
Default: '[]'.
##### `setenvifnocase`
Used by HTTPD to conditionally set environment variables for virtual hosts (caseless matching).
Default: '[]'.
##### `suphp_*`
* `suphp_addhandler`
* `suphp_configpath`
* `suphp_engine`
Sets up a virtual host with [suPHP](http://suphp.org/DocumentationView.html?file=apache/CONFIG).
* `suphp_addhandler`. Default: 'php5-script' on RedHat and FreeBSD, and 'x-httpd-php' on Debian and Gentoo.
* `suphp_configpath`. Default: `undef` on RedHat and FreeBSD, and '/etc/php5/apache2' on Debian and Gentoo.
* `suphp_engine`. Values: 'on' or 'off'. Default: 'off'.
'suphp' => { user => 'myappuser', group => 'myappgroup' },
}
}
```
##### `vhost_name`
Enables name-based virtual hosting. If no IP is passed to the virtual host, but the virtual host is assigned a port, then the virtual host name is 'vhost_name:port'. If the virtual host has no assigned IP or port, the virtual host name is set to the title of the resource.
Default: '*'.
##### `virtual_docroot`
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'.
Default: `false`.
``` puppet
apache::vhost { 'subdomain.loc':
vhost_name => '*',
port => '80',
virtual_docroot => '/var/www/%-2+',
docroot => '/var/www',
serveraliases => ['*.loc',],
}
```
##### `wsgi*`
* `wsgi_daemon_process`
* `wsgi_daemon_process_options`
* `wsgi_process_group`
* `wsgi_script_aliases`
* `wsgi_pass_authorization`
Sets up a virtual host with [WSGI](https://github.com/GrahamDumpleton/mod_wsgi).
* `wsgi_daemon_process`: A hash that sets the name of the WSGI daemon, accepting [certain keys](http://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIDaemonProcess.html). Default: `undef`.
* `wsgi_process_group`: Sets the group ID that the virtual host runs under. Default: `undef`.
* `wsgi_script_aliases`: Requires a hash of web paths to filesystem .wsgi paths. Default: `undef`.
* `wsgi_script_aliases_match`: Requires a hash of web path regexes to filesystem .wsgi paths. Default: `undef`
* `wsgi_pass_authorization`: Uses the WSGI application to handle authorization instead of Apache when set to 'On'. For more information, see [mod_wsgi's WSGIPassAuthorization documentation] (https://modwsgi.readthedocs.org/en/latest/configuration-directives/WSGIPassAuthorization.html). Default: `undef`, leading Apache to use its default value of 'Off'.
* `wsgi_chunked_request`: Enables support for chunked requests. Default: `undef`.
The `directories` parameter within the `apache::vhost` class passes an array of hashes to the virtual host to create [Directory](https://httpd.apache.org/docs/current/mod/core.html#directory), [File](https://httpd.apache.org/docs/current/mod/core.html#files), and [Location](https://httpd.apache.org/docs/current/mod/core.html#location) directive blocks. These blocks take the form, '< Directory /path/to/directory>...< /Directory>'.
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.
The `provider` key is optional. If missing, this key defaults to 'directory'. Values: 'directory', 'files', 'proxy', 'location', 'directorymatch', 'filesmatch', 'proxymatch' or 'locationmatch'. If you set `provider` to 'directorymatch', it uses the keyword 'DirectoryMatch' in the Apache config file.
An example use of `directories`:
``` puppet
apache::vhost { 'files.example.net':
docroot => '/var/www/files',
directories => [
{ 'path' => '/var/www/files',
'provider' => 'files',
'deny' => 'from all',
},
],
}
```
> **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.
Available handlers, represented as keys, should be placed within the `directory`, `files`, or `location` hashes. This looks like
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:
##### `addhandlers`
Sets [AddHandler](https://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'] }`.
Sets an [Allow](https://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.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
allow => 'from example.org',
},
],
}
```
##### `allow_override`
Sets the types of directives allowed in [.htaccess](https://httpd.apache.org/docs/current/mod/core.html#allowoverride) files. Accepts an array.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
allow_override => ['AuthConfig', 'Indexes'],
},
],
}
```
##### `auth_basic_authoritative`
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.
##### `auth_basic_fake`
Sets the value for [AuthBasicFake](https://httpd.apache.org/docs/current/mod/mod_auth_basic.html#authbasicfake), which statically configures authorization credentials for a given directive block.
##### `auth_basic_provider`
Sets the value for [AuthBasicProvider](https://httpd.apache.org/docs/current/mod/mod_auth_basic.html#authbasicprovider), which sets the authentication provider for a given location.
##### `auth_digest_algorithm`
Sets the value for [AuthDigestAlgorithm](https://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestalgorithm), which selects the algorithm used to calculate the challenge and response hashes.
###### `auth_digest_domain`
Sets the value for [AuthDigestDomain](https://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.
##### `auth_digest_nonce_lifetime`
Sets the value for [AuthDigestNonceLifetime](https://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestnoncelifetime), which controls how long the server nonce is valid.
##### `auth_digest_provider`
Sets the value for [AuthDigestProvider](https://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestprovider), which sets the authentication provider for a given location.
##### `auth_digest_qop`
Sets the value for [AuthDigestQop](https://httpd.apache.org/docs/current/mod/mod_auth_digest.html#authdigestqop), which determines the quality-of-protection to use in digest authentication.
##### `auth_digest_shmem_size`
Sets the value for [AuthAuthDigestShmemSize](https://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.
##### `auth_group_file`
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.
##### `auth_name`
Sets the value for [AuthName](https://httpd.apache.org/docs/current/mod/mod_authn_core.html#authname), which sets the name of the authorization realm.
##### `auth_require`
Sets the entity name you're requiring to allow access. Read more about [Require](https://httpd.apache.org/docs/current/mod/mod_authz_host.html#requiredirectives).
##### `auth_type`
Sets the value for [AuthType](https://httpd.apache.org/docs/current/mod/mod_authn_core.html#authtype), which guides the type of user authentication.
##### `auth_user_file`
Sets the value for [AuthUserFile](https://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.
##### `auth_merging`
Sets the value for [AuthMerging](https://httpd.apache.org/docs/current/mod/mod_authz_core.html#authmerging), which determines if authorization logic should be combined
##### `auth_ldap_url`
Sets the value for [AuthLDAPURL](https://httpd.apache.org/docs/current/mod/mod_authnz_ldap.html#authldapurl), which determines URL of LDAP-server(s) if AuthBasicProvider 'ldap' is used
##### `auth_ldap_bind_dn`
Sets the value for [AuthLDAPBindDN](https://httpd.apache.org/docs/current/mod/mod_authnz_ldap.html#authldapbinddn), which allows use of an optional DN used to bind to the LDAP-server when searching for entries if AuthBasicProvider 'ldap' is used.
##### `auth_ldap_bind_password`
Sets the value for [AuthLDAPBindPassword](https://httpd.apache.org/docs/current/mod/mod_authnz_ldap.html#authldapbindpassword), which allows use of an optional bind password to use in conjunction with the bind DN if AuthBasicProvider 'ldap' is used.
##### `auth_ldap_group_attribute`
Array of values for [AuthLDAPGroupAttribute](https://httpd.apache.org/docs/current/mod/mod_authnz_ldap.html#authldapgroupattribute), specifies which LDAP attributes are used to check for user members within ldap-groups.
Default: "member" and "uniquemember".
##### `auth_ldap_group_attribute_is_dn`
Sets value for [AuthLDAPGroupAttributeIsDN](https://httpd.apache.org/docs/current/mod/mod_authnz_ldap.html#authldapgroupattributeisdn), specifies if member of a ldapgroup is a dn or simple username. When set on, this directive says to use the distinguished name of the client username when checking for group membership. Otherwise, the username will be used. valid values are: "on" or "off"
##### `custom_fragment`
Pass a string of custom configuration directives to be placed at the end of the directory configuration.
``` puppet
apache::vhost { 'monitor':
…
directories => [
{
path => '/path/to/directory',
custom_fragment => '
<Location /balancer-manager>
SetHandler balancer-manager
Order allow,deny
Allow from all
</Location>
<Location /server-status>
SetHandler server-status
Order allow,deny
Allow from all
</Location>
ProxyStatus On',
},
]
}
```
##### `dav`
Sets the value for [Dav](http://httpd.apache.org/docs/current/mod/mod_dav.html#dav), which determines if the WebDAV HTTP methods should be enabled. The value can be either 'On', 'Off' or the name of the provider. A value of 'On' enables the default filesystem provider implemented by the `mod_dav_fs` module.
##### `dav_depth_infinity`
Sets the value for [DavDepthInfinity](http://httpd.apache.org/docs/current/mod/mod_dav.html#davdepthinfinity), which is used to enable the processing of `PROPFIND` requests having a `Depth: Infinity` header.
##### `dav_min_timeout`
Sets the value for [DavMinTimeout](http://httpd.apache.org/docs/current/mod/mod_dav.html#davmintimeout), which sets the time the server holds a lock on a DAV resource. The value should be the number of seconds to set.
##### `deny`
Sets a [Deny](https://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.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
deny => 'from example.org',
},
],
}
```
##### `error_documents`
An array of hashes used to override the [ErrorDocument](https://httpd.apache.org/docs/current/mod/core.html#errordocument) settings for the directory.
``` puppet
apache::vhost { 'sample.example.net':
directories => [
{ path => '/srv/www',
error_documents => [
{ 'error_code' => '503',
'document' => '/service-unavail',
},
],
},
],
}
```
##### `ext_filter_options`
Sets the [ExtFilterOptions](https://httpd.apache.org/docs/current/mod/mod_ext_filter.html) directive.
Note that you must declare `class { 'apache::mod::ext_filter': }` before using this directive.
``` puppet
apache::vhost { 'filter.example.org':
docroot => '/var/www/filter',
directories => [
{ path => '/var/www/filter',
ext_filter_options => 'LogStderr Onfail=abort',
},
],
}
```
##### `geoip_enable`
Sets the [GeoIPEnable](http://dev.maxmind.com/geoip/legacy/mod_geoip2/#Configuration) directive.
Note that you must declare `class {'apache::mod::geoip': }` before using this directive.
``` puppet
apache::vhost { 'first.example.com':
docroot => '/var/www/first',
directories => [
{ path => '/var/www/first',
geoip_enable => `true`,
},
],
}
```
##### `headers`
Adds lines for [Header](https://httpd.apache.org/docs/current/mod/mod_headers.html#header) directives.
Sets the [default ordering](https://httpd.apache.org/docs/current/mod/mod_autoindex.html#indexorderdefault) of the directory index.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
order => 'Allow,Deny',
index_order_default => ['Descending', 'Date'],
},
],
}
```
###### `index_style_sheet`
Sets the [IndexStyleSheet](https://httpd.apache.org/docs/current/mod/mod_autoindex.html#indexstylesheet), which adds a CSS stylesheet to the directory index.
Creates a [Limit](https://httpd.apache.org/docs/current/mod/core.html#limit) block inside the Directory block, which can also contain `require` directives.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/docroot',
directories => [
{ path => '/',
provider => 'location',
limit => [
{ methods => 'GET HEAD',
require => ['valid-user']
},
],
},
],
}
```
##### `limit_except`
Creates a [LimitExcept](https://httpd.apache.org/docs/current/mod/core.html#limitexcept) block inside the Directory block, which can also contain `require` directives.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/docroot',
directories => [
{ path => '/',
provider => 'location',
limit_except => [
{ methods => 'GET HEAD',
require => ['valid-user']
},
],
},
],
}
```
##### `mellon_enable`
Sets the [MellonEnable][`mod_auth_mellon`] directory to enable [`mod_auth_mellon`][]. You can use [`apache::mod::auth_mellon`][] to install `mod_auth_mellon`.
Related parameters follow the names of `mod_auth_mellon` directives:
- `mellon_cond`: Takes an array of mellon conditions that must be met to grant access, and creates a [MellonCond][`mod_auth_mellon`] directive for each item in the array.
- `mellon_endpoint_path`: Sets the [MellonEndpointPath][`mod_auth_mellon`] to set the mellon endpoint path.
- `mellon_sp_metadata_file`: Sets the [MellonSPMetadataFile][`mod_auth_mellon`] location of the SP metadata file.
- `mellon_idp_metadata_file`: Sets the [MellonIDPMetadataFile][`mod_auth_mellon`] location of the IDP metadata file.
- `mellon_saml_rsponse_dump`: Sets the [MellonSamlResponseDump][`mod_auth_mellon`] directive to enable debug of SAML.
- `mellon_set_env_no_prefix`: Sets the [MellonSetEnvNoPrefix][`mod_auth_mellon`] directive to a hash of attribute names to map
to environment variables.
- `mellon_sp_private_key_file`: Sets the [MellonSPPrivateKeyFile][`mod_auth_mellon`] directive for the private key location of the service provider.
- `mellon_sp_cert_file`: Sets the [MellonSPCertFile][`mod_auth_mellon`] directive for the public key location of the service provider.
- `mellon_user`: Sets the [MellonUser][`mod_auth_mellon`] attribute to use for the username.
##### `options`
Lists the [Options](https://httpd.apache.org/docs/current/mod/core.html#options) for the given Directory block.
Sets the order of processing Allow and Deny statements as per [Apache core documentation](https://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.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
order => 'Allow,Deny',
},
],
}
```
##### `passenger_enabled`
Sets the value for the [PassengerEnabled](http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerEnabled) directive to 'on' or 'off'. Requires `apache::mod::passenger` to be included.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
passenger_enabled => 'on',
},
],
}
```
> **Note:** There is an [issue](http://www.conandalton.net/2010/06/passengerenabled-off-not-working.html) using the PassengerEnabled directive with the PassengerHighPerformance directive.
##### `php_value` and `php_flag`
`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).
##### `php_admin_value` and `php_admin_flag`
`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).
##### `require`
Sets a `Require` directive as per the [Apache Authz documentation](https://httpd.apache.org/docs/current/mod/mod_authz_core.html#require). If no `require` is set, it will default to `Require all granted`.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
require => 'ip 10.17.42.23',
}
],
}
```
When more complex sets of requirement are needed, apache >= 2.4 provides the use of [RequireAll](https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html#requireall), [RequireNone](https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html#requirenone) or [RequireAny](https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html#requireany) directives.
Using the 'enforce' key, which only supports 'any','none','all' (other values are silently ignored), this could be established like:
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
require => {
enforce => 'any',
requires => [
'ip 1.2.3.4',
'not host host.example.com',
'user xyz',
],
},
},
],
}
```
If `require` is set to `unmanaged` it will not be set at all. This is useful for complex authentication/authorization requirements which are handled in a custom fragment.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
require => 'unmanaged',
}
],
}
```
##### `satisfy`
Sets a `Satisfy` directive per the [Apache Core documentation](https://httpd.apache.org/docs/2.2/mod/core.html#satisfy). **Deprecated:** This parameter is deprecated due to a change in Apache and only works with Apache 2.2 and lower.
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
satisfy => 'Any',
}
],
}
```
##### `sethandler`
Sets a `SetHandler` directive per the [Apache Core documentation](https://httpd.apache.org/docs/2.2/mod/core.html#sethandler).
``` puppet
apache::vhost { 'sample.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
sethandler => 'None',
}
],
}
```
##### `set_output_filter`
Sets a `SetOutputFilter` directive per the [Apache Core documentation](https://httpd.apache.org/docs/current/mod/core.html#setoutputfilter).
Creates URL [`rewrites`](#rewrites) rules in virtual host directories. Expects an array of hashes, and the hash keys can be any of 'comment', 'rewrite_base', 'rewrite_cond', or 'rewrite_rule'.
``` puppet
apache::vhost { 'secure.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
rewrites => [ { comment => 'Permalink Rewrites',
rewrite_base => '/'
},
{ rewrite_rule => [ '^index\.php$ - [L]' ]
},
{ rewrite_cond => [ '%{REQUEST_FILENAME} !-f',
'%{REQUEST_FILENAME} !-d',
],
rewrite_rule => [ '. /index.php [L]' ],
}
],
},
],
}
```
> **Note**: If you include rewrites in your directories, also include `apache::mod::rewrite` and consider setting the rewrites using the `rewrites` parameter in `apache::vhost` rather than setting the rewrites in the virtual host's directories.
##### `shib_request_settings`
Allows a 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.
When set to 'On', this turns on the use of request headers to publish attributes to applications. 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.
##### `ssl_options`
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 virtual host.
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 virtual host declaration, and can only be passed within `directories`.
``` puppet
apache::vhost { 'secure.example.net':
docroot => '/path/to/directory',
directories => [
{ path => '/path/to/directory',
suphp => {
user => 'myappuser',
group => 'myappgroup',
},
},
],
}
```
##### `additional_includes`
Specifies paths to additional static, specific Apache configuration files in virtual host directories. Values: a array of string path.
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 virtual hosts.
##### `ssl`
Enables SSL for the virtual host. SSL virtual hosts only respond to HTTPS queries. Values: Boolean.
Default: `false`.
##### `ssl_ca`
Specifies the SSL certificate authority.
Default: `undef`.
##### `ssl_cert`
Specifies the SSL certification.
Default: Depends on operating system.
* RedHat: '/etc/pki/tls/certs/localhost.crt'
* Debian: '/etc/ssl/certs/ssl-cert-snakeoil.pem'
* FreeBSD: '/usr/local/etc/apache22/server.crt'
* Gentoo: '/etc/ssl/apache2/server.crt'
##### `ssl_protocol`
Specifies [SSLProtocol](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol). Expects an array or space separated string of accepted protocols.
Sets [SSLHonorCipherOrder](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslhonorcipherorder), to cause Apache to use the server's preferred order of ciphers rather than the client's preferred order. Values:
Values: Boolean, 'on', 'off'.
Default: `true`.
##### `ssl_certs_dir`
Specifies the location of the SSL certification directory.
Default: Depends on operating system.
- Debian: '/etc/ssl/certs'
- Red Hat: '/etc/pki/tls/certs'
- FreeBSD: `undef`
- Gentoo: '/etc/ssl/apache2'
##### `ssl_chain`
Specifies the SSL chain. 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.
Default: `undef`.
##### `ssl_crl`
Specifies the certificate revocation list to use. (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.)
Default: `undef`.
##### `ssl_crl_path`
Specifies the location of the certificate revocation list. (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.)
Default: `undef`.
##### `ssl_crl_check`
Sets the certificate revocation check level via the [SSLCARevocationCheck directive](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcarevocationcheck). The 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.
Default: `undef`.
##### `ssl_key`
Specifies the SSL key.
Defaults are based on your operating system. Default work out of the box but must be updated in the base `apache` class with your specific certificate information before being used in production.
Sets the [SSLVerifyClient](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslverifyclient) directive, which sets the certificate verification level for client authentication.
``` puppet
apache::vhost { 'sample.example.net':
…
ssl_verify_client => 'optional',
}
```
Values: 'none', 'optional', 'require', and 'optional_no_ca'.
Default: `undef`.
##### `ssl_verify_depth`
Sets the [SSLVerifyDepth](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslverifydepth) directive, which specifies the maximum depth of CA certificates in client certificate verification.
``` puppet
apache::vhost { 'sample.example.net':
…
ssl_verify_depth => 1,
}
```
Default: `undef`.
##### `ssl_proxy_protocol`
Sets the [SSLProxyProtocol](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxyprotocol) directive, which controls which SSL protocol flavors `mod_ssl` should use when establishing its server environment for proxy. It connects to servers using only one of the provided protocols.
Default: `undef`.
##### `ssl_proxy_verify`
Sets the [SSLProxyVerify](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxyverify) directive, which configures certificate verification of the remote server when a proxy is configured to forward requests to a remote SSL server.
Default: `undef`.
##### `ssl_proxy_verify_depth`
Sets the [SSLProxyVerifyDepth](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxyverifydepth) directive, which configures how deeply mod_ssl should verify before deciding that the remote server does not have a valid certificate.
A depth of 0 means that only self-signed remote server certificates are accepted, the default depth of 1 means the remote server certificate can be self-signed or signed by a CA that is directly known to the server.
Default: `undef`
##### `ssl_proxy_ca_cert`
Sets the [SSLProxyCACertificateFile](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxycacertificatefile) directive, which specifies an all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. This file should be a concatenation of the PEM-encoded certificate files in order of preference.
Default: `undef`
##### `ssl_proxy_machine_cert`
Sets the [SSLProxyMachineCertificateFile](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxymachinecertificatefile) directive, which specifies an all-in-one file where you keep the certs and keys used for this server to authenticate itself to remote servers. This file should be a concatenation of the PEM-encoded certificate files in order of preference.
Sets the [SSLProxyCheckPeerCN](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxycheckpeercn) directive, which specifies whether the remote server certificate's CN field is compared against the hostname of the request URL.
Values: 'on', 'off'.
Default: `undef`
##### `ssl_proxy_check_peer_name`
Sets the [SSLProxyCheckPeerName](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxycheckpeername) directive, which specifies whether the remote server certificate's CN field is compared against the hostname of the request URL.
Values: 'on', 'off'.
Default: `undef`
##### `ssl_proxy_check_peer_expire`
Sets the [SSLProxyCheckPeerExpire](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxycheckpeerexpire) directive, which specifies whether the remote server certificate is checked for expiration or not.
Values: 'on', 'off'.
Default: `undef`
##### `ssl_options`
Sets the [SSLOptions](https://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 virtual host and can be a string or an array.
Sets the [SSLOpenSSLConfCmd](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslopensslconfcmd) directive, which provides direct configuration of OpenSSL parameters.
Default: `undef`
##### `ssl_proxyengine`
Specifies whether or not to use [SSLProxyEngine](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxyengine).
Boolean.
Default: `true`.
##### `ssl_stapling`
Specifies whether or not to use [SSLUseStapling](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslusestapling). By default, uses what is set globally.
This parameter only applies to Apache 2.4 or higher and is ignored on older versions.
Boolean or `undef`.
Default: `undef`
##### `ssl_stapling_timeout`
Can be used to set the [SSLStaplingResponderTimeout](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslstaplingrespondertimeout) directive.
This parameter only applies to Apache 2.4 or higher and is ignored on older versions.
Default: none.
##### `ssl_stapling_return_errors`
Can be used to set the [SSLStaplingReturnResponderErrors](http://httpd.apache.org/docs/current/mod/mod_ssl.html#sslstaplingreturnrespondererrors) directive.
This parameter only applies to Apache 2.4 or higher and is ignored on older versions.
Default: none.
#### Defined type: FastCGI Server
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.
** Note ** If using Ubuntu 10.04+, you'll need to manually enable the multiverse repository.
Ex:
``` puppet
apache::fastcgi::server { 'php':
host => '127.0.0.1:9000',
timeout => 15,
flush => `false`,
faux_path => '/var/www/php.fcgi',
fcgi_alias => '/php.fcgi',
file_type => 'application/x-httpd-php',
pass_header => ''
}
```
Within your virtual host, you can then configure the specified file type to be handled by the fastcgi server specified above.
The hostname or IP address and TCP port number (1-65535) of the FastCGI server.
It is also possible to pass a unix socket:
``` puppet
apache::fastcgi::server { 'php':
host => '/var/run/fcgi.sock',
}
```
##### `timeout`
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.
##### `flush`
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.
##### `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.
##### `alias`
A unique alias. This is used internally to link the action with the FastCGI server.
##### `file_type`
The MIME-type of the file to be processed by the FastCGI server.
##### `pass_header`
The name of an HTTP Request Header to be passed in the request environment. This option makes available the contents of headers which are normally not available (e.g. Authorization) to a CGI environment.
#### Defined type: `apache::vhost::custom`
The `apache::vhost::custom` defined type is a thin wrapper around the `apache::custom_config` defined type, and simply overrides some of its default settings specific to the virtual host directory in Apache.
**Parameters within `apache::vhost::custom`**:
##### `content`
Sets the configuration file's content.
##### `ensure`
Specifies if the virtual host file is present or absent.
Values: 'absent', 'present'.
Default: 'present'.
##### `priority`
Sets the relative load order for Apache HTTPD VirtualHost configuration files.
Default: '25'.
##### `verify_config`
Specifies whether to validate the configuration file before notifying the Apache service.
Boolean.
Default: `true`.
### Private defined types
#### Defined type: `apache::peruser::multiplexer`
This defined type checks if an Apache module has a class. If it does, it includes that class. If it does not, it passes the module name to the [`apache::mod`][] defined type.
#### Defined type: `apache::peruser::multiplexer`
Enables the [`Peruser`][] module for FreeBSD only.
#### Defined type: `apache::peruser::processor`
Enables the [`Peruser`][] module for FreeBSD only.
#### Defined type: `apache::security::file_link`
Links the `activated_rules` from [`apache::mod::security`][] to the respective CRS rules on disk.
### Templates
The Apache module relies heavily on templates to enable the [`apache::vhost`][] and [`apache::mod`][] defined types. These templates are built based on [Facter][] facts specific to your operating system. Unless explicitly called out, most templates are not meant for configuration.
### Functions
#### apache_pw_hash
Hashes a password in a format suitable for htpasswd files read by apache.
Currently uses SHA-hashes, because although this format is considered insecure, its the
most secure format supported by the most platforms.
## Limitations
### General
This module is CI tested against both [open source Puppet][] and [Puppet Enterprise][] on:
- CentOS 5 and 6
- Ubuntu 12.04 and 14.04
- Debian 7
- RHEL 5, 6, and 7
This module also provides functions for other distributions and operating systems, such as FreeBSD, Gentoo, and Amazon Linux, but is not formally tested on them and are subject to regressions.
### FreeBSD
In order to use this module on FreeBSD, you _must_ use apache24-2.4.12 (www/apache24) or newer.
### Gentoo
On Gentoo, this module depends on the [`gentoo/puppet-portage`][] Puppet module. Although several options apply or enable certain features and settings for Gentoo, it is not a [supported operating system][] for this module.
### RHEL/CentOS
The [`apache::mod::auth_cas`][], [`apache::mod::passenger`][], [`apache::mod::proxy_html`][] and [`apache::mod::shib`][] classes are not functional on RH/CentOS without providing dependency packages from extra repositories.
See their respective documentation below for related repositories and packages.
#### RHEL/CentOS 5
The [`apache::mod::passenger`][] and [`apache::mod::proxy_html`][] classes are untested because repositories are missing compatible packages.
#### RHEL/CentOS 6
The [`apache::mod::passenger`][] class is not installing, because the the EL6 repository is missing compatible packages.
#### RHEL/CentOS 7
The [`apache::mod::passenger`][] and [`apache::mod::proxy_html`][] classes are untested because the EL7 repository is missing compatible packages, which also blocks us from testing the [`apache::vhost`][] defined type's [`rack_base_uris`][] parameter.
### SELinux and custom paths
If [SELinux][] is in [enforcing mode][] and you want to use custom paths for `logroot`, `mod_dir`, `vhost_dir`, and `docroot`, you need to manage the files' context yourself.
You can do this with Puppet:
``` puppet
exec { 'set_apache_defaults':
command => 'semanage fcontext -a -t httpd_sys_content_t "/custom/path(/.*)?"',
path => '/bin:/usr/bin/:/sbin:/usr/sbin',
require => Package['policycoreutils-python'],
}
package { 'policycoreutils-python':
ensure => installed,
}
exec { 'restorecon_apache':
command => 'restorecon -Rv /apache_spec',
path => '/bin:/usr/bin/:/sbin:/usr/sbin',
before => Class['Apache::Service'],
require => Class['apache'],
}
class { 'apache': }
host { 'test.server':
ip => '127.0.0.1',
}
file { '/custom/path':
ensure => directory,
}
file { '/custom/path/include':
ensure => present,
content => '#additional_includes',
}
apache::vhost { 'test.server':
docroot => '/custom/path',
additional_includes => '/custom/path/include',
}
```
You must set the contexts using `semanage fcontext` instead of `chcon` because Puppet's `file` resources reset the values' context in the database if the resource doesn't specify it.
### Ubuntu 10.04
The [`apache::vhost::WSGIImportScript`][] parameter creates a statement inside the virtual host that is unsupported on older versions of Apache, causing it to fail. This will be remedied in a future refactoring.
### Ubuntu 16.04
The [`apache::mod::suphp`][] class is untested since repositories are missing compatible packages.
## Development
### Contributing
[Puppet][] 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 hardware, software, and deployment configurations that Puppet is intended to serve.
We want to make it as easy as possible to contribute changes so our modules work in your environment, but we also need contributors to follow a few guidelines to help us maintain and improve the modules' quality.
For more information, please read the complete [module contribution guide][].
### Testing
This project contains tests for both [rspec-puppet][] and [beaker-rspec][] to verify functionality. For detailed information on using these tools, please see their respective documentation.