diff --git a/.README.html b/.README.html index 791e11a..5f107f0 100644 --- a/.README.html +++ b/.README.html @@ -137,6 +137,11 @@

Contents

+

Requirements

+

See below

+

Collection requirements

+

The role requires external collections only for management of +rpm-ostree nodes. Please run the following command to +install them if you need to manage rpm-ostree nodes:

+
ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Limitations

Configuration over Network

The configuration of the firewall could limit access to the machine @@ -237,15 +251,15 @@

Gathering firewall ansible facts

To gather the firewall system role's ansible facts, call the system role with no arguments e.g.

-
vars:
-  firewall:
-

Another option is to gather a more detailed version of the ansible -facts by using the detailed argument e.g.

vars:
-  firewall:
-    detailed: true
+ firewall: +

Another option is to gather a more detailed version of the ansible +facts by using the detailed argument e.g.

+
vars:
+  firewall:
+    detailed: true

WARNING: firewall_config uses considerably more memory (+ ~165KB) when detailed=True. For reference, by default, firewall_config takes ~3KB when @@ -280,99 +294,99 @@

firewall_config

default_zone contains the configured default zone for the managed node's firewalld installation. It is a string value.

JSON representation of the structure of firewall_config fact:

-
{
-  "default": {...},
-  "custom": {...},
-  "default_zone": "public",
-}
+
{
+  "default": {...},
+  "custom": {...},
+  "default_zone": "public",
+}

default

The default subdictionary of firewall_config contains the default configuration for the managed node's firewalld configuration. This subdictionary only changes with changes to the managed node's firewalld installation.

default without detailed parameter set to true

-
"default": {
-  "zones": ["public",...],
-  "services": ["amanda_client",...],
-  "icmptypes": [...],
-  "helpers": [...],
-  "ipsets": [...],
-  "policies": [...],
-}
-

default when parameter set to true

"default": {
-  "zones": {
-    "public": {
-      ...
-    },
-    ...
-  },
-  "services": {
-    "amanda_client":{
-      ...
-    },
-    ...
-  },
-  "icmptypes": {
-    ...
-  },
-  "helpers": {
-    ...
-  },
-  "ipsets": {
-    ...
-  },
-  "policies": {
-    ...
-  },
-}
-

custom

-

The custom subdictionary contains any differences from the default -firewalld configuration. This includes a repeat for a default element if -that element has been modified in any way, and any new elements -introduced in addition to the defaults.

-

This subdictionary will be modified by any changes to the firewalld -installation done locally or remotely via the firewall system role.

-

If the managed nodes firewalld settings are not different from the -defaults, the custom key and subdictionary will not be present in -firewall_config. Additionally, if any of firewalld's settings have not -changed from the default, there will not be a key-value pair for that -setting in custom.

-

Below is the state of the custom subdictionary where at least one -permanent change was made to each setting:

+ "zones": ["public",...], + "services": ["amanda_client",...], + "icmptypes": [...], + "helpers": [...], + "ipsets": [...], + "policies": [...], +} +

default when parameter set to true

