rename a existing container

Closes #3036

Signed-off-by: Srini Brahmaroutu <srbrahma@us.ibm.com>
Upstream-commit: 21a809d9ae0ef8392f37c9262dca93ff31966e22
Component: engine

components/engine/docs/sources/reference/api/docker_remote_api_v1.15.md

@@ -647,6 +647,27 @@ Status Codes:
 -   **404** – no such container
 -   **500** – server error
 
+### Rename a container
+
+`POST /containers/(id)/rename/(new_name)`
+
+Rename the container `id` to a `new_name`
+
+**Example request**:
+
+        POST /containers/e90e34656806/rename/new_name HTTP/1.1
+
+**Example response**:
+
+        HTTP/1.1 204 No Content
+
+Status Codes:
+
+-   **204** – no error
+-   **404** – no such container
+-   **409** - conflict name already assigned
+-   **500** – server error
+
 ### Pause a container
 
 `POST /containers/(id)/pause`

components/engine/docs/sources/reference/commandline/cli.md

@@ -1366,6 +1366,30 @@ just a specific mapping:
     $ sudo docker port test 7890
     0.0.0.0:4321
 
+## pause
+
+    Usage: docker pause CONTAINER
+
+    Pause all processes within a container
+
+The `docker pause` command uses the cgroups freezer to suspend all processes in
+a container.  Traditionally when suspending a process the `SIGSTOP` signal is
+used, which is observable by the process being suspended. With the cgroups freezer
+the process is unaware, and unable to capture, that it is being suspended,
+and subsequently resumed.
+
+See the
+[cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroups/freezer-subsystem.txt)
+for further details.
+
+## rename
+
+    Usage: docker rename OLD_NAME NEW_NAME
+
+    rename a existing container to a NEW_NAME
+
+The `docker rename` command allows the container to be renamed to a different name.  
+
 ## ps
 
     Usage: docker ps [OPTIONS]