docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #343 from joaofnfernandes/machine-reference 

Update code blocks in machine/reference
This commit is contained in:
Joao Fernandes 2016-10-25 14:01:27 -07:00 committed by GitHub
parent c343c03782 5ea225187a
commit 9482ecaa40
20 changed files with 513 additions and 405 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
machine/reference/active.md
View File

@ -13,11 +13,16 @@ title: active
See which machine is "active" (a machine is considered active if the
`DOCKER_HOST` environment variable points to it).
```none
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL
dev - virtualbox Running tcp://192.168.99.103:2376
staging * digitalocean Running tcp://203.0.113.81:2376
$ echo $DOCKER_HOST
tcp://203.0.113.81:2376
$ docker-machine active
staging
```

15
machine/reference/config.md
View File

@ -10,6 +10,7 @@ title: config
# config
```none
Usage: docker-machine config [OPTIONS] [arg...]
Print the connection config for machine
@ -20,13 +21,15 @@ title: config
Options:
--swarm Display the Swarm config instead of the Docker daemon
```
For example:
$ docker-machine config dev
--tlsverify
--tlscacert="/Users/ehazlett/.docker/machines/dev/ca.pem"
--tlscert="/Users/ehazlett/.docker/machines/dev/cert.pem"
--tlskey="/Users/ehazlett/.docker/machines/dev/key.pem"
```none
$ docker-machine config dev \
--tlsverify \
--tlscacert="/Users/ehazlett/.docker/machines/dev/ca.pem" \
--tlscert="/Users/ehazlett/.docker/machines/dev/cert.pem" \
--tlskey="/Users/ehazlett/.docker/machines/dev/key.pem" \
-H tcp://192.168.99.103:2376
```

14
machine/reference/create.md
View File

