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

From Get docs
Ansible/docs/2.10/collections/community/hrobot/firewall module


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

Note

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

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

hetzner_password

string / required

The password for the Robot webservice user.

hetzner_user

string / required

The username for the Robot webservice user.

port

string

  • main

  • kvm

Switch port of firewall.

rules

dictionary

Firewall rules.

input

list / elements=dictionary

Input firewall rules.

action

string / required

  • 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

  • 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

  • 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

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

whitelist_hos

boolean

  • no
  • yes

Whether Hetzner services have access.



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


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.


Sample:

True




Authors

  • Felix Fontein (@felixfontein)

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