@@ -143,6 +143,18 @@ A Dockerfile is similar to a Makefile.

   **CMD** executes nothing at build time, but specifies the intended command for

   the image.

+**LABEL**

+ --**LABEL <key>[=<value>] [<key>[=<value>] ...]**

+

+ The **LABEL** instruction allows you to add meta-data to the image your 

+ Dockerfile is building. LABEL is specified as name value pairs. This data can

+ be retrieved using the `docker inspect` command.

+

+ The LABEL instruction allows for multiple labels to be set at one time. Like 

+ command line parsing, quotes and backslashes can be used to include spaces 

+ within values.

+

+

 **EXPOSE**

   -- `EXPOSE <port> [<port>...]`

   The **EXPOSE** instruction informs Docker that the container listens on the

@@ -24,6 +24,8 @@ docker-create - Create a new container

 [**--help**]

 [**-i**|**--interactive**[=*false*]]

 [**--ipc**[=*IPC*]]

+[**-l**|**--label**[=*[]*]]

+[**--label-file**[=*[]*]]

 [**--link**[=*[]*]]

 [**--lxc-conf**[=*[]*]]

 [**-m**|**--memory**[=*MEMORY*]]

@@ -102,6 +104,12 @@ IMAGE [COMMAND] [ARG...]

                                'container:<name|id>': reuses another container shared memory, semaphores and message queues

                                'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.

+**-l**, **--label**=[]

+   Set meta data on the container (e.g., --label=com.example.key=value)

+

+**--label-file**=[]

+   Read in a line delimited file of labels

+

 **--link**=[]

    Add link to another container in the form of <name or id>:alias

@@ -34,7 +34,9 @@ versions.

    Show all images (by default filter out the intermediate image layers). The default is *false*.

 **-f**, **--filter**=[]

-   Provide filter values (i.e., 'dangling=true')

+   Provide filter values. Valid filters:

+                          dangling=true - unlabeled images with no children

+                          label=<key> or label=<key>=<value>

 **--help**

   Print usage statement

@@ -83,6 +83,11 @@ To get information on a container use it's ID or instance name:

             "Ghost": false

         },

         "Image": "df53773a4390e25936f9fd3739e0c0e60a62d024ea7b669282b27e65ae8458e6",

