1oci-hooks(5) MAY 2018 oci-hooks(5)
2
6 oci-hooks - OCI hooks configuration directories
7
11 /usr/share/containers/oci/hooks.d/*.json
12
16 Provides a way for users to configure the intended hooks for Open
17 Container Initiative containers so they will only be executed for
18 containers that need their functionality, and then only for the stages
19 where they're needed.
20
23 Hooks are configured with JSON files (ending with a .json extension) in
24 a series of hook directories. The default directory is
25 /usr/share/containers/oci/hooks.d, but tools consuming this format may
26 change that default, include additional directories, or provide their
27 callers with ways to adjust the configuration directories.
28 If multiple directories are configured, a JSON filename in a preferred
31 directory masks entries with the same filename in directories with
32 lower precedence. For example, if a consuming tool watches for hooks
33 in /etc/containers/oci/hooks.d and /usr/share/containers/oci/hooks.d
34 (in order of decreasing precedence), then a hook definition in
35 /etc/containers/oci/hooks.d/01-my-hook.json will mask any definition in
36 /usr/share/containers/oci/hooks.d/01-my-hook.json.
37 Tools consuming this format may also opt to monitor the hook directries
40 for changes, in which case they will notice additions, changes, and
41 removals to JSON files without needing to be restarted or otherwise
42 signaled. When the tool monitors multiple hooks directories, the
43 precedence discussed in the previous paragraph still applies. For
44 example, if a consuming tool watches for hooks in
45 /etc/containers/oci/hooks.d and /usr/share/containers/oci/hooks.d (in
46 order of decreasing precedence), then writing a new hook definition to
47 /etc/containers/oci/hooks.d/01-my-hook.json will mask the hook
48 previously loaded from
49 /usr/share/containers/oci/hooks.d/01-my-hook.json. Subsequent changes
50 to /usr/share/containers/oci/hooks.d/01-my-hook.json will have no
51 effect on the consuming tool as long as
52 /etc/containers/oci/hooks.d/01-my-hook.json exists. Removing
53 /etc/containers/oci/hooks.d/01-my-hook.json will reload the hook from
54 /usr/share/containers/oci/hooks.d/01-my-hook.json.
55 Hooks are injected in the order obtained by sorting the JSON file
58 names, after converting them to lower case, based on their Unicode code
59 points. For example, a matching hook defined in 01-my-hook.json would
60 be injected before matching hooks defined in 02-another-hook.json and
61 01-UPPERCASE.json. It is strongly recommended to make the sort oder
62 unambiguous depending on an ASCII-only prefix (like the 01/02 above).
63 Each JSON file should contain an object with one of the following
66 schemas.
67
70 version (required string)
71 Sets the hook-definition version. For this schema version, the value
72 be 1.0.0.
73 hook (required object)
76 The hook to inject, with the hook-entry schema defined by the 1.0.1
77 OCI Runtime Specification.
78 when (required object)
81 Conditions under which the hook is injected. The following
82 properties can be specified, and at least one must be specified:
83 · always (optional boolean)
86 If set true, this condition matches.
87 · annotations (optional object)
89 If all annotations key/value pairs match a key/value pair
90 from the configured annotations, this condition matches.
91 Both keys and values must be POSIX extended regular
92 expressions.
93 · commands (optional array of strings)
95 If the configured process.args[0] matches an entry, this
96 condition matches.
97 Entries must be POSIX extended regular expressions.
98 · hasBindMounts (optional boolean)
100 If hasBindMounts is true and the caller requested
101 host-to-container bind mounts, this condition matches.
102 stages (required array of strings)
106 Stages when the hook must be injected. Entries must be chosen from
107 the 1.0.1 OCI Runtime Specification hook stages or from extension
108 stages supported by the package consumer.
109 If all of the conditions set in when match, then the hook must be
112 injected for the stages set in stages.
113
116 hook (required string)
117 Sets path in the injected hook.
118 arguments (optional array of strings)
121 Additional arguments to pass to the hook. The injected hook's args
122 is hook with arguments appended.
123 stages (required array of strings)
126 Stages when the hook must be injected. stage is an allowed synonym
127 for this property, but you must not set both stages and stage. Entries
128 must be chosen from the 1.0.1 OCI Runtime Specification hook stages or
129 from extension stages supported by the package consumer.
130 cmds (optional array of strings)
133 The hook must be injected if the configured process.args[0] matches
134 an entry. cmd is an allowed synonym for this property, but you must
135 not set both cmds and cmd. Entries must be POSIX extended regular
136 expressions.
137 annotations (optional array of strings)
140 The hook must be injected if an annotations entry matches a value
141 from the configured annotations. annotation is an allowed synonym for
142 this property, but you must not set both annotations and annotation.
143 Entries must be POSIX extended regular expressions.
144 hasbindmounts (optional boolean)
147 The hook must be injected if hasBindMounts is true and the caller
148 requested host-to-container bind mounts.
149
154 The following configuration injects oci-systemd-hook in the pre-start
155 and post-stop stages if process.args[0] ends with /init or /systemd:
156 $ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
159 {
160 "version": "1.0.0",
161 "hook": {
162 "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
163 }
164 "when": {
165 "args": [".*/init$" , ".*/systemd$"],
166 },
167 "stages": ["prestart", "poststop"]
168 }
169 The following example injects oci-umount --debug in the pre-start stage
173 if the container is configured to bind-mount host directories into the
174 container.
175 $ cat /etc/containers/oci/hooks.d/oci-umount.json
178 {
179 "version": "1.0.0",
180 "hook": {
181 "path": "/usr/libexec/oci/hooks.d/oci-umount",
182 "args": ["oci-umount", "--debug"],
183 }
184 "when": {
185 "hasBindMounts": true,
186 },
187 "stages": ["prestart"]
188 }
189 The following example injects nvidia-container-runtime-hook prestart
193 with particular environment variables in the pre-start stage if the
194 container is configured with an annotations entry whose key matches
195 ^com\.example\.department$ and whose value matches .*fluid-dynamics.*.
196 $ cat /etc/containers/oci/hooks.d/nvidia.json
199 {
200 "version": "1.0.0",
201 "hook": {
202 "path": "/usr/sbin/nvidia-container-runtime-hook",
203 "args": ["nvidia-container-runtime-hook", "prestart"],
204 "env": [
205 "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
206 "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
207 ]
208 },
209 "when": {
210 "annotations": {
211 "^com\\.example\\.department$": ".*fluid-dynamics$"
212 }
213 },
214 "stages": ["prestart"]
215 }
216
220 The following configuration injects oci-systemd-hook in the pre-start
221 and post-stop stages if process.args[0] ends with /init or /systemd:
222 $ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
225 {
226 "cmds": [".*/init$" , ".*/systemd$"],
227 "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
228 "stages": ["prestart", "poststop"]
229 }
230 The following example injects oci-umount --debug in the pre-start stage
234 if the container is configured to bind-mount host directories into the
235 container.
236 $ cat /etc/containers/oci/hooks.d/oci-umount.json
239 {
240 "hook": "/usr/libexec/oci/hooks.d/oci-umount",
241 "arguments": ["--debug"],
242 "hasbindmounts": true,
243 "stages": ["prestart"]
244 }
245 The following example injects nvidia-container-runtime-hook prestart in
249 the pre-start stage if the container is configured with an annotations
250 entry whose value matches .*fluid-dynamics.*.
251 $ cat /etc/containers/oci/hooks.d/osystemd-hook.json
254 {
255 "hook": "/usr/sbin/nvidia-container-runtime-hook",
256 "arguments": ["prestart"],
257 "annotations: [".*fluid-dynamics.*"],
258 "stages": ["prestart"]
259 }
260
265 oci-systemd-hook(1), oci-umount(1), locale(7)
266 · OCI Runtime Specification, 1.0.1, POSIX-platform hooks
269 ⟨https://github.com/opencontainers/runtime-
270 spec/blob/v1.0.1/config.md#posix-platform-hooks⟩
271 · OCI Runtime Specification, 1.0.1, process
273 ⟨https://github.com/opencontainers/runtime-
274 spec/blob/v1.0.1/config.md#process⟩
275 · POSIX extended regular expressions (EREs)
277 ⟨http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04⟩
278W. Trevor King OCI Hooks Configuration oci-hooks(5)