Update documentation for container struct in libcontainer

Docker-DCO-1.1-Signed-off-by: Michael Crosby <michael@crosbymichael.com> (github: crosbymichael)

pkg/libcontainer/container.go

@@ -4,27 +4,70 @@ import (
 	"github.com/dotcloud/docker/pkg/libcontainer/cgroups"
 )
 
-// Context is a generic key value pair that allows
-// arbatrary data to be sent
+// Context is a generic key value pair that allows arbatrary data to be sent
 type Context map[string]string
 
-// Container defines configuration options for how a
-// container is setup inside a directory and how a process should be executed
+// Container defines configuration options for executing a process inside a contained environment
 type Container struct {
-	Hostname     string              `json:"hostname,omitempty"`      // hostname
-	ReadonlyFs   bool                `json:"readonly_fs,omitempty"`   // set the containers rootfs as readonly
-	NoPivotRoot  bool                `json:"no_pivot_root,omitempty"` // this can be enabled if you are running in ramdisk
-	User         string              `json:"user,omitempty"`          // user to execute the process as
-	WorkingDir   string              `json:"working_dir,omitempty"`   // current working directory
-	Env          []string            `json:"environment,omitempty"`   // environment to set
-	Tty          bool                `json:"tty,omitempty"`           // setup a proper tty or not
-	Namespaces   map[string]bool     `json:"namespaces,omitempty"`    // namespaces to apply
-	Capabilities []string            `json:"capabilities,omitempty"`  // capabilities given to the container
-	Networks     []*Network          `json:"networks,omitempty"`      // nil for host's network stack
-	Cgroups      *cgroups.Cgroup     `json:"cgroups,omitempty"`       // cgroups
-	Context      Context             `json:"context,omitempty"`       // generic context for specific options (apparmor, selinux)
-	Mounts       Mounts              `json:"mounts,omitempty"`
-	DeviceNodes  map[string][]string `json:"device_nodes,omitempty"` // device nodes to add to the container's /dev
+	// Hostname optionally sets the container's hostname if provided
+	Hostname string `json:"hostname,omitempty"`
+
+	// ReadonlyFs will remount the container's rootfs as readonly where only externally mounted
+	// bind mounts are writtable
+	ReadonlyFs bool `json:"readonly_fs,omitempty"`
+
+	// NoPivotRoot will use MS_MOVE and a chroot to jail the process into the container's rootfs
+	// This is a common option when the container is running in ramdisk
+	NoPivotRoot bool `json:"no_pivot_root,omitempty"`
+
+	// User will set the uid and gid of the executing process running inside the container
+	User string `json:"user,omitempty"`
+
+	// WorkingDir will change the processes current working directory inside the container's rootfs
+	WorkingDir string `json:"working_dir,omitempty"`
+
+	// Env will populate the processes environment with the provided values
+	// Any values from the parent processes will be cleared before the values
+	// provided in Env are provided to the process
+	Env []string `json:"environment,omitempty"`
+
+	// Tty when true will allocate a pty slave on the host for access by the container's process
+	// and ensure that it is mounted inside the container's rootfs
+	Tty bool `json:"tty,omitempty"`
+
+	// Namespaces specifies the container's namespaces that it should setup when cloning the init process
+	// If a namespace is not provided that namespace is shared from the container's parent process
+	Namespaces map[string]bool `json:"namespaces,omitempty"`
+
+	// Capabilities specify the capabilities to keep when executing the process inside the container
+	// All capbilities not specified will be dropped from the processes capability mask
+	Capabilities []string `json:"capabilities,omitempty"`
+
+	// Networks specifies the container's network stop to be created
+	Networks []*Network `json:"networks,omitempty"`
+
+	// Cgroups specifies specific cgroup settings for the various subsystems that the container is
+	// placed into to limit the resources the container has available
+	Cgroups *cgroups.Cgroup `json:"cgroups,omitempty"`
+
+	// Context is a generic key value format that allows for additional settings to be passed
+	// on the container's creation
+	// This is commonly used to specify apparmor profiles, selinux labels, and different restrictions
+	// placed on the container's processes
+	Context Context `json:"context,omitempty"`
+
+	// Mounts specify additional source and destination paths that will be mounted inside the container's
+	// rootfs and mount namespace if specified
+	Mounts Mounts `json:"mounts,omitempty"`
+
+	// DeviceNodes are a list of 'required' and 'additional' nodes that will be mknod into the container's
+	// rootfs at /dev
+	//
+	// Required device nodes will return an error if the host system does not have this device available
+	//
+	// Additional device nodes are created but no error is returned if the host system does not have the
+	// device avaliable for use by the container
+	DeviceNodes map[string][]string `json:"device_nodes,omitempty"`
 }
 
 // Network defines configuration for a container's networking stack
@@ -32,9 +75,20 @@ type Container struct {
 // The network configuration can be omited from a container causing the
 // container to be setup with the host's networking stack
 type Network struct {
-	Type    string  `json:"type,omitempty"`    // type of networking to setup i.e. veth, macvlan, etc
-	Context Context `json:"context,omitempty"` // generic context for type specific networking options
-	Address string  `json:"address,omitempty"`
-	Gateway string  `json:"gateway,omitempty"`
-	Mtu     int     `json:"mtu,omitempty"`
+	// Type sets the networks type, commonly veth and loopback
+	Type string `json:"type,omitempty"`
+
+	// Context is a generic key value format for setting additional options that are specific to
+	// the network type
+	Context Context `json:"context,omitempty"`
+
+	// Address contains the IP and mask to set on the network interface
+	Address string `json:"address,omitempty"`
+
+	// Gateway sets the gateway address that is used as the default for the interface
+	Gateway string `json:"gateway,omitempty"`
+
+	// Mtu sets the mtu value for the interface and will be mirrored on both the host and
+	// container's interfaces if a pair is created, specifically in the case of type veth
+	Mtu int `json:"mtu,omitempty"`
 }