From ba4a9a04e7d69fd26cf083dca8f8bfbd0f04c455 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 27 Apr 2016 23:07:31 -0700 Subject: [PATCH 1/2] README: Punt detailed command description to the man pages This makes it easier to get a project overview from the README, and avoids the tedium of keeping parallel sets of detailed docs up to date. Signed-off-by: W. Trevor King --- README.md | 86 ++++++++++++++++--------------------------------------- 1 file changed, 25 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 7cc067c1b..0a41398c5 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,34 @@ # ocitools -ocitools is a collection of tools for working with the [OCI runtime specification](https://github.com/opencontainers/runtime-spec). +ocitools is a collection of tools for working with the [OCI runtime specification][runtime-spec]. -Generating OCI runtime spec configuration files ------------------------------------------- +## Generating an OCI runtime spec configuration files -``` -# ocitools generate --help -NAME: - generate - generate a OCI spec file - -USAGE: - command generate [command options] [arguments...] - -OPTIONS: - --rootfs path to the rootfs - --read-only make the container's rootfs read-only - --privileged enabled privileged container settings - --hostname "acme" hostname value for the container - --uid "0" uid for the process - --gid "0" gid for the process - --groups [--groups option --groups option] supplementary groups for the process - --cap-add [--cap-add option --cap-add option] add capabilities - --cap-drop [--cap-drop option --cap-drop option] drop capabilities - --network network namespace - --mount mount namespace - --pid pid namespace - --ipc ipc namespace - --uts uts namespace - --selinux-label process selinux label - --tmpfs [--tmpfs option --tmpfs option] mount tmpfs - --args command to run in the container - --env [--env option --env option] add environment variable - --mount-cgroups "ro" mount cgroups (rw,ro,no) - --bind [--bind option --bind option] bind mount directories src:dest:(rw,ro) - --prestart [--prestart option --prestart option] path to prestart hooks - --poststop [--poststop option --poststop option] path to poststop hooks - --root-propagation mount propagation for root - --os "linux" operating system the container is created for - --arch "amd64" architecture the container is created for - --cwd "/" current working directory for the process - --uidmappings [--uidmappings option ] add UIDMappings e.g HostID:ContainerID:Size - --gidmappings [--gidmappings option ] add GIDMappings e.g HostID:ContainerID:Size - --apparmor specify the the apparmor profile for the container - --seccomp-default specify the the defaultaction of Seccomp syscall restrictions - --seccomp-arch [--seccomp-arch option ] specify Additional architectures permitted to be used - for system calls - --seccomp-syscalls [--seccomp-syscalls option] specify syscalls used in Seccomp - e.g Name:Action:Arg1_index/Arg1_value/Arg1_valuetwo/Arg1_op, - Arg2_index/Arg2_value/Arg2_valuetwo/Arg2_op -``` - -Validating OCI bundle ------------------------------------------- +[`ocitools generate`][generate.1] is used to generate a `config.json` ([OCI spec][runtime-spec] file) to be used to instantiate an OCI container. +This `config.json` file can be placed into a directory and used by an OCI compatable runtime like [**runc**][runC] to run a container. +```sh +$ ocitools generate +$ cat config.json +{ + "ociVersion": "0.5.0", + … +} ``` -# ocitools validate --help -NAME: - validate - validate a OCI bundle -USAGE: - command validate [command options] [arguments...] +## Validating an OCI bundle -OPTIONS: - --path path to a bundle +[`ocitools validate`][validate.1] validates an OCI bundle. +```sh +$ ocitools generate +$ ocitools validate +FATA[0000] Bundle path shouldn't be empty ``` -Testing OCI runtimes ------------------------------------------- +## Testing OCI runtimes -``` +```sh $ make $ sudo make install $ sudo ./test_runtime.sh -r runc @@ -84,3 +42,9 @@ validating rlimits validating sysctls Runtime runc passed validation ``` + +[runC]: https://github.com/opencontainers/runc +[runtime-spec]: https://github.com/opencontainers/runtime-spec + +[generate.1]: man/ocitools-generate.1.md +[validate.1]: man/ocitools-validate.1.md From bb117396286aaa6f096bdcd4d48cc72870f7ba72 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 27 Apr 2016 23:14:57 -0700 Subject: [PATCH 2/2] man/ocitools-generate.1: Copy-edits for the description Also adjust the copy of this text in the README. I've left the reference-style links out of the man page, since go-md2man doesn't seem to be able to handle them, and instead creates troff with just the link targets: \[la]man/ocitools-generate.1.md\[ra] generates a \[la]https://github.com/opencontainers/runtime-spec/blob/master/config.md\[ra] for an ... Signed-off-by: W. Trevor King --- README.md | 6 ++++-- man/ocitools-generate.1.md | 8 ++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 0a41398c5..a3504fb14 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ ocitools is a collection of tools for working with the [OCI runtime specificatio ## Generating an OCI runtime spec configuration files -[`ocitools generate`][generate.1] is used to generate a `config.json` ([OCI spec][runtime-spec] file) to be used to instantiate an OCI container. -This `config.json` file can be placed into a directory and used by an OCI compatable runtime like [**runc**][runC] to run a container. +[`ocitools generate`][generate.1] generates a [`config.json`][config.json] for an [OCI bundle][bundle]. +This `config.json` file can be placed into a directory and used by an [OCI compatable runtime][runtime-spec] like [runC][] to run a container. ```sh $ ocitools generate @@ -43,6 +43,8 @@ validating sysctls Runtime runc passed validation ``` +[bundle]: https://github.com/opencontainers/runtime-spec/blob/master/bundle.md +[config.json]: https://github.com/opencontainers/runtime-spec/blob/master/config.md [runC]: https://github.com/opencontainers/runc [runtime-spec]: https://github.com/opencontainers/runtime-spec diff --git a/man/ocitools-generate.1.md b/man/ocitools-generate.1.md index fe4e3d616..abb6898d0 100644 --- a/man/ocitools-generate.1.md +++ b/man/ocitools-generate.1.md @@ -44,10 +44,10 @@ ocitools-generate - Generate a config.json for an OCI container [**--uts**] # DESCRIPTION -**ocitools generate** is used to generate a config.json (OCI spec file) to be used to -instantiate an OCI container. This config.json file can be placed into a -directory and used by an OCI compatable runtime like **runc** to run a -container. + +`ocitools generate` generates a `config.json` for an OCI bundle. This +`config.json` file can be placed into a directory and used by an OCI +compatable runtime like runC to run a container. # OPTIONS **--apparmor**="PROFILE"