Lifecycle Hooks

Overview

Lifecycle hooks let you run shell commands before or after a container is updated. Common use cases:

• Stop dependent services before updating
• Run database migrations after updating
• Send custom notifications
• Create network resources or volumes

Container labels

Hook enablement and allowlist

Allowlist matching rules

• No slash in entry (curl, sh): the basename of the hook command's first token is compared. curl matches both curl and /usr/bin/curl.
• Slash in entry (/usr/local/bin/notify.sh): an exact full-path match is required. The basename alone is not sufficient.

Example:

DD_HOOKS_ALLOWED_COMMANDS=curl,/usr/local/bin/notify.sh

This permits curl https://… and /usr/local/bin/notify.sh, but not notify.sh or /other/path/curl.

Hook environment variables

When a hook runs, drydock injects environment variables describing the update:

Injected hook environment values are sanitized before execution. Control characters and shell metacharacters `, $, ;, &, |, <, >, (, and ) are replaced with _, matching the command trigger's environment hardening. This protects hook scripts that expand Drydock-provided values but does not make arbitrary hook commands safe; keep hook commands trusted and quote variables in your scripts.

Command validation

Hook commands are validated against a restricted shell-safe grammar. Commands containing any of the following are rejected when the hook runs, with a clear error:

• Command substitution: $(...) or backticks (`)
• Output or input redirections: >, >>, <
• Command chaining metacharacters: ;, &&, ||, |

Simple positional arguments and environment variable references that do not use substitution are allowed. Use a wrapper script (mounted into the container) for complex logic.

Execution details

• Hooks run inside the drydock container using /bin/sh -c only when DD_HOOKS_ENABLED=true
• Combined stdout and stderr output is capped at 10 KB
• An exit code of 0 is treated as success; any non-zero code is a failure
• If a hook exceeds its timeout, it is killed and treated as a failure (exit code 1)
• Hooks are NOT executed during self-update

Threat model (label-sourced commands)

Hooks are sourced from container labels and then executed by drydock. Treat hook labels as a code-execution boundary.

• Trust boundary: Container labels (dd.hook.*) cross into the drydock runtime command executor.
• Trust boundary: Hook execution can cross from drydock into Docker host control when the socket is mounted.
• High-value assets: Docker socket access, mounted credentials/secrets, and network-reachable internal services.
• Attacker capability: Anyone who can modify deployed container labels (Compose manifests, swarm specs, API-driven container creation) can inject hook commands.
• Abuse path: A malicious label can execute arbitrary shell via /bin/sh -c, including secret exfiltration or unauthorized Docker API actions.
• Abuse path: Expensive hooks can degrade availability (for example long-running or fork-heavy commands), bounded by dd.hook.timeout.
• Mitigation: Restrict who can modify container specs/labels and protect deployment pipelines.
• Mitigation: Run drydock with least privilege; mount /var/run/docker.sock only when required.
• Mitigation: Keep dd.hook.pre.abort=true when you want fail-closed behavior on pre-hook errors.
• Mitigation: Monitor audit events (hook-configured, hook-pre-*, hook-post-*) for unauthorized hook changes and executions.

Pre-hook abort behavior

When dd.hook.pre.abort is true (the default), a failed pre-hook cancels the update entirely. Set it to false if you want the update to proceed regardless of hook outcome.

Audit events

Example

services:
  myapp:
    image: myapp:latest
    labels:
      - dd.watch=true
      - dd.hook.pre=docker exec mydb pg_dump -U postgres -F c -f /backup/pre-update.dump mydb
      - dd.hook.post=/usr/local/bin/notify-update.sh
      - dd.hook.pre.abort=true
      - dd.hook.timeout=120000

Commands that require shell redirects (>, |, etc.) must be wrapped in a script file and invoked via the hook (e.g. dd.hook.pre=/usr/local/bin/backup.sh).

Keep credentials out of hook labels. Put notification tokens and signed URLs in a mounted secret or environment variable read by the script instead.