Skip to content

Commit

Permalink
Merge pull request #31 from wollomatic/develop
Browse files Browse the repository at this point in the history 
Expose the filtered UNIX socket as a UNIX socket (implements #29)
  • Loading branch information
@wollomatic
wollomatic committed Sep 14, 2024
2 parents 35e6259 + 8520e78 commit 14352ea
Show file tree
Hide file tree
Showing 6 changed files with 138 additions and 63 deletions.
4 changes: 2 additions & 2 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.22.6-alpine3.20 AS build
FROM --platform=$BUILDPLATFORM golang:1.22.7-alpine3.20 AS build
WORKDIR /application
COPY . ./
ARG TARGETOS
Expand All @@ -17,4 +17,4 @@ USER 65534:65534
VOLUME /var/run/docker.sock
EXPOSE 2375
ENTRYPOINT ["/socket-proxy"]
COPY --from=build ./healthcheck ./socket-proxy /
COPY --from=build ./healthcheck ./socket-proxy /
37 changes: 25 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,17 @@ This is meant to be an additional layer of security. It does not replace other s

Socket-proxy listens per default only on `127.0.0.1`. Depending on what you need, you may want to set another listener address with the `-listenip` parameter. In almost every use case, `-listenip=0.0.0.0` will be the correct configuration when using socket-proxy in a docker image.

#### Using a unix socket instead of a TCP listener

> [!CAUTION]
> This is a new feature introduced in version 1.5.0. If you experience any issues, please feel free to open an GitHub issue.
If you want to proxy/filter the unix socket to a new unix socket instead to a TCP listener,
you need to set the `-proxysocketendpoint` parameter or the `SP_PROXYSOCKETENDPOIN` env variable to the socket path of the new unix socket.
This will also disable the TCP listener.

For example `-proxysocketendpoint=/tmp/filtered-socket.sock`

#### Setting up the IP address or hostname allowlist

Per default, only `127.0.0.1/32` is allowed to connect to socket-proxy. You may want to set another allowlist with the `-allowfrom` parameter, depending on your needs.
Expand Down Expand Up @@ -162,18 +173,20 @@ To log the API calls of the client application, set the log level to `DEBUG` and

socket-proxy can be configured via command line parameters or via environment variables. If both command line parameter and environment variables are set, the environment variable will be ignored.

| Parameter | Environment Variable | Default Value | Description |
|----------------------|-------------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-allowfrom` | `SP_ALLOWFROM` | `127.0.0.1/32` | Specifies the IP addresses of the clients or the hostname of one specific client allowed to connect to the proxy. The default value is `127.0.0.1/32`, which means only localhost is allowed. This default configuration may not be useful in most cases, but it is because of a secure-by-default design. To allow all IPv4 addresses, set `-allowfrom=0.0.0.0/0`. Alternatively, hostnames (comma-separated) can be set, for example `-allowfrom=traefik`, or `-allowfrom=traefik,dozzle`. Please remember that socket-proxy should never be exposed to a public network, regardless of this extra security layer. |
| `-allowhealthcheck` | `SP_ALLOWHEALTHCHECK` | (not set) | If set, it allows the included health check binary to check the socket connection via TCP port 55555 (socket-proxy then listens on `127.0.0.1:55555/health`) |
| `-listenip` | `SP_LISTENIP` | `127.0.0.1` | Specifies the IP address the server will bind on. Default is only the internal network. |
| `-logjson` | `SP_LOGJSON` | (not set) | If set, it enables logging in JSON format. If unset, docker-proxy logs in plain text format. |
| `-loglevel` | `SP_LOGLEVEL` | `INFO` | Sets the log level. Accepted values are: `DEBUG`, `INFO`, `WARN`, `ERROR`. |
| `-proxyport` | `SP_PROXYPORT` | `2375` | Defines the TCP port the proxy listens to. |
| `-shutdowngracetime` | `SP_SHUTDOWNGRACETIME` | `10` | Defines the time in seconds to wait before forcing the shutdown after sigtern or sigint (socket-proxy first tries to graceful shut down the TCP server) |
| `-socketpath` | `SP_SOCKETPATH` | `/var/run/docker.sock` | Specifies the UNIX socket path to connect to. By default, it connects to the Docker daemon socket. |
| `-stoponwatchdog` | `SP_STOPONWATCHDOG` | (not set) | If set, socket-proxy will be stopped if the watchdog detects that the unix socket is not available. |
| `-watchdoginterval` | `SP_WATCHDOGINTERVAL` | `0` | Check for socket availabibity every x seconds (disable checks, if not set or value is 0) |
| Parameter | Environment Variable | Default Value | Description |
|--------------------------------|----------------------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-allowfrom` | `SP_ALLOWFROM` | `127.0.0.1/32` | Specifies the IP addresses of the clients or the hostname of one specific client allowed to connect to the proxy. The default value is `127.0.0.1/32`, which means only localhost is allowed. This default configuration may not be useful in most cases, but it is because of a secure-by-default design. To allow all IPv4 addresses, set `-allowfrom=0.0.0.0/0`. Alternatively, hostnames (comma-separated) can be set, for example `-allowfrom=traefik`, or `-allowfrom=traefik,dozzle`. Please remember that socket-proxy should never be exposed to a public network, regardless of this extra security layer. |
| `-allowhealthcheck` | `SP_ALLOWHEALTHCHECK` | (not set/false) | If set, it allows the included health check binary to check the socket connection via TCP port 55555 (socket-proxy then listens on `127.0.0.1:55555/health`) |
| `-listenip` | `SP_LISTENIP` | `127.0.0.1` | Specifies the IP address the server will bind on. Default is only the internal network. |
| `-logjson` | `SP_LOGJSON` | (not set/false) | If set, it enables logging in JSON format. If unset, docker-proxy logs in plain text format. |
| `-loglevel` | `SP_LOGLEVEL` | `INFO` | Sets the log level. Accepted values are: `DEBUG`, `INFO`, `WARN`, `ERROR`. |
| `-proxyport` | `SP_PROXYPORT` | `2375` | Defines the TCP port the proxy listens to. |
| `-shutdowngracetime` | `SP_SHUTDOWNGRACETIME` | `10` | Defines the time in seconds to wait before forcing the shutdown after sigtern or sigint (socket-proxy first tries to graceful shut down the TCP server) |
| `-socketpath` | `SP_SOCKETPATH` | `/var/run/docker.sock` | Specifies the UNIX socket path to connect to. By default, it connects to the Docker daemon socket. |
| `-stoponwatchdog` | `SP_STOPONWATCHDOG` | (not set/false) | If set, socket-proxy will be stopped if the watchdog detects that the unix socket is not available. |
| `-watchdoginterval` | `SP_WATCHDOGINTERVAL` | `0` | Check for socket availabibity every x seconds (disable checks, if not set or value is 0) |
| `-proxysocketendpoint` | `SP_PROXYSOCKETENDPOINT` | (not set) | Proxy to the given unix socket instead of a TCP port |
| `-proxysocketendpointfilemode` | `SP_PROXYSOCKETENDPOINTFILEMODE` | `0400` | Explicitly set the file mode for the filtered unix socket endpoint (only useful with `-proxysocketendpoint`) |

### Changelog

Expand Down
Loading

0 comments on commit 14352ea

Please sign in to comment.