ufw

Table of Contents

1. Description
2. Setup - The basics of getting started with ufw
   • What ufw affects
   • Setup requirements
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module
6. License

Description

The ufw module manages the uncomplicated firewall (ufw). It allows to control netfilter rules (via ufw_rule resource) and routes (via ufw_route resource) as well as to manage ufw related configuration files.

This module succeeds the original attachmentgenie-ufw module that is now deprecated.

The key improvements:

• supports ufw route
• supports ufw framework (after.rules, before.rules, etc)
• supports purging unmanaged routes and rules

See limitations for the unsupported functionality.

Setup

What ufw affects

• Ufw rule and route settings of managed nodes.
• Configuration files (/etc/default/ufw, /etc/logrotate.d/ufw, /etc/rsyslog.d/20-ufw.conf, /etc/ufw/sysctl.conf).
• Custom rule files (after.rules, after6.rules, before.rules, before6.rules).
• Purges unmanaged ufw rules (if selected to purge).
• Purges unmanaged ufw routing rules (if selected to purge).
• Ufw package and service.

Setup requirements

The ufw module does not require any specific setup to be used.

Usage

Warning: UFW denies incoming traffic by default, so it locks out users unless provided a rule that allows remote management (ssh, etc).

Basic

class {'ufw':
  purge_unmanaged_rules  => true,
  purge_unmanaged_routes => true,
  rules                  => {
    'allow ssh connections' => {
      'action'       => 'allow',
      'to_ports_app' => 22,
    },
  }
}

Full

Entries in the rules accept the same parameters as ufw_rule does.

Entries in the routes accept the same parameters as ufw_route does.

Addresses support both individual hosts (10.1.3.1) and networks (10.1.3.0/24) in ipv4 and ipv6 formats.

To specify a list of ports, separate them with a comma without whitespaces: 80,443

To specify a range of ports, separate them by a colon without whitespaces: 8080:8085

Check REFERENCE.md for the parameter descriptions.

class {'ufw':
  manage_package           => true,
  package_name             => 'ufw',
  packege_ensure           => 'present',
  manage_service           => true,
  service_name             => 'ufw',
  service_ensure           => 'running',
  rules                    => {
    'sample rule' => {
      'ensure'         => 'present',
      'action'         => 'allow',
      'direction'      => 'out',
      'interface'      => 'eth0',
      'log'            => 'log',
      'from_addr'      => '10.1.3.0/24',
      'from_ports_app' => 3133,
      'to_addr'        => '10.3.3.3',
      'to_ports_app'   => 2122,
      'proto'          => 'tcp'
    },
  },
  routes                   => {
    'sample route' => {
      'ensure'         => 'present',
      'action'         => 'allow',
      'interface_in'   => 'any',
      'interface_out'  => 'any',
      'log'            => 'log',
      'from_addr'      => 'any',
      'from_ports_app' => undef,
      'to_addr'        => '10.5.0.0/24',
      'to_ports_app'   => undef,
      'proto'          => 'any',
    },
  },
  purge_unmanaged_rules    => true,
  purge_unmanaged_routes   => true,
  manage_default_config    => true,
  default_config_content   => file('ufw/default'),
  manage_logrotate_config  => true,
  logrotate_config_content => file('ufw/logrotate'),
  manage_rsyslog_config    => true,
  rsyslog_config_content   => file('ufw/rsyslog'),
  manage_sysctl_config     => true,
  sysctl_config_content    => file('ufw/sysctl'),
  manage_before_rules      => true,
  before_rules_content     => file('ufw/before.rules'),
  manage_before6_rules     => true,
  before6_rules_content    => file('ufw/before6.rules'),
  manage_after_rules       => true,
  after_rules_content      => file('ufw/after.rules'),
  manage_after6_rules      => true,
  after6_rules_content     => file('ufw/after6.rules'),
}

ufw_rule simple usage

ufw_rule { 'allow ssh':
  action         => 'allow',
  to_ports_app   => 22,
}

ufw_rule { 'allow https on eth1':
  action         => 'allow',
  to_ports_app   => 443,
  interface      => 'eth1'
}

ufw_rule usage

