Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

apache

Installs, configures, and manages Apache virtual hosts, web services, and modules.
Project URLRSS FeedReport issues

11,485,443 downloads

1,584 latest version

4.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 12.2.0 (latest)
  • 12.1.0
  • 12.0.3
  • 12.0.2
  • 12.0.1
  • 12.0.0
  • 11.1.0
  • 11.0.0
  • 10.1.1
  • 10.1.0
  • 10.0.0
  • 9.1.3
  • 9.1.2
  • 9.1.1
  • 9.1.0
  • 9.0.1
  • 9.0.0
  • 8.6.0
  • 8.5.0
  • 8.4.0
  • 8.3.0
  • 8.2.1
  • 8.2.0
  • 8.1.0
  • 8.0.0
  • 7.0.0
  • 6.5.1
  • 6.5.0
  • 6.4.0
  • 6.3.1
  • 6.3.0
  • 6.2.0
  • 6.1.0
  • 6.0.1
  • 6.0.0
  • 5.10.0
  • 5.9.0
  • 5.8.0
  • 5.7.0
  • 5.6.0
  • 5.5.0
  • 5.4.0
  • 5.3.0
  • 5.2.0
  • 5.1.0
  • 5.0.0
  • 4.1.0
  • 4.0.0
  • 3.5.0
  • 3.4.0
  • 3.3.0
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.3.1
  • 2.3.0
  • 2.2.0
  • 2.1.0
  • 2.0.0
  • 1.11.1
  • 1.11.0
  • 1.10.0
  • 1.9.0 (deleted)
  • 1.8.1
  • 1.8.0
  • 1.7.1
  • 1.7.0
  • 1.6.0
  • 1.5.0
  • 1.4.1
  • 1.4.0
  • 1.3.0
  • 1.2.0
  • 1.1.1
  • 1.1.0
  • 1.0.1
  • 1.0.0
  • 0.11.0
  • 0.10.0
  • 0.9.0
  • 0.8.1
  • 0.8.0
  • 0.7.0
  • 0.6.0
  • 0.5.0-rc1 (pre-release)
  • 0.4.0
  • 0.3.0
  • 0.2.2
  • 0.2.1
  • 0.2.0
  • 0.1.1
  • 0.0.4
  • 0.0.3 (deleted)
  • 0.0.2 (deleted)
  • 0.0.1 (deleted)
released Nov 1st 2019
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
  • Puppet >= 5.5.10 < 7.0.0
  • , , , , , ,
Tasks:
  • apache

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-apache', '5.2.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-apache
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-apache --version 5.2.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: apache, debian, web, virtualhost, passenger, proxy, ubuntu, ssl, rhel, apache2, httpd, centos, wsgi, virtual-host

Documentation

puppetlabs/apache — version 5.2.0 Nov 1st 2019

apache

Table of Contents

  1. Module description - What is the apache module, and what does it do?
  2. Setup - The basics of getting started with apache
  3. Usage - The classes and defined types available for configuration
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module

Module description

Apache HTTP Server (also called Apache HTTPD, or simply Apache) is a widely used web server. This Puppet module simplifies the task of creating configurations to manage Apache servers in your infrastructure. It can configure and manage a range of virtual host setups and provides a streamlined way to install and configure Apache modules.

Setup

What the apache module affects:

  • Configuration files and directories (created and written to)
    • WARNING: Configurations not managed by Puppet will be purged.
  • Package/service/configuration files for Apache
  • Apache modules
  • Virtual hosts
  • Listened-to ports
  • /etc/make.conf on FreeBSD and Gentoo

On Gentoo, this module depends on the gentoo/puppet-portage Puppet module. Note that while several options apply or enable certain features and settings for Gentoo, it is not a supported operating system for this module.

Warning: This module modifies Apache configuration files and directories and purges any configuration not managed by Puppet. Apache configuration should be managed by Puppet, as unmanaged configuration files can cause unexpected failures.

To temporarily disable full Puppet management, set the purge_configs parameter in the apache class declaration to false. We recommend this only as a temporary means of saving and relocating customized configurations.

Beginning with Apache

To have Puppet install Apache with the default parameters, declare the apache class:

class { 'apache': }

When you declare this class with the default options, the module:

  • Installs the appropriate Apache software package and required Apache modules for your operating system.
  • Places the required configuration files in a directory, with the default location Depends on operating system.
  • Configures the server with a default virtual host and standard port ('80') and address ('*') bindings.
  • Creates a document root directory Depends on operating system, typically /var/www.
  • Starts the Apache service.

Apache defaults depend on your operating system. These defaults work in testing environments but are not suggested for production. We recommend customizing the class's parameters to suit your site.

For instance, this declaration installs Apache without the apache module's default virtual host configuration, allowing you to customize all Apache virtual hosts:

