{"id":26569727,"url":"https://github.com/phrozenbyte/wg-udp2raw","last_synced_at":"2026-04-12T15:46:11.425Z","repository":{"id":282737494,"uuid":"949498587","full_name":"PhrozenByte/wg-udp2raw","owner":"PhrozenByte","description":"Runs WireGuard over a fake TCP connection using `udp2raw`.","archived":false,"fork":false,"pushed_at":"2025-03-16T17:11:23.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-16T17:19:31.532Z","etag":null,"topics":["bypass-firewall","faketcp","shell-script","udp-tunnel","udp2raw","udp2raw-tunnel","vpn","vpn-setup","wireguard","wireguard-tcp","wireguard-vpn","wireguard-vpn-setup"],"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/PhrozenByte.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":"2025-03-16T15:45:05.000Z","updated_at":"2025-03-16T17:11:27.000Z","dependencies_parsed_at":"2025-03-16T17:19:32.813Z","dependency_job_id":"e2d67ea2-e8c9-4f47-bf67-1ab00a961f27","html_url":"https://github.com/PhrozenByte/wg-udp2raw","commit_stats":null,"previous_names":["phrozenbyte/wg-udp2raw"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Fwg-udp2raw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Fwg-udp2raw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Fwg-udp2raw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhrozenByte%2Fwg-udp2raw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhrozenByte","download_url":"https://codeload.github.com/PhrozenByte/wg-udp2raw/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245021317,"owners_count":20548319,"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":["bypass-firewall","faketcp","shell-script","udp-tunnel","udp2raw","udp2raw-tunnel","vpn","vpn-setup","wireguard","wireguard-tcp","wireguard-vpn","wireguard-vpn-setup"],"created_at":"2025-03-22T21:22:23.279Z","updated_at":"2026-04-12T15:46:11.336Z","avatar_url":"https://github.com/PhrozenByte.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"`wg-udp2raw`\n============\n\nRuns WireGuard over a fake TCP connection using `udp2raw`.\n\n`wg-udp2raw` was created to ease running a [WireGuard](https://www.wireguard.com/) connection over a fake TCP connection using [`udp2raw`](https://github.com/wangyu-/udp2raw). It doesn't just setup `udp2raw` to wrap WireGuard, but also implements a watchdog that periodically checks whether the route to the WireGuard endpoint has changed and restarts `udp2raw` if necessary.\n\nOne can e.g. use hooks to nicely integrate `wg-udp2raw` into WireGuard. You'll find an [example WireGuard config](./etc/wireguard/wg-udp2raw.conf) (check `/etc/wireguard/\u003cconfig\u003e.conf`) intended to be used with [`wg-quick`](https://www.man7.org/linux/man-pages/man8/wg-quick.8.html) in this repository, but any other WireGuard management solution (e.g. NetworkManager) should work equally well if it has support for hooks. Take special care about the example's lower `MTU` of 1342 bytes due to `udp2raw`'s package size limitations, the `PreUp`, `PostUp`, and `PostDown` hooks, as well as the `Endpoint` always pointing to `127.0.0.1` (with an arbitrary local port) to tell WireGuard to connect to the endpoint via `udp2raw`.\n\n`wg-udp2raw` expects the `udp2raw@.service` Systemd unit to start `udp2raw` using the `/etc/udp2raw/\u003cconfig\u003e.conf` config file. `wg-udp2raw` will modify this config file to match what was passed to it as arguments. It will also be responsible for resolving the endpoint's hostname, and adding a direct route to the endpoint via the default interface (i.e. bypassing any VPN and thus not creating a traffic loop). You'll find the correct [`udp2raw` config](./etc/udp2raw/wg-udp2raw.conf) in this repository. It's strongly recommended that the Systemd unit starts `udp2raw` with an unprivileged user. If your distribution doesn't ship `udp2raw` with such Systemd unit, you can find an [example Systemd unit](./etc/systemd/system/udp2raw@.service) in this repository.\n\nOn the endpoint's side one should use a similar `udp2raw@.service` Systemd unit to permanently run a `udp2raw` server instance with matching configuration. On the server's side there's no need for `wg-udp2raw`.\n\n`wg-udp2raw` was written to run with [GNU Bash](https://www.gnu.org/software/bash/). It requires the [iproute2](https://wiki.linuxfoundation.org/networking/iproute2) utilities, [sed](https://sed.sourceforge.io/), [GNU awk](https://www.gnu.org/software/gawk/), [GNU grep](https://www.gnu.org/software/grep/), `getent` from the [GNU C library](https://www.gnu.org/software/libc/), and - obviously - [`udp2raw`](https://github.com/wangyu-/udp2raw) to be installed.\n\nMade with ❤️ by [Daniel Rudolf](https://www.daniel-rudolf.de/) ([@PhrozenByte](https://github.com/PhrozenByte)). `wg-udp2raw` is free and open source software, released under the terms of the [MIT license](LICENSE).\n\nUsage\n-----\n\nTo get started simply install the [`wg-udp2raw.sh`](./wg-udp2raw.sh) script to `/usr/local/lib/wg-udp2raw/wg-udp2raw.sh`, create the [`/etc/wireguard/wg-udp2raw.conf`](./etc/wireguard/wg-udp2raw.conf) and [`/etc/udp2raw/wg-udp2raw.conf`](./etc/udp2raw/wg-udp2raw.conf) configs, make sure that the [`wg-quick@.service`](https://www.man7.org/linux/man-pages/man8/wg-quick.8.html) and [`udp2raw@.service`](./etc/systemd/system/udp2raw@.service) Systemd units are present, and start WireGuard with `systemctl start wg-quick@wg-udp2raw.service`.\n\nThe `wg-udp2raw.sh` script accepts the following arguments:\n\n```console\n$ ./wg-udp2raw.sh --help\nUsage:\n  ./wg-udp2raw.sh up \u003cconfig\u003e \u003cendpoint_hostname\u003e \u003cendpoint_port\u003e \u003clocal_port\u003e\n  ./wg-udp2raw.sh down \u003cconfig\u003e\n  ./wg-udp2raw.sh watchdog \u003cconfig\u003e \u003cinterval\u003e\n```\n\nOn the server's side you don't need `wg-udp2raw`: You simply run both WireGuard and `udp2raw` permanently. The WireGuard setup doesn't differ from your usual setup. For `udp2raw` to work you just need to create a matching server config and start the `udp2raw@.service` Systemd unit permamently (`systemctl enable udp2raw@wg.service` and `systemctl start udp2raw@wg.service`). Here's an example `udp2raw` config (`/etc/udp2raw/wg.config`) for the server:\n\n```\n-s\n-l 0.0.0.0:51820\n-r 127.0.0.1:51820\n--raw-mode faketcp\n--cipher-mode xor\n--auth-mode simple\n-k wg-udp2raw vpn.example.com:51820\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphrozenbyte%2Fwg-udp2raw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphrozenbyte%2Fwg-udp2raw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphrozenbyte%2Fwg-udp2raw/lists"}