Merge pull request #661 from mikebrow/spec-help

adds detail to runc start and spec help text

man/runc-spec.8.md

@@ -5,7 +5,40 @@
    runc spec [command options] [arguments...]
 
 # DESCRIPTION
-   The spec command creates the new specification file named "config.json" for the bundle." 
+   The spec command creates the new specification file named "config.json" for
+the bundle.
+
+The spec generated is just a starter file. Editing of the spec is required to
+achieve desired results. For example, the newly generated spec includes an args
+parameter that is initially set to call the "sh" command when the container is
+started. Calling "sh" may work for an ubuntu container or busybox, but will not
+work for containers that do not include the "sh" program.
+
+EXAMPLE:
+  To run docker's hello-world container one needs to set the args parameter
+in the spec to call hello. This can be done using the sed command or a text
+editor. The following commands create a bundle for hello-world, change the
+default args parameter in the spec from "sh" to "/hello", then run the hello
+command in a new hello-world container named container1:
+
+    mkdir hello
+    cd hello
+    docker pull hello-world
+    docker export $(docker create hello-world) > hello-world.tar
+    mkdir rootfs
+    tar -C rootfs -xf hello-world.tar
+    runc spec
+    sed -i 's;"sh";"/hello";' config.json
+    runc start container1
+
+In the start command above, "container1" is the name for the instance of the
+container that you are starting. The name you provide for the container instance
+must be unique on your host.
+
+When starting a container through runc, runc needs root privilege. If not
+already running as root, you can use sudo to give runc root privilege. For
+example: "sudo runc start container1" will give runc root privilege to start the
+container on your host.
 
 # OPTIONS
    --bundle, -b         path to the root of the bundle directory

man/runc-start.8.md

@@ -10,7 +10,13 @@ your host.
 
 # DESCRIPTION
    The start command creates an instance of a container for a bundle. The bundle
-is a directory with a specification file and a root filesystem.
+is a directory with a specification file named "config.json" and a root
+filesystem.
+
+The specification file includes an args parameter. The args parameter is used
+to specify command(s) that get run when the container is started. To change the
+command(s) that get executed on start, edit the args parameter of the spec. See
+"runc spec --help" for more explanation.
 
 # OPTIONS
    --bundle, -b         path to the root of the bundle directory, defaults to the current directory

spec.go

@@ -25,7 +25,40 @@ var specCommand = cli.Command{
 	Name:      "spec",
 	Usage:     "create a new specification file",
 	ArgsUsage: "",
-	Description: `The spec command creates the new specification file named "` + specConfig + `" for the bundle." `,
+	Description: `The spec command creates the new specification file named "` + specConfig + `" for
+the bundle.
+
+The spec generated is just a starter file. Editing of the spec is required to
+achieve desired results. For example, the newly generated spec includes an args
+parameter that is initially set to call the "sh" command when the container is
+started. Calling "sh" may work for an ubuntu container or busybox, but will not
+work for containers that do not include the "sh" program.
+
+EXAMPLE:
+  To run docker's hello-world container one needs to set the args parameter
+in the spec to call hello. This can be done using the sed command or a text
+editor. The following commands create a bundle for hello-world, change the
+default args parameter in the spec from "sh" to "/hello", then run the hello
+command in a new hello-world container named container1:
+
+    mkdir hello
+    cd hello
+    docker pull hello-world
+    docker export $(docker create hello-world) > hello-world.tar
+    mkdir rootfs
+    tar -C rootfs -xf hello-world.tar
+    runc spec
+    sed -i 's;"sh";"/hello";' ` + specConfig + `
+    runc start container1
+
+In the start command above, "container1" is the name for the instance of the
+container that you are starting. The name you provide for the container instance
+must be unique on your host.
+
+When starting a container through runc, runc needs root privilege. If not
+already running as root, you can use sudo to give runc root privilege. For
+example: "sudo runc start container1" will give runc root privilege to start the
+container on your host.`,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  "bundle, b",

start.go

@@ -22,7 +22,13 @@ Where "<container-id>" is your name for the instance of the container that you
 are starting. The name you provide for the container instance must be unique on
 your host.`,
 	Description: `The start command creates an instance of a container for a bundle. The bundle
-is a directory with a specification file and a root filesystem.`,
+is a directory with a specification file named "` + specConfig + `" and a root
+filesystem.
+
+The specification file includes an args parameter. The args parameter is used
+to specify command(s) that get run when the container is started. To change the
+command(s) that get executed on start, edit the args parameter of the spec. See
+"runc spec --help" for more explanation.`,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  "bundle, b",