class { 'apache':
  default_vhost => false,
}

Note: When default_vhost is set to false, you have to add at least one apache::vhost resource or Apache will not start. To establish a default virtual host, either set the default_vhost in the apache class or use the apache::vhost defined type. You can also configure additional specific virtual hosts with the apache::vhost defined type.

Usage

Configuring virtual hosts

The default apache class sets up a virtual host on port 80, listening on all interfaces and serving the docroot parameter's default directory of /var/www.

To configure basic name-based virtual hosts, specify the port and docroot parameters in the apache::vhost defined type:

apache::vhost { 'vhost.example.com':
  port    => '80',
  docroot => '/var/www/vhost',
}

See the apache::vhost defined type's reference for a list of all virtual host parameters.

Note: Apache processes virtual hosts in alphabetical order, and server administrators can prioritize Apache's virtual host processing by prefixing a virtual host's configuration file name with a number. The apache::vhost defined type applies a default priority of 25, which Puppet interprets by prefixing the virtual host's file name with 25-. This means that if multiple sites have the same priority, or if you disable priority numbers by setting the priority parameter's value to false, Apache still processes virtual hosts in alphabetical order.

To configure user and group ownership for docroot, use the docroot_owner and docroot_group parameters:

apache::vhost { 'user.example.com':
  port          => '80',
  docroot       => '/var/www/user',
  docroot_owner => 'www-data',
  docroot_group => 'www-data',
}

Configuring virtual hosts with SSL

To configure a virtual host to use SSL encryption and default SSL certificates, set the ssl parameter. You must also specify the port parameter, typically with a value of '443', to accommodate HTTPS requests:

apache::vhost { 'ssl.example.com':
  port    => '443',
  docroot => '/var/www/ssl',
  ssl     => true,
}

To configure a virtual host to use SSL and specific SSL certificates, use the paths to the certificate and key in the ssl_cert and ssl_key parameters, respectively:

apache::vhost { 'cert.example.com':
  port     => '443',
  docroot  => '/var/www/cert',
  ssl      => true,
  ssl_cert => '/etc/ssl/fourth.example.com.cert',
  ssl_key  => '/etc/ssl/fourth.example.com.key',
}

To configure a mix of SSL and unencrypted virtual hosts at the same domain, declare them with separate apache::vhost defined types:

# The non-ssl virtual host
apache::vhost { 'mix.example.com non-ssl':
  servername => 'mix.example.com',
  port       => '80',
  docroot    => '/var/www/mix',
}

# The SSL virtual host at the same domain
apache::vhost { 'mix.example.com ssl':
  servername => 'mix.example.com',
  port       => '443',
  docroot    => '/var/www/mix',
  ssl        => true,
}

To configure a virtual host to redirect unencrypted connections to SSL, declare them with separate apache::vhost defined types and redirect unencrypted requests to the virtual host with SSL enabled:

apache::vhost { 'redirect.example.com non-ssl':
  servername      => 'redirect.example.com',
  port            => '80',
  docroot         => '/var/www/redirect',
  redirect_status => 'permanent',
  redirect_dest   => 'https://redirect.example.com/'
}

apache::vhost { 'redirect.example.com ssl':
  servername => 'redirect.example.com',
  port       => '443',
  docroot    => '/var/www/redirect',
  ssl        => true,
}

Configuring virtual host port and address bindings

Virtual hosts listen on all IP addresses ('*') by default. To configure the virtual host to listen on a specific IP address, use the ip parameter:

apache::vhost { 'ip.example.com':
  ip      => '127.0.0.1',
  port    => '80',
  docroot => '/var/www/ip',
}

You can also configure more than one IP address per virtual host by using an array of IP addresses for the ip parameter:

apache::vhost { 'ip.example.com':
  ip      => ['127.0.0.1','169.254.1.1'],
  port    => '80',
  docroot => '/var/www/ip',
}

You can configure multiple ports per virtual host by using an array of ports for the port parameter:

apache::vhost { 'ip.example.com':
  ip      => ['127.0.0.1'],
  port    => ['80','8080']
  docroot => '/var/www/ip',
}

To configure a virtual host with aliased servers, refer to the aliases using the serveraliases parameter:

apache::vhost { 'aliases.example.com':
  serveraliases => [
    'aliases.example.org',
    'aliases.example.net',
  ],
  port          => '80',
  docroot       => '/var/www/aliases',
}

To set up a virtual host with a wildcard alias for the subdomain mapped to a directory of the same name, such as '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:

apache::vhost { 'subdomain.loc':
  vhost_name      => '*',
  port            => '80',
  virtual_docroot => '/var/www/%-2+',
  docroot         => '/var/www',
  serveraliases   => ['*.loc',],
}

To configure a virtual host with filter rules, pass the filter directives as an array using the filters parameter:

apache::vhost { 'subdomain.loc':
  port    => '80',
  filters => [
    'FilterDeclare  COMPRESS',
    'FilterProvider COMPRESS DEFLATE resp=Content-Type $text/html',
    'FilterChain    COMPRESS',
    'FilterProtocol COMPRESS DEFLATE change=yes;byteranges=no',
  ],
  docroot => '/var/www/html',
}

Configuring virtual hosts for apps and processors

To set up a virtual host with suPHP, use the following parameters:

For example:

apache::vhost { 'suphp.example.com':
  port             => '80',
  docroot          => '/home/appuser/myphpapp',
  suphp_addhandler => 'x-httpd-php',
  suphp_engine     => 'on',
  suphp_configpath => '/etc/php5/apache2',
  directories      => [
    { 'path'  => '/home/appuser/myphpapp',
      'suphp' => {
        user  => 'myappuser',
        group => 'myappgroup',
      },
    },
  ],
}

To configure a virtual host to use the Web Server Gateway Interface (WSGI) for Python applications, use the wsgi set of parameters:

apache::vhost { 'wsgi.example.com':
  port                        => '80',
  docroot                     => '/var/www/pythonapp',
  wsgi_application_group      => '%{GLOBAL}',
  wsgi_daemon_process         => 'wsgi',
  wsgi_daemon_process_options => {
    processes    => '2',
    threads      => '15',
    display-name => '%{GROUP}',
  },
  wsgi_import_script          => '/var/www/demo.wsgi',
  wsgi_import_script_options  => {
    process-group     => 'wsgi',
    application-group => '%{GLOBAL}',
  },
  wsgi_process_group          => 'wsgi',
  wsgi_script_aliases         => { '/' => '/var/www/demo.wsgi' },
}

As of Apache 2.2.16, Apache supports FallbackResource, a simple replacement for common RewriteRules. You can set a FallbackResource using the fallbackresource parameter:

apache::vhost { 'wordpress.example.com':
  port             => '80',
  docroot          => '/var/www/wordpress',
  fallbackresource => '/index.php',
}

Note: The fallbackresource parameter only supports the 'disabled' value since Apache 2.2.24.

To configure a virtual host with a designated directory for Common Gateway Interface (CGI) files, use the scriptalias parameter to define the cgi-bin path:

apache::vhost { 'cgi.example.com':
  port        => '80',
  docroot     => '/var/www/cgi',
  scriptalias => '/usr/lib/cgi-bin',
}

To configure a virtual host for Rack, use the rack_base_uris parameter:

apache::vhost { 'rack.example.com':
  port           => '80',
  docroot        => '/var/www/rack',
  rack_base_uris => ['/rackapp1', '/rackapp2'],
}

Configuring IP-based virtual hosts

You can configure IP-based virtual hosts to listen on any port and have them respond to requests on specific IP addresses. In this example, the server listens on ports 80 and 81, because the example virtual hosts are not declared with a port parameter:

apache::listen { '80': }

apache::listen { '81': }

Configure the IP-based virtual hosts with the ip_based parameter:

apache::vhost { 'first.example.com':
  ip       => '10.0.0.10',
  docroot  => '/var/www/first',
  ip_based => true,
}

apache::vhost { 'second.example.com':
  ip       => '10.0.0.11',
  docroot  => '/var/www/second',
  ip_based => true,
}

You can also configure a mix of IP- and name-based virtual hosts in any combination of SSL and unencrypted configurations.

In this example, we add two IP-based virtual hosts on an IP address (in this example, 10.0.0.10). One uses SSL and the other is unencrypted:

apache::vhost { 'The first IP-based virtual host, non-ssl':
  servername => 'first.example.com',
  ip         => '10.0.0.10',
  port       => '80',
  ip_based   => true,
  docroot    => '/var/www/first',
}

apache::vhost { 'The first IP-based vhost, ssl':
  servername => 'first.example.com',
  ip         => '10.0.0.10',
  port       => '443',
  ip_based   => true,
  docroot    => '/var/www/first-ssl',
  ssl        => true,
}

Next, we add two name-based virtual hosts listening on a second IP address (10.0.0.20):

apache::vhost { 'second.example.com':
  ip      => '10.0.0.20',
  port    => '80',
  docroot => '/var/www/second',
}

apache::vhost { 'third.example.com':
  ip      => '10.0.0.20',
  port    => '80',
  docroot => '/var/www/third',
}

To add name-based virtual hosts that answer on either 10.0.0.10 or 10.0.0.20, you must disable the Apache default Listen 80, as it conflicts with the preceding IP-based virtual hosts. To do this, set the add_listen parameter to false:

apache::vhost { 'fourth.example.com':
  port       => '80',
  docroot    => '/var/www/fourth',
  add_listen => false,
}

