feat: configurable volume mountpoints

- Read default additional directories from optional config file
  /etc/nethserver/volumes.conf

- Pass volumes configuration to cluster/add-module action and validate
  it.

- Pre-create additional directories for application volumes in node's
  add-module.

- Pre-create application volumes during create-module, with volume bind
  mount to additional directories.

- Implement node's list-mountpoints action.

Author: DavidePrincipi

core/imageroot/usr/local/agent/actions/create-module/05create_volumes

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+
+#
+# Copyright (C) 2025 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+import agent
+import agent.volumes
+import json
+import sys
+import os
+from pathlib import Path
+
+def main():
+    request = json.load(sys.stdin)
+    module_id = os.environ["MODULE_ID"]
+    # Init defaults from /etc/nethserver/volumes.conf
+    volpaths = agent.volumes.get_configuration(module_id)
+    # Set values from request:
+    volpaths.update(request.get('volumes', {}))
+    for volname, basepath in volpaths.items():
+        # volpath example: /srv/pool0/samba1/shares/_data
+        volpath = Path(basepath) / module_id / volname.strip("/") / "_data"
+        os.makedirs(volpath)
+        agent.run_helper("podman", "volume", "create", "--ignore", "--opt=device=" + str(volpath), "--opt=type=bind", volname)
+
+if __name__ == "__main__":
+    agent.set_weight('05pullimages', '5')
+    main()

core/imageroot/usr/local/agent/actions/create-module/05pullimages

@@ -30,8 +30,6 @@ request = json.load(sys.stdin)
 images = request['images']
 agent_id = os.environ['AGENT_ID']
 
-agent.set_weight('05pullimages', '5')
-
 for image_url in images:
     image_name = agent.get_image_name_from_url(image_url)
 

core/imageroot/usr/local/agent/actions/create-module/validate-input.json

