Skip to content

hook_install

hook_install

OCI hook file generation and installation.

Writes the hook entrypoint script and JSON descriptors that tell podman to invoke terok-shield at createRuntime and poststop. Two entry points: :func:install_hooks for per-container setup during pre_start, and :func:setup_global_hooks for one-time system-wide installation.

Pure file I/O — no runtime container interaction.

install_hooks(*, hook_entrypoint, hooks_dir)

Write OCI hook entrypoint and JSON descriptors to a given directory.

WORKAROUND(hooks-dir-persist): currently only used for global hooks (user or root) because podman does not persist per-container --hooks-dir across stop/start. The per-container code path is kept for near-future use.

Parameters:

Name Type Description Default
hook_entrypoint Path

Where to write the entrypoint script.

 required
hooks_dir Path

Directory for hook JSON descriptors.

 required
Source code in src/terok_shield/core/hook_install.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def install_hooks(*, hook_entrypoint: Path, hooks_dir: Path) -> None:
    """Write OCI hook entrypoint and JSON descriptors to a given directory.

    WORKAROUND(hooks-dir-persist): currently only used for global hooks
    (user or root) because podman does not persist per-container
    ``--hooks-dir`` across stop/start.  The per-container code path is
    kept for near-future use.

    Args:
        hook_entrypoint: Where to write the entrypoint script.
        hooks_dir: Directory for hook JSON descriptors.
    """
    hook_entrypoint.parent.mkdir(parents=True, exist_ok=True)
    hooks_dir.mkdir(parents=True, exist_ok=True)
    _write_hook_files(hook_entrypoint, hooks_dir)

setup_global_hooks(target_dir, *, use_sudo=False)

Install OCI hooks system-wide for restart persistence.

Called by the setup CLI command. When use_sudo is True, writes to a temp directory first and copies via sudo cp — avoids needing the Python process itself to run as root.

Parameters:

Name Type Description Default
target_dir Path

Global hooks directory to install into.

 required
use_sudo bool

Copy files via sudo instead of writing directly.

 False
Source code in src/terok_shield/core/hook_install.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def setup_global_hooks(target_dir: Path, *, use_sudo: bool = False) -> None:
    """Install OCI hooks system-wide for restart persistence.

    Called by the ``setup`` CLI command.  When *use_sudo* is True, writes
    to a temp directory first and copies via ``sudo cp`` — avoids needing
    the Python process itself to run as root.

    Args:
        target_dir: Global hooks directory to install into.
        use_sudo: Copy files via ``sudo`` instead of writing directly.
    """
    if use_sudo:
        _install_via_sudo(target_dir)
    else:
        target_dir.mkdir(parents=True, exist_ok=True)
        _write_hook_files(target_dir / _ENTRYPOINT_NAME, target_dir)