📝 Full README
This commit is contained in:
Jairo Llopis
parent
53d9ee0732
commit
0014ddf65e
137
README.md
137
README.md
@ -1,40 +1,151 @@
|
||||
# Docker Socket Readonly Proxy
|
||||
# Docker Socket Proxy
|
||||
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-readonly:latest "Get your own version badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-readonly:latest "Get your own image badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-readonly:latest "Get your own commit badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-readonly "Get your own license badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own version badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own image badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own commit badge on microbadger.com")
|
||||
[](https://microbadger.com/images/tecnativa/docker-socket-proxy "Get your own license badge on microbadger.com")
|
||||
|
||||
## What?
|
||||
|
||||
This is a readonly proxy for the Docker Socket.
|
||||
This is a security-enhaced proxy for the Docker Socket.
|
||||
|
||||
## Why?
|
||||
|
||||
Giving access to your Docker socket could mean giving root access to your host,
|
||||
or even to your whole swarm, but some services require hooking into that socket to
|
||||
react to events, etc. Using this proxy lets you block anything you consider those services should not do.
|
||||
or even to your whole swarm, but some services require hooking into that socket
|
||||
to react to events, etc. Using this proxy lets you block anything you consider
|
||||
those services should not do.
|
||||
|
||||
## How?
|
||||
|
||||
We use the official [Alpine][]-based [HAProxy][] image with a small
|
||||
configuration file.
|
||||
|
||||
It blocks access to the Docker socket [API][] according to the environment
|
||||
It blocks access to the Docker socket API according to the environment
|
||||
variables you set. It returns a `HTTP 403 Forbidden` status for those dangerous
|
||||
requests that should never happen.
|
||||
|
||||
## Security recommendations
|
||||
|
||||
- Never expose this container's port to a public network. Only to a Docker
|
||||
networks where only reside the proxy itself and the service that uses it.
|
||||
- Revoke access to any API section that you consider your service should not
|
||||
need.
|
||||
- This image does not include TLS support, just plain HTTP proxy to the host
|
||||
Docker Unix socket (which is not TLS protected even if you configured your
|
||||
host for TLS protection). This is by design because you are supposed to
|
||||
restrict access to it through Docker's built-in firewall.
|
||||
- [Read the docs](#suppported-api-versions) for the API version you are using,
|
||||
and **know what you are doing**.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Run the API proxy:
|
||||
|
||||
$ docker container run \
|
||||
-d --privileged \
|
||||
--name dockerproxy \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-p 127.0.0.1:2375:2375 \
|
||||
tecnativa/docker-socket-proxy
|
||||
|
||||
2. Connect your local docker client to that socket:
|
||||
|
||||
$ export DOCKER_HOST=tcp://localhost
|
||||
|
||||
3. You can see the docker version:
|
||||
|
||||
$ docker version
|
||||
Client:
|
||||
Version: 17.03.1-ce
|
||||
API version: 1.27
|
||||
Go version: go1.7.5
|
||||
Git commit: c6d412e
|
||||
Built: Mon Mar 27 17:14:43 2017
|
||||
OS/Arch: linux/amd64
|
||||
|
||||
Server:
|
||||
Version: 17.03.1-ce
|
||||
API version: 1.27 (minimum version 1.12)
|
||||
Go version: go1.7.5
|
||||
Git commit: c6d412e
|
||||
Built: Mon Mar 27 17:14:43 2017
|
||||
OS/Arch: linux/amd64
|
||||
Experimental: false
|
||||
|
||||
4. You cannot see running containers:
|
||||
|
||||
$ docker container ls
|
||||
Error response from daemon: <html><body><h1>403 Forbidden</h1>
|
||||
Request forbidden by administrative rules.
|
||||
</body></html>
|
||||
|
||||
The same will happen to any containers that use this proxy's `2375` port to
|
||||
access the Docker socket API.
|
||||
|
||||
## Grant or revoke access to certain API sections
|
||||
|
||||
You grant and revoke access to certain features of the Docker API through
|
||||
environment variables.
|
||||
|
||||
Normally the variables match the URL prefix (i.e. `AUTH` blocks access to
|
||||
`/auth/*` parts of the API, etc.).
|
||||
|
||||
Possible values for these variables:
|
||||
|
||||
- `0` to **revoke** access.
|
||||
- `1` to **grant** access.
|
||||
|
||||
### Access granted by default
|
||||
|
||||
These API sections are mostly harmless and almost required for any service that
|
||||
uses the API, so they are granted by default.
|
||||
|
||||
- `EVENTS`
|
||||
- `PING`
|
||||
- `VERSION`
|
||||
|
||||
### Access revoked by default
|
||||
|
||||
#### Security-critical
|
||||
|
||||
These API sections are considered security-critical, and thus access is revoked
|
||||
by default. Maximum caution when enabling these.
|
||||
|
||||
- `AUTH`
|
||||
- `SECRETS`
|
||||
- `POST`: When disabled, only `GET` and `HEAD` operations are allowed, meaning
|
||||
any section of the API is read-only.
|
||||
|
||||
#### Not always needed
|
||||
|
||||
You will possibly need to grant access to some of these API sections, which are
|
||||
not so extremely critical but can expose some information that your service
|
||||
does not need.
|
||||
|
||||
- `BUILD`
|
||||
- `COMMIT`
|
||||
- `CONTAINERS`
|
||||
- `EXEC`
|
||||
- `IMAGES`
|
||||
- `INFO`
|
||||
- `NETWORKS`
|
||||
- `NODES`
|
||||
- `PLUGINS`
|
||||
- `SERVICES`
|
||||
- `SWARM`
|
||||
- `SYSTEM`
|
||||
- `TASKS`
|
||||
- `VOLUMES`
|
||||
|
||||
## Supported API versions
|
||||
|
||||
- [1.27](https://docs.docker.com/engine/api/v1.27/)
|
||||
|
||||
## Feedback
|
||||
|
||||
Please send any feedback (issues, questions) to the [issue tracker][].
|
||||
|
||||
[Alpine]: https://alpinelinux.org/
|
||||
[API]: https://docs.docker.com/engine/api/v1.27/
|
||||
[HAProxy]: http://www.haproxy.org/
|
||||
[issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues
|
||||
[Odoo]: https://www.odoo.com/
|
||||
[proxy mode]: https://www.odoo.com/documentation/10.0/reference/cmdline.html#cmdoption-odoo.py--proxy-mode
|
||||
[worker mode]: https://www.odoo.com/documentation/10.0/setup/deploy.html#worker-number-calculation
|
||||
|
||||
Loading…
Reference in New Issue
Block a user