Tosetupavirtualhostwithawildcardaliasforthesubdomainmappedtoasame-nameddirectory,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:
Ifyouneedtousethe[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`:
Installsthe[Shibboleth](http://shibboleth.net/) Apache module `mod_shib`, which enables SAML2 single sign-on (SSO) authentication by Shibboleth Identity Providers and Shibboleth Federations. This class only installs and configures the Apache components of a web application that consumes Shibboleth SSO identities, also known as a Shibboleth Service Provider. You can manage the Shibboleth configuration manually, with Puppet, or using a [Shibboleth Puppet Module](https://github.com/aethylred/puppet-shibboleth).
Specifiesan[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.
If[`apache::mod::passenger`][]isloadedand`PassengerHighPerformance`is'true',the`Alias`directivemightnotbeabletohonorthe`PassengerEnabled=>off`statement.See[thisarticle](http://www.conandalton.net/2010/06/passengerenabled-off-not-working.html) for details.
Alistofhasheswhichcanbeusedtooverridethe[ErrorDocument](https://httpd.apache.org/docs/current/mod/core.html#errordocument) settings for this virtual host. Default: '[]'.
Setsthe[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)'. Valid options must either begin with a '/' or be 'disabled'. Default: undef.
Addslinestoreplace,merge,orremoveresponseheaders.See[Apache'smod_headersdocumentation](https://httpd.apache.org/docs/current/mod/mod_headers.html#header) for more information. Valid options: A string, an array of strings, or undef. Default: undef.
Enablesan[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. Keys can be:
- `krb_local_user_mapping`: Strips @REALM from usernames for further use. Default: undef.
##### `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. Valid options: 'directory', 'absent'.
##### `logroot_mode`
Overrides the mode the logroot directory is set to. Default: undef. 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).
##### `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. Valid options: 'emerg', 'alert', 'crit', 'error', 'warn', 'notice', 'info' or 'debug'. Default: 'warn' for the global server configuration, which can be overridden on a per-virtual host basis.
###### `modsec_body_limit`
Configures the maximum request body size (in bytes) ModSecurity will accept for buffering
###### `modsec_disable_vhost`
Disables [`mod_security`][] on a virtual host. Only valid if [`apache::mod::security`][] is included. Valid options: Boolean. Default: undef.
###### `modsec_disable_ids`
Array of mod_security IDs to remove from the virtual host. Also takes a hash allowing removal of an ID from a specific location.
Specifies URLs you do not want to proxy. This parameter is meant to be used in combination with [`proxy_dest`](#proxy_dest).
##### `no_proxy_uris_match`
This directive is equivalent to [`no_proxy_uris`][], but takes regular expressions.
##### `proxy_preserve_host`
Sets the [ProxyPreserveHost Directive](https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypreservehost). Valid options: Boolean. Default: false.
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'.
##### `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. Default: false.
##### `options`
Sets the [`Options`][] for the specified virtual host. Default: ['Indexes','FollowSymLinks','MultiViews'], as demonstrated below:
> **Note**: If you use the [`directories`][] parameter of [`apache::vhost`][], 'Options', 'Override', and 'DirectoryIndex' are ignored because they are parameters within `directories`.
##### `override`
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.
##### `passenger_app_env`
Sets [PassengerAppEnv](https://www.phusionpassenger.com/library/config/apache/reference/#passengerappenv), the environment for the Passenger application. If not specifies, defaults to the global setting or 'production'.
##### `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.
##### `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. For Passenger > 3.0.0 the default is '0', since 5.0.0 it's '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.
##### `passenger_min_instances`
Sets [PassengerMinInstances](https://www.phusionpassenger.com/library/config/apache/reference/#passengermininstances), the minimum number of application processes to run.
##### `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. Valid options: 'true', 'false'. Default: undef.
##### `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. Default: '25'.
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.
##### `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. Default: undef. Parameters and location options can optionally be added as an array.
* `reverse_urls`. *Optional.* This setting is useful when used with `mod_proxy_balancer`. Valid options: 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. Valid options: 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, etc. 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, and the hash keys can be 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.
##### `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' => { 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.
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_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'. Valid options: '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
###### `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',
},
]
}
```
###### `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.
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:
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. Valid options 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. Valid options: 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. Valid options: Boolean. Default: false.
##### `ssl_ca`
Specifies the SSL certificate authority. Default: undef.
##### `ssl_cert`
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.
##### `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. Defaults: 'all', '-SSLv2', '-SSLv3'.
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. Default: true. In addition to true/false Boolean values, will also accept case-insensitive Strings 'on' or 'off'.
##### `ssl_certs_dir`
Specifies the location of the SSL certification directory. Default: Depends on the operating system.
- **Debian:** '/etc/ssl/certs'
- **Red Hat:** '/etc/pki/tls/certs'
- **FreeBSD:** '/usr/local/etc/apache22'
- **Gentoo:** '/etc/ssl/apache2'
##### `ssl_chain`
Specifies the SSL chain. Default: 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.
##### `ssl_crl`
Specifies the certificate revocation list to use. Default: 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.)
##### `ssl_crl_path`
Specifies the location of the certificate revocation list. Default: 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.)
##### `ssl_crl_check`
Sets the certificate revocation check level via the [SSLCARevocationCheck directive](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslcarevocationcheck). Default: 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.
##### `ssl_key`
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.)
##### `ssl_verify_client`
Sets the [SSLVerifyClient](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslverifyclient) directive, which sets the certificate verification level for client authentication. Valid options are: 'none', 'optional', 'require', and 'optional_no_ca'. Default: undef.
``` puppet
apache::vhost { 'sample.example.net':
…
ssl_verify_client => 'optional',
}
```
##### `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. Default: undef.
``` puppet
apache::vhost { 'sample.example.net':
…
ssl_verify_depth => 1,
}
```
##### `ssl_proxy_protocol`
Sets the [SSLProxyProtocol](https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslproxyprotocol) directive, which controls the SSL protocol flavors mod_ssl should use when establishing its server environment for proxy. It will only connect to servers using 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_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. Default: undef.
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. Valid options: '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. Valid options: '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. Valid options: '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. Default: undef.
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). Valid options: Boolean. Default: true.
#### 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`
`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. Valid options: '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. Valid options: 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.
## Limitations
### 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.
### RHEL/CentOS 5
The [`apache::mod::passenger`][] and [`apache::mod::proxy_html`][] classes are untested since repositories are missing compatible packages.
### RHEL/CentOS 6
The [`apache::mod::passenger`][] class is not installing as the the EL6 repository is missing compatible packages.
### RHEL/CentOS 7
The [`apache::mod::passenger`][] class is untested as the EL7 repository is missing compatible packages, which also blocks us from testing the [`apache::vhost`][] defined type's [`rack_base_uris`][] parameter.
### 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.
### Ubuntu 10.04
The [`apache::vhost::wsgi_import_script`][] 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.
### 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 above for related repositories and packages.
### 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 need to 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.
### FreeBSD
In order to use this module on FreeBSD, you _must_ use apache24-2.4.12 (www/apache24) or newer.
## Development
### Contributing
[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 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][].
### Running tests
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.