+        "Labels": {

+            "com.example.vendor": "Acme",

+            "com.example.license": "GPL",

+            "com.example.version": "1.0"

+        },

         "NetworkSettings": {

             "IPAddress": "172.17.0.2",

             "IPPrefixLen": 16,

@@ -36,6 +36,7 @@ the running containers.

 **-f**, **--filter**=[]

    Provide filter values. Valid filters:

                           exited=<int> - containers with exit code of <int>

+                          label=<key> or label=<key>=<value>

                           status=(restarting|running|paused|exited)

                           name=<string> - container's name

                           id=<ID> - container's ID

@@ -25,6 +25,8 @@ docker-run - Run a command in a new container

 [**--help**]

 [**-i**|**--interactive**[=*false*]]

 [**--ipc**[=*IPC*]]

+[**-l**|**--label**[=*[]*]]

+[**--label-file**[=*[]*]]

 [**--link**[=*[]*]]

 [**--lxc-conf**[=*[]*]]

 [**-m**|**--memory**[=*MEMORY*]]

@@ -197,6 +199,12 @@ ENTRYPOINT.

                                'container:<name|id>': reuses another container shared memory, semaphores and message queues

                                'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.

+**-l**, **--label**=[]

+   Set meta data on the container (e.g., --label=com.example.key=value)

+

+**--label-file**=[]

+   Read in a line delimited file of labels

+

 **--link**=[]

    Add link to another container in the form of <name or id>:alias

@@ -59,6 +59,7 @@ pages:

 - ['userguide/dockerimages.md', 'User Guide', 'Working with Docker Images' ]

 - ['userguide/dockerlinks.md', 'User Guide', 'Linking containers together' ]

 - ['userguide/dockervolumes.md', 'User Guide', 'Managing data in containers' ]

+- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom meta-data in Docker' ]

 - ['userguide/dockerrepos.md', 'User Guide', 'Working with Docker Hub' ]

 - ['userguide/level1.md', '**HIDDEN**' ]

 - ['userguide/level2.md', '**HIDDEN**' ]

@@ -75,7 +75,7 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.

 Build now has support for `LABEL` command which can be used to add user data

 to an image.  For example you could add data describing the content of an image.

-`LABEL "Vendor"="ACME Incorporated"`

+`LABEL "com.example.vendor"="ACME Incorporated"`

 **New!**

 `POST /containers/(id)/attach` and `POST /exec/(id)/start`

@@ -130,9 +130,9 @@ Create a container

              "Entrypoint": "",

              "Image": "ubuntu",

              "Labels": {

-                     "Vendor": "Acme",

-                     "License": "GPL",

-                     "Version": "1.0"

+                     "com.example.vendor": "Acme",

+                     "com.example.license": "GPL",

+                     "com.example.version": "1.0"

              },

              "Volumes": {

                      "/tmp": {}

@@ -194,7 +194,8 @@ Json Parameters:

 -   **OpenStdin** - Boolean value, opens stdin,

 -   **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects.

 -   **Env** - A list of environment variables in the form of `VAR=value`

--   **Labels** - A list of labels that will applied in the form of `VAR=value`

+-   **Labels** - A map of labels and their values that will be added to the 

+        container. It should be specified in the form `{"name":"value"[,"name2":"value2"]}`

 -   **Cmd** - Command to run specified as a string or an array of strings.

 -   **Entrypoint** - Set the entrypoint for the container a a string or an array

       of strings

@@ -304,11 +305,11 @@ Return low-level information on the container `id`

 			"ExposedPorts": null,

 			"Hostname": "ba033ac44011",

 			"Image": "ubuntu",

-                        "Labels": {

-                                "Vendor": "Acme",

-                                "License": "GPL",

-                                "Version": "1.0"

-                        },

+			"Labels": {

+				"com.example.vendor": "Acme",

+				"com.example.license": "GPL",

+				"com.example.version": "1.0"

+			},

 			"MacAddress": "",

 			"Memory": 0,

 			"MemorySwap": 0,

@@ -1181,9 +1182,9 @@ Return low-level information on the image `name`

                              "Dns": null,

                              "Image": "ubuntu",

                              "Labels": {

-                                    "Vendor": "Acme",

-                                    "License": "GPL",

-                                    "Version": "1.0"

+                                 "com.example.vendor": "Acme",

+                                 "com.example.license": "GPL",

+                                 "com.example.version": "1.0"

                              },

                              "Volumes": null,

                              "VolumesFrom": "",

@@ -331,13 +331,23 @@ default specified in `CMD`.

 ## LABEL

    LABEL <key>=<value> <key>=<value> <key>=<value> ...

- --The `LABEL` instruction allows you to describe the image your `Dockerfile`

-is building. `LABEL` is specified as name value pairs. This data can

+The `LABEL` instruction allows you to add meta-data to the image your 

+`Dockerfile` is building. `LABEL` is specified as name value pairs. This data can

 be retrieved using the `docker inspect` command

+    LABEL com.example.label-without-value

+    LABEL com.example.label-with-value="foo"

+    LABEL version="1.0"

+    LABEL description="This my ACME image" vendor="ACME Products"

-    LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products"

-    LABEL Version="1.0"

+As illustrated above, the `LABEL` instruction allows for multiple labels to be

+set at one time. Like command line parsing, quotes and backslashes can be used

+to include spaces within values.

+

+For example:

+

+    LABEL description="This text illustrates \

+    that label-values can span multiple lines."

 ## EXPOSE

@@ -791,6 +791,8 @@ Creates a new container.

       -h, --hostname=""          Container host name

       -i, --interactive=false    Keep STDIN open even if not attached

       --ipc=""                   IPC namespace to use

+      -l, --label=[]             Set meta data on the container (e.g., --label=com.example.key=value)

+      --label-file=[]            Read in a line delimited file of labels

       --link=[]                  Add link to another container

       --lxc-conf=[]              Add custom lxc options

       -m, --memory=""            Memory limit

@@ -1143,6 +1145,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b

 Current filters:

  * dangling (boolean - true or false)

+ * label (`label=<key>` or `label=<key>=<value>`)

 ##### Untagged images

@@ -1662,8 +1665,8 @@ removed before the image is removed.

       --link=[]                  Add link to another container

       --lxc-conf=[]              Add custom lxc options

       -m, --memory=""            Memory limit

-      -l, --label=[]             Set meta data on a container, for example com.example.key=value

-      -label-file=[]             Read in a line delimited file of labels

+      -l, --label=[]             Set meta data on the container (e.g., --label=com.example.key=value)

+      --label-file=[]            Read in a line delimited file of labels

       --mac-address=""           Container MAC address (e.g. 92:d0:c6:0a:29:33)

       --memory-swap=""           Total memory (memory + swap), '-1' to disable swap

       --name=""                  Assign a name to the container

@@ -1837,6 +1840,36 @@ An example of a file passed with `--env-file`

 This will create and run a new container with the container name being

 `console`.

+    $ sudo docker run -l my-label --env com.example.foo=bar ubuntu bash

+

+This sets two labels on the container. Label "my-label" doesn't have a value

+specified and will default to "" (empty string) for its value. Both `-l` and 

+`--env` can be repeated to add more labels. Label names are unique; if the same 

+label is specified multiple times, latter values overwrite the previous value.

+

+Labels can also be loaded from a line delimited file of labels using the 

+`--label-file` flag. The example below will load labels from a file named `labels`

+in the current directory;

+

+    $ sudo docker run --env-file ./labels ubuntu bash

+

+The format of the labels-file is similar to that used for loading environment

+variables (see `--env-file` above). An example of a file passed with `--env-file`;

+

+    $ cat ./labels

+    com.example.label1="a label"

+

+    # this is a comment

+    com.example.label2=another\ label

+    com.example.label3

+

+Multiple label-files can be loaded by providing the `--label-file` multiple 

+times.

+

+For additional information on working with labels, see 

+[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in

+the user guide.

+

     $ sudo docker run --link /redis:redis --name console ubuntu bash

 The `--link` flag will link the container named `/redis` into the newly

new file mode 100644

@@ -0,0 +1,194 @@

+page_title: Labels - custom meta-data in Docker

+page_description: Learn how to work with custom meta-data in Docker, using labels.

+page_keywords: Usage, user guide, labels, meta-data, docker, documentation, examples, annotating

+

+## Labels - custom meta-data in Docker

+

+Docker enables you to add meta-data to your images, containers, and daemons via

+labels. Meta-data can serve a wide range of uses ranging from adding notes or 

+licensing information to an image to identifying a host.

+

+Labels in Docker are implemented as `<key>` / `<value>` pairs and values are

+stored as *strings*.

+

+>**note:** Support for daemon-labels was added in docker 1.4.1, labels on

+>containers and images in docker 1.6.0

+

+### Naming your labels - namespaces

+

+Docker puts no hard restrictions on the names you pick for your labels, however,

+it's easy for labels to "conflict".

+

+For example, you're building a tool that categorizes your images in 

+architectures, doing so by using an "architecture" label;

+

+    LABEL architecture="amd64"

+

+    LABEL architecture="ARMv7"

+

+But a user decided to label images by Architectural style

+

+    LABEL architecture="Art Nouveau"

+

+To prevent such conflicts, Docker uses the convention to namespace label-names,

+using a reverse domain notation;

+

+

+- All (third-party) tools should namespace (prefix) their labels with the 

+  reverse DNS notation of a domain controlled by the author of the tool. For 

+  example, "com.example.some-label".

+- Namespaced labels should only consist of lower-cased alphanumeric characters,

+  dots and dashes (in short, `[a-z0-9-.]`), should start *and* end with an alpha

+  numeric character, and may not contain consecutive dots or dashes.

+- The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are

+  reserved for Docker's internal use.

+- Labels *without* namespace (dots) are reserved for CLI use. This allows end-

+  users to add meta-data to their containers and images, without having to type 

+  cumbersome namespaces on the command-line.

+

+

+> **Note:** Even though Docker does not *enforce* you to use namespaces,

+> preventing to do so will likely result in conflicting usage of labels. 

+> If you're building a tool that uses labels, you *should* use namespaces

+> for your labels.

+

+

+### Storing structured data in labels

+

+Labels can store any type of data, as long as its stored as a string. 

+

+

+    {

+        "Description": "A containerized foobar",

+        "Usage": "docker run --rm example/foobar [args]",

+        "License": "GPL",

+        "Version": "0.0.1-beta",

+        "aBoolean": true,

+        "aNumber" : 0.01234,

+        "aNestedArray": ["a", "b", "c"]

+    }

+

+Which can be stored in a label by serializing it to a string first;

+

+    LABEL com.example.image-specs="{\"Description\":\"A containerized foobar\",\"Usage\":\"docker run --rm example\\/foobar [args]\",\"License\":\"GPL\",\"Version\":\"0.0.1-beta\",\"aBoolean\":true,\"aNumber\":0.01234,\"aNestedArray\":[\"a\",\"b\",\"c\"]}"

+

+

+> **Note:** Although the example above shows it's *possible* to store structured 

+> data in labels, Docker does not treat this data any other way than a 'regular'

+> string. This means that Docker doesn't offer ways to query (filter) based on 

+> nested properties. If your tool needs to filter on nested properties, the 

+> tool itself should implement this.

+

+

+### Adding labels to images; the `LABEL` instruction

+

+Adding labels to your 

+

+

+    LABEL [<namespace>.]<name>[=<value>] ...

+

+The `LABEL` instruction adds a label to your image, optionally setting its value.

+Quotes surrounding name and value are optional, but required if they contain

+white space characters. Alternatively, backslashes can be used.

+

+Label values only support strings

+

+

+    LABEL vendor=ACME\ Incorporated

+    LABEL com.example.version.is-beta

+    LABEL com.example.version="0.0.1-beta"

+    LABEL com.example.release-date="2015-02-12"

+

+The `LABEL` instruction supports setting multiple labels in a single instruction

+using this notation;

+

+    LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"

+

+Wrapping is allowed by using a backslash (`\`) as continuation marker;

+

+    LABEL vendor=ACME\ Incorporated \

+          com.example.is-beta \

+          com.example.version="0.0.1-beta" \

+          com.example.release-date="2015-02-12"

+

+

+You can view the labels via `docker inspect`

+

+    $ docker inspect 4fa6e0f0c678

+

+    ...

+    "Labels": {

+        "vendor": "ACME Incorporated",

+        "com.example.is-beta": "",

+        "com.example.version": "0.0.1-beta",

+        "com.example.release-date": "2015-02-12"

+    }

+    ...

+

+    $ docker inspect -f "{{json .Labels }}" 4fa6e0f0c678

+

+    {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}

+

+> **note:** We recommend combining labels in a single `LABEl` instruction in

+> stead of using a `LABEL` instruction for each label. Each instruction in a

+> Dockerfile produces a new layer, which can result in an inefficient image if

+> many labels are used.

+

+### Querying labels

+

+Besides storing meta-data, labels can be used to filter your images and 

+containers.

+

+List all running containers that have a `com.example.is-beta` label;

+

+    # List all running containers that have a `com.example.is-beta` label

+    $ docker ps --filter "label=com.example.is-beta"

+

+

+List all running containers with a "color" label set to "blue";

+

+    $ docker ps --filter "label=color=blue"

+

+List all images with "vendor" "ACME"

+

+    $ docker images --filter "label=vendor=ACME"

+

+

+### Daemon labels

+

+

+

+    docker -d \

+      --dns 8.8.8.8 \

+      --dns 8.8.4.4 \

+      -H unix:///var/run/docker.sock \

+      --label com.example.environment="production" \

+      --label com.example.storage="ssd"

+

+And can be seen as part of the `docker info` output for the daemon;

+

+    docker -D info

+    Containers: 12

+    Images: 672

+    Storage Driver: aufs

+     Root Dir: /var/lib/docker/aufs

+     Backing Filesystem: extfs

+     Dirs: 697

+    Execution Driver: native-0.2

+    Kernel Version: 3.13.0-32-generic

+    Operating System: Ubuntu 14.04.1 LTS

+    CPUs: 1

+    Total Memory: 994.1 MiB

+    Name: docker.example.com

+    ID: RC3P:JTCT:32YS:XYSB:YUBG:VFED:AAJZ:W3YW:76XO:D7NN:TEVU:UCRW

+    Debug mode (server): false

+    Debug mode (client): true

+    Fds: 11

+    Goroutines: 14

+    EventsListeners: 0

+    Init Path: /usr/bin/docker

+    Docker Root Dir: /var/lib/docker

+    WARNING: No swap limit support

+    Labels:

+     com.example.environment=production

+     com.example.storage=ssd

@@ -76,7 +76,7 @@ func Parse(cmd *flag.FlagSet, args []string) (*Config, *HostConfig, *flag.FlagSe

 	cmd.Var(&flVolumes, []string{"v", "-volume"}, "Bind mount a volume")

 	cmd.Var(&flLinks, []string{"#link", "-link"}, "Add link to another container")

 	cmd.Var(&flDevices, []string{"-device"}, "Add a host device to the container")

-	cmd.Var(&flLabels, []string{"l", "-label"}, "Set meta data on a container, for example com.example.key=value")

+	cmd.Var(&flLabels, []string{"l", "-label"}, "Set meta data on a container")

 	cmd.Var(&flLabelsFile, []string{"-label-file"}, "Read in a line delimited file of labels")

 	cmd.Var(&flEnv, []string{"e", "-env"}, "Set environment variables")

 	cmd.Var(&flEnvFile, []string{"-env-file"}, "Read in a file of environment variables")