ufw_rule controls regular, non-routing rules.

Important: The default action is reject for both ufw_rule and ufw_route. So the traffic is rejected if action parameter is omitted.

ufw_rule { 'allow ssh from internal networks':
  ensure         => 'present',
  action         => 'allow',
  direction      => 'in',
  interface      => undef,
  log            => undef,
  from_addr      => '10.1.3.0/24',
  from_ports_app => 'any',
  to_addr        => '10.3.0.1',
  to_ports_app   => 22,
  proto          => 'tcp',
}

ufw_route usage

ufw_route controls routing rules.

ufw_route { 'route vpn traffic to internal net':
  ensure         => 'present',
  action         => 'allow',
  interface_in   => 'tun0',
  interface_out  => 'eth0',
  log            => 'log',
  from_addr      => 'any',
  from_ports_app => undef,
  to_addr        => '10.5.0.0/24',
  to_ports_app   => undef,
  proto          => 'any',
}

Reference

See REFERENCE.md.

Limitations

• The module does not handle ordering. The rules are added in the order they provided.
• It's possible to update a rule, but the update is performed through recreation which changes ordering.
• Comment field is used as a rule/route name. Duplicate comments may cause unexpected behavior.

Development and Contribution

See DEVELOPMENT.md.

License

MIT

Reference

Table of Contents

Classes

Public Classes

• ufw: The ufw class
• ufw::config: Manages ufw related configuration files
• ufw::install: Manages ufw package
• ufw::service: Manages ufw service

Private Classes

• ufw::params: Parameters for the ufw class

Resource types

• ufw_route: a ufw_route type controls routing rules
• ufw_rule: a ufw_rule type controls regular rules

Data types

• Ufw::LogLevel

Classes

ufw

The ufw class controls state of the ufw installation and service in the system. It also applies firewall rules.

Examples

class {'ufw':
  manage_package           => true,
  package_name             => 'ufw',
  packege_ensure           => 'present',
  manage_service           => 'true',
  service_name             => 'ufw',
  service_ensure           => 'running',
  rules                    => {
      'sample rule' => {
        'ensure'         => 'present',
        'action'         => 'allow',
        'direction'      => 'out',
        'interface'      => 'eth0',
        'log'            => 'log',
        'from_addr'      => '10.1.3.0/24',
        'from_ports_app' => 3133,
        'to_addr'        => '10.3.3.3',
        'to_ports_app'   => 2122,
        'proto'          => 'tcp',
      },
  },
  routes                   => {
    'sample route' => {
      'ensure'         => 'present',
      'action'         => 'allow',
      'interface_in'   => 'any',
      'interface_out'  => 'any',
      'log'            => 'log',
      'from_addr'      => 'any',
      'from_ports_app' => undef,
      'to_addr'        => '10.5.0.0/24',
      'to_ports_app'   => undef,
      'proto'          => 'any',
    },
  },
  purge_unmanaged_rules    => true,
  purge_unmanaged_routes   => true,
  log_level                => 'low',
  manage_default_config    => true,
  default_config_content   => file('ufw/default'),
  manage_logrotate_config  => true,
  logrotate_config_content => file('ufw/logrotate'),
  manage_rsyslog_config    => true,
  rsyslog_config_content   => file('ufw/rsyslog'),
  manage_sysctl_config     => true,
  sysctl_config_content    => file('ufw/sysctl'),
  manage_before_rules      => true,
  before_rules_content     => file('ufw/before'),
  manage_before6_rules     => true,
  before6_rules_content    => file('ufw/before6'),
  manage_after_rules       => true,
  after_rules_content      => file('ufw/after'),
  manage_after6_rules      => true,
  after6_rules_content     => file('ufw/after6'),
}

Parameters

The following parameters are available in the ufw class:

• manage_package
• package_name
• packege_ensure
• manage_service
• service_ensure
• service_name
• rules
• routes
• purge_unmanaged_rules
• purge_unmanaged_routes
• log_level
• manage_default_config
• default_config_content
• manage_logrotate_config
• logrotate_config_content
• manage_rsyslog_config
• rsyslog_config_content
• manage_sysctl_config
• sysctl_config_content
• manage_before_rules
• before_rules_content
• manage_before6_rules
• before6_rules_content
• manage_after_rules
• after_rules_content
• manage_after6_rules
• after6_rules_content

