1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2014, Timothy Vandenbrande <timothy.vandenbrande@gmail.com> 5# Copyright: (c) 2017, Artem Zinenko <zinenkoartem@gmail.com> 6# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 7 8DOCUMENTATION = r''' 9--- 10module: win_firewall_rule 11short_description: Windows firewall automation 12description: 13 - Allows you to create/remove/update firewall rules. 14options: 15 enabled: 16 description: 17 - Whether this firewall rule is enabled or disabled. 18 - Defaults to C(true) when creating a new rule. 19 type: bool 20 aliases: [ enable ] 21 state: 22 description: 23 - Should this rule be added or removed. 24 type: str 25 choices: [ absent, present ] 26 default: present 27 name: 28 description: 29 - The rule's display name. 30 - This is required unless I(group) is specified. 31 type: str 32 group: 33 description: 34 - The group name for the rule. 35 - If I(name) is not specified then the module will set the firewall options for all the rules in this group. 36 type: str 37 direction: 38 description: 39 - Whether this rule is for inbound or outbound traffic. 40 - Defaults to C(in) when creating a new rule. 41 type: str 42 choices: [ in, out ] 43 action: 44 description: 45 - What to do with the items this rule is for. 46 - Defaults to C(allow) when creating a new rule. 47 type: str 48 choices: [ allow, block ] 49 description: 50 description: 51 - Description for the firewall rule. 52 type: str 53 localip: 54 description: 55 - The local ip address this rule applies to. 56 - Set to C(any) to apply to all local ip addresses. 57 - Defaults to C(any) when creating a new rule. 58 type: str 59 remoteip: 60 description: 61 - The remote ip address/range this rule applies to. 62 - Set to C(any) to apply to all remote ip addresses. 63 - Defaults to C(any) when creating a new rule. 64 type: str 65 localport: 66 description: 67 - The local port this rule applies to. 68 - Set to C(any) to apply to all local ports. 69 - Defaults to C(any) when creating a new rule. 70 - Must have I(protocol) set 71 type: str 72 remoteport: 73 description: 74 - The remote port this rule applies to. 75 - Set to C(any) to apply to all remote ports. 76 - Defaults to C(any) when creating a new rule. 77 - Must have I(protocol) set 78 type: str 79 program: 80 description: 81 - The program this rule applies to. 82 - Set to C(any) to apply to all programs. 83 - Defaults to C(any) when creating a new rule. 84 type: str 85 service: 86 description: 87 - The service this rule applies to. 88 - Set to C(any) to apply to all services. 89 - Defaults to C(any) when creating a new rule. 90 type: str 91 protocol: 92 description: 93 - The protocol this rule applies to. 94 - Set to C(any) to apply to all services. 95 - Defaults to C(any) when creating a new rule. 96 type: str 97 profiles: 98 description: 99 - The profile this rule applies to. 100 - Defaults to C(domain,private,public) when creating a new rule. 101 type: list 102 aliases: [ profile ] 103 icmp_type_code: 104 description: 105 - The ICMP types and codes for the rule. 106 - This is only valid when I(protocol) is C(icmpv4) or C(icmpv6). 107 - Each entry follows the format C(type:code) where C(type) is the type 108 number and C(code) is the code number for that type or C(*) for all 109 codes. 110 - Set the value to just C(*) to apply the rule for all ICMP type codes. 111 - See U(https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml) 112 for a list of ICMP types and the codes that apply to them. 113 type: list 114notes: 115- Multiple firewall rules can share the same I(name), if there are multiple matches then the module will set the user 116 defined options for each matching rule. 117seealso: 118- module: community.windows.win_firewall 119author: 120 - Artem Zinenko (@ar7z1) 121 - Timothy Vandenbrande (@TimothyVandenbrande) 122''' 123 124EXAMPLES = r''' 125- name: Firewall rule to allow SMTP on TCP port 25 126 community.windows.win_firewall_rule: 127 name: SMTP 128 localport: 25 129 action: allow 130 direction: in 131 protocol: tcp 132 state: present 133 enabled: yes 134 135- name: Firewall rule to allow RDP on TCP port 3389 136 community.windows.win_firewall_rule: 137 name: Remote Desktop 138 localport: 3389 139 action: allow 140 direction: in 141 protocol: tcp 142 profiles: private 143 state: present 144 enabled: yes 145 146- name: Firewall rule to be created for application group 147 community.windows.win_firewall_rule: 148 name: SMTP 149 group: application 150 localport: 25 151 action: allow 152 direction: in 153 protocol: tcp 154 state: present 155 enabled: yes 156 157- name: Enable all the Firewall rules in application group 158 win_firewall_rule: 159 group: application 160 enabled: yes 161 162- name: Firewall rule to allow port range 163 community.windows.win_firewall_rule: 164 name: Sample port range 165 localport: 5000-5010 166 action: allow 167 direction: in 168 protocol: tcp 169 state: present 170 enabled: yes 171 172- name: Firewall rule to allow ICMP v4 echo (ping) 173 community.windows.win_firewall_rule: 174 name: ICMP Allow incoming V4 echo request 175 enabled: yes 176 state: present 177 profiles: private 178 action: allow 179 direction: in 180 protocol: icmpv4 181 icmp_type_code: 182 - '8:*' 183 184- name: Firewall rule to alloc ICMP v4 on all type codes 185 community.windows.win_firewall_rule: 186 name: ICMP Allow incoming V4 echo request 187 enabled: yes 188 state: present 189 profiles: private 190 action: allow 191 direction: in 192 protocol: icmpv4 193 icmp_type_code: '*' 194''' 195