apache::vhost { 'fifth.example.com':
  port       => '80',
  docroot    => '/var/www/fifth',
  add_listen => false,
}

Installing Apache modules

There are two ways to install Apache modules using the Puppet apache module:

Installing specific modules

The Puppet apache module supports installing many common Apache modules, often with parameterized configuration options. For a list of supported Apache modules, see the apache::mod::<MODULE NAME> class references.

For example, you can install the mod_ssl Apache module with default settings by declaring the apache::mod::ssl class:

class { 'apache::mod::ssl': }

apache::mod::ssl has several parameterized options that you can set when declaring it. For instance, to enable mod_ssl with compression enabled, set the ssl_compression parameter to true:

class { 'apache::mod::ssl':
  ssl_compression => true,
}

Note that some modules have prerequisites, which are documented in their references under apache::mod::<MODULE NAME>.

Installing arbitrary modules

You can pass the name of any module that your operating system's package manager can install to the apache::mod defined type to install it. Unlike the specific-module classes, the apache::mod defined type doesn't tailor the installation based on other installed modules or with specific parameters---Puppet only grabs and installs the module's package, leaving detailed configuration up to you.

For example, to install the mod_authnz_external Apache module, declare the defined type with the 'mod_authnz_external' name:

apache::mod { 'mod_authnz_external': }

There are several optional parameters you can specify when defining Apache modules this way. See the defined type's reference for details.

Configuring FastCGI servers to handle PHP files

FastCGI on Ubuntu 18.04

On Ubuntu 18.04, mod_fastcgi is no longer supported. So considering:

  • an Apache Vhost with docroot set to /var/www/html
  • a FastCGI server listening on 127.0.0.1:9000

you can then use the custom_fragment parameter to configure the virtual host to have the FastCGI server handle the specified file type:

apache::vhost { 'www':
  ...
  docroot         => '/var/www/html/',
  custom_fragment => 'ProxyPassMatch ^/(.*\.php)$ fcgi://127.0.0.1:9000/var/www/html/$1',
  ...
}

Please note you have to adjust the second ProxyPassMatch parameter to you docroot value (here /var/www/html/).

Other OSes

Add the apache::fastcgi::server defined type to allow FastCGI servers to handle requests for specific files. For example, the following defines a FastCGI server at 127.0.0.1 (localhost) on port 9000 to handle PHP requests:

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'
}

You can then use the custom_fragment parameter to configure the virtual host to have the FastCGI server handle the specified file type:

apache::vhost { 'www':
  ...
  custom_fragment => 'AddType application/x-httpd-php .php'
  ...
}

Load balancing examples

Apache supports load balancing across groups of servers through the mod_proxy Apache module. Puppet supports configuring Apache load balancing groups (also known as balancer clusters) through the apache::balancer and apache::balancermember defined types.

To enable load balancing with exported resources, export the apache::balancermember defined type from the load balancer member server:

@@apache::balancermember { "${::fqdn}-puppet00":
  balancer_cluster => 'puppet00',
  url              => "ajp://${::fqdn}:8009",
  options          => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],
}

Then, on the proxy server, create the load balancing group:

apache::balancer { 'puppet00': }

To enable load balancing without exporting resources, declare the following on the proxy server:

apache::balancer { 'puppet00': }

apache::balancermember { "${::fqdn}-puppet00":
  balancer_cluster => 'puppet00',
  url              => "ajp://${::fqdn}:8009",
  options          => ['ping=5', 'disablereuse=on', 'retry=5', 'ttl=120'],
}

Then declare the apache::balancer and apache::balancermember defined types on the proxy server.

To use the ProxySet directive on the balancer, use the proxy_set parameter of apache::balancer:

apache::balancer { 'puppet01':
  proxy_set => {
    'stickysession' => 'JSESSIONID',
    'lbmethod'      => 'bytraffic',
  },
}

Load balancing scheduler algorithms (lbmethod) are listed in mod_proxy_balancer documentation.

Reference

For information on classes, types and functions see the REFERENCE.md

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 that are specific to your operating system. Unless explicitly called out, most templates are not meant for configuration.

Tasks

The Apache module has a task that allows a user to reload the Apache config without restarting the service. Please refer to to the PE documentation or Bolt documentation on how to execute a task.

Limitations

For an extensive list of supported operating systems, see metadata.json

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:

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

Testing

Due to the difficult and specialised nature of acceptance testing mods in apache IE (high OS specificity), we have replaced acceptance tests with unit tests.

To run the unit tests, install the necessary gems:

bundle install

And then execute the command:

bundle exec rake parallel_spec

To check the code coverage, run:

COVERAGE=yes bundle exec rake parallel_spec

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 and check out CONTRIBUTING.md.