HUB
Sign inSign up

softfour/openvpn-gw

By softfour

•Updated about 10 hours ago

OpenVPN client container with static-route and NAT setup on Ubuntu 24.04.

Image
Networking
0

1.3K

softfour/openvpn-gw repository overview

⁠Softfour OpenVPN Client Gateway

Ubuntu 24.04 (noble) container running a OpenVPN client, with startup rules for static routes, packet forwarding and NAT. This is a VPN client, not a VPN server.

⁠Tags and platforms

TagBasePublished platform
latestubuntu:noblelinux/amd64

Checked on 2026-11-08. The tag is updated in place; use a digest to pin an exact image. No native ARM64 variant is currently advertised.

⁠Requirements

  • A Linux Docker host with TUN support and an available /dev/net/tun device.
  • NET_ADMIN inside the container for interface, route and firewall operations.
  • A provider-issued or administrator-prepared configuration, with access to any referenced credential or certificate files.
  • A forwarding and routing policy appropriate to your deployment. The examples do not configure host routes or a fail-closed policy for you.

⁠Quick start with Docker Compose

Place your configuration at ./client.ovpn. The container reads /opt/openvpn/client.ovpn. If it references other files, mount those files at the referenced paths as well.

services:
  ovpn-gw:
    image: softfour/openvpn-gw:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    sysctls:
      net.ipv4.ip_forward: "1"
    environment:
      TZ: "UTC"
    volumes:
      - ./client.ovpn:/opt/openvpn/client.ovpn:ro
    restart: unless-stopped
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 ovpn-gw

Create the configuration file before starting Compose and protect any credentials it contains. No application port is published by this example.

⁠Runtime configuration

VariableDefaultPurpose
TZUTCContainer time zone
ROUTE_MAPSEmptyStatic routes as CIDR:GATEWAY, separated by commas, semicolons or spaces
FIREWALL_SUBNETSEmptySource subnets used in the startup FORWARD acceptance rules; see limitations below

Example values for a topology where the next hop is reachable through eth0:

environment:
  TZ: "UTC"
  ROUTE_MAPS: "10.10.0.0/16:192.168.1.1,172.16.0.0/12:192.168.1.1"
  FIREWALL_SUBNETS: "192.168.1.0/24;192.168.2.0/24"

Replace these example networks and next hops with values reachable in your container network. ROUTE_MAPS adds routes via eth0; it does not add host routes or force all traffic through the VPN. Route-add failures are currently ignored by the entrypoint, so inspect the installed routes.

⁠Network behavior and security

The entrypoint adds NEW-connection acceptance rules from eth0 to tun0, an ESTABLISHED/RELATED acceptance rule, and a general POSTROUTING MASQUERADE rule. An empty FIREWALL_SUBNETS value adds a general acceptance rule for that forwarding path.

FIREWALL_SUBNETS does not establish a default-deny firewall policy: the current entrypoint adds acceptance rules without explicitly dropping other sources. Do not rely on this variable alone as an access boundary. The NAT rule is not restricted to the tunnel interface. A fail-closed kill switch and tunnel health check are not implemented by this entrypoint.

Other containers can share this service's network namespace using network_mode: "service:ovpn-gw". That uses the VPN container's routes, but traffic generated in the shared namespace is not controlled by the FORWARD source-subnet rules. Publish any required application ports on the VPN service. Separate-network clients require explicit routes through the gateway and working IP forwarding; merely connecting two containers to a Docker network does not select the VPN as their default gateway.

⁠Operations and troubleshooting

docker compose logs --tail=100 ovpn-gw
docker compose exec -T ovpn-gw ip address
docker compose exec -T ovpn-gw ip route
docker compose exec -T ovpn-gw iptables -S FORWARD
docker compose exec -T ovpn-gw iptables -t nat -S POSTROUTING

Check device availability, capabilities, configuration paths, certificates, tunnel interface, DNS and the return route from the remote network. Container running status alone does not prove that the VPN is connected or that traffic is isolated. Validate permitted and denied traffic, reconnection and tunnel-loss behavior in your topology before production use.

Logs may contain network or authentication details; redact them before sharing. Keep VPN configuration and credentials outside the image, mount configuration read-only and never commit credentials to the source repository.

⁠Upgrade and rollback

Record the image digest and back up the configuration before upgrading:

docker compose pull ovpn-gw
docker compose up -d ovpn-gw

Recheck tunnel and routing behavior after recreation. For rollback, set image to the previous softfour/openvpn-gw@sha256:... digest and recreate the service with the matching configuration.

⁠Maintenance and support

Maintained by Softfour⁠. For support, use your existing Softfour support channel and include the image tag, digest, platform and relevant logs with credentials removed.

The repository README is the source for this Docker Hub overview. Documentation updates do not change image contents. No versioned image changelog is currently published; record the digest before upgrading.

⁠License and upstream

Based on Ubuntu packages and OpenVPN⁠. Third-party components retain their respective licenses. Contact Softfour for licensing information about image-specific files.

Tag summary

Content type

Image

Digest

sha256:3a3b9fa7f…

Size

69.8 MB

Last updated

about 10 hours ago

docker pull softfour/openvpn-gw