"custom": {
+class="sourceCode json">"default": {
   "zones": {
-    "custom_zone": {
+    "public": {
       ...
     },
     ...
   },
   "services": {
-    "custom_service": {
+    "amanda_client":{
       ...
     },
     ...
   },
   "icmptypes": {
-    "custom": {
-      ...
-    },
+    ...
+  },
+  "helpers": {
     ...
   },
-  "helpers": {
+  "ipsets": {
     ...
   },
-  "ipsets": {
+  "policies": {
     ...
   },
-  "policies": {
-    ...
-  },
-}
+} +

custom

+

The custom subdictionary contains any differences from the default +firewalld configuration. This includes a repeat for a default element if +that element has been modified in any way, and any new elements +introduced in addition to the defaults.

+

This subdictionary will be modified by any changes to the firewalld +installation done locally or remotely via the firewall system role.

+

If the managed nodes firewalld settings are not different from the +defaults, the custom key and subdictionary will not be present in +firewall_config. Additionally, if any of firewalld's settings have not +changed from the default, there will not be a key-value pair for that +setting in custom.

+

Below is the state of the custom subdictionary where at least one +permanent change was made to each setting:

+
"custom": {
+  "zones": {
+    "custom_zone": {
+      ...
+    },
+    ...
+  },
+  "services": {
+    "custom_service": {
+      ...
+    },
+    ...
+  },
+  "icmptypes": {
+    "custom": {
+      ...
+    },
+    ...
+  },
+  "helpers": {
+    ...
+  },
+  "ipsets": {
+    ...
+  },
+  "policies": {
+    ...
+  },
+}

Variables

firewall_disable_conflicting_services

@@ -382,11 +396,11 @@

Variables

feature, set the variable firewall_disable_conflicting_services to true:

-
- name: Enable firewalld, disable conflicting services
-  include_role: linux-system-roles.firewall
-  vars:
-    firewall_disable_conflicting_services: true
+
- name: Enable firewalld, disable conflicting services
+  include_role: linux-system-roles.firewall
+  vars:
+    firewall_disable_conflicting_services: true

List of known conflicting services:

-
forward_port:
-  port: <port>
-  proto: <protocol>
-  [toport: <to-port>]
-  [toaddr: <to-addr>]
-

examples

forward_port: '447/tcp;;1.2.3.4'
-forward_port: ['447/tcp;;1.2.3.4','448/tcp;;1.2.3.5']
-forward_port:
-  - 447/tcp;;1.2.3.4
-  - 448/tcp;;1.2.3.5
-forward_port:
-  - port: 447
-    proto: tcp
-    toaddr: 1.2.3.4
-  - port: 448
-    proto: tcp
-    toaddr: 1.2.3.5
+class="sourceCode yaml">forward_port: + port: <port> + proto: <protocol> + [toport: <to-port>] + [toaddr: <to-addr>] +

examples

+
forward_port: '447/tcp;;1.2.3.4'
+forward_port: ['447/tcp;;1.2.3.4','448/tcp;;1.2.3.5']
+forward_port:
+  - 447/tcp;;1.2.3.4
+  - 448/tcp;;1.2.3.5
+forward_port:
+  - port: 447
+    proto: tcp
+    toaddr: 1.2.3.4
+  - port: 448
+    proto: tcp
+    toaddr: 1.2.3.5

port_forward is an alias for forward_port. Its use is deprecated and will be removed in an upcoming release.

masquerade

Enable or disable masquerade on the given zone.

-
masquerade: false
+
masquerade: false

rich_rule

String or list of rich rule strings. For the format see (Syntax for firewalld rich language rules)[https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html]

-
rich_rule: rule service name="ftp" audit limit value="1/m" accept
+
rich_rule: rule service name="ftp" audit limit value="1/m" accept

source

List of source address address range strings, or ipsets. A source address or address range is either an IP address or a network IP address with a mask for IPv4 or IPv6. For IPv4, the mask can be a network mask or a plain number. For IPv6 the mask is a plain number.

-
source: 192.0.2.0/24
+
source: 192.0.2.0/24

Ipsets are used with this option by prefixing "ipset:" to the name of the ipset

-
source: ipset:ipsetname
+
source: ipset:ipsetname

interface

String or list of interface name strings.

-
interface: eth2
+
interface: eth2

This role handles interface arguments similar to how firewalld's cli, firewall-cmd does, i.e. manages the interface through NetworkManager if possible, and handles the interface binding purely @@ -689,9 +703,9 @@

interface_pci_id

  • XXXX: Hexadecimal, corresponds to Vendor ID
  • YYYY: Hexadecimal, corresponds to Device ID
    • -
    # PCI id for Intel Corporation Ethernet Connection
-interface_pci_id: 8086:15d7
    +
    # PCI id for Intel Corporation Ethernet Connection
+interface_pci_id: 8086:15d7

    Only accepts PCI devices IDs that correspond to a named network interface, and converts all PCI device IDs to their respective logical interface names.

    @@ -704,31 +718,31 @@

    interface_pci_id

    icmp_block

    String or list of ICMP type strings to block. The ICMP type names needs to be defined in firewalld configuration.

    -
    icmp_block: echo-request
    +
    icmp_block: echo-request

    icmp_block_inversion

    ICMP block inversion bool setting. It enables or disables inversion of ICMP blocks for a zone in firewalld.

    -
    icmp_block_inversion: true
    +
    icmp_block_inversion: true

    target

    The firewalld zone target. If the state is set to absent,this will reset the target to default. Valid values are "default", "ACCEPT", "DROP", "%%REJECT%%".

    -
    target: ACCEPT
    +
    target: ACCEPT

    short

    Short description, only usable when defining or modifying a service or ipset. See service or ipset for more usage information.

    -
    short: Short Description
    +
    short: Short Description

    description

    Description for a service, only usable when adding a new service or modifying an existing service. See service or ipset for more information

    -
    description: Your description goes here
    +
    description: Your description goes here

    destination

    list of destination addresses, option only implemented for user-defined services. Takes 0-2 addresses, allowing for one IPv4 @@ -739,16 +753,16 @@

    destination

    works when abbreviating one or more subsequent IPv6 segments where x = 0) -
    destination:
-  - 1.1.1.0/24
-  - AAAA::AAAA:AAAA
    +
    destination:
+  - 1.1.1.0/24
+  - AAAA::AAAA:AAAA

    helper_module

    Name of a connection tracking helper supported by firewalld.

    -
    # Both properly specify nf_conntrack_ftp
-helper_module: ftp
-helper_module: nf_conntrack_ftp
    +
    # Both properly specify nf_conntrack_ftp
+helper_module: ftp
+helper_module: nf_conntrack_ftp

    timeout

    The amount of time in seconds a setting is in effect. The timeout is usable if

    @@ -758,24 +772,24 @@

    timeout

  • setting is used with services, ports, source ports, forward ports, masquerade, rich rules or icmp blocks
    • -
    timeout: 60
-state: enabled
-service: https
    +
    timeout: 60
+state: enabled
+service: https

    state

    Enable or disable the entry.

    -
    state: 'enabled' | 'disabled' | 'present' | 'absent'
    +
    state: 'enabled' | 'disabled' | 'present' | 'absent'

    NOTE: present and absent are only used for zone, target, and service operations, and cannot be used for any other operation.

    NOTE: zone - use state: present to add a zone, and state: absent to remove a zone, when zone is the only variable e.g.

    -
    firewall:
-  - zone: my-new-zone
-    state: present
    +
    firewall:
+  - zone: my-new-zone
+    state: present

    NOTE: target - you can also use state: present to add a target - state: absent will reset the target to the default.

    @@ -785,14 +799,14 @@

    runtime

    Enable changes in runtime configuration. If runtime parameter is not provided, the default will be set to True.

    -
    runtime: true
    +
    runtime: true

    permanent

    Enable changes in permanent configuration. If permanent parameter is not provided, the default will be set to True.

    -
    permanent: true
    +
    permanent: true

    The permanent and runtime settings are independent, so you can set only the runtime, or only the permanent. You cannot set both permanent and runtime to false.

    @@ -816,127 +830,129 @@

    Examples of Options

    runtime: false.

    Permit TCP traffic for port 80 in default zone, in addition to any existing configuration:

    -
    firewall:
-  - port: 80/tcp
-    state: enabled
    -

    Remove all existing firewall configuration, and permit TCP traffic -for port 80 in default zone:

    firewall:
-  - previous: replaced
-  - port: 80/tcp
-    state: enabled
    -

    Do not permit TCP traffic for port 80 in default zone:

    + - port: 80/tcp + state: enabled +

    Remove all existing firewall configuration, and permit TCP traffic +for port 80 in default zone:

    firewall:
-  - port: 80/tcp
-    state: disabled
    -

    Add masquerading to dmz zone:

    + - previous: replaced + - port: 80/tcp + state: enabled +

    Do not permit TCP traffic for port 80 in default zone:

    firewall:
-  - masquerade: true
-    zone: dmz
-    state: enabled
    -

    Remove masquerading to dmz zone:

    + - port: 80/tcp + state: disabled +

    Add masquerading to dmz zone:

    firewall:
-  - masquerade: false
+  - masquerade: true
     zone: dmz
     state: enabled
    -

    Allow interface eth2 in trusted zone:

    +

    Remove masquerading to dmz zone:

    firewall:
-  - interface: eth2
-    zone: trusted
+  - masquerade: false
+    zone: dmz
     state: enabled
    -

    Don't allow interface eth2 in trusted zone:

    +

    Allow interface eth2 in trusted zone:

    firewall:
   - interface: eth2
     zone: trusted
-    state: disabled
    -

    Permit traffic in default zone for https service:

    + state: enabled +

    Don't allow interface eth2 in trusted zone:

    firewall:
-  - service: https
-    state: enabled
    -

    Do not permit traffic in default zone for https service:

    + - interface: eth2 + zone: trusted + state: disabled +

    Permit traffic in default zone for https service:

    firewall:
   - service: https
-    state: disabled
    -

    Allow interface with PCI device ID '8086:15d7' in dmz zone

    + state: enabled +

    Do not permit traffic in default zone for https service:

    firewall:
-  - zone: dmz
-    interface_pci_id: 8086:15d7
-    state: enabled
    + - service: https + state: disabled +

    Allow interface with PCI device ID '8086:15d7' in dmz zone

    +
    firewall:
+  - zone: dmz
+    interface_pci_id: 8086:15d7
+    state: enabled

    Example Playbooks

    Erase all existing configuration, and enable ssh service:

    -
    ---
-- name: Erase existing config and enable ssh service
-  hosts: myhost
-
-  vars:
-    firewall:
-      - previous: replaced
-      - service: ssh
-        state: enabled
-  roles:
-    - linux-system-roles.firewall
    -

    With this playbook you can make sure that the tftp service is -disabled in the firewall:

    ---
-- name: Make sure tftp service is disabled
+- name: Erase existing config and enable ssh service
   hosts: myhost
 
   vars:
     firewall:
-      - service: tftp
-        state: disabled
-  roles:
-    - linux-system-roles.firewall
    -

    It is also possible to combine several settings into blocks:

    + - previous: replaced + - service: ssh + state: enabled + roles: + - linux-system-roles.firewall +

    With this playbook you can make sure that the tftp service is +disabled in the firewall:

    ---
-- name: Configure firewall
+- name: Make sure tftp service is disabled
   hosts: myhost
 
   vars:
     firewall:
-      - {service: [tftp,ftp],
-         port: ['443/tcp','443/udp'],
-         state: enabled}
-      - {forward_port: [eth2;447/tcp;;1.2.3.4,
-                        eth2;448/tcp;;1.2.3.5],
-          state: enabled}
-      - {zone: internal, service: tftp, state: enabled}
-      - {service: tftp, state: enabled}
-      - {port: '443/tcp', state: enabled}
-      - {forward_port: 'eth0;445/tcp;;1.2.3.4', state: enabled}
-         state: enabled}
-  roles:
-    - linux-system-roles.firewall
    -

    The block with several services, ports, etc. will be applied at once. -If there is something wrong in the block it will fail as a whole.

    + - service: tftp + state: disabled + roles: + - linux-system-roles.firewall +

    It is also possible to combine several settings into blocks:

    ---
-- name: Configure external zone in firewall
+- name: Configure firewall
   hosts: myhost
 
   vars:
     firewall:
-      - {zone: external,
-         service: [tftp,ftp],
-         port: ['443/tcp','443/udp'],
-         forward_port: ['447/tcp;;1.2.3.4',
-                        '448/tcp;;1.2.3.5'],
-         state: enabled}
-  roles:
-    - linux-system-roles.firewall
    + - {service: [tftp,ftp], + port: ['443/tcp','443/udp'], + state: enabled} + - {forward_port: [eth2;447/tcp;;1.2.3.4, + eth2;448/tcp;;1.2.3.5], + state: enabled} + - {zone: internal, service: tftp, state: enabled} + - {service: tftp, state: enabled} + - {port: '443/tcp', state: enabled} + - {forward_port: 'eth0;445/tcp;;1.2.3.4', state: enabled} + state: enabled} + roles: + - linux-system-roles.firewall +

    The block with several services, ports, etc. will be applied at once. +If there is something wrong in the block it will fail as a whole.

    +
    ---
+- name: Configure external zone in firewall
+  hosts: myhost
+
+  vars:
+    firewall:
+      - {zone: external,
+         service: [tftp,ftp],
+         port: ['443/tcp','443/udp'],
+         forward_port: ['447/tcp;;1.2.3.4',
+                        '448/tcp;;1.2.3.5'],
+         state: enabled}
+  roles:
+    - linux-system-roles.firewall
    +

    rpm-ostree

    +

    See README-ostree.md

    Authors

    Thomas Woerner

    License

    diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d4e87a..404aef2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,20 @@ Changelog ========= +[1.7.0] - 2023-10-26 +-------------------- + +### New Features + +- feat: support for ostree systems (#191) + +### Other Changes + +- build(deps): bump actions/checkout from 3 to 4 (#183) +- ci: ensure dependabot git commit message conforms to commitlint (#187) +- ci: use dump_packages.py callback to get packages used by role (#189) +- ci: tox-lsr version 3.1.1 (#192) + [1.6.4] - 2023-09-08 --------------------