apache
\n\n![\"Build](\"https://travis-ci.org/puppetlabs/puppetlabs-apache.png?branch=master\")
Table of Contents
\n\n- \n
- Overview - What is the Apache module? \n
- Module Description - What does the module do? \n
- Setup - The basics of getting started with Apache\n\n \n
- Usage - The classes, defined types, and their parameters available for configuration\n\n \n
- Implementation - An under-the-hood peek at what the module is doing\n\n \n
- Limitations - OS compatibility, etc. \n
- Development - Guide for contributing to the module \n
- Release Notes - Notes on the most recent updates to the module \n
Overview
\n\nThe Apache module allows you to set up virtual hosts and manage web services with minimal effort.
\n\nModule Description
\n\nApache is a widely-used web server, and this module provides a simplified way of creating configurations to manage your infrastructure. This includes the ability to configure and manage a range of different virtual host setups, as well as a streamlined way to install and configure Apache modules.
\n\nSetup
\n\nWhat Apache affects:
\n\n- \n
- configuration files and directories (created and written to)\n\n
- \n
- NOTE: Configurations that are not managed by Puppet will be purged. \n
\n - package/service/configuration files for Apache \n
- Apache modules \n
- virtual hosts \n
- listened-to ports \n
/etc/make.confon FreeBSD \n
Beginning with Apache
\n\nTo install Apache with the default parameters
\n\n class { 'apache': }\nThe defaults are determined by your operating system (e.g. Debian systems have one set of defaults, RedHat systems have another). These defaults will work well in a testing environment, but are not suggested for production. To establish customized parameters
\n\n class { 'apache':\n default_mods => false,\n default_confd_files => false,\n }\nConfigure a virtual host
\n\nDeclaring the apache class will create a default virtual host by setting up a vhost on port 80, listening on all interfaces and serving $apache::docroot.
class { 'apache': }\nTo configure a very basic, name-based virtual host
\n\n apache::vhost { 'first.example.com':\n port => '80',\n docroot => '/var/www/first',\n }\nNote: The default priority is 15. If nothing matches this priority, the alphabetically first name-based vhost will be used. This is also true if you pass a higher priority and no names match anything else.
\n\nA slightly more complicated example, which moves the docroot owner/group
\n\n apache::vhost { 'second.example.com':\n port => '80',\n docroot => '/var/www/second',\n docroot_owner => 'third',\n docroot_group => 'third',\n }\nTo set up a virtual host with SSL and default SSL certificates
\n\n apache::vhost { 'ssl.example.com':\n port => '443',\n docroot => '/var/www/ssl',\n ssl => true,\n }\nTo set up a virtual host with SSL and specific SSL certificates
\n\n apache::vhost { 'fourth.example.com':\n port => '443',\n docroot => '/var/www/fourth',\n ssl => true,\n ssl_cert => '/etc/ssl/fourth.example.com.cert',\n ssl_key => '/etc/ssl/fourth.example.com.key',\n }\nTo set up a virtual host with IP address different than '*'
\n\n apache::vhost { 'subdomain.example.com':\n ip => '127.0.0.1',\n port => '80',\n docrout => '/var/www/subdomain',\n }\nTo set up a virtual host with wildcard alias for subdomain mapped to same named directory\nhttp://examle.com.loc => /var/www/example.com
apache::vhost { 'subdomain.loc':\n vhost_name => '*',\n port => '80',\n virtual_docroot' => '/var/www/%-2+',\n docroot => '/var/www',\n serveraliases => ['*.loc',],\n }\nTo set up a virtual host with suPHP
\n\n apache::vhost { 'suphp.example.com':\n port => '80',\n docroot => '/home/appuser/myphpapp',\n suphp_addhandler => 'x-httpd-php',\n suphp_engine => 'on',\n suphp_configpath => '/etc/php5/apache2',\n directories => { path => '/home/appuser/myphpapp',\n 'suphp' => { user => 'myappuser', group => 'myappgroup' },\n }\n }\nTo set up a virtual host with WSGI
\n\n apache::vhost { 'wsgi.example.com':\n port => '80',\n docroot => '/var/www/pythonapp',\n wsgi_daemon_process => 'wsgi',\n wsgi_daemon_process_options =>\n { processes => '2', threads => '15', display-name => '%{GROUP}' },\n wsgi_process_group => 'wsgi',\n wsgi_script_aliases => { '/' => '/var/www/demo.wsgi' },\n }\nStarting 2.2.16, httpd supports FallbackResource which is a simple replace for common RewriteRules:
\n\n apache::vhost { 'wordpress.example.com':\n port => '80',\n docroot => '/var/www/wordpress',\n fallbackresource => '/index.php',\n }\nPlease note that the disabled argument to FallbackResource is only supported since 2.2.24.
To see a list of all virtual host parameters, please go here. To see an extensive list of virtual host examples please look here.
\n\nUsage
\n\nClasses and Defined Types
\n\nThis module modifies Apache configuration files and directories and will purge any configuration not managed by Puppet. Configuration of Apache should be managed by Puppet, as non-puppet configuration files can cause unexpected failures.
\n\nIt is possible to temporarily disable full Puppet management by setting the purge_configs parameter within the base apache class to 'false'. This option should only be used as a temporary means of saving and relocating customized configurations.
Class: apache
\n\nThe Apache module's primary class, apache, guides the basic setup of Apache on your system.
You may establish a default vhost in this class, the vhost class, or both. You may add additional vhost configurations for specific virtual hosts using a declaration of the vhost type.
Parameters within apache:
default_mods
\n\nSets up Apache with default settings based on your OS. Defaults to 'true', set to 'false' for customized configuration.
\n\ndefault_vhost
\n\nSets up a default virtual host. Defaults to 'true', set to 'false' to set up customized virtual hosts.
\n\ndefault_confd_files
\n\nGenerates default set of include-able apache configuration files under ${apache::confd_dir} directory. These configuration files correspond to what is usually installed with apache package on given platform.
default_ssl_vhost
\n\nSets up a default SSL virtual host. Defaults to 'false'.
\n\n apache::vhost { 'default-ssl':\n port => 443,\n ssl => true,\n docroot => $docroot,\n scriptalias => $scriptalias,\n serveradmin => $serveradmin,\n access_log_file => "ssl_${access_log_file}",\n }\nSSL vhosts only respond to HTTPS queries.
\n\ndefault_ssl_cert
\n\nThe default SSL certification, which is automatically set based on your operating system (/etc/pki/tls/certs/localhost.crt for RedHat, /etc/ssl/certs/ssl-cert-snakeoil.pem for Debian, /usr/local/etc/apache22/server.crt for FreeBSD). This default will work out of the box but must be updated with your specific certificate information before being used in production.
default_ssl_key
\n\nThe default SSL key, which is automatically set based on your operating system (/etc/pki/tls/private/localhost.key for RedHat, /etc/ssl/private/ssl-cert-snakeoil.key for Debian, /usr/local/etc/apache22/server.key for FreeBSD). This default will work out of the box but must be updated with your specific certificate information before being used in production.
default_ssl_chain
\n\nThe default SSL chain, which is automatically set to 'undef'. This default will work out of the box but must be updated with your specific certificate information before being used in production.
\n\ndefault_ssl_ca
\n\nThe default certificate authority, which is automatically set to 'undef'. This default will work out of the box but must be updated with your specific certificate information before being used in production.
\n\ndefault_ssl_crl_path
\n\nThe default certificate revocation list path, which is automatically set to 'undef'. This default will work out of the box but must be updated with your specific certificate information before being used in production.
\n\ndefault_ssl_crl
\n\nThe default certificate revocation list to use, which is automatically set to 'undef'. This default will work out of the box but must be updated with your specific certificate information before being used in production.
\n\nservice_name
\n\nName of apache service to run. Defaults to: 'httpd' on RedHat, 'apache2' on Debian, and 'apache22' on FreeBSD.
service_enable
\n\nDetermines whether the 'httpd' service is enabled when the machine is booted. Defaults to 'true'.
\n\nservice_ensure
\n\nDetermines whether the service should be running. Can be set to 'undef' which is useful when you want to let the service be managed by some other application like pacemaker. Defaults to 'running'.
\n\npurge_configs
\n\nRemoves all other apache configs and vhosts, which is automatically set to true. Setting this to false is a stopgap measure to allow the apache module to coexist with existing or otherwise managed configuration. It is recommended that you move your configuration entirely to resources within this module.
\n\nserveradmin
\n\nSets the server administrator. Defaults to 'root@localhost'.
\n\nservername
\n\nSets the servername. Defaults to fqdn provided by facter.
\n\nserver_root
\n\nA value to be set as ServerRoot in main configuration file (httpd.conf). Defaults to /etc/httpd on RedHat, /etc/apache2 on Debian and /usr/local on FreeBSD.
sendfile
\n\nMakes Apache use the Linux kernel 'sendfile' to serve static files. Defaults to 'On'.
\n\nserver_root
\n\nA value to be set as ServerRoot in main configuration file (httpd.conf). Defaults to /etc/httpd on RedHat and /etc/apache2 on Debian.
error_documents
\n\nEnables custom error documents. Defaults to 'false'.
\n\nhttpd_dir
\n\nChanges the base location of the configuration directories used for the service. This is useful for specially repackaged HTTPD builds but may have unintended consequences when used in combination with the default distribution packages. Default is based on your OS.
\n\nconfd_dir
\n\nChanges the location of the configuration directory your custom configuration files are placed in. Default is based on your OS.
\n\nvhost_dir
\n\nChanges the location of the configuration directory your virtual host configuration files are placed in. Default is based on your OS.
\n\nmod_dir
\n\nChanges the location of the configuration directory your Apache modules configuration files are placed in. Default is based on your OS.
\n\nmpm_module
\n\nConfigures which mpm module is loaded and configured for the httpd process by the apache::mod::event, apache::mod::itk, apache::mod::peruser, apache::mod::prefork and apache::mod::worker classes. Must be set to false to explicitly declare apache::mod::event, apache::mod::itk, apache::mod::peruser, apache::mod::prefork or apache::mod::worker classes with parameters. All possible values are event, itk, peruser, prefork, worker (valid values depend on agent's OS), or the boolean false. Defaults to prefork on RedHat and FreeBSD and worker on Debian. Note: on FreeBSD switching between different mpm modules is quite difficult (but possible). Before changing $mpm_module one has to deinstall all packages that depend on currently installed apache.
conf_template
\n\nSetting this allows you to override the template used for the main apache configuration file. This is a potentially risky thing to do as this module has been built around the concept of a minimal configuration file with most of the configuration coming in the form of conf.d/ entries. Defaults to 'apache/httpd.conf.erb'.
\n\nkeepalive
\n\nSetting this allows you to enable persistent connections.
\n\nkeepalive_timeout
\n\nAmount of time the server will wait for subsequent requests on a persistent connection. Defaults to '15'.
\n\nlogroot
\n\nChanges the location of the directory Apache log files are placed in. Defaut is based on your OS.
\n\nlog_level
\n\nChanges the verbosity level of the error log. Defaults to 'warn'. Valid values are emerg, alert, crit, error, warn, notice, info or debug.
ports_file
\n\nChanges the name of the file containing Apache ports configuration. Default is ${conf_dir}/ports.conf.
server_tokens
\n\nControls how much information Apache sends to the browser about itself and the operating system. See Apache documentation for 'ServerTokens'. Defaults to 'OS'.
\n\nserver_signature
\n\nAllows the configuration of a trailing footer line under server-generated documents. See Apache documentation for 'ServerSignature'. Defaults to 'On'.
\n\ntrace_enable
\n\nControls, how TRACE requests per RFC 2616 are handled. See Apache documentation for 'TraceEnable'. Defaults to 'On'.
\n\nmanage_user
\n\nSetting this to false will avoid the user resource to be created by this module. This is useful when you already have a user created in another puppet module and that you want to used it to run apache. Without this, it would result in a duplicate resource error.
\n\nmanage_group
\n\nSetting this to false will avoid the group resource to be created by this module. This is useful when you already have a group created in another puppet module and that you want to used it for apache. Without this, it would result in a duplicate resource error.
\n\npackage_ensure
\n\nAllow control over the package ensure statement. This is useful if you want to make sure apache is always at the latest version or whether it is only installed.
\n\nClass: apache::default_mods
\n\nInstalls default Apache modules based on what OS you are running
\n\n class { 'apache::default_mods': }\nDefined Type: apache::mod
\n\nUsed to enable arbitrary Apache httpd modules for which there is no specific apache::mod::[name] class. The apache::mod defined type will also install the required packages to enable the module, if any.
apache::mod { 'rewrite': }\n apache::mod { 'ldap': }\nClasses: apache::mod::[name]
\n\nThere are many apache::mod::[name] classes within this module that can be declared using include:
- \n
alias\nauth_basic\nauth_kerb\nautoindex\ncache\ncgi\ncgid\ndav\ndav_fs\ndav_svn\ndeflate\ndev\ndir* \ndisk_cache\nevent\nfastcgi\nfcgid\nheaders\ninfo\nitk\nldap\nmime\nmime_magic* \nmpm_event\nnegotiation\nnss* \npassenger* \nperl\nperuser\nphp(requiresmpm_moduleset toprefork) \nprefork* \nproxy* \nproxy_ajp\nproxy_html\nproxy_http\npython\nreqtimeout\nrewrite\nrpaf* \nsetenvif\nssl* (see apache::mod::ssl below) \nstatus* \nsuphp\nuserdir* \nvhost_alias\nworker* \nwsgi(see apache::mod::wsgi below) \nxsendfile\n
Modules noted with a * indicate that the module has settings and, thus, a template that includes parameters. These parameters control the module's configuration. Most of the time, these parameters will not require any configuration or attention.
\n\nThe modules mentioned above, and other Apache modules that have templates, will cause template files to be dropped along with the mod install, and the module will not work without the template. Any mod without a template will install package but drop no files.
\n\nClass: apache::mod::ssl
\n\nInstalls Apache SSL capabilities and utilizes ssl.conf.erb template. These are the defaults:
class { 'apache::mod::ssl':\n ssl_compression => false,\n ssl_options => [ 'StdEnvVars' ],\n }\nTo use SSL with a virtual host, you must either set thedefault_ssl_vhost parameter in apache to 'true' or set the ssl parameter in apache::vhost to 'true'.
Class: apache::mod::wsgi
\n\n class { 'apache::mod::wsgi':\n wsgi_socket_prefix => "\\${APACHE_RUN_DIR}WSGI",\n wsgi_python_home => '/path/to/virtenv',\n wsgi_python_path => '/path/to/virtenv/site-packages',\n }\nDefined Type: apache::vhost
\n\nThe Apache module allows a lot of flexibility in the set up and configuration of virtual hosts. This flexibility is due, in part, to vhost's setup as a defined resource type, which allows it to be evaluated multiple times with different parameters.
The vhost defined type allows you to have specialized configurations for virtual hosts that have requirements outside of the defaults. You can set up a default vhost within the base apache class as well as set a customized vhost setup as default. Your customized vhost (priority 10) will be privileged over the base class vhost (15).
If you have a series of specific configurations and do not want a base apache class default vhost, make sure to set the base class default host to 'false'.
class { 'apache':\n default_vhost => false,\n }\nParameters within apache::vhost:
The default values for each parameter will vary based on operating system and type of virtual host.
\n\naccess_log
\n\nSpecifies whether *_access.log directives should be configured. Valid values are 'true' and 'false'. Defaults to 'true'.
access_log_file
\n\nPoints to the *_access.log file. Defaults to 'undef'.
access_log_pipe
\n\nSpecifies a pipe to send access log messages to. Defaults to 'undef'.
\n\naccess_log_syslog
\n\nSends all access log messages to syslog. Defaults to 'undef'.
\n\naccess_log_format
\n\nSpecifies either a LogFormat nickname or custom format string for access log. Defaults to 'undef'.
\n\nadd_listen
\n\nDetermines whether the vhost creates a listen statement. The default value is 'true'.
\n\nSetting add_listen to 'false' stops the vhost from creating a listen statement, and this is important when you combine vhosts that are not passed an ip parameter with vhosts that are passed the ip parameter.
aliases
\n\nPasses a list of hashes to the vhost to create Alias or AliasMatch statements as per the mod_alias documentation. Each hash is expected to be of the form:
aliases => [\n { aliasmatch => '^/image/(.*)\\.jpg$', path => '/files/jpg.images/$1.jpg' }\n { alias => '/image', path => '/ftp/pub/image' },\n],\nFor Alias and AliasMatch to work, each will need a corresponding <Directory /path/to/directory> or <Location /path/to/directory> block. The Alias and AliasMatch directives are created in the order specified in the aliases paramter. As described in the mod_alias documentation more specific Alias or AliasMatch directives should come before the more general ones to avoid shadowing.
Note: If apache::mod::passenger is loaded and PassengerHighPerformance true is set, then Alias may have issues honouring the PassengerEnabled off statement. See this article for details.
block
\n\nSpecifies the list of things Apache will block access to. The default is an empty set, '[]'. Currently, the only option is 'scm', which blocks web access to .svn, .git and .bzr directories. To add to this, please see the Development section.
\n\ncustom_fragment
\n\nPass a string of custom configuration directives to be placed at the end of the vhost configuration.
\n\ndefault_vhost
\n\nSets a given apache::vhost as the default to serve requests that do not match any other apache::vhost definitions. The default value is 'false'.
directories
\n\nPasses a list of hashes to the vhost to create <Directory /path/to/directory>...</Directory> directive blocks as per the Apache core documentation. The path key is required in these hashes. An optional provider defaults to directory. Usage will typically look like:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [\n { path => '/path/to/directory', <directive> => <value> },\n { path => '/path/to/another/directory', <directive> => <value> },\n ],\n }\nNote: At least one directory should match docroot parameter, once you start declaring directories apache::vhost assumes that all required <Directory> blocks will be declared.
Note: If not defined a single default <Directory> block will be created that matches the docroot parameter.
provider can be set to any of directory, files, or location. If the pathspec starts with a ~, httpd will interpret this as the equivalent of DirectoryMatch, FilesMatch, or LocationMatch, respectively.
apache::vhost { 'files.example.net':\n docroot => '/var/www/files',\n directories => [\n { path => '~ (\\.swp|\\.bak|~)$', 'provider' => 'files', 'deny' => 'from all' },\n ],\n }\nThe directives will be embedded within the Directory (Files, or Location) directive block, missing directives should be undefined and not be added, resulting in their default vaules in Apache. Currently this is the list of supported directives:
addhandlers
\n\nSets AddHandler directives as per the Apache Core documentation. Accepts a list of hashes of the form { handler => 'handler-name', extensions => ['extension']}. Note that extensions is a list of extenstions being handled by the handler.\nAn example:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory',\n addhandlers => [ { handler => 'cgi-script', extensions => ['.cgi']} ],\n } ],\n }\nallow
\n\nSets an Allow directive as per the Apache Core documentation. An example:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', allow => 'from example.org' } ],\n }\nallow_override
\n\nSets the usage of .htaccess files as per the Apache core documentation. Should accept in the form of a list or a string. An example:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', allow_override => ['AuthConfig', 'Indexes'] } ],\n }\ndeny
\n\nSets an Deny directive as per the Apache Core documentation. An example:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', deny => 'from example.org' } ],\n }\nerror_documents
\n\nA list of hashes which can be used to override the ErrorDocument settings for this directory. Example:
\n\n apache::vhost { 'sample.example.net':\n directories => [ { path => '/srv/www'\n error_documents => [\n { 'error_code' => '503', 'document' => '/service-unavail' },\n ],\n }]\n }\nheaders
\n\nAdds lines for Header directives as per the Apache Header documentation. An example:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => {\n path => '/path/to/directory',\n headers => 'Set X-Robots-Tag "noindex, noarchive, nosnippet"',\n },\n }\noptions
\n\nLists the options for the given <Directory> block
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', options => ['Indexes','FollowSymLinks','MultiViews'] }],\n }\nindex_options
\n\nStyles the list
\n\n apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', options => ['Indexes','FollowSymLinks','MultiViews'], index_options => ['IgnoreCase', 'FancyIndexing', 'FoldersFirst', 'NameWidth=*', 'DescriptionWidth=*', 'SuppressHTMLPreamble'] }],\n }\nindex_order_default
\n\nSets the order of the list
\n\n apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', order => 'Allow,Deny', index_order_default => ['Descending', 'Date']}, ],\n }\norder
\n\nSets the order of processing Allow and Deny statements as per Apache core documentation. An example:
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', order => 'Allow,Deny' } ],\n }\nauth_type
\n\nSets the value for AuthType as per the Apache AuthType\ndocumentation.
auth_name
\n\nSets the value for AuthName as per the Apache AuthName\ndocumentation.
auth_digest_algorithm
\n\nSets the value for AuthDigestAlgorithm as per the Apache\nAuthDigestAlgorithm\ndocumentation
auth_digest_domain
\n\nSets the value for AuthDigestDomain as per the Apache AuthDigestDomain\ndocumentation.
auth_digest_nonce_lifetime
\n\nSets the value for AuthDigestNonceLifetime as per the Apache\nAuthDigestNonceLifetime\ndocumentation
auth_digest_provider
\n\nSets the value for AuthDigestProvider as per the Apache AuthDigestProvider\ndocumentation.
auth_digest_qop
\n\nSets the value for AuthDigestQop as per the Apache AuthDigestQop\ndocumentation.
auth_digest_shmem_size
\n\nSets the value for AuthAuthDigestShmemSize as per the Apache AuthDigestShmemSize\ndocumentation.
auth_basic_authoritative
\n\nSets the value for AuthBasicAuthoritative as per the Apache\nAuthBasicAuthoritative\ndocumentation.
auth_basic_fake
\n\nSets the value for AuthBasicFake as per the Apache AuthBasicFake\ndocumentation.
auth_basic_provider
\n\nSets the value for AuthBasicProvider as per the Apache AuthBasicProvider\ndocumentation.
auth_user_file
\n\nSets the value for AuthUserFile as per the Apache AuthUserFile\ndocumentation.
auth_require
\n\nSets the value for AuthName as per the Apache Require\ndocumentation
passenger_enabled
\n\nSets the value for the PassengerEnabled directory to on or off as per the Passenger documentation.
apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n directories => [ { path => '/path/to/directory', passenger_enabled => 'off' } ],\n }\nNote: This directive requires apache::mod::passenger to be active, Apache may not start with an unrecognised directive without it.
Note: Be aware that there is an issue using the PassengerEnabled directive with the PassengerHighPerformance directive.
ssl_options
\n\nString or list of SSLOptions for the given <Directory> block. This overrides, or refines the SSLOptions of the parent block (either vhost, or server).
apache::vhost { 'secure.example.net':\n docroot => '/path/to/directory',\n directories => [\n { path => '/path/to/directory', ssl_options => '+ExportCertData' }\n { path => '/path/to/different/dir', ssl_options => [ '-StdEnvVars', '+ExportCertData'] },\n ],\n }\nsuphp
\n\nAn array containing two values: User and group for the suPHP_UserGroup setting.\nThis directive must be used with suphp_engine => on in the vhost declaration. This directive only works in <Directory> or <Location>.
apache::vhost { 'secure.example.net':\n docroot => '/path/to/directory',\n directories => [\n { path => '/path/to/directory', suphp => { user => 'myappuser', group => 'myappgroup' }\n ],\n }\ncustom_fragment
\n\nPass a string of custom configuration directives to be placed at the end of the\ndirectory configuration.
\n\ndirectoryindex
\n\nSet a DirectoryIndex directive, to set the list of resources to look for, when the client requests an index of the directory by specifying a / at the end of the directory name..
\n\ndocroot
\n\nProvides the DocumentRoot directive, identifying the directory Apache serves files from.
\n\ndocroot_group
\n\nSets group access to the docroot directory. Defaults to 'root'.
\n\ndocroot_owner
\n\nSets individual user access to the docroot directory. Defaults to 'root'.
\n\nerror_log
\n\nSpecifies whether *_error.log directives should be configured. Defaults to 'true'.
error_log_file
\n\nPoints to the *_error.log file. Defaults to 'undef'.
error_log_pipe
\n\nSpecifies a pipe to send error log messages to. Defaults to 'undef'.
\n\nerror_log_syslog
\n\nSends all error log messages to syslog. Defaults to 'undef'.
\n\nerror_documents
\n\nA list of hashes which can be used to override the ErrorDocument settings for this vhost. Defaults to []. Example:
apache::vhost { 'sample.example.net':\n error_documents => [\n { 'error_code' => '503', 'document' => '/service-unavail' },\n { 'error_code' => '407', 'document' => 'https://example.com/proxy/login' },\n ],\n }\nensure
\n\nSpecifies if the vhost file is present or absent.
\n\nfastcgi_server
\n\nSpecifies the filename as an external FastCGI application. Defaults to 'undef'.
\n\nfastcgi_socket
\n\nFilename used to communicate with the web server. Defaults to 'undef'.
\n\nfastcgi_dir
\n\nDirectory to enable for FastCGI. Defaults to 'undef'.
\n\nadditional_includes
\n\nSpecifies paths to additional static vhost-specific Apache configuration files.\nThis option is useful when you need to implement a unique and/or custom\nconfiguration not supported by this module.
\n\nip
\n\nThe IP address the vhost listens on. Defaults to 'undef'.
\n\nip_based
\n\nEnables an IP-based vhost. This parameter inhibits the creation of a NameVirtualHost directive, since those are used to funnel requests to name-based vhosts. Defaults to 'false'.
\n\nlogroot
\n\nSpecifies the location of the virtual host's logfiles. Defaults to /var/log/<apache log location>/.
log_level
\n\nSpecifies the verbosity level of the error log. Defaults to warn for the global server configuration and can be overridden on a per-vhost basis using this parameter. Valid value for log_level is one of emerg, alert, crit, error, warn, notice, info or debug.
no_proxy_uris
\n\nSpecifies URLs you do not want to proxy. This parameter is meant to be used in combination with proxy_dest.
options
\n\nLists the options for the given virtual host
\n\n apache::vhost { 'site.name.fdqn':\n …\n options => ['Indexes','FollowSymLinks','MultiViews'],\n }\noverride
\n\nSets the overrides for the given virtual host. Accepts an array of AllowOverride arguments.
\n\nport
\n\nSets the port the host is configured on.
\n\npriority
\n\nSets the relative load-order for Apache httpd VirtualHost configuration files. Defaults to '25'.
\n\nIf nothing matches the priority, the first name-based vhost will be used. Likewise, passing a higher priority will cause the alphabetically first name-based vhost to be used if no other names match.
\n\nNote: 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'.
proxy_dest
\n\nSpecifies the destination address of a proxypass configuration. Defaults to 'undef'.
\n\nproxy_pass
\n\nSpecifies an array of path => uri for a proxypass configuration. Defaults to 'undef'.
\n\nExample:
\n\n$proxy_pass = [\n { 'path' => '/a', 'url' => 'http://backend-a/' },\n { 'path' => '/b', 'url' => 'http://backend-b/' },\n { 'path' => '/c', 'url' => 'http://backend-a/c' }\n]\n\napache::vhost { 'site.name.fdqn':\n …\n proxy_pass => $proxy_pass,\n}\nrack_base_uris
\n\nSpecifies the resource identifiers for a rack configuration. The file paths specified will be listed as rack application roots for passenger/rack in the _rack.erb template. Defaults to 'undef'.
redirect_dest
\n\nSpecifies the address to redirect to. Defaults to 'undef'.
\n\nredirect_source
\n\nSpecifies the source items? that will 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.
apache::vhost { 'site.name.fdqn':\n …\n redirect_source => ['/images','/downloads'],\n redirect_dest => ['http://img.example.com/','http://downloads.example.com/'],\n }\nredirect_status
\n\nSpecifies the status to append to the redirect. Defaults to 'undef'.
\n\n apache::vhost { 'site.name.fdqn':\n …\n redirect_status => ['temp','permanent'],\n }\nrequest_headers
\n\nSpecifies additional request headers.
\n\n apache::vhost { 'site.name.fdqn':\n …\n request_headers => [\n 'append MirrorID "mirror 12"',\n 'unset MirrorID',\n ],\n }\nrewrite_base
\n\nLimits the rewrite_rule to the specified base URL. Defaults to 'undef'.
apache::vhost { 'site.name.fdqn':\n …\n rewrite_rule => '^index\\.html$ welcome.html',\n rewrite_base => '/blog/',\n }\nThe above example would limit the index.html -> welcome.html rewrite to only something inside of http://example.com/blog/.
\n\nrewrite_cond
\n\nRewrites a URL via rewrite_rule based on the truth of specified conditions. For example
apache::vhost { 'site.name.fdqn':\n …\n rewrite_cond => '%{HTTP_USER_AGENT} ^MSIE',\n }\nwill rewrite URLs only if the visitor is using IE. Defaults to 'undef'.
\n\nNote: At the moment, each vhost is limited to a single list of rewrite conditions. In the future, you will be able to specify multiple rewrite_cond and rewrite_rules per vhost, so that different conditions get different rewrites.
rewrite_rule
\n\nCreates URL rewrite rules. Defaults to 'undef'. This parameter allows you to specify, for example, that anyone trying to access index.html will be served welcome.html.
\n\n apache::vhost { 'site.name.fdqn':\n …\n rewrite_rule => '^index\\.html$ welcome.html',\n }\nscriptalias
\n\nDefines a directory of CGI scripts to be aliased to the path '/cgi-bin'
\n\nscriptaliases
\n\nPasses a list of hashes to the vhost to create ScriptAlias or ScriptAliasMatch statements as per the mod_alias documentation. Each hash is expected to be of the form:
scriptaliases => [\n {\n alias => '/myscript',\n path => '/usr/share/myscript',\n },\n {\n aliasmatch => '^/foo(.*)',\n path => '/usr/share/fooscripts$1',\n },\n {\n aliasmatch => '^/bar/(.*)',\n path => '/usr/share/bar/wrapper.sh/$1',\n },\n {\n alias => '/neatscript',\n path => '/usr/share/neatscript',\n },\n ]\nThese directives are created in the order specified. As with Alias and AliasMatch directives the more specific aliases should come before the more general ones to avoid shadowing.
serveradmin
\n\nSpecifies the email address Apache will display when it renders one of its error pages.
\n\nserveraliases
\n\nSets the server aliases of the site.
\n\nservername
\n\nSets the primary name of the virtual host.
\n\nsetenv
\n\nUsed by HTTPD to set environment variables for vhosts. Defaults to '[]'.
\n\nsetenvif
\n\nUsed by HTTPD to conditionally set environment variables for vhosts. Defaults to '[]'.
\n\nssl
\n\nEnables SSL for the virtual host. SSL vhosts only respond to HTTPS queries. Valid values are 'true' or 'false'.
\n\nssl_ca
\n\nSpecifies the certificate authority.
\n\nssl_cert
\n\nSpecifies the SSL certification.
\n\nssl_protocol
\n\nSpecifies the SSL Protocol (SSLProtocol).
\n\nssl_cipher
\n\nSpecifies the SSLCipherSuite.
\n\nssl_honorcipherorder
\n\nSets SSLHonorCipherOrder directive, used to prefer the server's cipher preference order
\n\nssl_certs_dir
\n\nSpecifies the location of the SSL certification directory. Defaults to /etc/ssl/certs on Debian and /etc/pki/tls/certs on RedHat.
ssl_chain
\n\nSpecifies the SSL chain.
\n\nssl_crl
\n\nSpecifies the certificate revocation list to use.
\n\nssl_crl_path
\n\nSpecifies the location of the certificate revocation list.
\n\nssl_key
\n\nSpecifies the SSL key.
\n\nssl_verify_client
\n\nSets SSLVerifyClient directives as per the Apache Core documentation. Defaults to undef.\nAn example:
apache::vhost { 'sample.example.net':\n …\n ssl_verify_client => 'optional',\n }\nssl_verify_depth
\n\nSets SSLVerifyDepth directives as per the Apache Core documentation. Defaults to undef.\nAn example:
apache::vhost { 'sample.example.net':\n …\n ssl_verify_depth => 1,\n }\nssl_options
\n\nSets SSLOptions directives as per the Apache Core documentation. This is the global setting for the vhost and can be a string or an array. Defaults to undef. A single string example:
apache::vhost { 'sample.example.net':\n …\n ssl_options => '+ExportCertData',\n }\nAn array of strings example:
\n\n apache::vhost { 'sample.example.net':\n …\n ssl_options => [ '+StrictRequire', '+ExportCertData' ],\n }\nssl_proxyengine
\n\nSpecifies whether to use SSLProxyEngine or not. Defaults to false.
vhost_name
\n\nThis parameter is for use with name-based virtual hosting. Defaults to '*'.
\n\nitk
\n\nHash containing infos to configure itk as per the ITK documentation.
\n\nKeys could be:
\n\n- \n
- user + group \n
- assignuseridexpr \n
- assigngroupidexpr \n
- maxclientvhost \n
- nice \n
- limituidrange (Linux 3.5.0 or newer) \n
- limitgidrange (Linux 3.5.0 or newer) \n
Usage will typically look like:
\n\n apache::vhost { 'sample.example.net':\n docroot => '/path/to/directory',\n itk => {\n user => 'someuser',\n group => 'somegroup',\n },\n }\nVirtual Host Examples
\n\nThe Apache module allows you to set up pretty much any configuration of virtual host you might desire. This section will address some common configurations. Please see the Tests section for even more examples.
\n\nConfigure a vhost with a server administrator
\n\n apache::vhost { 'third.example.com':\n port => '80',\n docroot => '/var/www/third',\n serveradmin => 'admin@example.com',\n }\n\n\n
Set up a vhost with aliased servers
\n\n apache::vhost { 'sixth.example.com':\n serveraliases => [\n 'sixth.example.org',\n 'sixth.example.net',\n ],\n port => '80',\n docroot => '/var/www/fifth',\n }\n\n\n
Configure a vhost with a cgi-bin
\n\n apache::vhost { 'eleventh.example.com':\n port => '80',\n docroot => '/var/www/eleventh',\n scriptalias => '/usr/lib/cgi-bin',\n }\n\n\n
Set up a vhost with a rack configuration
\n\n apache::vhost { 'fifteenth.example.com':\n port => '80',\n docroot => '/var/www/fifteenth',\n rack_base_uris => ['/rackapp1', '/rackapp2'],\n }\n\n\n
Set up a mix of SSL and non-SSL vhosts at the same domain
\n\n #The non-ssl vhost\n apache::vhost { 'first.example.com non-ssl':\n servername => 'first.example.com',\n port => '80',\n docroot => '/var/www/first',\n }\n\n #The SSL vhost at the same domain\n apache::vhost { 'first.example.com ssl':\n servername => 'first.example.com',\n port => '443',\n docroot => '/var/www/first',\n ssl => true,\n }\n\n\n
Configure a vhost to redirect non-SSL connections to SSL
\n\n apache::vhost { 'sixteenth.example.com non-ssl':\n servername => 'sixteenth.example.com',\n port => '80',\n docroot => '/var/www/sixteenth',\n redirect_status => 'permanent'\n redirect_dest => 'https://sixteenth.example.com/'\n }\n apache::vhost { 'sixteenth.example.com ssl':\n servername => 'sixteenth.example.com',\n port => '443',\n docroot => '/var/www/sixteenth',\n ssl => true,\n }\n\n\n
Set up IP-based vhosts on any listen port and have them respond to requests on specific IP addresses. In this example, we will set listening on ports 80 and 81. This is required because the example vhosts are not declared with a port parameter.
\n\n apache::listen { '80': }\n apache::listen { '81': }\nThen we will set up the IP-based vhosts
\n\n apache::vhost { 'first.example.com':\n ip => '10.0.0.10',\n docroot => '/var/www/first',\n ip_based => true,\n }\n apache::vhost { 'second.example.com':\n ip => '10.0.0.11',\n docroot => '/var/www/second',\n ip_based => true,\n }\n\n\n
Configure a mix of name-based and IP-based vhosts. First, we will add two IP-based vhosts on 10.0.0.10, one SSL and one non-SSL
\n\n apache::vhost { 'The first IP-based vhost, non-ssl':\n servername => 'first.example.com',\n ip => '10.0.0.10',\n port => '80',\n ip_based => true,\n docroot => '/var/www/first',\n }\n apache::vhost { 'The first IP-based vhost, ssl':\n servername => 'first.example.com',\n ip => '10.0.0.10',\n port => '443',\n ip_based => true,\n docroot => '/var/www/first-ssl',\n ssl => true,\n }\nThen, we will add two name-based vhosts listening on 10.0.0.20
\n\n apache::vhost { 'second.example.com':\n ip => '10.0.0.20',\n port => '80',\n docroot => '/var/www/second',\n }\n apache::vhost { 'third.example.com':\n ip => '10.0.0.20',\n port => '80',\n docroot => '/var/www/third',\n }\nIf you want to add two name-based vhosts so that they will answer on either 10.0.0.10 or 10.0.0.20, you MUST declare add_listen => 'false' to disable the otherwise automatic 'Listen 80', as it will conflict with the preceding IP-based vhosts.
apache::vhost { 'fourth.example.com':\n port => '80',\n docroot => '/var/www/fourth',\n add_listen => false,\n }\n apache::vhost { 'fifth.example.com':\n port => '80',\n docroot => '/var/www/fifth',\n add_listen => false,\n }\nImplementation
\n\nClasses and Defined Types
\n\nClass: apache::dev
\n\nInstalls Apache development libraries
\n\n class { 'apache::dev': }\nOn FreeBSD you're required to define apache::package or apache class before apache::dev.
Defined Type: apache::listen
\n\nControls which ports Apache binds to for listening based on the title:
\n\n apache::listen { '80': }\n apache::listen { '443': }\nDeclaring this defined type will add all Listen directives to the ports.conf file in the Apache httpd configuration directory. apache::listen titles should always take the form of: <port>, <ipv4>:<port>, or [<ipv6>]:<port>
Apache httpd requires that Listen directives must be added for every port. The apache::vhost defined type will automatically add Listen directives unless the apache::vhost is passed add_listen => false.
Defined Type: apache::namevirtualhost
\n\nEnables named-based hosting of a virtual host
\n\n class { 'apache::namevirtualhost`: }\nDeclaring this defined type will add all NameVirtualHost directives to the ports.conf file in the Apache https configuration directory. apache::namevirtualhost titles should always take the form of: *, *:<port>, _default_:<port>, <ip>, or <ip>:<port>.
Defined Type: apache::balancermember
\n\nDefine members of a proxy_balancer set (mod_proxy_balancer). Very useful when using exported resources.
\n\nOn every app server you can export a balancermember like this:
\n\n @@apache::balancermember { "${::fqdn}-puppet00":\n balancer_cluster => 'puppet00',\n url => "ajp://${::fqdn}:8009"\n options => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],\n }\nAnd on the proxy itself you create the balancer cluster using the defined type apache::balancer:
\n\n apache::balancer { 'puppet00': }\nIf you need to use ProxySet in the balncer config you can do as so:
\n\n apache::balancer { 'puppet01':\n proxy_set => {'stickysession' => 'JSESSIONID'},\n }\nTemplates
\n\nThe Apache module relies heavily on templates to enable the vhost and apache::mod defined types. These templates are built based on Facter facts around your operating system. Unless explicitly called out, most templates are not meant for configuration.
Limitations
\n\nThis has been tested on Ubuntu Precise, Debian Wheezy, CentOS 5.8, and FreeBSD 9.1.
\n\nDevelopment
\n\nOverview
\n\nPuppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
\n\nWe want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
\n\nYou can read the complete module contribution guide on the Puppet Labs wiki.
\n\nRunning tests
\n\nThis project contains tests for both rspec-puppet and rspec-system to verify functionality. For in-depth information please see their respective documentation.
\n\nQuickstart:
\n\ngem install bundler\nbundle install\nbundle exec rake spec\nbundle exec rake spec:system\nCopyright and License
\n\nCopyright (C) 2012 Puppet Labs Inc
\n\nPuppet Labs can be contacted at: info@puppetlabs.com
\n\nLicensed under the Apache License, Version 2.0 (the "License");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at
\n\nhttp://www.apache.org/licenses/LICENSE-2.0
\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an "AS IS" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.
\n