@ -15,6 +15,7 @@ Create a machine. Requires the `--driver` flag to indicate which provider
(VirtualBox, DigitalOcean, AWS, etc.) the machine should be created on, and an
argument to indicate the name of the created machine.
```none
$ docker-machine create --driver virtualbox dev
Creating CA: /home/username/.docker/machine/certs/ca.pem
Creating client certificate: /home/username/.docker/machine/certs/cert.pem
@ -26,6 +27,7 @@ argument to indicate the name of the created machine.
Starting VirtualBox VM...
Starting VM...
To see how to connect Docker to this machine, run: docker-machine env dev
```
## Accessing driver-specific flags in the help text
@ -34,6 +36,7 @@ drivers. These largely control aspects of Machine's provisoning process
(including the creation of Docker Swarm containers) that the user may wish to
customize.
```none
$ docker-machine create
Docker Machine Version: 0.5.0 (45e3688)
Usage: docker-machine create [OPTIONS] [arg...]
@ -61,6 +64,7 @@ customize.
--swarm-host "tcp://0.0.0.0:3376" ip/socket to listen on for Swarm master
--swarm-addr addr to advertise for Swarm (default: detect and use the machine IP)
--swarm-experimental Enable Swarm experimental features
```
Additionally, drivers can specify flags that Machine can accept as part of their
plugin code. These allow users to customize the provider-specific parameters of
@ -70,6 +74,7 @@ geographical region (`--amazonec2-region us-west-1`), and so on.
To see the provider-specific flags, simply pass a value for `--driver` when
invoking the `create` help text.
```none
$ docker-machine create --driver virtualbox --help
Usage: docker-machine create [OPTIONS] [arg...]
@ -107,6 +112,7 @@ invoking the `create` help text.
--virtualbox-import-boot2docker-vm The name of a Boot2Docker VM to import
--virtualbox-memory "1024" Size of memory for host in MB [$VIRTUALBOX_MEMORY_SIZE]
--virtualbox-no-share Disable the mount of your home directory
```
You may notice that some flags specify environment variables that they are
associated with as well (located to the far left hand side of the row). If
@ -137,12 +143,14 @@ filesystem has been created, and so on.
The following is an example usage:
```none
$ docker-machine create -d virtualbox \
--engine-label foo=bar \
--engine-label spam=eggs \
--engine-storage-driver overlay \
--engine-insecure-registry registry.myco.com \
foobarmachine
```
This will create a virtual machine running locally in Virtualbox which uses the
`overlay` storage backend, has the key-value pairs `foo=bar` and `spam=eggs` as
@ -150,6 +158,7 @@ labels on the engine, and allows pushing / pulling from the insecure registry
located at `registry.myco.com`. You can verify much of this by inspecting the
output of `docker info`:
```none
$ eval $(docker-machine env foobarmachine)
$ docker info
Containers: 0
@ -162,6 +171,7 @@ output of `docker info`:
foo=bar
spam=eggs
provider=virtualbox
```
The supported flags are as follows:
@ -181,10 +191,12 @@ for all containers, and always use the `syslog` [log
driver](/engine/reference/run.md#logging-drivers-log-driver) you
could run the following create command:
```none
$ docker-machine create -d virtualbox \
--engine-opt dns=8.8.8.8 \
--engine-opt log-driver=syslog \
gdns
```
Additionally, Docker Machine supports a flag, `--engine-env`, which can be used to
specify arbitrary environment variables to be set within the engine with the syntax `--engine-env name=value`. For example, to specify that the engine should use `example.com` as the proxy server, you could run the following create command:
@ -217,6 +229,7 @@ you won't have to worry about it.
Example create:
```none
$ docker-machine create -d virtualbox \
--swarm \
--swarm-master \
@ -224,6 +237,7 @@ Example create:
--swarm-strategy binpack \
--swarm-opt heartbeat=5 \
upbeat
```
This will set the swarm scheduling strategy to "binpack" (pack in containers as
tightly as possible per host instead of spreading them out), and the "heartbeat"

12
machine/reference/env.md
View File

@ -13,6 +13,7 @@ title: env
Set environment variables to dictate that `docker` should run a command against
a particular machine.
```none
$ docker-machine env --help
Usage: docker-machine env [OPTIONS] [arg...]
@ -28,11 +29,13 @@ a particular machine.
--shell Force environment to be configured for a specified shell: [fish, cmd, powershell, tcsh], default is sh/bash
--unset, -u Unset variables instead of setting them
--no-proxy Add machine IP to NO_PROXY environment variable
```
`docker-machine env machinename` will print out `export` commands which can be
run in a subshell. Running `docker-machine env -u` will print `unset` commands
which reverse this effect.
```none
$ env | grep DOCKER
$ eval "$(docker-machine env dev)"
$ env | grep DOCKER
@ -44,6 +47,7 @@ which reverse this effect.
$ eval "$(docker-machine env -u)"
$ env | grep DOCKER
$ # The environment variables have been unset.
```
The output described above is intended for the shells `bash` and `zsh` (if
you're not sure which shell you're using, there's a very good possibility that
@ -55,12 +59,14 @@ If you are using `fish` and the `SHELL` environment variable is correctly set to
the path where `fish` is located, `docker-machine env name` will print out the
values in the format which `fish` expects:
```none
set -x DOCKER_TLS_VERIFY 1;
set -x DOCKER_CERT_PATH "/Users/nathanleclaire/.docker/machine/machines/overlay";
set -x DOCKER_HOST tcp://192.168.99.102:2376;
set -x DOCKER_MACHINE_NAME overlay
# Run this command to configure your shell:
# eval "$(docker-machine env overlay)"
```
If you are on Windows and using either Powershell or `cmd.exe`, `docker-machine env`
Docker Machine should now detect your shell automatically. If the automagic detection does not work you
@ -68,6 +74,7 @@ If you are on Windows and using either Powershell or `cmd.exe`, `docker-machine
For Powershell:
```none
$ docker-machine.exe env --shell powershell dev
$Env:DOCKER_TLS_VERIFY = "1"
$Env:DOCKER_HOST = "tcp://192.168.99.101:2376"
@ -75,15 +82,18 @@ For Powershell:
$Env:DOCKER_MACHINE_NAME = "dev"
# Run this command to configure your shell:
# docker-machine.exe env --shell=powershell dev | Invoke-Expression
```
For `cmd.exe`:
```none
$ docker-machine.exe env --shell cmd dev
set DOCKER_TLS_VERIFY=1
set DOCKER_HOST=tcp://192.168.99.101:2376
set DOCKER_CERT_PATH=C:\Users\captain\.docker\machine\machines\dev
set DOCKER_MACHINE_NAME=dev
# Run this command to configure your shell: copy and paste the above values into your command prompt
```
## Excluding the created machine from proxies
@ -95,6 +105,7 @@ This is useful when using `docker-machine` with a local VM provider (e.g.
`virtualbox` or `vmwarefusion`) in network environments where a HTTP proxy is
required for internet access.
```none
$ docker-machine env --no-proxy default
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://192.168.99.104:2376"
@ -103,6 +114,7 @@ required for internet access.
export NO_PROXY="192.168.99.104"
# Run this command to configure your shell:
# eval "$(docker-machine env default)"
```
You may also want to visit the [documentation on setting `HTTP_PROXY` for the
created daemon using the `--engine-env` flag for `docker-machine

4
machine/reference/help.md
View File

@ -10,14 +10,17 @@ title: help
# help
```none
Usage: docker-machine help [arg...]
Shows a list of commands or help for one command
```
Usage: docker-machine help _subcommand_
For example:
```none
$ docker-machine help config
Usage: docker-machine config [OPTIONS] [arg...]
@ -29,3 +32,4 @@ For example:
Options:
--swarm Display the Swarm config instead of the Docker daemon
```

17
machine/reference/inspect.md
View File

@ -11,6 +11,7 @@ title: inspect
# inspect
```none
Usage: docker-machine inspect [OPTIONS] [arg...]
Inspect information about a machine
@ -20,6 +21,7 @@ title: inspect
Options:
--format, -f Format the output using the given go template.
```
By default, this will render information about a machine as JSON. If a format is
specified, the given template will be executed for each result.
@ -36,7 +38,9 @@ In addition to the `text/template` syntax, there are some additional functions,
This is the default usage of `inspect`.
```none
$ docker-machine inspect dev
{
"DriverName": "virtualbox",
"Driver": {
@ -49,31 +53,32 @@ This is the default usage of `inspect`.
},
...
}
```
**Get a machine's IP address:**
For the most part, you can pick out any field from the JSON in a fairly
straightforward manner.
{% raw %}
```none
$ docker-machine inspect --format='{{.Driver.IPAddress}}' dev
192.168.5.99
{% endraw %}
```
**Formatting details:**
If you want a subset of information formatted as JSON, you can use the `json`
function in the template.
{% raw %}
```none
$ docker-machine inspect --format='{{json .Driver}}' dev-fusion
{"Boot2DockerURL":"","CPUS":8,"CPUs":8,"CaCertPath":"/Users/hairyhenderson/.docker/machine/certs/ca.pem","DiskSize":20000,"IPAddress":"172.16.62.129","ISO":"/Users/hairyhenderson/.docker/machine/machines/dev-fusion/boot2docker-1.5.0-GH747.iso","MachineName":"dev-fusion","Memory":1024,"PrivateKeyPath":"/Users/hairyhenderson/.docker/machine/certs/ca-key.pem","SSHPort":22,"SSHUser":"docker","SwarmDiscovery":"","SwarmHost":"tcp://0.0.0.0:3376","SwarmMaster":false}
{% endraw %}
```
While this is usable, it's not very human-readable. For this reason, there is
`prettyjson`:
{% raw %}
```
$ docker-machine inspect --format='{{prettyjson .Driver}}' dev-fusion
{
"Boot2DockerURL": "",
@ -92,4 +97,4 @@ While this is usable, it's not very human-readable. For this reason, there is
"SwarmHost": "tcp://0.0.0.0:3376",
"SwarmMaster": false
}
{% endraw %}
```

3
machine/reference/ip.md
View File

@ -12,8 +12,11 @@ title: ip
Get the IP address of one or more machines.
```none
$ docker-machine ip dev
192.168.99.104
$ docker-machine ip dev dev2
192.168.99.104
192.168.99.105
```

4
machine/reference/kill.md
View File

@ -11,15 +11,18 @@ title: kill
# kill
```none
Usage: docker-machine kill [arg...]
Kill (abruptly force stop) a machine
Description:
Argument(s) are one or more machine names.
```
For example:
```none
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL
dev * virtualbox Running tcp://192.168.99.104:2376
@ -27,3 +30,4 @@ For example:
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL
dev * virtualbox Stopped
```

16
machine/reference/ls.md
View File

@ -10,6 +10,7 @@ title: ls
# ls
```none
Usage: docker-machine ls [OPTIONS] [arg...]
List machines
@ -20,6 +21,7 @@ title: ls
--filter [--filter option --filter option] Filter output based on conditions provided
--timeout, -t "10" Timeout in seconds, default to 10s
--format, -f Pretty-print machines using a Go template
```
## Timeout
@ -31,9 +33,11 @@ the -t flag for this purpose with a numerical value in seconds.
### Example
```none
$ docker-machine ls -t 12
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
default - virtualbox Running tcp://192.168.99.100:2376 v1.9.1
```
## Filtering
@ -50,6 +54,7 @@ The currently supported filters are:
### Examples
```none
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
dev - virtualbox Stopped
@ -69,6 +74,7 @@ The currently supported filters are:
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
foo1 - virtualbox Running tcp://192.168.99.105:2376 v1.9.1
foo2 * virtualbox Running tcp://192.168.99.107:2376 v1.9.1
```
## Formatting
@ -77,7 +83,7 @@ The formatting option (`--format`) will pretty-print machines using a Go templat
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
| -------------- | ---------------------------------------- |
|:---------------|:-----------------------------------------|
| .Name | Machine name |
| .Active | Is the machine active? |
| .ActiveHost | Is the machine an active non-swarm host? |
@ -96,17 +102,17 @@ when using the table directive, will include column headers as well.
The following example uses a template without headers and outputs the `Name` and `Driver` entries separated by a colon
for all running machines:
{% raw %}
```none
$ docker-machine ls --format "{{.Name}}: {{.DriverName}}"
default: virtualbox
ec2: amazonec2
{% endraw %}
```
To list all machine names with their driver in a table format you can use:
{% raw %}
```none
$ docker-machine ls --format "table {{.Name}} {{.DriverName}}"
NAME DRIVER
default virtualbox
ec2 amazonec2
{% endraw %}
```

3
machine/reference/provision.md
View File

@ -19,10 +19,13 @@ originally specified Swarm or Engine configuration).
Usage is `docker-machine provision [name]`. Multiple names may be specified.
```none
$ docker-machine provision foo bar
Copying certs to the local machine directory...
Copying certs to the remote machine...
Setting Docker configuration on the remote daemon...
```
The Machine provisioning process will:

5
machine/reference/regenerate-certs.md
View File

@ -10,6 +10,7 @@ title: regenerate-certs
# regenerate-certs
```none
Usage: docker-machine regenerate-certs [OPTIONS] [arg...]
Regenerate TLS Certificates for a machine
@ -20,11 +21,15 @@ title: regenerate-certs
Options:
--force, -f Force rebuild and do not prompt
```
Regenerate TLS certificates and update the machine with new certs.
For example:
```none
$ docker-machine regenerate-certs dev
Regenerate TLS machine certs? Warning: this is irreversible. (y/n): y
Regenerating TLS certificates
```

4
machine/reference/restart.md
View File

@ -11,16 +11,20 @@ title: restart
# restart
```none
Usage: docker-machine restart [arg...]
Restart a machine
Description:
Argument(s) are one or more machine names.
```
Restart a machine. Oftentimes this is equivalent to
`docker-machine stop; docker-machine start`. But some cloud driver try to implement a clever restart which keeps the same
ip address.
```
$ docker-machine restart dev
Waiting for VM to start...
```

4
machine/reference/rm.md
View File

@ -14,6 +14,7 @@ title: rm
Remove a machine. This will remove the local reference as well as delete it
on the cloud provider or virtualization management platform.
```none
$ docker-machine rm --help
Usage: docker-machine rm [OPTIONS] [arg...]
@ -27,9 +28,11 @@ on the cloud provider or virtualization management platform.
--force, -f Remove local configuration even if machine cannot be removed, also implies an automatic yes (`-y`)
-y Assumes automatic yes to proceed with remove, without prompting further user confirmation
```
## Examples
```none
$ docker-machine ls
NAME ACTIVE URL STATE URL SWARM DOCKER ERRORS
bar - virtualbox Running tcp://192.168.99.101:2376 v1.9.1
@ -65,3 +68,4 @@ on the cloud provider or virtualization management platform.
$ docker-machine rm -y foo
About to remove foo
Successfully removed foo
```

2
machine/reference/scp.md
View File

@ -18,6 +18,7 @@ machine's case, you don't have to specify the name, just the path.
Consider the following example:
```none
$ cat foo.txt
cat: foo.txt: No such file or directory
$ docker-machine ssh dev pwd
@ -27,6 +28,7 @@ Consider the following example:
foo.txt 100% 28 0.0KB/s 00:00
$ cat foo.txt
A file created remotely!
```
Just like how `scp` has a `-r` flag for copying files recursively,
`docker-machine` has a `-r` flag for this feature.

13
machine/reference/ssh.md
View File

@ -14,6 +14,7 @@ Log into or run a command on a machine using SSH.
To login, just run `docker-machine ssh machinename`:
```none
$ docker-machine ssh dev
## .
## ## ## ==
@ -32,19 +33,26 @@ To login, just run `docker-machine ssh machinename`:
docker@boot2docker:~$ ls /
Users/ dev/ home/ lib/ mnt/ proc/ run/ sys/ usr/
bin/ etc/ init linuxrc opt/ root/ sbin/ tmp var/
```
You can also specify commands to run remotely by appending them directly to the
`docker-machine ssh` command, much like the regular `ssh` program works:
```none
$ docker-machine ssh dev free
total used free shared buffers
Mem: 1023556 183136 840420 0 30920
-/+ buffers: 152216 871340
Swap: 1212036 0 1212036
```
Commands with flags will work as well:
```none
$ docker-machine ssh dev df -h
Filesystem Size Used Available Use% Mounted on
rootfs 899.6M 85.9M 813.7M 10% /
tmpfs 899.6M 85.9M 813.7M 10% /
@ -53,6 +61,7 @@ Commands with flags will work as well:
cgroup 499.8M 0 499.8M 0% /sys/fs/cgroup
/dev/sda1 18.2G 58.2M 17.2G 0%
/mnt/sda1/var/lib/docker/aufs
```
If you are using the "external" SSH type as detailed in the next section, you
can include additional arguments to pass through to the `ssh` binary in the
@ -61,7 +70,9 @@ the command generated by Docker Machine). For instance, the following command
will forward port 8080 from the `default` machine to `localhost` on your host
computer:
```bash
$ docker-machine ssh default -L 8080:localhost:8080
```
## Different types of SSH
@ -80,7 +91,9 @@ and Docker Machine will act sensibly out of the box. However, if you
deliberately want to use the Go native version, you can do so with a global
command line flag / environment variable like so:
```bash
$ docker-machine --native-ssh ssh dev
```
There are some variations in behavior between the two methods, so please report
any issues or inconsistencies if you come across them.

