mirror of
https://github.com/Tecnativa/docker-socket-proxy
synced 2024-12-21 22:28:07 +00:00
📝 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-proxy: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-proxy: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-proxy: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 "Get your own license badge on microbadger.com")
|
||||||
|
|
||||||
## What?
|
## What?
|
||||||
|
|
||||||
This is a readonly proxy for the Docker Socket.
|
This is a security-enhaced proxy for the Docker Socket.
|
||||||
|
|
||||||
## Why?
|
## Why?
|
||||||
|
|
||||||
Giving access to your Docker socket could mean giving root access to your host,
|
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
|
or even to your whole swarm, but some services require hooking into that socket
|
||||||
react to events, etc. Using this proxy lets you block anything you consider those services should not do.
|
to react to events, etc. Using this proxy lets you block anything you consider
|
||||||
|
those services should not do.
|
||||||
|
|
||||||
## How?
|
## How?
|
||||||
|
|
||||||
We use the official [Alpine][]-based [HAProxy][] image with a small
|
We use the official [Alpine][]-based [HAProxy][] image with a small
|
||||||
configuration file.
|
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
|
variables you set. It returns a `HTTP 403 Forbidden` status for those dangerous
|
||||||
requests that should never happen.
|
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
|
## 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
|
## Feedback
|
||||||
|
|
||||||
Please send any feedback (issues, questions) to the [issue tracker][].
|
Please send any feedback (issues, questions) to the [issue tracker][].
|
||||||
|
|
||||||
[Alpine]: https://alpinelinux.org/
|
[Alpine]: https://alpinelinux.org/
|
||||||
[API]: https://docs.docker.com/engine/api/v1.27/
|
|
||||||
[HAProxy]: http://www.haproxy.org/
|
[HAProxy]: http://www.haproxy.org/
|
||||||
[issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues
|
[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