From 6860fe154ad1a6c9fc84860b8cb25acf52fdb94c Mon Sep 17 00:00:00 2001 From: Aleksa Sarai Date: Mon, 10 Oct 2016 04:36:43 +1100 Subject: [PATCH] docs: update documentation Add documentation for the new configuration file format, as well as the new `ocid config` subcommand and the changed --socket option. Signed-off-by: Aleksa Sarai --- .gitignore | 1 + Makefile | 17 ++++++++---- docs/ocid.8.md | 38 ++++++++++++++++++------- docs/ocid.conf.5.md | 67 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 107 insertions(+), 16 deletions(-) create mode 100644 docs/ocid.conf.5.md diff --git a/.gitignore b/.gitignore index fda90951..7e048ddf 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ conmon/conmon.o pause/pause pause/pause.o /docs/ocid.8 +/docs/ocid.conf.5 vendor/src/github.com/kubernetes-incubator/cri-o diff --git a/Makefile b/Makefile index 655deb81..6d8e5fc0 100644 --- a/Makefile +++ b/Makefile @@ -49,7 +49,7 @@ clean: rm -f ${OCID_LINK} rm -f conmon/conmon.o conmon/conmon rm -f pause/pause.o pause/pause - rm -f docs/*.1 docs/*.8 + rm -f docs/*.1 docs/*.5 docs/*.8 find . -name \*~ -delete find . -name \#\* -delete @@ -73,30 +73,35 @@ binaries: ${OCID_LINK} ocid ocic conmon pause MANPAGES_MD = $(wildcard docs/*.md) -docs/%.1: docs/%.1.md +docs/%.8: docs/%.8.md @which go-md2man > /dev/null 2>/dev/null || (echo "ERROR: go-md2man not found. Consider 'make install.tools' target" && false) $(GO_MD2MAN) -in $< -out $@.tmp && touch $@.tmp && mv $@.tmp $@ -docs/%.8: docs/%.8.md +docs/%.5: docs/%.5.md @which go-md2man > /dev/null 2>/dev/null || (echo "ERROR: go-md2man not found. Consider 'make install.tools' target" && false) $(GO_MD2MAN) -in $< -out $@.tmp && touch $@.tmp && mv $@.tmp $@ docs: $(MANPAGES_MD:%.md=%) -install: +install: install -D -m 755 ocid ${INSTALLDIR}/ocid install -D -m 755 ocic ${INSTALLDIR}/ocic install -D -m 755 conmon/conmon $(PREFIX)/libexec/ocid/conmon install -D -m 755 pause/pause $(PREFIX)/libexec/ocid/pause install -d $(PREFIX)/share/man/man8 - install -m 644 $(basename $(MANPAGES_MD)) $(PREFIX)/share/man/man8 + install -m 644 $(wildcard docs/*.8.md) $(PREFIX)/share/man/man8 + install -d $(PREFIX)/share/man/man5 + install -m 644 $(wildcard docs/*.5.md) $(PREFIX)/share/man/man5 uninstall: rm -f ${INSTALLDIR}/{ocid,ocic} rm -f $(PREFIX)/libexec/ocid/{conmon,pause} - for i in $(basename $(MANPAGES_MD)); do \ + for i in $(wildcard docs/*.8.md); do \ rm -f $(PREFIX)/share/man/man8/$$(basename $${i}); \ done + for i in $(wildcard docs/*.5.md); do \ + rm -f $(PREFIX)/share/man/man5/$$(basename $${i}); \ + done .PHONY: .gitvalidation # When this is running in travis, it will only check the travis commit range diff --git a/docs/ocid.8.md b/docs/ocid.8.md index f80ba030..2b0516c5 100644 --- a/docs/ocid.8.md +++ b/docs/ocid.8.md @@ -10,14 +10,14 @@ ocid - Enable OCI Kubernetes Container Runtime daemon [**--containerdir**=[*value*]] [**--debug**] [**--help**|**-h**] +[**--listen**=[*value*]] [**--log**=[*value*]] [**--log-format value**] [**--pause**=[*value*]] [**--root**=[*value*]] [**--runtime**=[*value*]] [**--sandboxdir**=[*value*]] -[**--selinux-enabled**] -[**--socket**=[*value*]] +[**--selinux**] [**--version**|**-v**] # DESCRIPTION @@ -32,9 +32,11 @@ ocid is meant to provide an integration path between OCI conformant runtimes and * Monitoring and logging required to satisfy the CRI * Resource isolation as required by the CRI -**ocid [OPTIONS]** +**ocid [GLOBAL OPTIONS]** -# OPTIONS +**ocid [GLOBAL OPTIONS] config [OPTIONS]** + +# GLOBAL OPTIONS **--conmon**="" path to the conmon executable (default: "/usr/libexec/ocid/conmon") @@ -48,6 +50,9 @@ ocid is meant to provide an integration path between OCI conformant runtimes and **--help, -h** Print usage statement +**--listen**="" + Path to ocid socket (default: "/var/run/ocid.sock") + **--log**="" Set the log file path where internal debug information is written @@ -66,14 +71,27 @@ ocid is meant to provide an integration path between OCI conformant runtimes and **--sandboxdir**="" OCID pod sandbox dir (default: "/var/lib/ocid/sandboxes") -**--selinux-enabled** - Enable selinux support - -**--socket**="" - Path to ocid socket (default: "/var/run/ocid.sock") +**--selinux** + Enable selinux support (default: false) **--version, -v** Print the version +# COMMANDS +OCID's default command is to start the daemon. However, it currently offers a +single additional subcommand. + +## config + +Outputs a commented version of the configuration file that would've been used +by OCID. This allows you to save you current configuration setup and then load +it later with **--config**. Global options will modify the output. + +**--default** + Output the default configuration (without taking into account any configuration options). + +# SEE ALSO +ocid.conf(5) + # HISTORY -Sept 2016, Originally compiled by Dan Walsh +Sept 2016, Originally compiled by Dan Walsh and Aleksa Sarai diff --git a/docs/ocid.conf.5.md b/docs/ocid.conf.5.md new file mode 100644 index 00000000..655f4d78 --- /dev/null +++ b/docs/ocid.conf.5.md @@ -0,0 +1,67 @@ +% ocid.conf(5) Open Container Initiative Daemon +% Aleksa Sarai +% OCTOBER 2016 + +# NAME +ocid.conf - Syntax of OCID configuration file + +# DESCRIPTION +The OCID configuration file specifies all of the available command-line options +for the ocid(8) program, but in a TOML format that can be more easily modified +and versioned. + +# FORMAT +The [TOML format][toml] is used as the encoding of the configuration file. +Every option and subtable listed here is nested under a global "ocid" table. +No bare options are used. The format of TOML can be simplified to: + + [table] + option = value + + [table.subtable1] + option = value + + [table.subtable2] + option = value + +## OCID TABLE + +The `ocid` table supports the following options: + + +**container_dir**="" + OCID container dir (default: "/var/lib/ocid/containers") + +**root**="" + OCID root dir (default: "/var/lib/ocid") + +**sandbox_dir**="" + OCID pod sandbox dir (default: "/var/lib/ocid/sandboxes") + + +## OCID.API TABLE + +**listen**="" + Path to ocid socket (default: "/var/run/ocid.sock") + +## OCID.RUNTIME TABLE + +**conmon**="" + path to the conmon executable (default: "/usr/libexec/ocid/conmon") + +**runtime**="" + OCI runtime path (default: "/usr/bin/runc") + +**selinux** + Enable selinux support (default: false) + +## OCID.IMAGE TABLE + +**pause**="" + Path to the pause executable (default: "/usr/libexec/ocid/pause") + +# SEE ALSO +ocid(8) + +# HISTORY +Oct 2016, Originally compiled by Aleksa Sarai