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 <asarai@suse.de>

.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

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,11 +73,11 @@ 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 $@
 
@@ -89,14 +89,19 @@ install:
 	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

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 <dwalsh@redhat.com>
+Sept 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com> and Aleksa Sarai <asarai@suse.de>

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 <asarai@suse.de>