1oci-hooks(5)                     Configuration                    oci-hooks(5)
2
3
4
5W. Trevor King MAY 2018
6
7

NAME

9       oci-hooks - OCI hooks configuration directories
10
11
12

SYNOPSIS

14       /usr/share/containers/oci/hooks.d/*.json
15
16
17

DESCRIPTION

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
24

Directories

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
32
33       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
41
42       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
58
59       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
66
67       Each  JSON  file  should  contain  an  object with one of the following
68       schemas.
69
70

1.0.0 Hook Schema

72       version (required string)
73         Sets the hook-definition version.  For this schema version, the value
74       be 1.0.0.
75
76
77       hook (required object)
78         The  hook  to inject, with the hook-entry schema defined by the 1.0.1
79       OCI Runtime Specification.
80
81
82       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
86
87always (optional boolean)
88                  If set true, this condition matches.
89
90annotations (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
96commands (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
101hasBindMounts (optional boolean)
102                  If hasBindMounts is true and the caller  requested  host-to-
103                container bind mounts, this condition matches.
104
105
106
107       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
112
113       If  all  of the conditions set in when match, then the hook must be in‐
114       jected for the stages set in stages.
115
116

0.1.0 Hook Schema

118       hook (required string)
119         Sets path in the injected hook.
120
121
122       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
126
127       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
133
134       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
140
141       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
147
148       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
152
153

EXAMPLE

1.0.0 Hook Schema

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
159
160              $ 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
172
173
174       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
178
179              $ 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
192
193
194       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
199
200              $ 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
219
220

0.1.0 Hook Schema

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
225
226              $ 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
233
234
235       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
239
240              $ 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
248
249
250       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
254
255              $ 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
263
264
265

SEE ALSO

267       oci-systemd-hook(1), oci-umount(1), locale(7)
268
269
270              • OCI Runtime Specification, 1.0.1, POSIX-platform hooks
271
272              • OCI Runtime Specification, 1.0.1, process
273
274              • POSIX extended regular expressions (EREs)
275
276
277
278
279Hooks                                 OCI                         oci-hooks(5)
Impressum