EZProxy Puppet Module

Overview
Module Description - What the module does and why it is useful
Setup - The basics of getting started with ezproxy
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

Overview

Puppet module for installing, configuring, and managing OCLC's EZProxy.

Module Description

This module manages the installation and configuration of EZProxy and any dependencies and allows you to work with proxy stanzas in a more structured format.

Individual databases and sites are built into file fragments which are then concatenated together. You can also specify a remote url to use as a source for things like Sage or Oxford Journals.

Upgrading

Changes from 1.x

This module now requires Puppet version >= 4. The last release with Puppet 3 support is 1.1.0.
The EZProxy key is now a required parameter, as the module manages key authorization.
The EZProxy service runs under systemd, depending on platform.
EZProxy now logs to the /var/log/ezproxy directory by default now, and a logrotate rule is set for it.
All 64-bit Debian family operating systems now use lib32z1 for compatibility.
The default group has been downcased.
The installed EZProxy version is now available as a custom external fact: ezproxy_version
EZProxy can be upgraded in place if the desired version of EZProxy is different from the current version.

Parameter Changes

key sets the EZProxy authorization or WS key
ezproxy_group is now group
ezproxy_user is now user
install_path is now install_dir
ezproxy_url is now server_name
log_user has been deprecated
log_type now sets wither to log by session or username
dependencies as an overridable parameter has been deprecated

Setup

What ezproxy affects

A daemon user. Default: ezproxy
The install directory. Default: /usr/local/ezproxy
The ezproxy binary.
EZProxy key authorization (WSKey in EZProxy 6+).
A log directory. Default: /var/log/ezproxy
A logrotate rule.
installs lib32z1 or glibc.i686 (depending on platform) for 64-bit compatibility
installs dos2unix for config file sanitization
$INSTALL_DIR/config.txt which handles all of the EZProxy configuration
$INSTALL_DIR/user.txt which handles user management
$INSTALL_DIR/groups.txt which sets the order of the group include files
$INSTALL_DIR/group_default.txt which is built out of file fragments for each individual EZProxy entry
An init or systemd service, depending on platform. Note: Service management can be disabled.

Usage

This module contains a single public class with a single required parameter, the EZProxy key:

class { 'ezproxy':
  key => 'my-ezproxy-key',
}

You'll probably want to provide a few basic parameters for your particular environment:

class { 'ezproxy':
  key               => 'my-ezproxy-key',
  server_name       => 'ezproxy.myinstitution.edu',
  proxy_by_hostname => true,
  login_port        => '80',
  max_sessions      => '1000',
  max_vhosts        => '2500',
  local_users       => [ 'user1:supersecure:admin', ],
}

There are also two defined types for creating EZProxy stanzas depending on whether you want to provide the values yourself or grab a provided config file from a URL.

ezproxy::remote_config { 'Oxford Journals':
  download_link => 'http://www.oxfordjournals.org/help/techinfo/ezproxyconfig.txt',
  file_name     => 'oxford_journals',
  max_days      => '30',
}

Note that the downloaded config fill will get passed through dos2unix in order to strip out any potential Windows file artifacts.

ezproxy::stanza { 'FirstSearch':
  urls    => [ 'http://firstsearch.oclc.org/FSIP' ],
  hosts   => [ 'firstsearch.oclc.org' ],
  domains => [ 'oclc.org' ],
}

EZProxy upgrades

EZProxy can be upgraded by incrementing this version number. This will STOP the running instance of EZProxy and attempt to upgrade.

class { 'ezproxy':
  key     => 'my-ezproxy-key',
  version => '6.2.2',
}

Groups

If you want to set up groups, they're also available as defined types:

ezproxy::group { 'whatever':
  group_order => 1,
}

You can also specify which group any stanza should use like this:

ezproxy::stanza { 'FirstSearch':
  urls    => [ 'http://firstsearch.oclc.org/FSIP' ],
  hosts   => [ 'firstsearch.oclc.org' ],
  domains => [ 'oclc.org' ],
  group   => 'whatever',
}

Authenticating via LDAP or CAS

Aside from local user authentication, you can also set up LDAP or CAS authentication with a couple of parameters.