1oci-hooks(5) Configuration oci-hooks(5)
2W. Trevor King MAY 2018
6
9 oci-hooks - OCI hooks configuration directories
10
14 /usr/share/containers/oci/hooks.d/*.json
15
19 Provides a way for users to configure the intended hooks for Open Con‐
20 tainer Initiative containers so they will only be executed for contain‐
21 ers that need their functionality, and then only for the stages where
22 they're needed.
23
26 Hooks are configured with JSON files (ending with a .json extension) in
27 a series of hook directories. The default directory is /usr/share/con‐
28 tainers/oci/hooks.d, but tools consuming this format may change that
29 default, include additional directories, or provide their callers with
30 ways to adjust the configuration directories.
31 If multiple directories are configured, a JSON filename in a preferred
34 directory masks entries with the same filename in directories with
35 lower precedence. For example, if a consuming tool watches for hooks
36 in /etc/containers/oci/hooks.d and /usr/share/containers/oci/hooks.d
37 (in order of decreasing precedence), then a hook definition in
38 /etc/containers/oci/hooks.d/01-my-hook.json will mask any definition in
39 /usr/share/containers/oci/hooks.d/01-my-hook.json.
40 Tools consuming this format may also opt to monitor the hook directo‐
43 ries for changes, in which case they will notice additions, changes,
44 and removals to JSON files without needing to be restarted or otherwise
45 signaled. When the tool monitors multiple hooks directories, the
46 precedence discussed in the previous paragraph still applies. For ex‐
47 ample, if a consuming tool watches for hooks in /etc/contain‐
48 ers/oci/hooks.d and /usr/share/containers/oci/hooks.d (in order of de‐
49 creasing precedence), then writing a new hook definition to /etc/con‐
50 tainers/oci/hooks.d/01-my-hook.json will mask the hook previously
51 loaded from /usr/share/containers/oci/hooks.d/01-my-hook.json. Subse‐
52 quent changes to /usr/share/containers/oci/hooks.d/01-my-hook.json will
53 have no effect on the consuming tool as long as /etc/contain‐
54 ers/oci/hooks.d/01-my-hook.json exists. Removing /etc/contain‐
55 ers/oci/hooks.d/01-my-hook.json will reload the hook from
56 /usr/share/containers/oci/hooks.d/01-my-hook.json.
57 Hooks are injected in the order obtained by sorting the JSON file
60 names, after converting them to lower case, based on their Unicode code
61 points. For example, a matching hook defined in 01-my-hook.json would
62 be injected before matching hooks defined in 02-another-hook.json and
63 01-UPPERCASE.json. It is strongly recommended to make the sort order
64 unambiguous depending on an ASCII-only prefix (like the 01/02 above).
65 Each JSON file should contain an object with one of the following
68 schemas.
69
72 version (required string)
73 Sets the hook-definition version. For this schema version, the value
74 be 1.0.0.
75 hook (required object)
78 The hook to inject, with the hook-entry schema defined by the 1.0.1
79 OCI Runtime Specification.
80 when (required object)
83 Conditions under which the hook is injected. The following proper‐
84 ties can be specified, and at least one must be specified:
85 • always (optional boolean)
88 If set true, this condition matches.
89 • annotations (optional object)
91 If all annotations key/value pairs match a key/value pair
92 from the configured annotations, this condition matches.
93 Both keys and values must be POSIX extended regular expres‐
94 sions.
95 • commands (optional array of strings)
97 If the configured process.args[0] matches an entry, this
98 condition matches.
99 Entries must be POSIX extended regular expressions.
100 • hasBindMounts (optional boolean)
102 If hasBindMounts is true and the caller requested host-to-
103 container bind mounts, this condition matches.
104 stages (required array of strings)
108 Stages when the hook must be injected. Entries must be chosen from
109 the 1.0.1 OCI Runtime Specification hook stages or from extension
110 stages supported by the package consumer.
111 If all of the conditions set in when match, then the hook must be in‐
114 jected for the stages set in stages.
115
118 hook (required string)
119 Sets path in the injected hook.
120 arguments (optional array of strings)
123 Additional arguments to pass to the hook. The injected hook's args
124 is hook with arguments appended.
125 stages (required array of strings)
128 Stages when the hook must be injected. stage is an allowed synonym
129 for this property, but you must not set both stages and stage. Entries
130 must be chosen from the 1.0.1 OCI Runtime Specification hook stages or
131 from extension stages supported by the package consumer.
132 cmds (optional array of strings)
135 The hook must be injected if the configured process.args[0] matches
136 an entry. cmd is an allowed synonym for this property, but you must
137 not set both cmds and cmd. Entries must be POSIX extended regular ex‐
138 pressions.
139 annotations (optional array of strings)
142 The hook must be injected if an annotations entry matches a value
143 from the configured annotations. annotation is an allowed synonym for
144 this property, but you must not set both annotations and annotation.
145 Entries must be POSIX extended regular expressions.
146 hasbindmounts (optional boolean)
149 The hook must be injected if hasBindMounts is true and the caller re‐
150 quested host-to-container bind mounts.
151
156 The following configuration injects oci-systemd-hook in the pre-start
157 and post-stop stages if process.args[0] ends with /init or /systemd:
158 $ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
161 {
162 "version": "1.0.0",
163 "hook": {
164 "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
165 },
166 "when": {
167 "commands": [".*/init$" , ".*/systemd$"]
168 },
169 "stages": ["prestart", "poststop"]
170 }
171 The following example injects oci-umount --debug in the pre-start stage
175 if the container is configured to bind-mount host directories into the
176 container.
177 $ cat /etc/containers/oci/hooks.d/oci-umount.json
180 {
181 "version": "1.0.0",
182 "hook": {
183 "path": "/usr/libexec/oci/hooks.d/oci-umount",
184 "args": ["oci-umount", "--debug"],
185 },
186 "when": {
187 "hasBindMounts": true
188 },
189 "stages": ["prestart"]
190 }
191 The following example injects nvidia-container-runtime-hook prestart
195 with particular environment variables in the pre-start stage if the
196 container is configured with an annotations entry whose key matches
197 ^com\.example\.department$ and whose value matches .*fluid-dynamics.*.
198 $ cat /etc/containers/oci/hooks.d/nvidia.json
201 {
202 "version": "1.0.0",
203 "hook": {
204 "path": "/usr/sbin/nvidia-container-runtime-hook",
205 "args": ["nvidia-container-runtime-hook", "prestart"],
206 "env": [
207 "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
208 "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
209 ]
210 },
211 "when": {
212 "annotations": {
213 "^com\\.example\\.department$": ".*fluid-dynamics$"
214 }
215 },
216 "stages": ["prestart"]
217 }
218
222 The following configuration injects oci-systemd-hook in the pre-start
223 and post-stop stages if process.args[0] ends with /init or /systemd:
224 $ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
227 {
228 "cmds": [".*/init$" , ".*/systemd$"],
229 "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
230 "stages": ["prestart", "poststop"]
231 }
232 The following example injects oci-umount --debug in the pre-start stage
236 if the container is configured to bind-mount host directories into the
237 container.
238 $ cat /etc/containers/oci/hooks.d/oci-umount.json
241 {
242 "hook": "/usr/libexec/oci/hooks.d/oci-umount",
243 "arguments": ["--debug"],
244 "hasbindmounts": true,
245 "stages": ["prestart"]
246 }
247 The following example injects nvidia-container-runtime-hook prestart in
251 the pre-start stage if the container is configured with an annotations
252 entry whose value matches .*fluid-dynamics.*.
253 $ cat /etc/containers/oci/hooks.d/osystemd-hook.json
256 {
257 "hook": "/usr/sbin/nvidia-container-runtime-hook",
258 "arguments": ["prestart"],
259 "annotations: [".*fluid-dynamics.*"],
260 "stages": ["prestart"]
261 }
262
267 oci-systemd-hook(1), oci-umount(1), locale(7)
268 • OCI Runtime Specification, 1.0.1, POSIX-platform hooks
271 • OCI Runtime Specification, 1.0.1, process
273 • POSIX extended regular expressions (EREs)
275Hooks OCI oci-hooks(5)