Forge Home

webserver

Wrapper around puppetlabs/apache with SSL and Kerberos from FreeIPA

5,014 downloads

5,014 latest version

5.0 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

  • 0.1.0 (latest)
released Mar 1st 2018
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 6.0.0
  • ,

Start using this module

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

Add this module to your Puppetfile:

mod 'fheinle-webserver', '0.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add fheinle-webserver
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install fheinle-webserver --version 0.1.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

Documentation

fheinle/webserver — version 0.1.0 Mar 1st 2018

krb-webserver

This is a wrapper around Apache and Apache::Vhost from puppetlabs/apache that adds SSL and Kerberos compatible with FreeIPA.

Table of Contents

  1. Description
  2. Setup
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.

Description

This wrapper installs the required Apache2 modules for authentication using Kerberos and SSSD, so it also respects HBAC rules defined in FreeIPA.

For a vhost, it enables Kerberos based authentication for its document root and sets up its configuration with an SSL certificate retrieved from your FreeIPA server. Both options can be disabled.

Setup

What krb-webserver affects

  • Apache configuration: enables modules
  • Apache vhosts: adds 1 http and optionally 1 https vhost
  • PAM configuration: adds new config file in /etc/pam.d/
  • File system: creates document root directory

Setup Requirements

You should set up a Kerberos principal in FreeIPA and retrieve both an SSL key and accompanying certificate for your host. Also, retrieve the ticket for your principal and store it in a keytab accessible by apache, e.g. in /etc/apache2/krb5_keytab.

You will need to install and set up apache separately, maybe with puppetlabs/apache.

Usage

Configuring your webserver for Kerberos auth is easy:

class {'::webserver': }

This will install required packages and enable mod_authnz_pam and mod_auth_kerb. Also, it will create a new pam configuration for web access that requires SSSD for authorization.

Setting up a new vhost:

webserver::vhost {'awesome_vhost':
    $vhost_name        = $::facts['fqdn'],
    $docroot           = "/var/www/${vhost_name}/html",
    $ssl               = true,
    $kerberos          = true,
    $web_user          = 'www-data',
    $default_vhost     = false,
    $ssl_cert_filename = "/etc/apache2/ssl/${vhost_name}.crt.crt",
    $ssl_key_filename  = "/etc/apache2/ssl/${vhost_name}.crt.key",
    $krb_auth_realm    = undef,
    $krb_5keytab       = undef,
    $krb_servicename   = 'http'
}

Those are the default settings, obviously you need to override them with your customizations. Especially make sure to set the correct values to $krb5_*.

Reference

Class webserver

Enables mod_auth_kerb and mod_authnz_pam, create a PAM configuration file that requires SSSD.

  • This class has no configuration settings

Defined Type webserver::vhost

Create a new apache virtual host. This will create a $docroot directory owned by $web_user. If $ssl is set to true, additionally to a https vhost it will create a http vhost redirecting to https automatically.

  • vhost_name: Hostname the vhost uses, i.e. ServerName in apache
  • docroot: directory static files will be served from
  • ssl: bool use SSL?
  • kerberos: bool require Kerberos?
  • web_user: username docroot will belong to
  • default_vhost: bool is this the default apache vhost?
  • ssl_cert_filename: Path to SSL certificate
  • ssl_key_filename: Path to SSL private key
  • krb_auth_realm: optional if kerberos is false name of your kerberos realm
  • krb_5keytab: optinal if kerberos is false path to kerberos keytab file accessible by apache
  • krb_servicename optional if kerberos is false name of your kerberos service name you set up in FreeIPA

Limitations

Currently this is a limited wrapper around vhost creation, i.e. it will not pass through additional apache vhost settings to the module it wraps. You may, however, access that instance of Apache::Vhost using the regular puppet syntax of Apache::Vhost[your.vhost.here].