major doc update

Modulefile

@@ -1,20 +1,10 @@
 name 'puppet-pureftpd'
-version '1.0.3'
-
-author '5Ub-Z3r0'
-license 'GPL v3'
-project_page 'https://github.com/5Ub-Z3r0/puppet-pureftpd'
-source 'https://github.com/5Ub-Z3r0/puppet-pureftpd.git'
-summary 'Pure-FTPd  module'
-description 'This module manages Pure-FTPd via Puppet.
-
-It currently supports only RHEL, altough it should be easy to modify it to manage Debian-like systems.
-
-Requirements:
-
- * [Facter](http://www.puppetlabs.com/puppet/related-projects/facter/) 1.6.1 or greater (versions that support the osfamily fact)
-
-Todo:
-- complete the config_mysql and config_pgsql defines
-'
+version '1.0.0'
+
+author 'Joshua Hoblitt <[email protected]>'
+license 'Apache + GPLv3'
+project_page 'https://github.com/jhoblitt/puppet-pureftpd'
+source 'https://github.com/jhoblitt/puppet-pureftpd.git'
+summary 'Manages the pure-ftpd package with comprehensive configuration support'
+description 'Manages the pure-ftpd package with comprehensive configuration support'
 dependency 'puppetlabs/stdlib', '>= 4.1.0'

README.md

@@ -3,48 +3,128 @@ Puppet pureftpd Module
 
 [![Build Status](https://travis-ci.org/jhoblitt/puppet-pureftpd.png)](https://travis-ci.org/jhoblitt/puppet-pureftpd)
 
+#### Table of Contents
+
+1. [Overview](#overview)
+2. [Description](#description)
+3. [Usage](#usage)
+4. [Limitations](#limitations)
+    * [Tested Platforms](#tested-platforms)
+5. [Support](#support)
+
+
+Overview
+--------
+
+Manages the pure-ftpd package with comprehensive configuration support'
+
 
 Description
 -----------
 
-This is a puppet module for installation and configuration of the `pure-ftpd`
-software.
+This is a puppet module for installation and configuration of the
+[`pure-ftpd`](http://www.pureftpd.org/project/pure-ftpd) software package.  It
+aims to support all valid configuration file values.
 
+### Forked
 
-Examples
---------
+This module started out as a fork of
+[`5Ub-Z3r0/puppet-pureftpd`](https://github.com/5Ub-Z3r0/puppet-pureftpd) but
+has been so heavily redesigned over time that it's probably not reasonable to
+blame any of the design or implementation on
+[`5Ub-Z3r0`](https://github.com/5Ub-Z3r0).  It would also be exceptionally
+difficult to re-unify the two modules due to fundamental API differences.
+
+The original module was marked as being licensed under `GPLv3` in comments and
+no `LICENSE` file was present.  Very little to none of the original module code
+remains in the present version of this module.  All contributions by `Joshua
+Hoblitt` are licensed under `Apache License, Version 2.0`.  You should consult
+with a lawyer for a legal opinion as to weather or not this module constitutes
+a derived work.
+
+
+Usage
+-----
+
+In general, any valid `pure-ftpd` configuration file option (including the
+separate configuration files for auth modules) can be set by creating a key in
+the appropriate class parameter hash but with the name of the option
+transliterated to *lowercase*.  The values passed to that option are handled
+completely as raw strings but this module.  No effort is made to handle
+`boolean` or `integer` values as `pure-ftpd` itself is not consistent in how it
+handles these values.
+
+For example, if you wanted to create the configuration option example below in the file `/etc/pure-ftpd/pure-ftpd.conf`,
+
+    ChrootEveryone yes
+
+You would declare it like this to the puppet module:
 
-### Basic
+    class { 'pureftpd':
+      config => {
+        chrooteveryone => 'yes',
+      }
+    }
+
+The notable exception to that rule is for these `pure-ftpd.conf` options, which
+should not need to be manually declared.  Passing a hash of configuration
+options to the appropriate class parameter automatically defines these options
+for you.
+
+    LDAPConfigFile
+    MySQLConfigFile
+    PGSQLConfigFile
+
+
+### `pure-ftpd` Options
+
+The `pure-ftpd` documentation does not provide a canonical list of all possible
+configuration options with examples.  However, there are number of "HOW TO"s on
+the official [documentation](http://www.pureftpd.org/project/pure-ftpd/doc) web
+page.
 
-Install `pure-ftpd` with an empty `pure-ftpd.conf` config file (accepting all
-defaults) and start `pure-ftpd` as a stand alone daemon.
+There is a list of command line switches in the distribution's
+[`README`](https://github.com/jedisct1/pure-ftpd/blob/master/README) that
+should all have `pure-ftpd.conf` option analogs.
+
+Here are some useful sources for discovering configuration parameters with examples:
+
+* [`pure-ftpd.conf`](https://github.com/jedisct1/pure-ftpd/blob/master/configuration-file/pure-ftpd.conf.in)
+* [`pureftpd-ldap.conf`](https://github.com/jedisct1/pure-ftpd/blob/master/pureftpd-ldap.conf)
+* [`pureftpd-mysql.conf`](https://github.com/jedisct1/pure-ftpd/blob/master/pureftpd-mysql.conf)
+* [`pureftpd-pgsql.conf`](https://github.com/jedisct1/pure-ftpd/blob/master/pureftpd-pgsql.conf)
+
+### Basic Usage
+
+Install the `pure-ftpd` package with an empty `pure-ftpd.conf` config file
+(accepting all defaults) and start `pure-ftpd` as a stand alone daemon.
 
     class { 'pureftpd': }
 
-### Selinux support
+### SELinux Support
 
     class { 'pureftpd':
       use_selinux => true,
     }
 
-### Setting configuration options
+### Setting Configuration Options
+
+Options for `pure-ftpd.conf`] should be passed into the `config` class
+parameter as a hash.
 
     class { 'pureftpd':
-      use_selinux => true,
       config      => {
         ipv4only         => 'Yes',
         passiveportrange => '49999:59999',
       },
     }
 
-### Enabling LDAP authentication
+### Enabling LDAP Authentication
+
+Options for `pureftpd-ldap.conf`] should be passed into the `config_ldap` class
+parameter as a hash.
 
     class { 'pureftpd':
-      use_selinux => true,
-      config      => {
-        ipv4only         => 'Yes',
-        passiveportrange => '49999:59999',
-      },
       config_ldap => {
         ldapserver      => 'ldap.example.com',
         ldapauthmethod  => 'PASSWORD',
@@ -62,14 +142,43 @@ defaults) and start `pure-ftpd` as a stand alone daemon.
       },
     }
 
-### Enabling PGSQL authentication
+### Enabling MYSQL Authentication
+
+Options for `pureftpd-mysql.conf`] should be passed into the `config_mysql`
+class parameter as a hash.
 
     class { 'pureftpd':
-      use_selinux => true,
-      config      => {
-        ipv4only         => 'Yes',
-        passiveportrange => '49999:59999',
+      config_mysql               => {
+        mysqlserver              => 'localhost'
+        mysqlport                => '3306'
+        mysqlsocket              => '/tmp/mysql.sock'
+        mysqluser                => 'root'
+        mysqlpassword            => 'rootpw'
+        mysqldatabase            => 'pureftpd'
+        mysqlcrypt               => 'cleartext'
+        mysqltransactions        => 'On'
+        mysqlgetpw               => 'SELECT Password FROM users WHERE User="\L"'
+        mysqlgetuid              => 'SELECT Uid FROM users WHERE User="\L"'
+        mysqldefaultuid          => '1000'
+        mysqlgetgid              => 'SELECT Gid FROM users WHERE User="\L"'
+        mysqldefaultgid          => '1000'
+        mysqlgetdir              => 'SELECT Dir FROM users WHERE User="\L"'
+        mysqlforcetildeexpansion => '0'
+        mysqlgetqtafs            => 'SELECT QuotaFiles FROM users WHERE User="\L"'
+        mysqlgetqtasz            => 'SELECT QuotaSize FROM users WHERE User="\L"'
+        mysqlgetratioul          => 'SELECT ULRatio FROM users WHERE User="\L"'
+        mysqlgetratiodl          => 'SELECT DLRatio FROM users WHERE User="\L"'
+        mysqlgetbandwidthul      => 'SELECT ULBandwidth FROM users WHERE User="\L"'
+        mysqlgetbandwidthdl      => 'SELECT DLBandwidth FROM users WHERE User="\L"'
       },
+    }
+
+### Enabling PGSQL Authentication
+
+Options for `pureftpd-pgsql.conf`] should be passed into the `config_pgsql`
+class parameter as a hash.
+
+    class { 'pureftpd':
       config_pgsql => {
         pgsqlserver         => 'localhost',
         pgsqlport           => '5432',
@@ -91,3 +200,34 @@ defaults) and start `pure-ftpd` as a stand alone daemon.
         pgsqlgetbandwidthdl => 'SELECT DLBandwidth FROM users WHERE User=\'\L\'',
       },
     }
+
+### Canonical Example
+
+Limitations
+-----------
+
+At present, this module is only capable of installing the `pure-ftpd` package
+and enabling it as a daemonized service.  The lack of uninstallation support is
+probably a bug.
+
+Only support for `$::osfamily == 'RedHat'` has been implemented.  Adding
+support for other platform should be trivial but needs to involve full up
+integration testing.
+
+The supported configuration file values were discovered via code inspection of
+the `pure-ftpd` `v1.0.31` release.  There are possibly new configuration
+values that have been introduced it subsequent releases.  Any configuration
+values present in a `pure-ftpd` but not supported by this module should be
+considered a bug.
+
+### Tested Platforms
+
+* el6.x
+
+
+Support
+-------
+
+Please log tickets and issues at
+[github](https://github.com/jhoblitt/puppet-pureftpd/issues)
+

manifests/config.pp

@@ -1,13 +1,7 @@
 # == Class: pureftpd::config
 #
-# This module manages the pure-ftpd server configuration file
+# Manages the `pure-ftpd.conf` file.  This class should be considered private.
 #
-# === Parameters
-#
-# === Authors
-#
-# 5Ub-Z3r0
-# Joshua Hoblitt <[email protected]>
 #
 class pureftpd::config(
   $ipv4only                   = undef,

manifests/config/ldap.pp

@@ -1,17 +1,9 @@
 # == Class: pureftpd::config::ldap
 #
-# This module manages the pure-ftpd configuration files with LDAP
-# authentication
+# Manages the `pureftpd-ldap.conf` file.  This class should be considered
+# private.
 #
-# === Parameters
 #
-#
-# === Authors
-#
-# 5Ub-Z3r0
-# Joshua Hoblitt <[email protected]>
-#
-
 class pureftpd::config::ldap (
   $ldapserver          = undef,
   $ldapport            = undef,

manifests/config/mysql.pp

@@ -1,21 +1,9 @@
 # == Class: pureftpd::config::mysql
 #
-# This module manages the pure-ftpd configuration files with mysql
-# authentication
+# Manages the `pureftpd-mysql.conf` file.  This class should be considered
+# private.
 #
-# === Parameters
 #
-#
-# === Authors
-#
-# 5Ub-Z3r0
-# Joshua Hoblitt <[email protected]>
-#
-# === TODO:
-#
-# - implement template and variables for the mysql config file
-#
-
 class pureftpd::config::mysql (
   $mysqlserver                = undef,
   $mysqlport                  = undef,

manifests/config/pgsql.pp

@@ -1,16 +1,8 @@
 # == Class: pureftpd::config::pgsql
 #
-# This module manages the pure-ftpd configuration files with pgsql
-# authentication
+# Manages the `pureftpd-pgsql.conf` file.  This class should be considered
+# private.
 #
-# === Authors
-#
-# 5Ub-Z3r0
-# Joshua Hoblitt <[email protected]>
-#
-# === TODO:
-#
-# - implement template and variables for the pgsql config file
 #
 class pureftpd::config::pgsql (
   $pgsqlserver         = undef,

manifests/init.pp

@@ -1,19 +1,44 @@
 # == Class: pureftpd
 #
-# This class installs, configures, and enables the pure-ftpd server
+# This class installs, configures, and enables the pure-ftpd package
 #
 # === Parameters
 #
 # [*use_selinux*]
+#   Boolean. Manages whether or not to enable the selinux extensions.
+#
 #   Optional, defaults to false.
-#   Manages whether or not to enable the selinux extensions.
 #
 # [*config*]
+#   A hash of configuration file options to be created in `pure-ftpd.conf`.
+#
+#   Optional, defaults to `{}`.
+#
+# [*config_ldap*]
+#   A hash of configuration file options to be created in `pureftpd-ldap.conf`.
+#
+#   Optional, defaults to `{}`.
+#
+# [*config_mysql*]
+#   A hash of configuration file options to be created in `pureftpd-mysql.conf`.
+#
+#   Optional, defaults to `{}`.
+#
+# [*config_pgsql*]
+#   A hash of configuration file options to be created in `pureftpd-pgsql.conf`.
+#
 #   Optional, defaults to `{}`.
 #
-# === Authors
+# === Examples
+#
+#    class { 'pureftpd':
+#      use_selinux => true,
+#      config      => {
+#        ipv4only         => 'Yes',
+#        passiveportrange => '49999:59999',
+#      },
+#    }
 #
-# 5Ub-Z3r0
 #
 class pureftpd (
   $use_selinux  = false,