Merge pull request #47 from wking/readme-link-man-pages

README: Punt detailed command description to the man pages
opencontainers · Apr 28, 2016 · 8e89de8 · 8e89de8
2 parents 12fa259 + bb11739
commit 8e89de8
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 65 deletions.
diff --git 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] 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
+$ 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,11 @@ validating rlimits
 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
+
+[generate.1]: man/ocitools-generate.1.md
+[validate.1]: man/ocitools-validate.1.md
diff --git 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"