manage_package

Data type: Boolean

If the class should manage an ufw package.

Default value: $ufw::params::manage_package

package_name

Data type: String[1]

Ufw package to manage.

Default value: $ufw::params::package_name

packege_ensure

Data type: String[1]

What state the package should be in.

Default value: $ufw::params::package_ensure

manage_service

Data type: Boolean

If the module should manage the ufw service state.

Default value: $ufw::params::manage_service

service_ensure

Data type: Stdlib::Ensure::Service

Defines the state of the ufw service.

Default value: $ufw::params::service_ensure

service_name

Data type: String[1]

The name of the ufw service to manage.

Default value: $ufw::params::service_name

rules

Data type: Hash[String[1], Hash]

Rule definitions to apply.

Default value: $ufw::params::rules

routes

Data type: Hash[String[1], Hash]

Routing definitions to apply.

Default value: $ufw::params::routes

purge_unmanaged_rules

Data type: Boolean

Defines if unmanaged rules should be purged. Default: false

Default value: $ufw::params::purge_unmanaged_rules

purge_unmanaged_routes

Data type: Boolean

Defines if unmanaged routes should be purged. Default: false

Default value: $ufw::params::purge_unmanaged_routes

log_level

Data type: Ufw::LogLevel

Logging level. Default: 'low'

Default value: $ufw::params::log_level

manage_default_config

Data type: Boolean

If the module should manage /etc/default/ufw. Default: true

Default value: $ufw::params::manage_default_config

default_config_content

Data type: String[1]

Configuration content to put to /etc/default/ufw. Default is taken from files/default of this module.

Default value: $ufw::params::default_config_content

manage_logrotate_config

Data type: Boolean

If the module should manage /etc/logrotate.d/ufw. Default: true

Default value: $ufw::params::manage_logrotate_config

logrotate_config_content

Data type: String[1]

Configuration content to put to /etc/logrotate.d/ufw. Default is taken from files/logrotate of this module.

Default value: $ufw::params::logrotate_config_content

manage_rsyslog_config

Data type: Boolean

If the module should manage /etc/rsyslog.d/20-ufw.conf. Default: true

Default value: $ufw::params::manage_rsyslog_config

rsyslog_config_content

Data type: String[1]

Configuration content to put to /etc/rsyslog.d/20-ufw.conf. Default is taken from files/ufw of this module.

Default value: $ufw::params::rsyslog_config_content

manage_sysctl_config

Data type: Boolean

If the module should manage /etc/ufw/sysctl.conf. Default: true

Default value: $ufw::params::manage_sysctl_config

sysctl_config_content

Data type: String[1]

Configuration content to put to /etc/ufw/sysctl.conf. Default is taken from files/sysctl of this module.

Default value: $ufw::params::sysctl_config_content

manage_before_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/before.rules. Default: true

Default value: $ufw::params::manage_before_rules

before_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/before.rules. Default is taken from files/before.rules of this module.

Default value: $ufw::params::before_rules_content

manage_before6_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/before6.rules. Default: true

Default value: $ufw::params::manage_before6_rules

before6_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/before6.rules. Default is taken from files/before6.rules of this module.

Default value: $ufw::params::before6_rules_content

manage_after_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/after.rules. Default: true

Default value: $ufw::params::manage_after_rules

after_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/after.rules. Default is taken from files/after.rules of this module.

Default value: $ufw::params::after_rules_content

manage_after6_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/after6.rules. Default: true

Default value: $ufw::params::manage_after6_rules

after6_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/after6.rules. Default is taken from files/after6.rules of this module.

Default value: $ufw::params::after6_rules_content

ufw::config

Manages ufw related configuration files.

Examples

