community.proxmox.proxmox_cluster_firewall_security_group module – Cluster firewall security group management for Proxmox VE

Note

This module is part of the community.proxmox collection (version 2.1.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.proxmox. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.proxmox.proxmox_cluster_firewall_security_group.

New in community.proxmox 2.1.0

Synopsis

• Manage cluster-level firewall security groups in Proxmox VE.

• Security groups hold ordered firewall rules that can be attached to guest rules.

• If rules is omitted when state=present, the module only creates the group and/or updates its comment; existing rules are not read or modified.

• If rules is set (including an empty list), the module synchronizes the full ordered ruleset, mapping list index 0 to position 0, etc.

Requirements

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

• proxmoxer >= 2.3

• requests

Parameters

Parameter	Comments
api_host string	Specify the target host of the Proxmox VE cluster. Uses the PROXMOX_HOST environment variable if not specified.
api_otp string	Specify the OTP. Uses the PROXMOX_OTP environment variable if not specified.
api_password string	Specify the password to authenticate with. Uses the PROXMOX_PASSWORD environment variable if not specified.
api_port integer	Specify the target port of the Proxmox VE cluster. Uses the PROXMOX_PORT environment variable if not specified.
api_timeout integer	Time limit for requests towards the Proxmox VE API. Default: 5
api_token_id string	Specify the token ID. Uses the PROXMOX_TOKEN_ID environment variable if not specified.
api_token_secret string	Specify the token secret. Uses the PROXMOX_TOKEN_SECRET environment variable if not specified.
api_user string	Specify the user to authenticate with. Uses the PROXMOX_USER environment variable if not specified. Default: "root@pam"
ca_path path	Path to a local certificate, which will be used to verify TLS connections. Ignored if validate_certs=false.
comment string	Security group comment.
name string / required	Security group name.
purge_omitted_rule_fields boolean	Whether each rules entry is the complete desired state of the rule at its position. If true, the rules of the group are fully declarative. Optional rule fields that are omitted from a rule entry are removed from the existing rule. If false, optional rule fields that are omitted from a rule entry are preserved from the existing rule. Only used when rules is set. If not set, false is used and a deprecation warning is shown when rules is set. The default will change to true in community.proxmox 3.0.0. Choices: false true
rules list / elements=dictionary	Full ordered list of firewall rules for the group, with index 0 as position 0, etc. Omitted to manage only the group and comment, leaving current rules unchanged. [] to remove all rules. If purge_omitted_rule_fields=true, each rule entry is the complete desired state of the rule at its position. Otherwise, optional rule fields (rules[].comment, rules[].dest, etc.) that are omitted from a rule entry are preserved from the existing rule on updates. Optional rule fields except rules[].log can be removed from the existing rule by setting them to ''. rules[].log can only be removed with purge_omitted_rule_fields=true.
action string / required	Rule action (ACCEPT, DROP, REJECT, or a security group name if rules[].type is group.
comment string	Rule comment.
dest string	Match packet destination address. This can refer to a single IP address, an IP set (‘+ipsetname’) or an IP alias definition. You can also specify an address range like 20.34.101.207-201.3.9.99, or a list of IP addresses and networks (entries are separated by comma). Please do not mix IPv4 and IPv6 addresses inside such lists.
dport string	Match TCP/UDP destination port. You can use service names or simple numbers 0-65535, as defined in /etc/services. Port ranges can be specified with ‘\d+:\d+’, for example 80:85, and you can use comma separated list to match several ports or ranges.
enabled boolean	Whether the rule is active. Choices: false true ← (default)
icmp_type string	ICMP type (when rules[].proto is icmp or icmpv6/ipv6-icmp).
iface string	Network interface name.
log string	Log level for matching packets. Choices: "emerg" "alert" "crit" "err" "warning" "notice" "info" "debug" "nolog"
macro string	Built-in firewall macro name. Use predefined standard macro from https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_firewall_macro_definitions
proto string	Match IP protocol (name or number per /etc/protocols).
source string	Match packet source address. This can refer to a single IP address, an IP set (‘+ipsetname’) or an IP alias definition. You can also specify an address range like 20.34.101.207-201.3.9.99, or a list of IP addresses and networks (entries are separated by comma). Please do not mix IPv4 and IPv6 addresses inside such lists.
sport string	Match TCP/UDP source port. You can use service names or simple numbers 0-65535, as defined in /etc/services. Port ranges can be specified with ‘\d+:\d+’, for example 80:85, and you can use comma separated list to match several ports or ranges.
type string / required	Rule direction or special type. Choices: "in" "out" "forward" "group"
state string	The desired state of the security group. Choices: "present" ← (default) "absent"
validate_certs boolean	Validate the TLS certificates used for the connection to the Proxmox VE API. May be set through the environment variable PROXMOX_VALIDATE_CERTS. Choices: false true ← (default)

Attributes

Attribute	Support	Description
action_group	Action group: community.proxmox.proxmox	Use group/community.proxmox.proxmox in module_defaults to set defaults for this module.
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

Proxmox VE security group reference

Security group reference for Proxmox VE Firewall

community.proxmox.proxmox_cluster_firewall_options

Cluster-level firewall options management for Proxmox VE cluster.

community.proxmox.proxmox_node_firewall_options

Node-level firewall options management for Proxmox VE cluster.

community.proxmox.proxmox_firewall

Manage firewall rules in Proxmox.

Authentication

Complete guide for the Proxmox API authentication

Examples

- name: Webserver security group
  community.proxmox.proxmox_cluster_firewall_security_group:
    name: webserver
    comment: Managed by Ansible
    purge_omitted_rule_fields: true
    rules:
      - type: in
        action: ACCEPT
        comment: Allow HTTP
        dest: 192.168.1.100
        dport: "80"
        proto: tcp
        log: info
      - type: in
        action: ACCEPT
        comment: Allow HTTPS
        dest: 192.168.1.100
        dport: "443"
        proto: tcp
        log: info

Return Values

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

Key	Description
comment string	The security group comment. Returned: on success Sample: "Managed by Ansible"
msg string	A short message on what the module did. Returned: always Sample: "Security group web updated"
name string	The security group name. Returned: on success Sample: "webserver"
rules list / elements=dictionary	The security group rules. Returned: on success, only if state=present and rules is set Sample: []

Authors

• Clément Cruau (@PendaGTP)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication