windows_firewall
Version information
This version is compatible with:
- Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x
- Puppet >= 6.1.0 < 7.0.0
Start using this module
Add this module to your Puppetfile:
mod 'puppet-windows_firewall', '4.0.0'
Learn more about managing modules with a PuppetfileDocumentation
Windows Firewall module for Puppet
Table of Contents
- Overview - What is the windows_firewall module?
- Module Description - What does the module do?
- Setup - The basics of getting started with windows_firewall
- Usage - The classes, defined types, and their parameters available for configuration
- Implementation - An under-the-hood peek at what the module is doing
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
- Release Notes - Notes on the most recent updates to the module
Overview
This is a module that will manage the Microsoft Windows Firewall and it's exceptions.
Module Description
The windows_firewall module will primarily manage the state of the windows firewall application on your windows system. Optionally it will also allow you to configure any exceptions that you need to have in place.
Setup
What windows_firewall affects
- windows firewall service and corresponding Windows Registry keys
- windows registry keys and values for any defined exception rules
Beginning with windows_firewall
The windows_firewall resource allows you to manage the firewall service itself.
class { 'windows_firewall': ensure => 'stopped' }
On Server 2012 and up, additional features are available to be managed, including Windows firewall zones Domain, Public, and Private via types and providers.
class { 'windows_firewall':
ensure => 'running',
}
windowsfirewall { 'domain':
ensure => 'present',
default_outbound_action => 'allow',
}
You may also query resources on Server 2012 and up via puppet resource windowsfirewall
.
Once the windows firewall is managed you may then want to start managing the rules and exceptions within it.
windows_firewall::exception { 'WINRM':
ensure => present,
direction => 'in',
action => 'allow',
enabled => true,
protocol => 'TCP',
local_port => 5985,
remote_port => 'any',
display_name => 'Windows Remote Management HTTP-In',
description => 'Inbound rule for Windows Remote Management via WS-Management. [TCP 5985]',
}
Usage
Classes and Defined Types
Class: windows_firewall
Parameters within windows_firewall
:
ensure
Determines whether or not the service must be running and enabled. If not included, the module will assume that the windows firewall service should be running and enabled. Valid values are 'running' and 'stopped'.
Defined Type: windows_firewall::exception
Parameters within windows_firewall::exception
:
ensure
Determines whether or not the firewall exception is 'present' or 'absent'
direction
Sets the direction of the exception rule, either: 'in' or 'out'.
action
Sets the action type of the exception, either: 'allow' or 'block'.
enabled
Determines whether the exception is enabled, either: 'true' or 'false'. Defaults to 'true'.
protocol
Sets the protocol to be included in the exception rule, either: 'TCP' or 'UDP'.
local_port
Defines the local port to be included in the exception for port-based exception rules, either: an integer between 1 and 65535, a port range (two integers separated by a hyphen, a comma separated list of integers, or the string 'any'.
remote_port
Defines the remote port to be included in the exception for port-based exception rules, either: an integer between 1 and 65535, a port range (two integers separated by a hyphen, a comma separated list of integers, or the string 'any'.
remote_ip
Specifies remote hosts that can use this rule.
program
Defines the full path to the program to be included in the exception for program-based exception rules
display_name
Sets the Display Name of the exception rule. Defaults to the title of the resource.
description
A description of the exception to apply.
allow_edge_traversal
Specifies that the traffic for this exception traverses an edge device
Parameters within windowsfirewall
(Limited to 2012 and up)
ensure
Determines whether the firewall zone is Enabled, 'present', or Disabled, 'absent'.
allow_inbound_rules
Specifies whether the firewall blocks inbound traffic or not. If set to 'False', then all inbound firewall rules will be ignored. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
allow_local_firewall_rules
Specifies whether the local firewall rules should be merged into the effective policy along with Group Policy settings. If set to 'False', then all rules defined by the local administrator are ignored, and only GPO based firewall rules are applied. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
allow_local_ipsec_rules
Specifies whether the local IPsec rules should be merged into the effective policy along with Group Policy settings. If set to 'False', then all rules defined by the local administrator are ignored, and only GPO based IPsec rules are applied. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
allow_unicast_response_to_multicast
Allows unicast responses to multi-cast traffic. If set to 'False', the computer discards unicast responses to outgoing multi-cast or broadcast messages. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
allow_user_apps
Specifies whether traffic from local user applications is allowed through the firewall. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
allow_user_ports
Specifies whether traffic is allowed through local user ports. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
default_inbound_action
Specifies how to filter inbound traffic. 'Allow' allows all inbound network traffic, whether or not it matches an inbound rule. Accepts 'Block', 'Allow', or 'NotConfigured'. Defaults to 'Block'.
default_outbound_action
Specifies how to filter outbound traffic. 'Block' blocks outbound network traffic that does not match an outbound rule. Accepts 'Block', 'Allow', or 'NotConfigured'. Defaults to 'Allow'.
disabled_interface_aliases
Specifies a list of interfaces on which firewall settings are excluded.
enable_stealth_mode_for_ipsec
Enables stealth mode for IPsec traffic. If set to 'True', it will block outgoing ICMP unreachable and TCP reset messages for a port when no application is listening on that port. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'NotConfigured'.
log_allowed
Specifies how to handle logging for allowed packets. If set to 'True', Windows writes an entry to the log whenever an incoming or outgoing connection is allowed by the policy. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'False'.
log_blocked
Specifies how to handle logging for dropped packets. If set to 'True', Windows writes an entry to the log whenever an incoming or outgoing connection is prevented by the policy. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'False'.
log_ignored
Specifies how to handle logging for ignored packets. If set to 'True', windows writes an entry to the log whenever an incoming or outgoing connection is prevented by the policy. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'False'.
log_file_name
Specifies the path and filename of the file to which log entries are
written. Accepts windows environment variables. Defaults to
%windir%\system32\logfiles\firewall\pfirewall.log
.
log_max_size_kilobytes
Specifies the maximum file size of the log. Accepts a number between '1' and '32767'. Defaults to '4096'.
notify_on_listen
Specifies whether user gets notified when an application starts listening for inbound connections. If set to 'False', Windows does not notify the user whenever a program or service starts listening for inbound connections. Accepts 'True', 'False', or 'NotConfigured'. Defaults to 'True'.
Reference
Classes
Public Classes
windows_firewall
: The main class of the module for managing the state of the windows firewall.
Defined Types
Public Types
- [
windows_firewall::exception
] Manages the configuration of firewall exceptions
Module Specific Provider
- [
windowsfirewall
] Manages the configuration of firewall zones.
Limitations
This module is tested on the following platforms:
- Windows 2008 R2, Windows 2012 R2, and Windows 2016.
Development
Contributing
Please read CONTRIBUTING.md for full details on contributing to this project.
Changelog
All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.
v4.0.0 (2021-03-20)
Breaking changes:
- Drop Puppet 5; require Puppet 6.1.0 #114 (bastelfreak)
Fixed bugs:
- Fixing display_name to default to the resource title #113 (msiroskey)
- Fix truncated verification #107 (JasonN3)
Closed issues:
- remote_port and local_port should also support string for comma-separated port list or dash-separated port range. #80
Merged pull requests:
- Local and Remote port range and csv #80 #106 (sbezzy)
- Fixed provider for making changes via Puppet #104 (Nekototori)
- Make more use of data types #103 (alexjfisher)
v3.0.0 (2020-07-30)
Breaking changes:
- modulesync 2.7.0 and drop puppet 4 #88 (bastelfreak)
Implemented enhancements:
- New Provider with Types and Docs #89 (alexjfisher)
Fixed bugs:
- Master O/S conditionals Completely Broken #66
Closed issues:
- Missing dependency puppetlabs-registry in PuppetForge version. #29
Merged pull requests:
- modulesync 3.0.0 & puppet-lint updates #101 (bastelfreak)
- Bump puppetlabs/registry #99 (spotter-puppet)
- Allow puppetlabs/stdlib 6.x #98 (dhoppe)
- Remove duplicate CONTRIBUTING.md file #94 (dhoppe)
- Support puppetlabs/stdlib 6.x. #92 (pillarsdotnet)
- removed operatingsystemversion and old os testing #90 (Nekototori)
- Remove Linux acceptance nodesets #84 (ekohl)
v2.0.2 (2018-10-19)
Fixed bugs:
- Documentation is not updated for new puppet 4 data types #65
Closed issues:
- Update documentation for changed attribute data types #79
Merged pull requests:
- modulesync 2.2.0 and allow puppet 6.x #82 (bastelfreak)
- example and param doc update #81 (joeypiccola)
- allow puppetlabs/stdlib 5.x #77 (bastelfreak)
v2.0.1 (2018-08-20)
Fixed bugs:
- Remove hardcoded c drive reference for firewall exceptions #63 (TraGicCode)
Closed issues:
- Update puppetlabs-registry module dependency #72
- Don't working when Windows installed not on drive C:\ #52
- Use in-built Windows Facter facts #45
- liamjbennett/win_facts module causes Registry errors #34
- fixing remote ports #22
- fix broken ensure=absent #21
Merged pull requests:
- allow puppetlabs/registry 2.x #74 (bastelfreak)
- Remove docker nodesets #69 (bastelfreak)
- drop EOL OSs; fix puppet version range #68 (bastelfreak)
- Puppet 4+ data types to get rid of some validate_re #61 (ofalk)
v2.0.0 (2017-11-17)
Merged pull requests:
- bump puppet version dependency to >= 4.7.1 \< 6.0.0 #58 (bastelfreak)
v1.1.0 (2017-02-11)
This is the last release with Puppet3 support!
- Fix several markdown issues
- Add missing badges
- Fix several rubocop issues
- Set min version_requirement for Puppet + bump deps
- Rubocop: automatic fixes
2016-05-08 Release 1.0.3
- modulesync with voxpupuli defaults
2016-02-03 Release 1.0.2
- Added support for matching remote ports
2015-07-23 Release 1.0.1
- Fixed rules not being deleted
2013-10-20 Release 0.0.3
- Add program rule support, various other fixes
2013-10-20 Release 0.0.2
- Some bug fixes and additional testing
2013-10-20 Release 0.0.1
- The initial version
* This Changelog was automatically generated by github_changelog_generator
Dependencies
- puppetlabs/stdlib (>= 4.25.1 < 7.0.0)
- puppetlabs/registry (>= 1.1.1 < 4.0.0)
Copyright (c) 2014 Liam Bennett (liamjbennett@gmail.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.