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
Requirements
Parameters
See Also
Examples
Return Values

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.

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