{"id":17929823,"url":"https://github.com/valdikss/nat-traversal-github-actions-openvpn-wireguard","last_synced_at":"2025-05-11T00:56:20.048Z","repository":{"id":50712290,"uuid":"519895627","full_name":"ValdikSS/nat-traversal-github-actions-openvpn-wireguard","owner":"ValdikSS","description":"OpenVPN and WireGuard server on GitHub Actions: representative NAT traversal case","archived":false,"fork":false,"pushed_at":"2023-04-26T21:44:56.000Z","size":11,"stargazers_count":205,"open_issues_count":0,"forks_count":33,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-31T21:42:46.547Z","etag":null,"topics":["nat","nat-hole-punching","nat-traversal","openvpn","udp-hole-punching","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ValdikSS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-07-31T21:57:37.000Z","updated_at":"2025-03-24T23:35:25.000Z","dependencies_parsed_at":"2024-04-16T06:37:52.288Z","dependency_job_id":"78c5bef1-bb69-47e4-9cb8-7fc0b96bbdcb","html_url":"https://github.com/ValdikSS/nat-traversal-github-actions-openvpn-wireguard","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValdikSS%2Fnat-traversal-github-actions-openvpn-wireguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValdikSS%2Fnat-traversal-github-actions-openvpn-wireguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValdikSS%2Fnat-traversal-github-actions-openvpn-wireguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValdikSS%2Fnat-traversal-github-actions-openvpn-wireguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ValdikSS","download_url":"https://codeload.github.com/ValdikSS/nat-traversal-github-actions-openvpn-wireguard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253330826,"owners_count":21891848,"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":["nat","nat-hole-punching","nat-traversal","openvpn","udp-hole-punching","wireguard"],"created_at":"2024-10-28T21:10:39.515Z","updated_at":"2025-05-09T21:43:53.547Z","avatar_url":"https://github.com/ValdikSS.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"OpenVPN and WireGuard server on GitHub Actions: representative NAT traversal case\n=========================\n\nIt's not possible to run server software on GitHub Actions using regular methods: the worker virtual machine is placed behind Network Address Translation (NAT), which prevents it from receiving direct inbound TCP/UDP connections.  \nThis repository consists of GitHub Actions jobs for OpenVPN and WireGuard VPN servers which traverse NAT, making possible to establish VPN connection to the Actions worker machine directly, without any additional tunnel, third-party service, or port forwarding software.\n\nThis is a **step-by-step, thoroughly documented practical UDP NAT traversal showcase using GitHub Actions with OpenVPN/WireGuard servers as an example, with only stock software from Ubuntu repositories**.\n\nNAT used on GitHub Actions is one of the most common ones: it's not the friendliest and not the ugliest.\n\n\u003e Independent Mapping, Port Dependent Filter, random port, will hairpin\n\nOnce you learn the traversal principle used in this repository, you'll understand the general idea behind any modern NAT traversal implementation.\n\n## How to use\n\nIt is assumed that you run Linux.\n\n1. Fork this repository and clone your fork\n2. Place your SSH public key into `authorized_keys` file, git commit it\n3. Make sure you have `stun-client` by hanpfei installed (`apt install stun-client` on Debian/Ubuntu, `dnf install stun` on Fedora), as well as `openvpn` and/or `wireguard`\n3. Run `./run.sh openvpn` for OpenVPN server or `./run.sh wireguard` for WireGuard server\n4. Navigate to **Actions** tab of your repository, open corresponding job and check either `Print OpenVPN connection string` or `Print WireGuard configuration file` for VPN connection instructions\n5. Connect to the VPN using the instructions from the Action\n6. After connecting to the VPN, run `ssh root@192.168.166.1` to connect to your Actions worker\n\nNOTE: your IP address will be visible in the commit history for everyone. Set the repository as private if you find this inappropriate for your threat model.\n\n## How does it work\n\nThe Action jobs ([openvpn](https://github.com/ValdikSS/nat-traversal-github-actions-openvpn-wireguard/blob/master/.github/workflows/openvpn-server.yml), [wireguard](https://github.com/ValdikSS/nat-traversal-github-actions-openvpn-wireguard/blob/master/.github/workflows/wireguard-server.yml)) in this repository:\n\n* Wait for a specific commit message with IP address and port of the client\n* Set up OpenVPN UDP/WireGuard server behind Actions worker NAT\n* Determine external IP address and NAT port mapping for VPN port using STUN client\n* Punch NAT with empty UDP packet every 28 seconds towards client's IP address and port from the VPN server port using `nping` until the client is connected\n\nThe client-side run.sh script:\n\n* Checks for NAT type on the client\n* Determines mapped external source port using STUN\n* git commits \u0026 pushes client's external IP address and mapped port discovered with STUN, as well as local source port to include it in configuration files and one-liners generated by the Actions job\n* Keeps NAT mapping alive for non-port-preserving NATs\n\n## Questions and answers\n\n#### ‣ Does it work?\n\nYes, it bypasses NAT for UDP traffic of GitHub Actions worker running on Microsoft Azure infrastructure behind NAT of the following type:\n\n\u003e Independent Mapping, Port Dependent Filter, random port, will hairpin\n\nYou will be able to connect to WireGuard/OpenVPN server running on your Actions worker directly, which is not possible otherwise.\n\n#### ‣ But can I connect to it behind another NAT, from the client side?\n\nYes, you can connect to it if you're behind the most common NAT with \"Independent Mapping\" characteristics, either port-preserving or non-port-preserving (random port).\n\n`run.sh` script will do everything for you, including NAT type identification.\n\n#### ‣ Independent mapping? Port preserving? I know only Cone and Symmetric NAT!\n\nThe cone/port-restricted/symmetric NAT nomenclature is a bit outdated and does not describe all the NAT types found on the real Internet precisely.  \nActions worker is placed after port-restricted NAT (which also does not preserve the source port).\n\n*For NAT type identification, refer to [RFC4787](https://datatracker.ietf.org/doc/html/rfc4787) and [RFC5128](https://datatracker.ietf.org/doc/html/rfc5128)*\n\n#### ‣ Where can I get more information?\n\nThe Actions workflow files (jobs) has detailed comments for each step, read it for [openvpn](https://github.com/ValdikSS/nat-traversal-github-actions-openvpn-wireguard/blob/master/.github/workflows/openvpn-server.yml) and [wireguard](https://github.com/ValdikSS/nat-traversal-github-actions-openvpn-wireguard/blob/master/.github/workflows/wireguard-server.yml)\n\nGeneral NAT traversal information:\n\n* https://bford.info/pub/net/p2pnat/\n* https://tailscale.com/blog/how-nat-traversal-works/\n\nEven more detailed writeup, covering all NAT aspects, will follow later.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaldikss%2Fnat-traversal-github-actions-openvpn-wireguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaldikss%2Fnat-traversal-github-actions-openvpn-wireguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaldikss%2Fnat-traversal-github-actions-openvpn-wireguard/lists"}