Forge Home

pfsense

Providers and facts for pfSense

10,750 downloads

7,665 latest version

1.3 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

  • 99.99.99 (latest)
  • 0.2.1
  • 0.2.0
  • 0.1.0
released Feb 1st 2016
This version is compatible with:
  • Puppet >= 2.7.0 < 4.0.0
This module has been deprecated by its author since Nov 4th 2019.

The reason given was: No longer maintained

The author has suggested fraenki-opnsense as its replacement.

Start using this module

Documentation

fraenki/pfsense — version 99.99.99 Feb 1st 2016

#WARNING

This module is now OBSOLETE. All efforts have been shifted to OPNsense. The new project is available at https://github.com/fraenki/puppet-opnsense. For more information on OPNsense please visit https://opnsense.org/.

####Table of Contents

##Overview

This is a collection of providers and facts to manage pfSense firewalls.

NOTE: This is NOT related to the pfSense project in any way. Do NOT ask the pfSense developers for support.

##Module Description

This is intended to be a growing collection of providers and facts. In its current state it provides the following features:

  • pfsense_user: a provider to manage pfSense users
  • pfsense_group: a provider to manage pfSense groups
  • package: a provider to manage native pfSense packages
  • pfsense_version: facts to gather pfSense version information

Of course, it would be desirable to have a provider for cronjobs too. Contributions are welcome! :-)

##Usage

###Create a user

This will create a user, but does not grant any permissions.

pfsense_user { 'user001':
  ensure   => 'present',
  password => '$1$dSJImFph$GvZ7.1UbuWu.Yb8etC0re.',
  comment  => 'pfsense test user',
}

In our next example the user will have shell access (SSH) to the box and full access to the webGUI.

pfsense_user { 'user001':
  ensure         => 'present',
  password       => '$1$dSJImFph$GvZ7.1UbuWu.Yb8etC0re.',
  comment        => 'pfsense test user',
  privileges     => [ 'user-shell-access', 'page-all' ],
  authorizedkeys => [
    'ssh-rsa AAAAksdjfkjsdhfkjhsdfkjhkjhkjhkj user1@example.com',
    'ssh-rsa AAAAksdjfkjsdhfkjhsdfkjhkjhkjhkj user2@example.com',
  ],
}

###Create a group

This will create a fully functional group:

pfsense_group { 'group001':
  ensure  => 'present',
  comment => 'pfsense test group',
}

In this example the group will inherit privileges to its members:

pfsense_group { 'group001':
  ensure     => 'present',
  comment    => 'pfsense test group',
  privileges => [ 'user-shell-access', 'page-all' ],
}

NOTE: The providers are NOT aware of privilege inheritance, see Limitations for details.

###Manage packages

You need to enable a helper class. This will install a command line tool to keep the provider simple:

class { 'pfsense': }

Now you can use it like any other package provider:

package { 'iftop':
  ensure => 'present',
}

NOTE: Package names on pfSense are case-sensitive. You need to write 'Cron' instead of 'cron' to install the package.

###Deleting resources

This provider does NOT purge unmanaged resources. So you need to define a resource as 'absent' if you want it to be removed:

pfsense_user { 'user001':
  ensure   => 'absent',
  password => '$1$dSJImFph$GvZ7.1UbuWu.Yb8etC0re.',
}

pfsense_group { 'group001':
  ensure  => 'absent',
}

###pfSense facts

pfsense => true
pfsense_version => 2.1.4-RELEASE
pfsense_version_base => 8.3
pfsense_version_kernel => 8.1

##Reference

###Feature overview

pfsense.rb:

  • base provider, includes common functions
  • read/write config.xml, clear cache, config revisions

pfsense_user.rb:

  • user management
  • ssh key management
  • user privilege management
  • account expiry

pfsense_group.rb:

  • group management
  • group privilege management

###Additional user parameters

To set an account expiration date:

expiry => '2014-08-01'

To remove expiry date, set it to absent:

expiry => 'absent'

###Privileges

You must specify user/group privileges by using the internal pfSense names. The provider will not even try to validate privilege names, because pfSense silently ignores invalid privileges.

A complete list of pfSense privileges is available in priv.defs.inc from the pfSense repository: https://github.com/pfsense/pfsense/blob/master/etc/inc/priv.defs.inc

###Known limitations

You need to be aware of the following limitations:

  • No safety net. If you delete the admin user your pfSense firewall is lost.
  • User/group providers are NOT aware of group privilege inheritance.
  • The indention of config.xml will be changed. Prepare for a huge diff when making changes.
  • Removing all unmanaged resources (purge => true) is NOT supported.

##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.

##Legal

pfSense® is Copyright © 2004-2015 Electric Sheep Fencing LLC. All rights reserved.