class {'ufw::config':
  log_level                => 'low',
  manage_default_config    => true,
  default_config_content   => file('ufw/default'),
  manage_logrotate_config  => true,
  logrotate_config_content => file('ufw/logrotate'),
  manage_rsyslog_config    => true,
  rsyslog_config_content   => file('ufw/rsyslog'),
  manage_sysctl_config     => true,
  sysctl_config_content    => file('ufw/sysctl'),
  manage_before_rules      => true,
  before_rules_content     => file('ufw/before.rules'),
  manage_before6_rules     => true,
  before6_rules_content    => file('ufw/before6.rules'),
  manage_after_rules       => true,
  after_rules_content      => file('ufw/after.rules'),
  manage_after6_rules      => true,
  after6_rules_content     => file('ufw/after.rules'),
}

Parameters

The following parameters are available in the ufw::config class:

• log_level
• manage_default_config
• default_config_content
• manage_logrotate_config
• logrotate_config_content
• manage_rsyslog_config
• rsyslog_config_content
• manage_sysctl_config
• sysctl_config_content
• manage_before_rules
• before_rules_content
• manage_before6_rules
• before6_rules_content
• manage_after_rules
• after_rules_content
• manage_after6_rules
• after6_rules_content

log_level

Data type: Ufw::LogLevel

Logging level. Default: 'low'

Default value: $ufw::log_level

manage_default_config

Data type: Boolean

Controls if the module should manage /etc/default/ufw.

Default value: $ufw::manage_default_config

default_config_content

Data type: String[1]

Configuration content to put to /etc/default/ufw.

Default value: $ufw::default_config_content

manage_logrotate_config

Data type: Boolean

Controls if the module should manage /etc/logrotate.d/ufw.

Default value: $ufw::manage_logrotate_config

logrotate_config_content

Data type: String[1]

Configuration content to put to /etc/logrotate.d/ufw.

Default value: $ufw::logrotate_config_content

manage_rsyslog_config

Data type: Boolean

Controls if the module should manage /etc/rsyslog.d/20-ufw.conf.

Default value: $ufw::manage_rsyslog_config

rsyslog_config_content

Data type: String[1]

Configuration content to put to /etc/rsyslog.d/20-ufw.conf.

Default value: $ufw::rsyslog_config_content

manage_sysctl_config

Data type: Boolean

Controls if the module should manage /etc/ufw/sysctl.conf.

Default value: $ufw::manage_sysctl_config

sysctl_config_content

Data type: String[1]

Configuration content to put to /etc/ufw/sysctl.conf.

Default value: $ufw::sysctl_config_content

manage_before_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/before.rules.

Default value: $ufw::manage_before_rules

before_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/before.rules.

Default value: $ufw::before_rules_content

manage_before6_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/before6.rules.

Default value: $ufw::manage_before6_rules

before6_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/before6.rules.

Default value: $ufw::before6_rules_content

manage_after_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/after.rules.

Default value: $ufw::manage_after_rules

after_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/after.rules.

Default value: $ufw::after_rules_content

manage_after6_rules

Data type: Boolean

Controls if the module should manage /etc/ufw/after6.rules.

Default value: $ufw::manage_after6_rules

after6_rules_content

Data type: String[1]

Configuration content to put to /etc/ufw/after6.rules.

Default value: $ufw::after6_rules_content

ufw::install

This class manages ufw package installation.

Examples

class {'ufw::install':
  manage_package => true,
  package_name   => 'ufw',
  packege_ensure => 'present',
}

Parameters

The following parameters are available in the ufw::install class:

• manage_package
• package_name
• packege_ensure

manage_package

Data type: Boolean

If the class should manage an ufw package.

Default value: $ufw::manage_package

package_name

Data type: String[1]

Ufw package to manage.

Default value: $ufw::package_name

packege_ensure

Data type: String[1]

What state the package should be in.

Default value: $ufw::packege_ensure

ufw::service

Manages ufw service.

Examples

class {'ufw::service':
  manage_service => true,
  service_ensure => 'running',
  service_name   => 'ufw',
}

Parameters

The following parameters are available in the ufw::service class:

• manage_service
• service_ensure
• service_name

manage_service

Data type: Boolean

If the module should manage the ufw service state.

Default value: $ufw::manage_service

service_ensure

Data type: Stdlib::Ensure::Service

Defines the state of the ufw service.

Default value: $ufw::service_ensure

service_name

Data type: String[1]

The name of the ufw service to manage.

