deploy: provision merkle log at UCLA

Author: tianyuan129

README.md

@@ -69,6 +69,10 @@ docker compose exec -e HOME=/testbed/root-ca-home master ndnsec list -c
 
 Each node runs the pinned `ndnd-repo` container with identity `<default_prefix>/ndnd/repo` (e.g. `/ndn/edu/ucla/ndnd/repo`). Master generates a dedicated key, obtains a certificate from the local site CA, and installs the public chain selected by `globals.ndnd_repo_anchors`. The repo can write only its keychain and storage; it has no access to CA private keys or master renewal scripts.
 
+## NDNd Merkle
+
+Only UCLA runs the `ndnd-merkle` container, selected by `services.ndnd-merkle.hosts: [UCLA]` in `config.yml`, with identity `/ndn/edu/ucla/ndnd/merkle`. Master automatically provisions and renews its dedicated site-issued certificate using the same testbed anchors as the repo. Its trust schema permits testbed-certified users to append under their own identities and only the log key to sign responses. History persists in `dist/ndnd-merkle/storage`.
+
 ## Development
 
 For debugging and development, you can define `DEBUG=1` in your `.env` file. This will prevent the `dist` folder from auto-rendering and disable git polling. You can then use docker compose as usual to manage the containers.

config.yml

@@ -39,6 +39,12 @@ services:
     template_path: templates/ndnd-repo
     render_path: dist/ndnd-repo
 
+  ndnd-merkle:
+    hosts: [UCLA]
+    profile: merkle-log
+    template_path: templates/ndnd-merkle
+    render_path: dist/ndnd-merkle
+
   ndncert:
     template_path: templates/ndncert
     render_path: dist/ndncert

docker-compose.yml

@@ -175,6 +175,34 @@ services:
     logging:
       driver: local
 
+  ndnd-merkle:
+    image: ghcr.io/named-data/ndnd:20261012
+    pull_policy: always
+    profiles: [merkle-log] # selected by config.yml through maintenance
+    init: true
+    volumes:
+      - /run/nfd:/run/nfd:ro
+      - ${PWD}/dist/ndnd-merkle/keys:/config/keys
+      - ${PWD}/dist/ndnd-merkle/storage:/config/storage
+      - ${PWD}/dist/ndnd-merkle/merkle.yml:/config/merkle.yml:ro
+      - ${PWD}/dist/ndnd-merkle/management-schema.tlv:/config/management-schema.tlv:ro
+    environment:
+      NDN_CLIENT_TRANSPORT: unix:///run/nfd/nfd.sock
+    command: [merkle, run, /config/merkle.yml]
+    network_mode: none
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    mem_limit: 2g
+    cpus: 1
+    pids_limit: 128
+    restart: unless-stopped
+    depends_on:
+      nfd: { condition: service_healthy }
+      serve-certs: { condition: service_started }
+    logging:
+      driver: local
+
   ndncert:
     image: ghcr.io/ucla-irl/ndncert-ca:20250923
     init: true

framework/internal/compose.py

@@ -1,14 +1,17 @@
 import json
+import os
 import subprocess
 import sys
+from . import conf
 
 STATUS_CACHE = {}
 
-def config() -> dict:
+def config(node: str = None) -> dict:
     """
     Get the global configuration for the docker compose
     """
     try:
+        os.environ['COMPOSE_PROFILES'] = conf.compose_profiles(node)
         cmd = ['docker', 'compose', 'config', '--format', 'json']
         result = subprocess.run(cmd, stdout=subprocess.PIPE)
         return json.loads(result.stdout)

framework/internal/conf.py

@@ -1,6 +1,8 @@
 import yaml
+import shlex
 
 from dataclasses import dataclass
+from os import getenv
 from typing import Any
 
 from .utils import read_dotenv
@@ -29,3 +31,26 @@ def get() -> Config:
             config.globals[rkey] = value
 
     return config
+
+
+def service_enabled(service: dict, node: str) -> bool:
+    return 'hosts' not in service or node in service['hosts']
+
+
+def compose_profiles(node: str = None) -> str:
+    """Apply tracked host profiles without replacing operator-managed profiles."""
+    env = read_dotenv()
+    node = node or getenv('MANAGED_HOST', env.get('MANAGED_HOST'))
+    services = get().services.values()
+    managed = {service['profile'] for service in services if 'profile' in service}
+    default_profiles = ''.join(shlex.split(env.get('COMPOSE_PROFILES', ''), comments=True))
+    requested = [p.strip() for p in getenv('COMPOSE_PROFILES', default_profiles).split(',')]
+    if '*' in requested:
+        with open('docker-compose.yml') as stream:
+            compose = yaml.safe_load(stream)
+        requested = [p for service in compose['services'].values() for p in service.get('profiles', [])]
+    profiles = [p for p in requested
+                if p and p not in managed]
+    profiles.extend(service['profile'] for service in services
+                    if 'profile' in service and service_enabled(service, node))
+    return ','.join(dict.fromkeys(profiles))

