Merge pull request #2079 from estesp/man-pages

Add initial man pages

.gitignore

@@ -1,4 +1,5 @@
 /bin/
+/man/
 coverage.txt
 profile.out
 containerd.test

Makefile

@@ -57,6 +57,7 @@ TEST_REQUIRES_ROOT_PACKAGES=$(filter \
 
 # Project binaries.
 COMMANDS=ctr containerd containerd-stress containerd-release
+MANPAGES=ctr.1 containerd.1 config.toml.5 containerd-config.1
 
 GO_TAGS=$(if $(BUILDTAGS),-tags "$(BUILDTAGS)",)
 GO_LDFLAGS=-ldflags '-s -w -X $(PKG)/version.Version=$(VERSION) -X $(PKG)/version.Revision=$(REVISION) -X $(PKG)/version.Package=$(PKG) $(EXTRA_LDFLAGS)'
@@ -82,7 +83,7 @@ BINARIES=$(addprefix bin/,$(COMMANDS))
 TESTFLAGS ?= -v $(TESTFLAGS_RACE)
 TESTFLAGS_PARALLEL ?= 8
 
-.PHONY: clean all AUTHORS build binaries test integration generate protos checkprotos coverage ci check help install uninstall vendor release
+.PHONY: clean all AUTHORS build binaries test integration generate protos checkprotos coverage ci check help install uninstall vendor release mandir install-man
 .DEFAULT: default
 
 all: binaries
@@ -157,6 +158,25 @@ bin/containerd-shim: cmd/containerd-shim FORCE # set !cgo and omit pie for a sta
 binaries: $(BINARIES) ## build binaries
 	@echo "$(WHALE) $@"
 
+man: mandir $(addprefix man/,$(MANPAGES))
+	@echo "$(WHALE) $@"
+
+mandir:
+	@mkdir -p man
+
+man/%: docs/man/%.md FORCE
+	@echo "$(WHALE) $<"
+	go-md2man -in "$<" -out "$@"
+
+define installmanpage
+mkdir -p $(DESTDIR)/man/man$(2);
+gzip -c $(1) >$(DESTDIR)/man/man$(2)/$(3).gz;
+endef
+
+install-man:
+	@echo "$(WHALE) $@"
+	$(foreach manpage,$(addprefix man/,$(MANPAGES)), $(call installmanpage,$(manpage),$(subst .,,$(suffix $(manpage))),$(notdir $(manpage))))
+
 release: $(BINARIES)
 	@echo "$(WHALE) $@"
 	@rm -rf releases/$(RELEASE) releases/$(RELEASE).tar.gz

docs/man/config.toml.5.md

@@ -0,0 +1,130 @@
+# config.toml 5 02/02/2018
+
+## SYNOPSIS
+
+The **config.toml** file is a configuration file for the containerd daemon. The
+file must be placed in **/etc/containerd/** or used with the **--config**
+option of **containerd** to be used by the daemon. If the file does not exist
+at the appropriate location or is not provided via the **--config** option
+containerd uses its default configuration settings, which can be displayed
+with the **containerd config(1)** command.
+
+## DESCRIPTION
+
+The TOML file used to configure the containerd daemon settings has a short
+list of global settings followed by a series of sections for specific areas
+of daemon configuration. There is also a section for **plugins** that allows
+each containerd plugin to have an area for plugin-specific configuration and
+settings.
+
+## FORMAT
+
+**root**
+: The root directory for containerd metadata. (Default: "/var/lib/containerd")
+
+**state**
+: The state directory for containerd (Default: "/run/containerd")
+
+**oom_score**
+: The out of memory (OOM) score applied to the containerd daemon process (Default: 0)
+
+**[grpc]**
+: Section for gRPC socket listener settings. Contains three properties:
+ - **address** (Default: "/run/containerd/containerd.sock")
+ - **uid** (Default: 0)
+ - **gid** (Default: 0)
+
+**[debug]**
+: Section to enable and configure a debug socket listener. Contains four properties:
+ - **address** (Default: "/run/containerd/debug.sock")
+ - **uid** (Default: 0)
+ - **gid** (Default: 0)
+ - **level** (Default: "info") sets the debug log level
+
+**[metrics]**
+: Section to enable and configure a metrics listener. Contains two properties:
+ - **address** (Default: "") Metrics endpoint does not listen by default
+ - **grpc_histogram** (Default: false) Turn on or off gRPC histogram metrics
+
+**[cgroup]**
+: Section for Linux cgroup specific settings
+ - **path** (Default: "") Specify a custom cgroup path for created containers
+
+**[plugins]**
+: The plugins section contains configuration options exposed from installed plugins.
+The following plugins are enabled by default and their settings are shown below.
+Plugins that are not enabled by default will provide their own configuration values
+documentation.
+ - **[plugins.cgroup]** has one option __no_prometheus__ (Default: **false**)
+ - **[plugins.diff]** has one option __default__, a list by default set to **["walking"]**
+ - **[plugins.linux]** has several options for configuring the runtime, shim, and related options:
+   **shim** specifies the shim binary (Default: **"containerd-shim"**),
+   **runtime** is the OCI compliant runtime binary (Default: **"runc"**),
+   **runtime_root** is the root directory used by the runtime (Default: **""**),
+   **no_shim** specifies whether to use a shim or not (Default: **false**),
+   **shim_debug** turns on debugging for the shim (Default: **false**)
+ - **[plugins.scheduler]** has several options that perform advanced tuning for the scheduler:
+   **pause_threshold** is the maximum amount of time GC should be scheduled (Default: **0.02**),
+   **deletion_threshold** guarantees GC is scheduled after n number of deletions (Default: **0** [not triggered]),
+   **mutation_threshold** guarantees GC is scheduled after n number of database mutations (Default: **100**),
+   **schedule_delay** defines the delay after trigger event before scheduling a GC (Default **"0ms"** [immediate]),
+   **startup_delay** defines the delay after startup before scheduling a GC (Default **"100ms"**)
+
+## EXAMPLE
+
+The following is a complete **config.toml** default configuration example:
+
+```
+root = "/var/lib/containerd"
+state = "/run/containerd"
+oom_score = 0
+
+[grpc]
+  address = "/run/containerd/containerd.sock"
+  uid = 0
+  gid = 0
+
+[debug]
+  address = "/run/containerd/debug.sock"
+  uid = 0
+  gid = 0
+  level = "info"
+
+[metrics]
+  address = ""
+  grpc_histogram = false
+
+[cgroup]
+  path = ""
+
+[plugins]
+  [plugins.cgroups]
+    no_prometheus = false
+  [plugins.diff]
+    default = ["walking"]
+  [plugins.linux]
+    shim = "containerd-shim"
+    runtime = "runc"
+    runtime_root = ""
+    no_shim = false
+    shim_debug = false
+  [plugins.scheduler]
+    pause_threshold = 0.02
+    deletion_threshold = 0
+    mutation_threshold = 100
+    schedule_delay = 0
+    startup_delay = 100000000
+```
+
+## BUGS
+
+Please file any specific issues that you encounter at
+https://github.com/containerd/containerd.
+
+## AUTHOR
+
+Phil Estes <estesp@gmail.com>
+
+## SEE ALSO
+
+ctr(1), containerd-config(1), containerd(1)

docs/man/containerd-config.1.md

@@ -0,0 +1,37 @@
+# containerd-config 1 01/30/2018
+
+## SYNOPSIS
+
+containerd config [command]
+
+## DESCRIPTION
+
+The *containerd config* command has one subcommand, named *default*, which
+will display on standard output the default containerd config for this version
+of the containerd daemon.
+
+This output can be piped to a __config.toml(5)__ file and placed in
+**/etc/containerd** to be used as the configuration for containerd on daemon
+startup. The configuration can be placed in any filesystem location and used
+with the **--config** option to the containerd daemon as well.
+
+See __config.toml(5)__ for more information on the containerd configuration
+options.
+
+## OPTIONS
+
+**default**
+: This subcommand will output the TOML formatted containerd configuration to standard output
+
+## BUGS
+
+Please file any specific issues that you encounter at
+https://github.com/containerd/containerd.
+
+## AUTHOR
+
+Phil Estes <estesp@gmail.com>
+
+## SEE ALSO
+
+ctr(1), config.toml(5), containerd(1)

docs/man/containerd.1.md

@@ -0,0 +1,56 @@
+# containerd 1 01/29/2018
+
+## SYNOPSIS
+
+containerd [global options] command [command options] [arguments...]
+
+## DESCRIPTION
+
+**containerd** is a high performance container runtime whose daemon can be started
+by using this command. If none of the *config*, *publish*, or *help* commands
+are specified the default action of the **containerd** command is to start the
+containerd daemon in the foreground.
+
+A default configuration is used if no TOML configuration is specified or located
+at the default file location. The *containerd config* command can be used to
+generate the default configuration for containerd. The output of that command
+can be used and modified as necessary as a custom configuration.
+
+The *publish* command is used internally by parts of the containerd runtime
+to publish events. It is not meant to be used as a standalone utility.
+
+## OPTIONS
+
+**--config value, -c value**
+: Specify the default path to the configuration file (default: "/etc/containerd/config.toml")
+
+**--log-level value, -l value**
+: Set the logging level. Available levels are: [debug, info, warn, error, fatal, panic]
+
+**--address value, -a value**
+: UNIX socket address for containerd's GRPC server to listen on (default: "/run/containerd/containerd.sock")
+
+**--root value**
+: The containerd root directory (default: "/var/lib/containerd"). A persistent directory location where metadata and image content are stored
+
+**--state value**
+: The containerd state directory (default: "/run/containerd"). A transient state directory used during containerd operation
+
+**--help, -h**
+: Show containerd command help text
+
+**--version, -v**
+: Print the containerd server version
+
+## BUGS
+
+Please file any specific issues that you encounter at
+https://github.com/containerd/containerd.
+
+## AUTHOR
+
+Phil Estes <estesp@gmail.com>
+
+## SEE ALSO
+
+ctr(1), config.toml(5), containerd-config(1)

docs/man/ctr.1.md

@@ -0,0 +1,94 @@
+# ctr 1 01/30/2018
+
+## SYNOPSIS
+
+**ctr [global options] command [command options] [arguments...]**
+
+## DESCRIPTION
+
+**ctr** is an unsupported debug and administrative client for interacting
+with the containerd daemon. Because it is unsupported, the commands,
+options, and operation are not guaranteed to be backward compatible or
+stable from release to release of the containerd project.
+
+## OPTIONS
+
+The following commands are available in the **ctr** utility:
+
+**plugins,plugin**
+: Provides information about containerd plugins
+
+**version**
+: Prints the client and server versions
+
+**containers,c,container**
+: Manages and interacts with containers
+
+**content**
+: Manages and interacts with content
+
+**events,event**
+: Displays containerd events
+
+**images,image**
+: Manages and interacts with images
+
+**namespaces,namespace**
+: Manages and interacts with containerd namespaces
+
+**pprof**
+: Provides golang pprof outputs for containerd
+
+**run**
+: Runs a container
+
+**snapshots,snapshot**
+: Manages and interacts with snapshots
+
+**tasks,t,task**
+: Manages and interacts with tasks
+
+**shim**
+: Interacts with a containerd shim directly
+
+**help,h**
+: Displays a list of commands or help for one specific command
+
+The following global options apply to all **ctr** commands:
+
+**--debug**
+: Enable debug output in logs
+
+**--address value, -a value**
+: Address for containerd's GRPC server (default: */run/containerd/containerd.sock*)
+
+**--timeout value**
+: Total timeout for ctr commands (default: *0s*)
+
+**--connect-timeout value**
+: Timeout for connecting to containerd (default: *0s*)
+
+**--namespace value, -n value**
+: Namespace to use with commands (default: *default*) [also read from *$CONTAINERD_NAMESPACE*]
+
+**--help, -h**
+: Show help text
+
+**--version, -v**
+: Prints the **ctr** version
+
+## BUGS
+
+Note that the **ctr** utility is not an officially supported part of the
+containerd project releases.
+
+However, please feel free to file any specific issues that you encounter at
+https://github.com/containerd/containerd.
+
+## AUTHOR
+
+Phil Estes <estesp@gmail.com>
+
+## SEE ALSO
+
+containerd(1), config.toml(5), containerd-config(1)

script/setup/install-dev-tools

@@ -8,3 +8,4 @@ go get -u github.com/stevvooe/protobuild
 go get -u github.com/alecthomas/gometalinter
 gometalinter --install >/dev/null
 go get -u github.com/LK4D4/vndr
+go get -u github.com/cpuguy83/go-md2man