@@ -12,6 +12,18 @@
     ],
     "type": "object",
     "properties": {
+        "volumes": {
+            "type": "object",
+            "description": "Optional mapping of application volume names to filesystem mount points.",
+            "patternProperties": {
+                "[^/]+": {
+                    "description": "Absolute filesystem directory path under /",
+                    "example": "/srv/pool0",
+                    "type": "string",
+                    "pattern": "^/.+$"
+                }
+            }
+        },
         "images": {
             "type": "array",
             "items": {

core/imageroot/usr/local/agent/pypkg/agent/volumes.py

@@ -0,0 +1,59 @@
+#
+# Copyright (C) 2025 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+import sys
+import subprocess
+import json
+from configparser import ConfigParser
+
+def _parse_config() -> ConfigParser:
+    config = ConfigParser(
+        delimiters=("="),
+        comment_prefixes=("#"),
+        inline_comment_prefixes=("#"),
+        empty_lines_in_values=False,
+    )
+    try:
+        config.read("/etc/nethserver/volumes.conf")
+    except FileNotFoundError:
+        pass
+    return config
+
+def get_configuration(module_id:str) -> dict:
+    """Return the volume configuration for the given module_id by reading
+    the config file /etc/nethserver/volumes.conf."""
+    app_type = module_id.rstrip('0123456789')
+    oconfig = _parse_config()
+    if module_id in oconfig:
+        section_key = module_id
+    elif app_type in oconfig:
+        section_key = app_type
+    else:
+        return {}
+    return dict(oconfig[section_key].items())
+
+def get_base_paths() -> list:
+    with subprocess.Popen(["findmnt", "--real", "--json", "--bytes", "--output", "SOURCE,TARGET,SIZE,USED,LABEL", "--nofsroot", "--type", "novfat"], stdout=subprocess.PIPE) as hproc:
+        ofindmnt = json.load(hproc.stdout)
+    orootfs = ofindmnt["filesystems"][0]
+    paths = []
+    for ofs in orootfs.get("children", []):
+        if ofs["source"] == orootfs["source"]:
+            continue # ignore bind mounts
+        elif ofs["target"].startswith("/boot"):
+            continue # ignore /boot* mountpoints
+        opath = {
+            "path": ofs["target"],
+            "label": ofs["label"] or "",
+        }
+        if "size" in ofs:
+            opath["size"] = ofs["size"]
+            opath["used"] = ofs["used"]
+        paths.append(opath)
+    return paths
+
+if __name__ == "__main__":
+    json.dump(get_base_paths(), fp=sys.stdout)
+

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

@@ -35,6 +35,22 @@ request = json.load(sys.stdin)
 node_id = int(request['node'])
 agent.assert_exp(node_id > 0)
 check_idle_time = request.get('check_idle_time')
+volumes = request.get('volumes', {})
+
+if volumes:
+    # Retrieve the list of valid mountpoint paths from the node:
+    list_mountpoints_result = agent.tasks.run(
+        agent_id=f'node/{node_id}',
+        action='list-mountpoints',
+        endpoint="redis://cluster-leader",
+    )
+    valid_paths = [x["path"] for x in list_mountpoints_result['output'] or []]
+    for qpath in volumes.values():
+        if qpath not in valid_paths:
+            print(agent.SD_ERR + f'Unknown mountpoint path "{qpath}" in node {node_id}.', file=sys.stderr)
+            agent.set_status('validation-failed')
+            json.dump([{'field':'volumes', 'parameter':'volumes','value': qpath, 'error':'unknown_mountpoint_path'}], fp=sys.stdout)
+            sys.exit(3)
 
 rdb = agent.redis_connect(privileged=True)
 
@@ -147,6 +163,7 @@ add_module_result = agent.tasks.run(
         "environment": module_environment,
         "tcp_ports_demand": tcp_ports_demand,
         "udp_ports_demand": udp_ports_demand,
+        'volumes': volumes,
     },
     endpoint="redis://cluster-leader",
     progress_callback=agent.get_progress_callback(34,66),
@@ -188,6 +205,7 @@ create_module_result = agent.tasks.run(
     action="create-module",
     data={
         'images': extra_images,
+        'volumes': volumes,
     },
     endpoint="redis://cluster-leader",
     check_idle_time=0, # disable idle check and wait until the agent is up

core/imageroot/var/lib/nethserver/cluster/actions/add-module/validate-input.json

@@ -4,6 +4,13 @@
     "$id": "http://schema.nethserver.org/cluster/add-module-input.json",
     "description": "Input schema of the add-module action",
     "examples": [
+        {
+            "image": "samba",
+            "node": 2,
+            "volumes": {
+                "shares": "/srv/pool0"
+            }
+        },
         {
             "image": "traefik",
             "node": 1
@@ -19,6 +26,18 @@
         "node"
     ],
     "properties": {
+        "volumes": {
+            "type": "object",
+            "description": "Optional mapping of application volume names to filesystem mount points.",
+            "patternProperties": {
+                "[^/]+": {
+                    "description": "Absolute filesystem directory path under /",
+                    "example": "/srv/pool0",
+                    "type": "string",
+                    "pattern": "^/.+$"
+                }
+            }
+        },
         "check_idle_time": {
             "title": "Agent liveness check limit",
             "description": "Change the default check limit value (default 8 seconds)",

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

@@ -24,9 +24,11 @@ import os
 import sys
 import json
 import agent
+import agent.volumes
 import uuid
 import hashlib
 import node.ports_manager
+import pwd
 
 def save_environment(env):
     with open('state/environment', 'w') as envf:
@@ -113,6 +115,22 @@ else: # rootless
     # Start the module agent
     agent.run_helper('loginctl', 'enable-linger', module_id).check_returncode()
 
+# Create base paths for the module volumes
+volumes = agent.volumes.get_configuration(module_id)
+volumes.update(request.get('volumes', {}))
+if volumes:
+    pwent = pwd.getpwnam(module_id)
+    valid_mountpoint_paths = [x["path"] for x in agent.volumes.get_base_paths()]
+    for volbase in set(volumes.values()):
+        if volbase not in valid_mountpoint_paths:
+            print(agent.SD_WARNING + 'Skip creation of unknown mountpoint path:', volbase, file=sys.stderr)
+            continue
+        try:
+            os.mkdir(f"{volbase}/{module_id}", mode=0o700)
+            os.chown(f"{volbase}/{module_id}", pwent[2], pwent[3]) # chown uid:gid
+        except FileExistsError:
+            pass
+
 json.dump({
     "redis_sha256":redis_sha256,
 }, sys.stdout)

core/imageroot/var/lib/nethserver/node/actions/add-module/validate-input.json

@@ -4,6 +4,16 @@
     "$id": "http://schema.nethserver.org/node/add-module-input.json",
     "description": "Install a module on the worker node",
     "examples": [
+        {
+            "volumes": {
+                "shares": "/srv/pool0"
+            },
+            "module_id": "samba1",
+            "is_rootfull": false,
+            "environment": {
+                "IMAGE_URL": "ghcr.io/nethserver/samba:3.2.0"
+            }
+        },
         {
             "module_id": "mymodule2",
             "is_rootfull": false,
@@ -21,6 +31,18 @@
         "udp_ports_demand"
     ],
     "properties": {
+        "volumes": {
+            "type": "object",
+            "description": "Optional mapping of application volume names to filesystem mount points.",
+            "patternProperties": {
+                "[^/]+": {
+                    "description": "Absolute filesystem directory path under /",
+                    "example": "/srv/pool0",
+                    "type": "string",
+                    "pattern": "^/.+$"
+                }
+            }
+        },
         "environment": {
             "type": "object",
             "title": "Initial module environment",

core/imageroot/var/lib/nethserver/node/actions/list-mountpoints/50list_mountpoints

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+
+#
+# Copyright (C) 2025 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+import agent
+import agent.volumes
+import json
+import sys
+import os
+
+def main():
+    json.dump({"mountpoints":agent.volumes.get_base_paths()}, fp=sys.stdout)
+
+if __name__ == "__main__":
+    main()

core/imageroot/var/lib/nethserver/node/actions/list-mountpoints/validate-output.json

@@ -0,0 +1,48 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "list-mountpoints output",
+    "$id": "http://schema.nethserver.org/node/list-mountpoints.json",
+    "description": "Output schema of the list-mountpoints action",
+    "examples": [
+        {
+            "mountpoints": [
+                {
+                    "path": "/mnt/xvolume_davidep_cluster0_rl1",
+                    "label": "VOL01",
+                    "size": 2136997888,
+                    "used": 49049600
+                }
+            ]
+        }
+    ],
+    "type": "object",
+    "properties": {
+        "mountpoints": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/mountpoint"
+            }
+        }
+    },
+    "$defs": {
+        "mountpoint": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string"
+                },
+                "label": {
+                    "type": "string"
+                },
+                "size": {
+                    "type": "number",
+                    "description": "bytes"
+                },
+                "used": {
+                    "type": "number",
+                    "description": "bytes"
+                }
+            }
+        }
+    }
+}