Skip to content

docs/podman.1: Link to hook documentation #772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

docs/podman.1: Link to hook documentation #772

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3da7a4b
hooks/docs: Add oci-hooks.5 and per-package man page building
wking May 15, 2018
9956b8b
docs/podman.1: Link to hook documentation
wking May 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ binaries: varlink_generate podman python-podman

test-binaries: test/bin2img/bin2img test/copyimg/copyimg test/checkseccomp/checkseccomp

MANPAGES_MD ?= $(wildcard docs/*.md)
MANPAGES_MD ?= $(wildcard docs/*.md pkg/*/docs/*.md)
MANPAGES ?= $(MANPAGES_MD:%.md=%)

$(MANPAGES): %: %.md .gopathok
Expand Down
7 changes: 3 additions & 4 deletions contrib/spec/podman.spec.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,6 @@ providing packages with %{import_path} prefix.
%prep
%autosetup -Sgit -n podman-%{shortcommit}
sed -i '/\/bin\/env/d' completions/bash/%{name}
mv pkg/hooks/README.md pkg/hooks/README-hooks.md

%build
mkdir _build
Expand Down Expand Up @@ -459,7 +458,7 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath}

%files
%license LICENSE
%doc README.md CONTRIBUTING.md pkg/hooks/README-hooks.md install.md code-of-conduct.md transfer.md
%doc README.md CONTRIBUTING.md install.md code-of-conduct.md transfer.md
%{_bindir}/%{name}
%{_mandir}/man1/*.1*
%{_mandir}/man5/*.5*
Expand All @@ -477,14 +476,14 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath}
%if 0%{?with_devel}
%files -n libpod-devel -f devel.file-list
%license LICENSE
%doc README.md CONTRIBUTING.md pkg/hooks/README-hooks.md install.md code-of-conduct.md transfer.md
%doc README.md CONTRIBUTING.md install.md code-of-conduct.md transfer.md
%dir %{gopath}/src/%{provider}.%{provider_tld}/%{project}
%endif

%if 0%{?with_unit_test} && 0%{?with_devel}
%files unit-test-devel -f unit-test-devel.file-list
%license LICENSE
%doc README.md CONTRIBUTING.md pkg/hooks/README-hooks.md install.md code-of-conduct.md transfer.md
%doc README.md CONTRIBUTING.md install.md code-of-conduct.md transfer.md
%endif

%changelog
Expand Down
12 changes: 11 additions & 1 deletion docs/podman.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,12 +121,22 @@ has the capability to debug pods/images created by crio.

Note this is not a volume mount. The content of the volumes is copied into container storage, not bind mounted directly from the host.

**hook JSON** (`/usr/share/containers/oci/hooks.d/*.json`)

Each `*.json` file in `/usr/share/containers/oci/hooks.d` configures a hook for Podman containers. For more details on the syntax of the JSON files and the semantics of hook injection, see `oci-hooks(5)`.

Podman and libpod currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.

For the annotation conditions, libpod uses any annotations set in the generated OCI configuration.

For the bind-mount conditions, only mounts explicitly requested by the caller via `--volume` are considered. Bind mounts that libpod inserts by default (e.g. `/dev/shm`) are not considered.

**registries.conf** (`/etc/containers/registries.conf`)

registries.conf is the configuration file which specifies which registries should be consulted when completing image names which do not include a registry or domain portion.

## SEE ALSO
crio(8), storage.conf(5)
`oci-hooks(5)`, `storage.conf(5)`, `crio(8)`

## HISTORY
Dec 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com>
161 changes: 1 addition & 160 deletions pkg/hooks/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,170 +11,11 @@ For example the [oci-systemd-hook][] only executes if the command is `init` or `
This means if we automatically enabled all hooks, every container would have to execute `oci-systemd-hook`, even if they don't run systemd inside of the container.
Performance would also suffer if we exectuted each hook at each stage ([pre-start][], [post-start][], and [post-stop][]).

## Notational Conventions
The hooks configuration is documented in [`oci-hooks.5`][docs/oci-hooks.5.md].

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119].

## JSON Definition

This package reads all [JSON][] files (ending with a `.json` extention) from a series of hook directories.
For both `crio` and `podman`, hooks are read from `/usr/share/containers/oci/hooks.d/*.json`.

For `crio`, hook JSON is also read from `/etc/containers/oci/hooks.d/*.json`.
If files of with the same name exist in both directories, the one in `/etc/containers/oci/hooks.d` takes precedence.

Hooks MUST be injected in the JSON filename case- and width-insensitive collation order.
Collation order depends on your locale, as set by [`LC_ALL`][LC_ALL], [`LC_COLLATE`][LC_COLLATE], or [`LANG`][LANG] (in order of decreasing precedence).
For example, in the [POSIX locale][LC_COLLATE-POSIX], a matching hook defined in `01-my-hook.json` would be injected before matching hooks defined in `02-another-hook.json` and `01-UPPERCASE.json`.

Each JSON file should contain an object with the following properties:

### 1.0.0 Hook Schema

* **`version`** (REQUIRED, string) Sets the hook-definition version.
For this schema version, the value MUST be 1.0.0.
* **`hook`** (REQUIRED, object) The hook to inject, with the [hook-entry schema][spec-hooks] defined by the 1.0.1 OCI Runtime Specification.
* **`when`** (REQUIRED, object) Conditions under which the hook is injected.
The following properties can be specified:

* **`always`** (OPTIONAL, boolean) If set `true`, this condition matches.
* **`annotations`** (OPTIONAL, object) If all `annotations` key/value pairs match a key/value pair from the [configured annotations][spec-annotations], this condition matches.
Both keys and values MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`commands`** (OPTIONAL, array of strings) If the configured [`process.args[0]`][spec-process] matches an entry, this condition matches.
Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`hasBindMounts`** (OPTIONAL, boolean) If `hasBindMounts` is true and the caller requested host-to-container bind mounts (beyond those that CRI-O or libpod use by default), this condition matches.
* **`stages`** (REQUIRED, array of strings) Stages when the hook MUST be injected.
Entries MUST be chosen from the 1.0.1 OCI Runtime Specification [hook stages][spec-hooks] or from extention stages supported by the package consumer.

If *all* of the conditions set in `when` match, then the `hook` MUST be injected for the stages set in `stages`.

#### Example

The following configuration injects [`oci-systemd-hook`][oci-systemd-hook] in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:

```console
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
"version": "1.0.0",
"hook": {
"path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
}
"when": {
"args": [".*/init$" , ".*/systemd$"],
},
"stages": ["prestart", "poststop"]
}
```

The following example injects [`oci-umount --debug`][oci-umount] in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.

```console
$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
"version": "1.0.0",
"hook": {
"path": "/usr/libexec/oci/hooks.d/oci-umount",
"args": ["oci-umount", "--debug"],
}
"when": {
"hasBindMounts": true,
},
"stages": ["prestart"]
}
```

The following example injects [`nvidia-container-runtime-hook prestart`][nvidia-container-runtime-hook] with particular environment variables in the [pre-start][] phase if the container is configured with an `annotations` entry whose key matches `^com\.example\.department$` and whose value matches `.*fluid-dynamics.*`.

```console
$ cat /etc/containers/oci/hooks.d/nvidia.json
{
"hook": {
"path": "/usr/sbin/nvidia-container-runtime-hook",
"args": ["nvidia-container-runtime-hook", "prestart"],
"env": [
"NVIDIA_REQUIRE_CUDA=cuda>=9.1",
"NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
]
},
"when": {
"annotations": {
"^com\.example\.department$": ".*fluid-dynamics$"
}
},
"stages": ["prestart"]
}
```

### 0.1.0 Hook Schema

Previous versions of CRI-O and libpod supported the 0.1.0 hook schema:

* **`hook`** (REQUIRED, string) Sets [`path`][spec-hooks] in the injected hook.
* **`arguments`** (OPTIONAL, array of strings) Additional arguments to pass to the hook.
The injected hook's [`args`][spec-hooks] is `hook` with `arguments` appended.
* **`stages`** (REQUIRED, array of strings) Stages when the hook MUST be injected.
`stage` is an allowed synonym for this property, but you MUST NOT set both `stages` and `stage`.
Entries MUST be chosen from the 1.0.1 OCI Runtime Specification [hook stages][spec-hooks] or from extention stages supported by the package consumer.
* **`cmds`** (OPTIONAL, array of strings) The hook MUST be injected if the configured [`process.args[0]`][spec-process] matches an entry.
`cmd` is an allowed synonym for this property, but you MUST NOT set both `cmds` and `cmd`.
Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`annotations`** (OPTIONAL, array of strings) The hook MUST be injected if an `annotations` entry matches a value from the [configured annotations][spec-annotations].
`annotation` is an allowed synonym for this property, but you MUST NOT set both `annotations` and `annotation`.
Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`hasbindmounts`** (OPTIONAL, boolean) The hook MUST be injected if `hasBindMounts` is true and the caller requested host-to-container bind mounts (beyond those that CRI-O or libpod use by default).

#### Example

The following configuration injects [`oci-systemd-hook`][oci-systemd-hook] in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:

```console
$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
"cmds": [".*/init$" , ".*/systemd$"],
"hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
"stages": ["prestart", "poststop"]
}
```

The following example injects [`oci-umount --debug`][oci-umount] in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.

```console
$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
"hook": "/usr/libexec/oci/hooks.d/oci-umount",
"arguments": ["--debug"],
"hasbindmounts": true,
"stages": ["prestart"]
}
```

The following example injects [`nvidia-container-runtime-hook prestart`][nvidia-container-runtime-hook] in the [pre-start][] phase if the container is configured with an `annotations` entry whose value matches `.*fluid-dynamics.*`.

```console
$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
{
"hook": "/usr/sbin/nvidia-container-runtime-hook",
"arguments": ["prestart"],
"annotations: [".*fluid-dynamics.*"],
"stages": ["prestart"]
}
```

[JSON]: https://tools.ietf.org/html/rfc8259
[LANG]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
[LC_ALL]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
[LC_COLLATE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_02
[LC_COLLATE-POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_02_06
[nvidia-container-runtime-hook]: https://github.com/NVIDIA/nvidia-container-runtime/tree/master/hook/nvidia-container-runtime-hook
[oci-systemd-hook]: https://github.com/projectatomic/oci-systemd-hook
[oci-umount]: https://github.com/projectatomic/oci-umount
[POSIX-ERE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04
[post-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststart
[post-stop]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststop
[pre-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#prestart
[rfc2119]: http://tools.ietf.org/html/rfc2119
[runc]: https://github.com/opencontainers/runc
[runtime-spec]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/spec.md
[spec-annotations]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#annotations
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks
[spec-process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#process
1 change: 1 addition & 0 deletions pkg/hooks/docs/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.5
Loading