Apache

Overview
Requirements
Variable Overrides
Role Variables
Dependencies
Examples
Development / Contributing
License
Author Information

Overview

This role installs and manages the Apache HTTPD Web Server

Requirements

This role requires Ansible 2.1 or higher and platform requirements are listed in the metadata file.

If you are using SSL/TLS you should provided your own certificate and key files. By default it will use the localhost certificate and key created by the system.

Variable Overrides

Varibles listed as a key with no values in defaults/main.yml can be overriden via group or extra variables yet still set a default value via OS-specific variable includes ( see vars/*.yml ).

This is accomplished via the set_overrides.yml task file which determines if a value is passed to the role or if the value is None and then initializes the variable with a default value from the OS-specific variable includes

Role Variables

The variables that can be passed to this role and a brief description about them are as follows. (For all variables, take a look at defaults/main.yml)

See Variable Overrides for information on variables not listed with a default value and the ability to override them via pass-ins.

apache_packages:

The set of packages to be installed.

apache_service:

The service name for the apache daemon to run on the system.

apache_state:

The Apache daemon state to be enforced. This should generally remain the default value.

apache_enabled:

Weather the apache service should start on boot. This should generally remain the default value.

Modules

Status ( mod_status )

apache_mod_status_manage: True

Enable management of the Apache status module configuration.

apache_mod_status_allow_from:
  - 127.0.0.1
  - ::1

Array of hosts allowed to access the Apache status page. Defaults to localhost via IPv4 and IPv6

VirtualHosts

Virtualhost Dict Keys: Defaults

All default Apache VirtualHost entries are removed during the running of this play and declaired VirtualHosts are generated. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_vhosts_template: vhostsj2

apache_vhosts:
  - server_name: "example.mysite.com"
    template: "../path/to/custom/template"

The template used for generating VirtualHost configurations. This can be used to call a custom template if desired per VirtualHost. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_vhost_ssl: True

Enables/Disables SSL for the virtual host. SSL virtual hosts only respond to HTTPS queries. Defaults to True, SSL should be used everywhere!! Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_ssl_certs_dir:

The directory containing Certificates of Certification Authorities (CAs), used for SSl/TLS configuration. This should generally remain the default value. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_ssl_default_cert:

The PEM-encoded certificate file, used for SSL/TLS configuration. Defaults are based on local certificate generated by your OS. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_ssl_default_key:

The PEM-encoded private key file, used for SSL/TLS configuration. Defaults are based on local certificate generated by your OS. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_ssl_honorcipherorder: 'On'

Sets SSLHonorCipherOrder, to cause Apache to use the server's preferred order of ciphers rather than the client's preferred order default for VritualHosts

apache_ssl_protocol: 'all -SSLv2 -SSLv3'

Specifies SSLProtocol default for VritualHosts. Expects a space separated string of accepted protocols.

apache_ssl_ciphersuite: 'HIGH:MEDIUM:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4'

Specifies SSLCipherSuite default for VritualHosts.

apache_vhost_ip: '*'

IP address the virtual host listens on. Default behavior of listening on all IPs. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

apache_vhost_port: '443'

Port the Virtualhost is configured to listen on. Defaults to 443. Overridden inside the apache_vhosts variable on a per Virtualhost basis within the dict.

Virtualhost Dict Keys

apache_vhosts:
  - server_name: 'site.example.com'

Sets the servername corresponding to the hostname you connect to the Virtualhost at. Sets the Apache ServerName directive. Default: undef

apache_vhosts:
  - serveraliases:
      - 'site.example.org'
      - 'site.example.net'

List of server aliases for the Virtualhost. Sets the ServerAlias Directive. Default: undef

apache_vhosts:
  - server_admin 'admin@example.com'

Specifies the email address Apache displays when it renders one of its error pages. Default: undef

apache_vhosts:
  - virtual_docroot: '/var/www/%-2+'

Sets the VirtualDocumentRoot directive to allow you to determine where Apache HTTP Server will find your documents based on the value of the server name. Default: undef

apache_vhosts:
  - docroot: '/var/www/html'

Sets the default DocumentRoot location for a VritualHost. Default: undef

apache_vhosts:
  - aliases:
      - alias: '/image'
        path: '/ftp/pub/image'
      - aliasmatch: '^/image/(.*)\.jpg$'
        path: '/files/jpg.images/$1.jpg'
      - scriptalias: '/nagios/cgi-bin/'
        path: '/usr/lib/nagios/cgi-bin/'
      - scriptaliasmatch: '^/cgi-bin(.*)'
        path: '/usr/local/share/cgi-bin$1'

A list of hashes to create Alias, AliasMatch, ScriptAlias or ScriptAliasMatch directives. Default: undef

apache_vhosts:
  - fallbackresource: '/index.php'

Sets the 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

apache_vhosts:
  - allow_encoded_slashes:

Sets the server default for the AllowEncodedSlashes declaration, which modifies the responses to URLs containing '' and '/' characters. Valid options: 'on', 'off', 'nodecode'. Default: undef

Directories Directives

apache_vhosts:
  - directories:
      - provider: 'directory'
        path: '/var/www/html'
        options: ['Indexes','FollowSymLinks','MultiViews']

A list of hashes to create Directory directive blocks (TODO: File/Location) directive blocks.

Note: At least one directory should match the docroot parameter. After you start declaring directories, this role assumes that all required Directory blocks will be declared. If not defined, a single default Directory block is created that matches the docroot variable.

Directory Keys

provider: 'directory'

Each hash passed to directories must contain provider as one of the keys. Currently directory is the only available provider.

path: '/var/www/html'

The path key set the path for the directory block.Each hash passed to directories must contain path as one of the keys.

header:
  - 'Set X-Robots-Tag "noindex, noarchive, nosnippet"'

List that adds lines for Header directives within the directory block.

geoip_enable: On

Sets the GeoIPEnable directive within the directory block. Note that the GEOIP Module must be configured before using this directive.

options:
  - 'Indexes'
  - 'FollowSymLinks'
  - 'MultiViews'

Lists the Options for the given Directory block.

index_options:
  - 'IgnoreCase'
  - 'FancyIndexing'
  - 'FoldersFirst'
  - 'NameWidth=*'
  - 'DescriptionWidth=*'
  - 'SuppressHTMLPreamble'

Allows configuration settings for directory indexing

index_order_default:
  - 'Descending'
  - 'Date'

Sets the default ordering of the directory index

index_style_sheet: '/styles/style.css'

Sets the IndexStyleSheet, which adds a CSS stylesheet to the directory index.

allow_override:
  - 'AuthConfig'
  - 'Indexes'

Sets the types of directives allowed in .htaccess files. Accepts an array. Defaults to None

require: 'unmanaged'

Sets a Require directive as per the Apache Authz documentation. If no require is set, it will default to Require all granted.

auth_require: 'valid-user'

Sets the entity name you're requiring to allow access

order: 'Allow,Deny'

Sets the order of processing Allow and Deny statements. It only works with Apache 2.2 and lower.

deny:
  - 'from example.org'

Sets a Deny directive, specifying which hosts are denied access to the server. It only works with Apache 2.2 and lower.

allow:
  - 'from example.org'

Sets an Allow directive, which groups authorizations based on hostnames or IPs. It only works with Apache 2.2 and lower. If no allow is set, it will default to Allow from all.

satisfy: 'Any'

Sets a Satisfy directive. It only works with Apache 2.2 and lower.

Additional Include Directives

apache_vhosts:
  - additional_includes:
      - '/tmp/proxy_group_a'
      - '/tmp/proxy_group_b'

A list of hashes to create Include or IncludeOptional (Apache 2.4 or newer) directive blocks. Specifies paths to additional static, virtual host-specific Apache configuration files. You can use this parameter to implement a unique, custom configuration not supported by this module.

apache_vhosts:
  - error_log_destination:

The location to write the the Virtualhost error log. Defaults to apache_log_dir

apache_vhosts:
  - log_level:

Specifies the verbosity of the error log. Valid options: 'emerg', 'alert', 'crit', 'error', 'warn', 'notice', 'info' or 'debug'.

apache_vhosts:
  - access_log_destination:

The location to write the the Virtualhost error log. Defaults to apache_log_dir

apache_vhosts:
  - action:

Sets the Action directive for the Virtualhost

apache_vhosts:
  - block: 'smc'

Specifies the list of things to which Apache blocks access. Valid option: 'scm', which blocks web access to .svn, .git, and .bzr directories. Default: undef

apache_vhosts:
  - headers:
    - 'Set X-Robots-Tag "noindex, noarchive, nosnippet"'

Array of Header directives to be set in the Virutalhost.

apache_vhosts:
  - request_headers:
    - 'append MirrorID "mirror 12"'
    - 'unset MirrorID'

Array of Header directives to be set in the Virutalhost.

apache_vhosts:
  - redirects:
      - redirect: '/index.html'
        status: 'permanent'
        destination: 'http://google.com'
      - redirectmatch: '\.git(/.*|$)/'
        stats: '404'
        destination: 'http://www.example.com/1'

A list of hashes to create Rediret and/or RedirectMatch directives. Default: undef

  apache_vhosts:
    - rewrite_inherit: True

Sets the Apache RewriteOptions Inherit directive for the Virtualhost if defined.

  apache_vhosts:
    - rewrites:
      - comment      => 'redirect IE'
        rewrite_cond => ['%{HTTP_USER_AGENT} ^MSIE']
        rewrite_rule => ['^index\.html$ welcome.html']

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.

SSL Directives

  apache_vhosts:
    - ssl: True

Enables/Disables SSL for the virtual host. SSL virtual hosts only respond to HTTPS queries. Defaults to apache_vhost_ssl

  apache_vhosts:
    - ssl_cert:

The PEM-encoded certificate file, used for SSL/TLS configuration. Defaults to apache_ssl_default_cert

  apache_vhosts:
    - ssl_key:

The PEM-encoded private key file, used for SSL/TLS configuration. Defaults to apache_ssl_default_key

  apache_vhosts:
    - ssl_chain:

The optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate . Default: undef

  apache_vhosts:
    - ssl_certs_dir:

The directory containing Certificates of Certification Authorities (CAs), used for SSl/TLS configuration. Defaults to apache_ssl_certs_dir

  apache_vhosts:
    - ssl_ca:

The all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. Default: undef

  apache_vhosts:
    - ssl_crl_path:

The directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with

  apache_vhosts:
    - ssl_crl:

The all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with. Default: undef

  apache_vhosts:
    - ssl_crl_check:

Enables certificate revocation list (CRL) checking, valid options are chain|leaf|none. Default: undef

  apache_vhosts:
    - ssl_honorcipherorder:

Enables the servers preference when hoosing a cipher during an SSLv3 or TLSv1 handshake. Defaults to apache_ssl_honorcipherorder

  apache_vhosts:
    - ssl_protocol:

Sets the SSLProtocol directive to control which versions of the SSL/TLS protocol will be accepted in new connections. Defaults to apache_ssl_protocol

  apache_vhosts:
    - ssl_cipher:

Configures the Cipher Suite the client is permitted to negotiate in the SSL handshake phase. Defaults to apache_ssl_ciphersuite

  apache_vhosts:
    - ssl_verify_client:

Sets the Certificate verification level for the Client Authentication. Defaults: undef

  apache_vhosts:
    - ssl_verify_depth:

Sets how deeply mod_ssl should verify before deciding that the clients don't have a valid certificate. Default: undef

  apache_vhosts:
    - ssl_options:

Sets the SSLOptions directive, which configures various SSL engine run-time options. Defaults undef

  apache_vhosts:
    - ssl_openssl_conf_cmd:

Sets the SSLOpenSSLConfCmd directive, which provides direct configuration of OpenSSL parameters. Default: undef

  apache_vhosts:
    - custom_fragment:

Passes a string of custom configuration directives to place at the end of the virtual host configuration. Default: undef.

apache_vhosts:
  - charset:

Sets a default media charset value for the AddDefaultCharset directive, which is added to text/plain and text/html responses.

apache_vhosts:
  - port: 80

Overrides the port the Virtualhost is configured to listen. Default: See apache_vhost_port

apache_vhosts:
  - ssl: False

Enables/Disables SSL for the virtual host. SSL virtual hosts only respond to HTTPS queries. Default: See apache_vhost_ssl

Dependencies

None

Example Playbook(s)

Use Virtualhost default configurations from defaults/main.yml

---
roles:
  - role: ansible-role-apache

Set custom Virtualhost entries via Playbook variables

---
vars:
  apache_vhosts:
    - server_name: site.example.com
      serveraliases:
        - site.example.org
        - site.example.net
      port: 80
      ssl: False
      docroot: '/var/www/site_com'

roles:
  - role: ansible-role-apache

Set custom entries via Group Variables

group_vars/web1.example.dev/apache.yml

---
apache_vhosts:
    - server_name: site.example.com
      serveraliases:
        - site.example.org
        - site.example.net
      port: 80
      ssl: False
      docroot: '/var/www/site_com'

---
roles:
  - role: ansible-role-apache

Development / Contributing

See Contributing.

Note: This role is currently only tested against the following OS and Ansible versions:

Operating Systems / version

CentOS 6.x
CentOS 7.x

Ansible Versions

2.2.2
latest

License

Licensed under the MIT License. See the LICENSE file for details.

Author Information

Steven Bambling

smbambling/ansible-role-apache