Mix portsadm node role with existing roles (#726)

- As only one role can be granted to a module on the local node, define
additional roles, given by the union of existing roles fwadm and tunadm.

- The deallocate-ports action step is unnecessary since the
allocate-ports/deallocate-ports node actions do not manage "_rsync"
allocations. These can only be handled by the cluster agent.

Refs NethServer/dev#6974

core/imageroot/var/lib/nethserver/cluster/actions/add-node/50update

@@ -166,6 +166,20 @@ cluster.grants.grant(rdb, "remove-tun", f'node/{node_id}', "tunadm")
 
 cluster.grants.grant(rdb, "allocate-ports", f'node/{node_id}', "portsadm")
 cluster.grants.grant(rdb, "deallocate-ports", f'node/{node_id}', "portsadm")
+cluster.grants.grant(rdb, "allocate-ports", f'node/{node_id}', "fwadm,portsadm")
+cluster.grants.grant(rdb, "deallocate-ports", f'node/{node_id}', "fwadm,portsadm")
+cluster.grants.grant(rdb, "add-public-service", f'node/{node_id}', "fwadm,portsadm")
+cluster.grants.grant(rdb, "remove-public-service", f'node/{node_id}', "fwadm,portsadm")
+cluster.grants.grant(rdb, "add-custom-zone", f'node/{node_id}', "fwadm,portsadm")
+cluster.grants.grant(rdb, "remove-custom-zone", f'node/{node_id}', "fwadm,portsadm")
+cluster.grants.grant(rdb, "allocate-ports", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "deallocate-ports", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "add-tun", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "remove-tun", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "add-public-service", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "remove-public-service", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "add-custom-zone", f'node/{node_id}', "tunadm,portsadm")
+cluster.grants.grant(rdb, "remove-custom-zone", f'node/{node_id}', "tunadm,portsadm")
 
 # Grant on cascade the owner role on the new node, to users with the owner
 # role on cluster

core/imageroot/var/lib/nethserver/cluster/update-core-pre-modules.d/50update_grants

@@ -25,7 +25,20 @@ cluster.grants.grant(rdb, action_clause="list-modules",  to_clause="accountprovi
 for node_id in set(rdb.hvals('cluster/module_node')):
     cluster.grants.grant(rdb, "allocate-ports", f'node/{node_id}', "portsadm")
     cluster.grants.grant(rdb, "deallocate-ports", f'node/{node_id}', "portsadm")
-
+    cluster.grants.grant(rdb, "allocate-ports", f'node/{node_id}', "fwadm,portsadm")
+    cluster.grants.grant(rdb, "deallocate-ports", f'node/{node_id}', "fwadm,portsadm")
+    cluster.grants.grant(rdb, "add-public-service", f'node/{node_id}', "fwadm,portsadm")
+    cluster.grants.grant(rdb, "remove-public-service", f'node/{node_id}', "fwadm,portsadm")
+    cluster.grants.grant(rdb, "add-custom-zone", f'node/{node_id}', "fwadm,portsadm")
+    cluster.grants.grant(rdb, "remove-custom-zone", f'node/{node_id}', "fwadm,portsadm")
+    cluster.grants.grant(rdb, "allocate-ports", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "deallocate-ports", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "add-tun", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "remove-tun", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "add-public-service", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "remove-public-service", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "add-custom-zone", f'node/{node_id}', "tunadm,portsadm")
+    cluster.grants.grant(rdb, "remove-custom-zone", f'node/{node_id}', "tunadm,portsadm")
 #
 # END of grant updates
 #

core/imageroot/var/lib/nethserver/node/install-finalize.sh

@@ -128,6 +128,20 @@ cluster.grants.grant(rdb, action_clause="remove-custom-zone",  to_clause="tunadm
 
 cluster.grants.grant(rdb, action_clause="allocate-ports",  to_clause="portsadm", on_clause='node/1')
 cluster.grants.grant(rdb, action_clause="deallocate-ports",  to_clause="portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="allocate-ports",  to_clause="fwadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="deallocate-ports",  to_clause="fwadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="add-public-service",  to_clause="fwadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="remove-public-service",  to_clause="fwadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="add-custom-zone",  to_clause="fwadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="remove-custom-zone",  to_clause="fwadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="allocate-ports",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="deallocate-ports",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="add-tun",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="remove-tun",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="add-public-service",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="remove-public-service",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="add-custom-zone",  to_clause="tunadm,portsadm", on_clause='node/1')
+cluster.grants.grant(rdb, action_clause="remove-custom-zone",  to_clause="tunadm,portsadm", on_clause='node/1')
 
 cluster.grants.grant(rdb, action_clause="update-routes", to_clause="accountprovider", on_clause='cluster')
 cluster.grants.grant(rdb, action_clause="bind-user-domains",  to_clause="accountconsumer", on_clause='cluster')

docs/core/port_allocation.md

@@ -5,6 +5,21 @@ nav_order: 17
 parent: Core
 ---
 
+# Port allocation
+
+The `ports_manager` library handles the low-level port allocation storage.
+It registers and stores UDP and TCP port information in a SQLite database
+for the local node within the cluster.
+
+The SQLite database file, `ports.sqlite`, is stored in the node's `state/`
+directory. To inspect its contents, use the following command:
+
+    podman run -i --rm --volume /var/lib/nethserver/node/state/ports.sqlite:/srv/ports.sqlite:z alpine ash -c 'apk add sqlite ; sqlite3 /srv/ports.sqlite' <<<"SELECT *, 'tcp' FROM TCP_PORTS UNION SELECT *, 'udp' FROM UDP_PORTS;"
+
+For more information, refer to [Port
+allocation](../../modules/port_allocation) under the Modules section.
+
+
 ## Importing the Library
 
 To use the `ports_manager` library, you need to import it into your Python script as follows:

docs/modules/port_allocation.md

@@ -8,7 +8,7 @@ parent: Modules
 # Port allocation
 
 Many web application modules need a TCP or UDP port to run a backend exposed by Traefik.
-Such modules can set the `org.nethserver.tcp-ports-demand` and `org.nethserver.tcp-ports-demand` which takes an integer number as value.
+Such modules can set the `org.nethserver.tcp-ports-demand` and `org.nethserver.udp-ports-demand` which takes an integer number as value.
 Example:
 ```
 org.nethserver.tcp-ports-demand=1
@@ -26,11 +26,37 @@ The available environment variables will be:
 
 Currently, allocated ports are saved in an SQLite database file managed by the local node agent.
 
+## Authorizations
+
+The module requires an additional role to manage port allocation, which is
+assigned by setting the `org.nethserver.authorizations` label on the
+module image, as shown in the following example:
+
+    org.nethserver.authorizations = node:portsadm
+
+The following additional label values can be used to mix port allocations
+with other existing node-related roles:
+
+- `org.nethserver.authorizations = node:fwadm,portsadm`
+- `org.nethserver.authorizations = node:tunadm,portsadm`
+
+Note that the value must be exactly one of the above. Other combinations
+like `node:portsadm,fwadm` are not valid.
+
+The module will be granted execution permissions for the following actions
+on the local node:
+- `allocate-ports`
+- `deallocate-ports`
+
+These actions can be carried out using the agent library without making
+direct node API calls, as explained in the next section.
+
 ## Agent library
 
 The Python `agent` library provides a convenient interface for managing port allocation and deallocation, based on the node actions `allocate_ports` and `deallocate_ports`.
 
 It is optional to specify the `module_id` when calling the port allocation or deallocation functions. By default, if the `module_id` is not provided, the function will automatically use the value of the `MODULE_ID` environment variable. This simplifies the function calls in common scenarios, ensuring the correct module name is used without manual input. However, if needed, you can still explicitly pass the `module_id`.
+Note that only the cluster agent can modify the port allocations of other modules.
 
 ### Allocate ports
 
@@ -67,15 +93,3 @@ For more information about functions, see [Port allocation](../../core/port_allo
 
 These functions dynamically allocate and deallocate ports based on the module's needs without requiring direct interaction with the node's APIs.
 
-## Authorizations
-
-The module requires an additional role to manage port allocation, which is assigned by setting the `org.nethserver.authorizations` label on the module image, as shown in the following example:
-
-```
-org.nethserver.authorizations = node:portsadm
-```
-The module will be granted execution permissions for the following actions on the local node:
-- `allocate-ports`
-- `deallocate-ports`
-
-However, as mentioned above, these actions can be carried out using the agent library without making direct node API calls.