diff --git a/man/runc-spec.8.md b/man/runc-spec.8.md index 3a2e5da8..71db7c98 100644 --- a/man/runc-spec.8.md +++ b/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 diff --git a/man/runc-start.8.md b/man/runc-start.8.md index 07c42ffd..ef60f6ca 100644 --- a/man/runc-start.8.md +++ b/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 diff --git a/spec.go b/spec.go index 87bbff88..7dd975d8 100644 --- a/spec.go +++ b/spec.go @@ -22,10 +22,43 @@ import ( ) 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." `, + Name: "spec", + Usage: "create a new specification file", + ArgsUsage: "", + 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", diff --git a/start.go b/start.go index 65863e94..a3015ab8 100644 --- a/start.go +++ b/start.go @@ -22,7 +22,13 @@ Where "" 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",