*********************************
Configuring Sarus for OCI hooks
*********************************

In order to extend the core functionality provided by a container runtime, the
OCI Runtime Specification allows for components to be hooked into the
container's lifecycle, performing custom actions. These `OCI hooks
<https://github.com/opencontainers/runtime-spec/blob/main/config.md#posix-platform-hooks>`_
are especially amenable to HPC use cases, where the dedicated hardware and
highly-tuned software adopted by high-performance systems are in contrast with
the platform-agnostic nature of software containers. Effectively, OCI hooks
provide solutions for the container runtime to allow access to system-specific
features and specialized resources within container instances.

To enable the use of hooks in Sarus, the :ref:`hooksDir <config-reference-hooksDir>` directory specified
in *sarus.json* must be populated with `OCI hook JSON configuration files
<https://github.com/containers/common/blob/main/pkg/hooks/docs/oci-hooks.5.md>`_.
Sarus currently supports the OCI hook schema version 1.0.0.

Sarus parses the JSON files in :ref:`hooksDir <config-reference-hooksDir>` (subdirectories excluded) and,
if the ``when`` conditions specified in a JSON are all true, the corresponding OCI hook is inserted into the
OCI bundle's configuration file that is generated by Sarus.

The hooks will effectively be called by the OCI-compliant runtime specified with the
``runcPath`` parameter in *sarus.json*.

The hooks are inserted into the OCI bundle's configuration file and executed by the OCI-compliant runtime in
the order obtained by lexicographically sorting the JSON file names.

All the hooks configured in the :ref:`hooksDir <config-reference-hooksDir>` directory must
satisfy the :ref:`security requirements <post-installation-permissions-security>` for critical
files and directories.


Hooks use cases
===============

In the following pages, we will provide guidance on how to enable hooks
for specific use cases:

.. toctree::
   :maxdepth: 1

   mpi-hook
   nvidia-container-toolkit
   mount-hook
   glibc-hook
   ssh-hook
   slurm-global-sync-hook
   timestamp-hook
   amdgpu-hook