W3cubDocs

/Ansible

community.hrobot.firewall – Manage Hetzner’s dedicated server firewall

Note

This plugin is part of the community.hrobot collection (version 1.2.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.hrobot.

To use it in a playbook, specify: community.hrobot.firewall.

Synopsis

  • Manage Hetzner’s dedicated server firewall.
  • Note that idempotency check for TCP flags simply compares strings and doesn’t try to interpret the rules. This might change in the future.

Requirements

The below requirements are needed on the host that executes this module.

  • ipaddress

Parameters

Parameter Choices/Defaults Comments
allowlist_hos
boolean
    Choices:
  • no
  • yes
Whether Hetzner services have access.

aliases: whitelist_hos
hetzner_password
string / required
The password for the Robot webservice user.
hetzner_user
string / required
The username for the Robot webservice user.
port
string
    Choices:
  • main ←
  • kvm
Switch port of firewall.
rules
dictionary
Firewall rules.
input
list / elements=dictionary
Input firewall rules.
action
string / required
    Choices:
  • accept
  • discard
Action if rule matches.
dst_ip
string
Destination IP address or subnet address.
CIDR notation.
dst_port
string
Destination port or port range.
ip_version
string / required
    Choices:
  • ipv4
  • ipv6
Internet protocol version.
Note that currently, only IPv4 is supported by Hetzner.
name
string
Name of the firewall rule.
protocol
string
Protocol above IP layer
src_ip
string
Source IP address or subnet address.
CIDR notation.
src_port
string
Source port or port range.
tcp_flags
string
TCP flags or logical combination of flags.
Flags supported by Hetzner are syn, fin, rst, psh and urg.
They can be combined with | (logical or) and & (logical and).
See the documentation for more information.
server_ip
string / required
The server's main IP address.
state
string
    Choices:
  • present ←
  • absent
Status of the firewall.
Firewall is active if state is present, and disabled if state is absent.
timeout
integer
Default:
180
Timeout (in seconds) for waiting for firewall to be configured.
update_timeout
integer
Default:
30
Timeout to use when configuring the firewall.
Note that the API call returns before the firewall has been successfully set up.
wait_delay
integer
Default:
10
Delay to wait (in seconds) before checking again whether the firewall has been configured.
wait_for_configured
boolean
    Choices:
  • no
  • yes ←
Whether to wait until the firewall has been successfully configured before determining what to do, and before returning from the module.
The API returns status in progress when the firewall is currently being configured. If this happens, the module will try again until the status changes to active or disabled.
Please note that there is a request limit. If you have to do multiple updates, it can be better to disable waiting, and regularly use community.hrobot.firewall_info to query status.

See Also

See also

Firewall documentation

Hetzner’s documentation on the stateless firewall for dedicated servers

community.hrobot.firewall_info

Retrieve information on firewall configuration.

Examples

- name: Configure firewall for server with main IP 1.2.3.4
  community.hrobot.firewall:
    hetzner_user: foo
    hetzner_password: bar
    server_ip: 1.2.3.4
    state: present
    allowlist_hos: yes
    rules:
      input:
        - name: Allow everything to ports 20-23 from 4.3.2.1/24
          ip_version: ipv4
          src_ip: 4.3.2.1/24
          dst_port: '20-23'
          action: accept
        - name: Allow everything to port 443
          ip_version: ipv4
          dst_port: '443'
          action: accept
        - name: Drop everything else
          ip_version: ipv4
          action: discard
  register: result

- ansible.builtin.debug:
    msg: "{{ result }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
firewall
dictionary
success
The firewall configuration.
allowlist_hos
boolean
added in 1.2.0 of community.hrobot
 success
Whether Hetzner services have access.

Sample:
True
port
string
success
Switch port of firewall.
main or kvm.

Sample:
main
rules
dictionary
success
Firewall rules.
input
list / elements=dictionary
success
Input firewall rules.
action
string
success
Action if rule matches.
accept or discard.

Sample:
accept
dst_ip
string
success
Destination IP address or subnet address.
CIDR notation.

Sample:
1.2.3.4/32
dst_port
string
success
Destination port or port range.

Sample:
443
ip_version
string
success
Internet protocol version.

Sample:
ipv4
name
string
success
Name of the firewall rule.

Sample:
Allow HTTP access to server
protocol
string
success
Protocol above IP layer

Sample:
tcp
src_ip
string
success
Source IP address or subnet address.
CIDR notation.
src_port
string
success
Source port or port range.
tcp_flags
string
success
TCP flags or logical combination of flags.
server_ip
string
success
Server's main IP address.

Sample:
1.2.3.4
server_number
integer
success
Hetzner's internal server number.

Sample:
12345
status
string
success
Status of the firewall.
active or disabled.
Will be in process if the firewall is currently updated, and wait_for_configured is set to no or timeout to a too small value.

Sample:
active
whitelist_hos
boolean
success
Whether Hetzner services have access.
Old name of return value allowlist_hos, will be removed eventually.

Sample:
True


Authors

  • Felix Fontein (@felixfontein)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/hrobot/firewall_module.html