framework/internal/render.py

@@ -35,7 +35,7 @@ def render(node_name: str, dry: bool = False) -> None:
     config = conf.get()
 
     # Get the docker compose config
-    compose_config = compose.config()
+    compose_config = compose.config(node_name)
 
     # Load environment and templates for each service. Set undefined to StrictUndefined to throw
     # a noisy error if a value that is present in the template is not passed in as a value.
@@ -66,7 +66,7 @@ def render(node_name: str, dry: bool = False) -> None:
     # For each service, render templates with the corresponding values
     for service, values in config.services.items():
         # Check if the service is enabled
-        if service not in compose_config['services']:
+        if not conf.service_enabled(values, node_name) or service not in compose_config['services']:
             continue
 
         # Check if any file did change

framework/service-profiles.py

@@ -0,0 +1,15 @@
+"""Resolve tracked host selection for shell maintenance jobs."""
+import argparse
+from os import getenv
+
+from internal import conf
+from internal.utils import read_dotenv
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument('--service', choices=list(conf.get().services))
+args = parser.parse_args()
+if args.service:
+    node = getenv('MANAGED_HOST', read_dotenv().get('MANAGED_HOST'))
+    print(int(conf.service_enabled(conf.get().services[args.service], node)))
+else:
+    print(conf.compose_profiles())

scripts/cert-renew.sh

@@ -35,3 +35,28 @@ if [[ -f dist/ndnd-repo/.security-changed ]]; then
     fi
     rm -f dist/ndnd-repo/.security-changed
 fi
+
+# Optional services run after the core renewals and retain their own retry state.
+MERKLE_ENABLED=$(python3 framework/service-profiles.py --service ndnd-merkle) || exit $?
+if [[ "${MERKLE_ENABLED}" == 1 ]]; then
+    MERKLE_DIR=dist/ndnd-merkle
+    if [[ -n "${FORCE}" ]]; then
+        touch "${MERKLE_DIR}/.renew-pending"
+    fi
+    MERKLE_FORCE=""
+    if [[ -f "${MERKLE_DIR}/.renew-pending" ]]; then
+        MERKLE_FORCE="--force"
+    fi
+    if bash "${MERKLE_DIR}/renew.sh" ${MERKLE_FORCE:+"${MERKLE_FORCE}"}; then
+        rm -f "${MERKLE_DIR}/.renew-pending"
+        if [[ -f "${MERKLE_DIR}/.security-changed" ]]; then
+            RUNNING_LOG=$(PWD="${ROOT_DIR:-$PWD}" docker compose ps --status running -q ndnd-merkle) || exit $?
+            if [[ -n "${RUNNING_LOG}" ]]; then
+                PWD="${ROOT_DIR:-$PWD}" docker compose restart ndnd-merkle || exit $?
+            fi
+            rm -f "${MERKLE_DIR}/.security-changed"
+        fi
+    else
+        echo "NDNd Merkle credential renewal failed; core services renewed, log will retry next poll" >&2
+    fi
+fi

scripts/cron-host.sh

@@ -24,7 +24,11 @@ fi
 # to recreate everything when master is updated
 docker compose up -d master --no-deps
 
+# Resolve service profiles from Git configuration inside the existing master image.
+COMPOSE_PROFILES=$(docker compose exec -T master python3 framework/service-profiles.py) || exit $?
+export COMPOSE_PROFILES
+
 # Ensure services are running
 docker compose up -d --remove-orphans
 
-echo -e "Finished cron-host at $(date)" >&2
+echo -e "Finished cron-host at $(date)" >&2

scripts/ndnd-repo-security.py scripts/ndnd-infra-security.pyscripts/ndnd-repo-security.py renamed to scripts/ndnd-infra-security.py

@@ -89,17 +89,17 @@ def get_key(directory, identity):
     keys = list(directory.glob('*.key'))
     if keys:
         if len(keys) != 1:
-            raise ValueError('Expected exactly one private repo key')
+            raise ValueError('Expected exactly one private service key')
         wire = decode_pem(keys[0].read_text(), 'KEY')
         name, meta, content, pointers = parse_data(wire)
         if (meta.content_type != 9 or len(name) != len(identity) + 2
                 or Name.to_bytes(name[:-2]) != Name.to_bytes(identity)
                 or bytes(name[-2]) != Component.from_str('KEY')):
-            raise ValueError('Existing repo key has the wrong identity or format')
+            raise ValueError('Existing service key has the wrong identity or format')
         key = ECC.import_key(bytes(content))
         keys[0].chmod(0o600)
         if not key.has_private() or not verify_ecdsa(key.public_key(), pointers):
-            raise ValueError('Invalid private repo key')
+            raise ValueError('Invalid private service key')
         return name, key, wire
 
     key = ECC.generate(curve='P-256')