5
machine/reference/start.md
View File

@ -11,14 +11,19 @@ title: start
# start
```none
Usage: docker-machine start [arg...]
Start a machine
Description:
Argument(s) are one or more machine names.
```
For example:
```none
$ docker-machine start dev
Starting VM...
```

4
machine/reference/status.md
View File

@ -10,14 +10,18 @@ title: status
# status
```none
Usage: docker-machine status [arg...]
Get the status of a machine
Description:
Argument is a machine name.
```
For example:
```
$ docker-machine status dev
Running
```

7
machine/reference/stop.md
View File

@ -11,19 +11,26 @@ title: stop
# stop
```none
Usage: docker-machine stop [arg...]
Gracefully Stop a machine
Description:
Argument(s) are one or more machine names.
```
For example:
```none
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL
dev * virtualbox Running tcp://192.168.99.104:2376
$ docker-machine stop dev
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL
dev * virtualbox Stopped
```

3
machine/reference/upgrade.md
View File

@ -20,12 +20,15 @@ example, if the machine uses boot2docker for its OS, this command will download
the latest boot2docker ISO and replace the machine's existing ISO with the
latest.
```none
$ docker-machine upgrade default
Stopping machine to do the upgrade...
Upgrading machine default...
Downloading latest boot2docker release to /home/username/.docker/machine/cache/boot2docker.iso...
Starting machine back up...
Waiting for VM to start...
```
> **Note**: If you are using a custom boot2docker ISO specified using
> `--virtualbox-boot2docker-url` or an equivalent flag, running an upgrade on

2
machine/reference/url.md
View File

@ -12,5 +12,7 @@ title: url
Get the URL of a host
```none
$ docker-machine url dev
tcp://192.168.99.109:2376
```