-
-
Notifications
You must be signed in to change notification settings - Fork 3
/
readme-vars.yml
330 lines (257 loc) · 15 KB
/
readme-vars.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
---
# project information
project_name: socket-proxy
full_custom_readme: |
{% raw -%}
[](https://linuxserver.io)
[](https://blog.linuxserver.io "all the things you can do with our containers including How-To guides, opinions and much more!")
[](https://discord.gg/YWrKVTn "realtime support / chat with the community and the team.")
[](https://discourse.linuxserver.io "post on our community forum.")
[](https://fleet.linuxserver.io "an online web interface which displays all of our maintained images.")
[](https://github.com/linuxserver "view the source for all of our repositories.")
[](https://opencollective.com/linuxserver "please consider helping us by either donating or contributing to our budget")
The [LinuxServer.io](https://linuxserver.io) team brings you another container release.
Find us at:
* [Blog](https://blog.linuxserver.io) - all the things you can do with our containers including How-To guides, opinions and much more!
* [Discord](https://discord.gg/YWrKVTn) - realtime support / chat with the community and the team.
* [Discourse](https://discourse.linuxserver.io) - post on our community forum.
* [Fleet](https://fleet.linuxserver.io) - an online web interface which displays all of our maintained images.
* [GitHub](https://github.com/linuxserver) - view the source for all of our repositories.
* [Open Collective](https://opencollective.com/linuxserver) - please consider helping us by either donating or contributing to our budget
# [linuxserver/socket-proxy](https://github.com/linuxserver/docker-socket-proxy)
[](https://scarf.sh/gateway/linuxserver-ci/docker/linuxserver%2Fsocket-proxy)
[](https://github.com/linuxserver/docker-socket-proxy)
[](https://github.com/linuxserver/docker-socket-proxy/releases)
[](https://github.com/linuxserver/docker-socket-proxy/packages)
[](https://gitlab.com/linuxserver.io/docker-socket-proxy/container_registry)
[](https://quay.io/repository/linuxserver.io/socket-proxy)
[](https://hub.docker.com/r/linuxserver/socket-proxy)
[](https://hub.docker.com/r/linuxserver/socket-proxy)
[](https://ci.linuxserver.io/job/Docker-Pipeline-Builders/job/docker-socket-proxy/job/main/)
The Socket Proxy is a security-enhanced proxy which allows you to apply access rules to the Docker socket, limiting the attack surface for containers such as watchtower or Traefik that need to use it.
## Supported Architectures
We utilise the docker manifest for multi-platform awareness. More information is available from docker [here](https://distribution.github.io/distribution/spec/manifest-v2-2/#manifest-list) and our announcement [here](https://blog.linuxserver.io/2019/02/21/the-lsio-pipeline-project/).
Simply pulling `lscr.io/linuxserver/socket-proxy:latest` should retrieve the correct image for your arch, but you can also pull specific arch images via tags.
The architectures supported by this image are:
| Architecture | Available | Tag |
| :----: | :----: | ---- |
| x86-64 | ✅ | amd64-\<version tag\> |
| arm64 | ✅ | arm64v8-\<version tag\> |
| armhf | ❌ | |
## Application Setup
This container is based on [https://github.com/Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) and as such does not follow our usual container conventions. It *does not* support mods or custom scripts/services, or running as a user other than root (or the docker user in a rootless environment). It is designed to act as a drop-in replacement for the Tecnativa container.
The container should be run on the same docker network as the service(s) using it. Most containers that would normally connect to a mounted docker.sock can have their endpoint overridden using the `DOCKER_HOST` environment variable if they do not offer the option in their configuration; it should typically be pointed to `tcp://socket-proxy:2375`.
* Never expose this container's port to a public network. It should be treated the same way you would treat the docker socket or TCP endpoint.
* Revoke access to any API section that you consider your service should not need.
* To see the versions of the API your Docker daemon and client support, use `docker version` and check the `API version`.
* [Read the docs](https://docs.docker.com/engine/api/) for the API version you are using for an explanation of all the available endpoints.
## Read-Only Operation
This image can be run with a read-only container filesystem. For details please [read the docs](https://docs.linuxserver.io/misc/read-only/).
## Usage
To help you get started creating a container from this image you can either use docker compose or the docker cli.
>[!NOTE]
>Unless a parameter is flaged as 'optional', it is *mandatory* and a value must be provided.
### docker compose (recommended, [click here for more info](https://docs.linuxserver.io/general/docker-compose))
```yaml
---
services:
socket-proxy:
image: lscr.io/linuxserver/socket-proxy:latest
container_name: socket-proxy
environment:
- ALLOW_START=0 #optional
- ALLOW_STOP=0 #optional
- ALLOW_RESTARTS=0 #optional
- AUTH=0 #optional
- BUILD=0 #optional
- COMMIT=0 #optional
- CONFIGS=0 #optional
- CONTAINERS=0 #optional
- DISABLE_IPV6=0 #optional
- DISTRIBUTION=0 #optional
- EVENTS=1 #optional
- EXEC=0 #optional
- IMAGES=0 #optional
- INFO=0 #optional
- NETWORKS=0 #optional
- NODES=0 #optional
- PING=1 #optional
- PLUGINS=0 #optional
- POST=0 #optional
- PROXY_READ_TIMEOUT=240 #optional
- SECRETS=0 #optional
- SERVICES=0 #optional
- SESSION=0 #optional
- SWARM=0 #optional
- SYSTEM=0 #optional
- TASKS=0 #optional
- VERSION=1 #optional
- VOLUMES=0 #optional
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped
read_only: true
tmpfs:
- /run
```
### docker cli ([click here for more info](https://docs.docker.com/engine/reference/commandline/cli/))
```bash
docker run -d \
--name=socket-proxy \
-e ALLOW_START=0 `#optional` \
-e ALLOW_STOP=0 `#optional` \
-e ALLOW_RESTARTS=0 `#optional` \
-e AUTH=0 `#optional` \
-e BUILD=0 `#optional` \
-e COMMIT=0 `#optional` \
-e CONFIGS=0 `#optional` \
-e CONTAINERS=0 `#optional` \
-e DISTRIBUTION=0 `#optional` \
-e DISABLE_IPV6=0 `#optional` \
-e EVENTS=1 `#optional` \
-e EXEC=0 `#optional` \
-e IMAGES=0 `#optional` \
-e INFO=0 `#optional` \
-e NETWORKS=0 `#optional` \
-e NODES=0 `#optional` \
-e PING=1 `#optional` \
-e PLUGINS=0 `#optional` \
-e POST=0 `#optional` \
-e PROXY_READ_TIMEOUT=240 `#optional` \
-e SECRETS=0 `#optional` \
-e SERVICES=0 `#optional` \
-e SESSION=0 `#optional` \
-e SWARM=0 `#optional` \
-e SYSTEM=0 `#optional` \
-e TASKS=0 `#optional` \
-e VERSION=1 `#optional` \
-e VOLUMES=0 `#optional` \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
--restart unless-stopped \
--read-only \
--tmpfs /run \
lscr.io/linuxserver/socket-proxy:latest
```
## Parameters
Containers are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate `<external>:<internal>` respectively. For example, `-p 8080:80` would expose port `80` from inside the container to be accessible from the host's IP on port `8080` outside the container.
| Parameter | Function |
| :----: | --- |
| `-e ALLOW_START=0` | `/containers/{id}/start` - **This option will work even if `POST=0`** |
| `-e ALLOW_STOP=0` | `/containers/{id}/stop` - **This option will work even if `POST=0`** |
| `-e ALLOW_RESTARTS=0` | `/containers/{id}/stop`, `/containers/{id}/restart`, and `/containers/{id}/kill` - **This option will work even if `POST=0`** |
| `-e AUTH=0` | `/auth` |
| `-e BUILD=0` | `/build` |
| `-e COMMIT=0` | `/commit` |
| `-e CONFIGS=0` | `/configs` |
| `-e CONTAINERS=0` | `/containers` |
| `-e DISTRIBUTION=0` | `/distribution` |
| `-e DISABLE_IPV6=0` | Set to `1` to prevent nginx binding to the IPv6 interface for legacy system that cannot support IPv6. |
| `-e EVENTS=1` | `/events` |
| `-e EXEC=0` | `/exec` & `/containers/{id}/exec` |
| `-e IMAGES=0` | `/images` |
| `-e INFO=0` | `/info` |
| `-e NETWORKS=0` | `/networks` |
| `-e NODES=0` | `/nodes` |
| `-e PING=1` | `/_ping` |
| `-e PLUGINS=0` | `/plugins` |
| `-e POST=0` | When set to `0`, only `GET` and `HEAD` operations are allowed, making API access read-only. |
| `-e PROXY_READ_TIMEOUT=240` | Connection timeout when no data is being sent. Useful for tailing quiet containers. Accepts values in s/m/h/d/w, no suffix assumes s. |
| `-e SECRETS=0` | `/secrets` |
| `-e SERVICES=0` | `/services` |
| `-e SESSION=0` | `/session` |
| `-e SWARM=0` | `/swarm` |
| `-e SYSTEM=0` | `/system` |
| `-e TASKS=0` | `/tasks` |
| `-e VERSION=1` | `/version` |
| `-e VOLUMES=0` | `/volumes` |
| `-v /var/run/docker.sock:ro` | Mount the host docker socket into the container. |
| `--read-only` | Make the container filesystem read-only. |
| `--tmpfs /run` | Mount /run to tmpfs (RAM) to make it writeable. |
## Support Info
* Shell access whilst the container is running:
```bash
docker exec -it socket-proxy /bin/sh
```
* To monitor the logs of the container in realtime:
```bash
docker logs -f socket-proxy
```
* Container version number:
```bash
docker inspect -f '{{ index .Config.Labels "build_version" }}' socket-proxy
```
* Image version number:
```bash
docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/socket-proxy:latest
```
## Updating Info
Most of our images are static, versioned, and require an image update and container recreation to update the app inside. With some exceptions (noted in the relevant readme.md), we do not recommend or support updating apps inside the container. Please consult the [Application Setup](#application-setup) section above to see if it is recommended for the image.
Below are the instructions for updating containers:
### Via Docker Compose
* Update images:
* All images:
```bash
docker compose pull
```
* Single image:
```bash
docker compose pull socket-proxy
```
* Update containers:
* All containers:
```bash
docker compose up -d
```
* Single container:
```bash
docker compose up -d socket-proxy
```
* You can also remove the old dangling images:
```bash
docker image prune
```
### Via Docker Run
* Update the image:
```bash
docker pull lscr.io/linuxserver/socket-proxy:latest
```
* Stop the running container:
```bash
docker stop socket-proxy
```
* Delete the container:
```bash
docker rm socket-proxy
```
* You can also remove the old dangling images:
```bash
docker image prune
```
### Image Update Notifications - Diun (Docker Image Update Notifier)
>[!TIP]
>We recommend [Diun](https://crazymax.dev/diun/) for update notifications. Other tools that automatically update containers unattended are not recommended or supported.
## Building locally
If you want to make local modifications to these images for development purposes or just to customize the logic:
```bash
git clone https://github.com/linuxserver/docker-socket-proxy.git
cd docker-socket-proxy
docker build \
--no-cache \
--pull \
-t lscr.io/linuxserver/socket-proxy:latest .
```
The ARM variants can be built on x86_64 hardware and vice versa using `lscr.io/linuxserver/docker-qemu-static`
```bash
docker run --rm --privileged lscr.io/linuxserver/docker-qemu-static --reset
```
Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64`.
## Versions
* **02.01.25:** - Support custom read timeout values.
* **05.12.24:** - Rebase to Alpine 3.21.
* **26.08.24:** - Change `ALLOW_START`, `ALLOW_STOP`, and `ALLOW_RESTARTS` to work even with `POST=0`.
* **24.05.24:** - Rebase to Alpine 3.20.
* **15.04.24:** - Allow disabling IPv6 support for legacy devices.
* **08.04.24:** - Use nginx due to haproxy's wonky websockets handling.
* **07.04.24:** - Initial Release.
{%- endraw %}