Default value: $ufw::service_name

Resource types

ufw_route

This type provides Puppet with the capabilities to manage ufw routing rules.

Important: The default action is reject, so traffic would be rejected if action parameter is omitted.

Autorequires:

• Class[ufw::install]

Examples

ufw_route { 'route vpn traffic to internal net':
  ensure         => 'present',
  action         => 'allow',
  interface_in   => 'tun0',
  interface_out  => 'eth0',
  log            => 'log',
  from_addr      => 'any',
  from_ports_app => undef,
  to_addr        => '10.5.0.0/24',
  to_ports_app   => undef,
  proto          => 'any',
}

Properties

The following properties are available in the ufw_route type.

action

Data type: Enum[allow, deny, reject, limit]

Action to perform. default: reject

Default value: reject

ensure

Data type: Enum[present, absent]

Whether this resource should be present or absent on the target system.

Default value: present

from_addr

Data type: Optional[String]

Source address. default: any

Default value: any

from_ports_app

Data type: Optional[Variant[Integer, String]]

Source address ports or app.

interface_in

Data type: Optional[String]

Interface that recieves traffic.

interface_out

Data type: Optional[String]

Interface that sends traffic.

log

Data type: Optional[Enum[log, log-all]]

Logging option.

proto

Data type: Optional[String]

Protocol. default: any

Default value: any

to_addr

Data type: Optional[String]

Destination address. default: any

Default value: any

to_ports_app

Data type: Optional[Variant[Integer, String]]

Destination address ports or app.

Parameters

The following parameters are available in the ufw_route type.

• name

name

namevar

Data type: String

The name of the resource you want to manage.

ufw_rule

This type provides Puppet with the capabilities to manage regular ufw rules.

Important: The default action is reject, so traffic would be rejected if action parameter is omitted.

Autorequires:

• Class[ufw::install]

Examples

ufw_rule { 'allow ssh from internal networks':
  ensure         => 'present',
  action         => 'allow',
  direction      => 'in',
  interface      => undef,
  log            => undef,
  from_addr      => '10.1.3.0/24',
  from_ports_app => 'any',
  to_addr        => '10.3.0.1',
  to_ports_app   => 22,
  proto          => 'tcp',
}

Properties

The following properties are available in the ufw_rule type.

action

Data type: Enum[allow, deny, reject, limit]

Action to perform. default: reject

Default value: reject

direction

Data type: Enum['in', 'out']

Traffic direction. default: in

Default value: in

ensure

Data type: Enum[present, absent]

Whether this resource should be present or absent on the target system.

Default value: present

from_addr

Data type: Optional[String]

Source address. default: any

Default value: any

from_ports_app

Data type: Optional[Variant[Integer, String]]

Source address ports or app.

interface

Data type: Optional[String]

Interface that recieves traffic.

log

Data type: Optional[Enum[log, log-all]]

Logging option.

proto

Data type: Optional[String]

Protocol. default: any

Default value: any

to_addr

Data type: Optional[String]

Destination address. default: any

Default value: any

to_ports_app

Data type: Optional[Variant[Integer, String]]

Destination address ports or app.

Parameters

The following parameters are available in the ufw_rule type.

• name

name

namevar

Data type: String

The name of the resource you want to manage.

Data types

Ufw::LogLevel

The Ufw::LogLevel data type.

Alias of

Enum['off', 'low', 'medium', 'high', 'full']

Changelog

All notable changes to this project will be documented in this file.

Release 1.0.3

Features

• Added ufw service refresh when configuration files change (#6)
• Added more acceptance tests (#7)
• Added support for logging level setting (#8)

Bugfixes

• No longer attempt to load rules and routes before ufw is installed (#5)

Release 1.0.2

Bugfixes

• Removed stdlib types from ufw_rule and ufw_route to allow module run on agent nodes

Release 1.0.1

Features

• Added Debian 8.0 "Jessie", Debian 9.0 "Stretch" to the list of supported systems
• Added Ubuntu 16.04 "Xenial", Ubuntu 20.04 "Focal" to the list of supported systems

Release 1.0.0

Features

• Initial release of the module

Template

Features

Bugfixes

Known Issues