dotcloud/docker — pull request #1907 by crosbymichael (2013-09-17 18:18:24+00:00)
Title: Docker Links

Docker links allow users to easily connect one container to another.

**Basic Usage**
```bash
REDIS=$(docker run -d crosbymichael/redis)
echo $REDIS
32da9f6caf76

docker ps
32da9f6caf76 crosbymichael/redis:latest /redis/src/redis-ser 7 minutes ago Up 7 minutes 6379/tcp

docker run -link $REDIS:6379:redis -t -i linktesting sh

BusyBox v1.19.3 (Ubuntu 1:1.19.3-7ubuntu1.1) built-in shell (ash)
Enter 'help' for a list of built-in commands.

/ #

/ # echo $REDIS_ADDR
tcp://172.17.0.2:6379
/ # ./redis-cli -h 172.17.0.2
redis 172.17.0.2:6379>
```

**View links for the container**
```bash
docker link $REDIS
ID FROM TO PORT ALIAS
721aa034d10c:redis 32da9f6caf76 721aa034d10c 6379/tcp redis
```

**Remove an active link and prohibit communication**
```bash
docker link -rm 721aa034d10c:redis
Link successfully removed: 721aa034d10c:redis
docker link $REDIS
ID FROM TO PORT ALIAS

# From the client
/ # ./redis-cli -h 172.17.0.2
redis 172.17.0.2:6379> set name docker
Error: Connection timed out
/ #
```

##Publish a container's port to the host
This PR also allows a user to pick what host IP/interface the docker ports are bound to.

**Publish redis to local host only**
```bash
docker run -d -p 127.0.0.1::6379 crosbymichael/redis
c370d0c2741d
docker ps
ID IMAGE COMMAND CREATED STATUS PORTS
c370d0c2741d crosbymichael/redis:latest /redis/src/redis-ser 7 seconds ago Up 6 seconds 127.0.0.1:49153->6379/tcp
```

There is still a few things to be done in this PR but I wanted to get it out in front of the community for feedback.
##TODO:
* Update documentation
* Link and publish unit tests
* -p == publish ( not port )
* Link to docker engine
* Sample client libs