#vpasswd

##Table of Contents

• Overview
• Module Description
• Requirements
  • Experimental Feature
  • Dependencies
• Usage
  • Setup HIERA: Simple example (YAML)
  • Setup HIERA: Complex example (YAML)
  • Basic Usage (Dovecot)
  • Basic Usage (ProFTPD)
  • Complex Example
• Reference
  • HIERA attribute reference
  • Module parameter reference
  • Performance
  • Iterations/Lambdas
• Development

##Overview

This module manages virtual users and creates passwd-like files.

##Module Description

Virtual users are users not found in /etc/passwd. Many applications support virtual users for increased security. You will need to provide a file in passwd-like format. This module will create those files for you.

Features:

• Use HIERA to provide user data
• Choose from pre-defined schemes for Dovecot, ProFTPd and htpasswd (Apache)
• Drop your own schemes to the template directory

NOTE: To manage your mail environment - domains, addresses, routes, policies - you may want to checkout the vmail module.

##Requirements

This module will not try to install packages or manage services. Its only purpose is to create files. All other things are up to you and probably other modules.

###Experimental Feature

This module requires iterations/lambdas. You need puppet 3.2+ and the future parser enabled in order to use this module.

###Dependencies

Currently requires the puppetlabs/concat and puppetlabs/stdlib module. I recommend to use my vmail module for mail domain and mail relay management. Besides that thias-postfix and jproyo-dovecot are useful to manage the mail services.

##Usage

First, you need to define your users in HIERA. While this module tries to be as flexible as possible, it requires you to use the expected syntax.

###Setup HIERA: Simple example (YAML)

virtual_accounts:
  john:
    comment: John Doe
    password: $1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1
    features:
      mail: true
  sue:
    comment: Sue Doe
    password: $1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1
    features:
      mail: true

###Setup HIERA: Complex example (YAML)

virtual_accounts:
  john:
    comment: John Doe
    password: $1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1
    features:
      ftp: false
      mail: true
      www: false
    settings:
      aliases: [john.doe, jd]
      maildir: john_doe
      maildomains:
        company.com:
          aliases: [sales]
        example.com:
      quota: 1024M
  sue:
    comment: Sue Doe
    password: $1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1
    features:
      ftp: false
      mail: true
      www: false
    settings:
      aliases: [sue.doe, sd]
      maildir: sue_doe
      maildomains:
        company.com:
          aliases: [accounting, contact]
        example.com:
      quota: 1024M
  steve:
    comment: Steve Smith
    password: $1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1
    features:
      ftp: true
      mail: true
      www: true
    home: /stor/nfs/home/steve
    settings:
      aliases: [steve.smith, ss]
      maildir: service
      maildomains:
        company.com:
          aliases: [helpdesk, hostmaster, support]
      quota: 4096M

###Basic Usage (Dovecot)

The most basic, yet fully-working example for Dovecot:

$virtual_accounts = hiera_hash('virtual_accounts')

vpasswd::dovecot { 'my dovecot users':
  hash    => $virtual_accounts,
}

This will create a passwd-like file in dovecot scheme with the following content:

john@company.com:{MD5-CRYPT}$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:0:0::/var/mail/john::userdb_quota_rule=*:bytes=1024M
john.doe@company.com:{MD5-CRYPT}$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:0:0::/var/mail/john::userdb_quota_rule=*:bytes=1024M
jd@company.com:{MD5-CRYPT}$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:0:0::/var/mail/john::userdb_quota_rule=*:bytes=1024M
sales@company.com:{MD5-CRYPT}$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:0:0::/var/mail/john::userdb_quota_rule=*:bytes=1024M
(...)

###Basic Usage (ProFTPD)

A basic example for ProFTPD:

$virtual_accounts = hiera_hash('virtual_accounts')

vpasswd::proftpd { 'my proftpd users':
  hash    => $virtual_accounts,
}

This will create a passwd-like file in ProFTPD scheme with the following content:

john:$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:65534:65534:::/bin/sh
sue:$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:65534:65534:::/bin/sh
steve:$1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1:65534:65534::/stor/nfs/home/steve:/bin/sh

###Complex Example

You may want to customize the whole thing by adding your own template "flavour" to the module directory and use vpasswd::file directly:

$my_accounts = hiera_hash('my_accounts')

vpasswd::file { 'MyApp passwd file':
  file       => '/etc/myapp.passwd',
  flavour    => 'myapp',
  group      => 'www',
  hash       => $my_accounts,
  owner      => 'www',
  requires   => { feature => 'myapp' },
}

##Reference

###HIERA attribute reference

All currently supported attributes:

virtual_accounts:
  john_doe:
    comment: John Doe
    password: $1$LIq.MKZE$oYK01CVMjxPfBEicJDE9L1
    features:
      ftp: false
      mail: true
      www: false
    home: /stor/nfs/home/john
    settings:
      aliases: [john.doe, jd]
      local_alias: john.doe
      maildir: john_doe/default
      maildomains:
        company.com:
          aliases: [sales]
        2ndcompany.com:
          username: ceo
          aliases: [contact, sales]
      quota: 1024M
      username: john.doe

###Module parameter reference

All currently supported parameters:

vpasswd::dovecot { 'Dovecot passwd file':
  file         => '/foo/dovecot/users.passwd',
  flavour      => 'dovecot',
  group        => 'mail',
  hash         => $my_accounts,
  mailbox_base => '/foo/mail',
  owner        => 'mail',
  parent_gid   => '143',
  parent_uid   => '143',
  parent_shell => '/bin/sh',
  requires     => { feature => 'mail' },
}

###Performance

This module does not scale well. The performance suffers from the future parser and the large number of objects being created during a puppet run, or maybe it's the concat module. If you find a way to improve performance, please let me know.

30+ users:

puppet-master[114547]: Compiled catalog in 2.44 seconds
Notice: Finished catalog run in 2.38 seconds
puppet agent --test --verbose  5.27s user 1.32s system 31% cpu 20.967 total

500+ users:

puppet-master[10967]: Compiled catalog in 83.08 seconds
Notice: Finished catalog run in 43.60 seconds
puppet agent --test --verbose  95.35s user 13.63s system 17% cpu 10:34.92 total

In the latter case you want to set configtimeout = 10m.

###Iterations/Lambdas

Why does this module depend on experimental features like iterations/lambdas? I wanted to keep the defined types simple, but still make it possible to use the same user data multiple times (for multiple files, multiple applications). To avoid duplicate declarations I needed to use iterations (and unique names for every object, hence separators were born).

##Development

Please use the github issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.

Changelog

0.1.3

• Bugfix: Fix puppet-lint issues

0.1.2

• Feature: Also detect the Apache variant of the MD5-based password algorithm (apr1)
• Contributor: TravellingGuy

0.1.1

• Bugfix: Fix a copy and paste error

0.1.0

• Initial release