{"id":13880586,"url":"https://github.com/wfg/docker-openvpn-client","last_synced_at":"2025-07-16T17:30:43.351Z","repository":{"id":37904353,"uuid":"237636800","full_name":"wfg/docker-openvpn-client","owner":"wfg","description":"OpenVPN client with killswitch and proxy servers; built on Alpine","archived":true,"fork":false,"pushed_at":"2024-03-16T18:17:31.000Z","size":80,"stargazers_count":354,"open_issues_count":32,"forks_count":109,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-24T09:34:00.165Z","etag":null,"topics":["openvpn-client","proxy-server","socks-proxy","vpn-tunnel"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wfg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-01T15:43:15.000Z","updated_at":"2024-11-15T20:15:14.000Z","dependencies_parsed_at":"2024-03-16T21:13:57.934Z","dependency_job_id":"a9620344-9192-46fc-8788-06c1f688e0ab","html_url":"https://github.com/wfg/docker-openvpn-client","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/wfg/docker-openvpn-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wfg%2Fdocker-openvpn-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wfg%2Fdocker-openvpn-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wfg%2Fdocker-openvpn-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wfg%2Fdocker-openvpn-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wfg","download_url":"https://codeload.github.com/wfg/docker-openvpn-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wfg%2Fdocker-openvpn-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527541,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openvpn-client","proxy-server","socks-proxy","vpn-tunnel"],"created_at":"2024-08-06T08:03:14.607Z","updated_at":"2025-07-16T17:30:43.107Z","avatar_url":"https://github.com/wfg.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# OpenVPN Client for Docker\n\nArchived in favor of [a WireGuard version](https://github.com/wfg/docker-wireguard).\n\n## What is this and what does it do?\n[`ghcr.io/wfg/openvpn-client`](https://github.com/users/wfg/packages/container/package/openvpn-client) is a containerized OpenVPN client.\nIt has a kill switch built with `iptables` that kills Internet connectivity to the container if the VPN tunnel goes down for any reason.\n\nThis image requires you to supply the necessary OpenVPN configuration file(s).\nBecause of this, any VPN provider should work.\n\nIf you find something that doesn't work or have an idea for a new feature, issues and **pull requests are welcome** (however, I'm not promising they will be merged).\n\n## Why?\nHaving a containerized VPN client lets you use container networking to easily choose which applications you want using the VPN instead of having to set up split tunnelling.\nIt also keeps you from having to install an OpenVPN client on the underlying host.\n\n## How do I use it?\n### Getting the image\nYou can either pull it from GitHub Container Registry or build it yourself.\n\nTo pull it from GitHub Container Registry, run\n```\ndocker pull ghcr.io/wfg/openvpn-client\n```\n\nTo build it yourself, run\n```\ndocker build -t ghcr.io/wfg/openvpn-client https://github.com/wfg/docker-openvpn-client.git#:build\n```\n\n### Creating and running a container\nThe image requires the container be created with the `NET_ADMIN` capability and `/dev/net/tun` accessible.\nBelow are bare-bones examples for `docker run` and Compose; however, you'll probably want to do more than just run the VPN client.\nSee the below to learn how to have [other containers use `openvpn-client`'s network stack](#using-with-other-containers).\n\n#### `docker run`\n```\ndocker run --detach \\\n  --name=openvpn-client \\\n  --cap-add=NET_ADMIN \\\n  --device=/dev/net/tun \\\n  --volume \u003cpath/to/config/dir\u003e:/config \\\n  ghcr.io/wfg/openvpn-client\n```\n\n#### `docker-compose`\n```yaml\nservices:\n  openvpn-client:\n    image: ghcr.io/wfg/openvpn-client\n    container_name: openvpn-client\n    cap_add:\n      - NET_ADMIN\n    devices:\n      - /dev/net/tun\n    volumes:\n      - \u003cpath/to/config/dir\u003e:/config\n    restart: unless-stopped\n```\n\n#### Environment variables\n| Variable | Default (blank is unset) | Description |\n| --- | --- | --- |\n| `ALLOWED_SUBNETS` | | A list of one or more comma-separated subnets (e.g. `192.168.0.0/24,192.168.1.0/24`) to allow outside of the VPN tunnel. |\n| `AUTH_SECRET` | | Docker secret that contains the credentials for accessing the VPN. |\n| `CONFIG_FILE` | | The OpenVPN configuration file or search pattern. If unset, a random `.conf` or `.ovpn` file will be selected. |\n| `KILL_SWITCH` | `on` | Whether or not to enable the kill switch. Set to any \"truthy\" value[1] to enable. |\n\n[1] \"Truthy\" values in this context are the following: `true`, `t`, `yes`, `y`, `1`, `on`, `enable`, or `enabled`.\n\n##### Environment variable considerations\n###### `ALLOWED_SUBNETS`\nIf you intend on connecting to containers that use the OpenVPN container's network stack (which you probably do), **you will probably want to use this variable**.\nRegardless of whether or not you're using the kill switch, the entrypoint script also adds routes to each of the `ALLOWED_SUBNETS` to allow network connectivity from outside of Docker.\n\n##### `AUTH_SECRET`\nCompose has support for [Docker secrets](https://docs.docker.com/engine/swarm/secrets/#use-secrets-in-compose).\nSee the [Compose file](docker-compose.yml) in this repository for example usage of passing proxy credentials as Docker secrets.\n\n### Using with other containers\nOnce you have your `openvpn-client` container up and running, you can tell other containers to use `openvpn-client`'s network stack which gives them the ability to utilize the VPN tunnel.\nThere are a few ways to accomplish this depending how how your container is created.\n\nIf your container is being created with\n1. the same Compose YAML file as `openvpn-client`, add `network_mode: service:openvpn-client` to the container's service definition.\n2. a different Compose YAML file than `openvpn-client`, add `network_mode: container:openvpn-client` to the container's service definition.\n3. `docker run`, add `--network=container:openvpn-client` as an option to `docker run`.\n\nOnce running and provided your container has `wget` or `curl`, you can run `docker exec \u003ccontainer_name\u003e wget -qO - ifconfig.me` or `docker exec \u003ccontainer_name\u003e curl -s ifconfig.me` to get the public IP of the container and make sure everything is working as expected.\nThis IP should match the one of `openvpn-client`.\n\n#### Handling ports intended for connected containers\nIf you have a connected container and you need to access a port that container, you'll want to publish that port on the `openvpn-client` container instead of the connected container.\nTo do that, add `-p \u003chost_port\u003e:\u003ccontainer_port\u003e` if you're using `docker run`, or add the below snippet to the `openvpn-client` service definition in your Compose file if using `docker-compose`.\n```yaml\nports:\n  - \u003chost_port\u003e:\u003ccontainer_port\u003e\n```\nIn both cases, replace `\u003chost_port\u003e` and `\u003ccontainer_port\u003e` with the port used by your connected container.\n\n### Verifying functionality\nOnce you have container running `ghcr.io/wfg/openvpn-client`, run the following command to spin up a temporary container using `openvpn-client` for networking.\nThe `wget -qO - ifconfig.me` bit will return the public IP of the container (and anything else using `openvpn-client` for networking).\nYou should see an IP address owned by your VPN provider.\n```\ndocker run --rm -it --network=container:openvpn-client alpine wget -qO - ifconfig.me\n```\n\n### Troubleshooting\n#### VPN authentication\nYour OpenVPN configuration file may not come with authentication baked in.\nTo provide OpenVPN the necessary credentials, create a file (any name will work, but this example will use `credentials.txt`) next to the OpenVPN configuration file with your username on the first line and your password on the second line.\n\nFor example:\n```\nvpn_username\nvpn_password\n```\n\nIn the OpenVPN configuration file, add the following line:\n```\nauth-user-pass credentials.txt\n```\n\nThis will tell OpenVPN to read `credentials.txt` whenever it needs credentials.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwfg%2Fdocker-openvpn-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwfg%2Fdocker-openvpn-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwfg%2Fdocker-openvpn-client/lists"}