@@ -112,19 +112,23 @@ def get_key(directory, identity):
     return name, key, wire
 
 
-def provision(directory, site_home, site_prefix, anchors_path, force=False, renew_before_days=30):
+def provision(directory, site_home, site_prefix, anchors_path, force=False, renew_before_days=30, service='repo'):
     # Serialize overlapping cron/manual renewal runs without rotating the key.
     with (directory / '.security.lock').open('a') as lock:
         fcntl.flock(lock, fcntl.LOCK_EX)
-        return provision_locked(directory, site_home, site_prefix, anchors_path, force, renew_before_days)
+        return provision_locked(directory, site_home, site_prefix, anchors_path, force, renew_before_days, service)
 
 
-def provision_locked(directory, site_home, site_prefix, anchors_path, force, renew_before_days):
-    with (directory / 'repo.yml').open() as stream:
-        config = yaml.safe_load(stream)['repo']
+def provision_locked(directory, site_home, site_prefix, anchors_path, force, renew_before_days, service):
+    if service not in ('repo', 'merkle'):
+        raise ValueError('Unsupported NDNd service')
+    if service == 'merkle' and site_prefix != '/ndn/edu/ucla':
+        raise ValueError('Merkle log provisioning is restricted to UCLA')
+    with (directory / f'{service}.yml').open() as stream:
+        config = yaml.safe_load(stream)[service]
     identity = Name.normalize(config['name'])
-    if Name.to_bytes(identity) != Name.to_bytes(Name.normalize(site_prefix + '/ndnd/repo')):
-        raise ValueError('Repo identity must be <site-prefix>/ndnd/repo')
+    if Name.to_bytes(identity) != Name.to_bytes(Name.normalize(site_prefix + '/ndnd/' + service)):
+        raise ValueError(f'Identity must be <site-prefix>/ndnd/{service}')
 
     now = datetime.now(timezone.utc)
     site_wire = decode_certificate(site_home / 'site.ndncert')
@@ -156,7 +160,7 @@ def provision_locked(directory, site_home, site_prefix, anchors_path, force, ren
     keys.mkdir(mode=0o700, exist_ok=True)
     keys.chmod(0o700)
     key_name, key, key_wire = get_key(keys, identity)
-    cert_path = directory / 'repo.ndncert'
+    cert_path = directory / f'{service}.ndncert'
     cert_wire = decode_certificate(cert_path) if cert_path.exists() else None
     margin = timedelta(days=renew_before_days)
     renew = force or cert_wire is None
@@ -174,7 +178,7 @@ def provision_locked(directory, site_home, site_prefix, anchors_path, force, ren
         before = max(now - timedelta(minutes=5), site_before, root_before).replace(microsecond=0)
         after = min(now + timedelta(days=90), site_after, root_after).replace(microsecond=0)
         if after <= now + margin:
-            raise ValueError('Renew the site/root certificate before issuing a repo certificate')
+            raise ValueError('Renew the site/root certificate before issuing a service certificate')
         signer = Sha256WithEcdsaSigner(key_name, key.export_key(format='DER', use_pkcs8=False))
         _, csr = new_cert(key_name, Component.from_str('self'),
                           key.public_key().export_key(format='DER'), signer, before, after)
@@ -189,7 +193,7 @@ def provision_locked(directory, site_home, site_prefix, anchors_path, force, ren
                 or bytes(cert.content) != key.public_key().export_key(format='DER')
                 or not verify_certificate(cert_wire, site_wire)
                 or not before <= actual_before <= now < actual_after <= after):
-            raise ValueError('Site CA returned an invalid repo certificate')
+            raise ValueError('Site CA returned an invalid service certificate')
 
     # Prepare every credential before marking it for a service reload.
     changed = import_packet(keys, key_wire, 'KEY')
@@ -198,7 +202,7 @@ def provision_locked(directory, site_home, site_prefix, anchors_path, force, ren
     changed |= write_atomic(cert_path, base64.encodebytes(cert_wire))
     if changed:
         write_atomic(directory / '.security-changed', b'\n')
-    print(f"NDNd repo {config['name']}: {'credentials updated' if changed else 'credentials current'}")
+    print(f"NDNd {service} {config['name']}: {'credentials updated' if changed else 'credentials current'}")
     return changed
 
 
@@ -208,6 +212,7 @@ def provision_locked(directory, site_home, site_prefix, anchors_path, force, ren
     parser.add_argument('--site-home', type=Path, required=True)
     parser.add_argument('--site-prefix', required=True)
     parser.add_argument('--anchors', type=Path, required=True)
+    parser.add_argument('--service', choices=('repo', 'merkle'), default='repo')
     parser.add_argument('--force', action='store_true')
     args = parser.parse_args()
-    provision(args.directory, args.site_home, args.site_prefix, args.anchors, args.force)
+    provision(args.directory, args.site_home, args.site_prefix, args.anchors, args.force, service=args.service)