{"id":14984491,"url":"https://github.com/n-storm/boringguard","last_synced_at":"2025-06-23T03:40:53.195Z","repository":{"id":214212060,"uuid":"701604607","full_name":"N-Storm/boringguard","owner":"N-Storm","description":"A Wireguard VPN install \u0026 configuration Ansible role with Boringtun userspace implementation.","archived":false,"fork":false,"pushed_at":"2024-06-28T03:26:49.000Z","size":8893,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T20:48:57.197Z","etag":null,"topics":["aarch64","ansible","ansible-role","ansible-roles","arm","arm64","armv7","boringtun","userspace","wireguard","wireguard-configuration","wireguard-server","wireguard-vpn","wireguard-vpn-setup","x86-64"],"latest_commit_sha":null,"homepage":"https://github.com/N-Storm/boringguard","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/N-Storm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.boringtun-cli.txt","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":"2023-10-07T03:20:31.000Z","updated_at":"2025-02-05T01:39:50.000Z","dependencies_parsed_at":"2025-02-18T00:32:16.663Z","dependency_job_id":"6e41dfff-0cb0-4871-ad3b-6514e77513a5","html_url":"https://github.com/N-Storm/boringguard","commit_stats":null,"previous_names":["n-storm/boringguard"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/N-Storm/boringguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N-Storm%2Fboringguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N-Storm%2Fboringguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N-Storm%2Fboringguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N-Storm%2Fboringguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/N-Storm","download_url":"https://codeload.github.com/N-Storm/boringguard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/N-Storm%2Fboringguard/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261406782,"owners_count":23153835,"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":["aarch64","ansible","ansible-role","ansible-roles","arm","arm64","armv7","boringtun","userspace","wireguard","wireguard-configuration","wireguard-server","wireguard-vpn","wireguard-vpn-setup","x86-64"],"created_at":"2024-09-24T14:09:09.531Z","updated_at":"2025-06-23T03:40:48.181Z","avatar_url":"https://github.com/N-Storm.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"Boringguard\n===========\n\nA Wireguard VPN install \u0026 configuration [Ansible](https://ansible.com) role with [Boringtun](https://github.com/cloudflare/boringtun) userspace implementation.\nBoringtun is a userspace Wireguard \"server\" implementation by [CloudFlare](https://www.cloudflare.com/). It works on various architectures and doesn't require\na kernel module to work. This makes it possible to run it under container-type VPS (OpenVZ/Virtuozzo/LXC/etc) without the possibility to load or use additional\nkernel modules. Consequently, you can operate your Wireguard private VPN server even on cheap NAT VPS. However, it has to be TUN/TAP enabled (most providers\nhave an option to enable it).\n\nThis role comes with pre-compiled `boringtun-cli` binaries, packaged in deb and rpm formats. They are unmodified builds from sources as is. They are bundled as\nbinary packages with the playbook because most (if not all) Linux distros lack them in their repos. And I wasn't able to find them in 3rd party trusted repos either.\nIt's actually the most significant reason I created this role for my purposes and decided to share it afterward. But if you're skeptical about using my binary builds,\nyou can build and package your own binaries. Instructions for building those can be found [here](build/README.md).\n\nThis role comes with x86_64 and ARM (armv7 hardfloat and aarch64) packages. Thus, it's possible to install on SBCs like Raspberry Pi, Orange Pi, etc., and on\nplans like Hetzner ARM VPS, for example.\n\nSupported architectures\n-----------------------\n\n- x86_64\n- aarch64 (ARM64)\n- ARMv7 Hardfloat\n\nSupported target distros\n------------------------\n\n- Debian 11, 12 (recommended)\n- Ubuntu 20.04, 22.04\n- EL (CentOS, RHEL, RockyLinux, AlmaLinux, Oracle Linux) 8, 9\n\nThe execution of this playbook has been tested on Debian 11 \u0026 12 as the Ansible host.\n\nUsage\n-----\n\nIf you aren't familiar with Ansible or looking for a quick start, take a look at this guide: [QUICKSTART.md](QUICKSTART.md).\n\nInstall `ansible` \u0026 `qrencode` packages. Make sure you have the ansible.posix collection installed (`ansible-galaxy collection list`). Debian 11, 12 will have it\ninstalled with the ansible package (you can check this with `ansible-galaxy collection list`).\n\nPlace this role under your Ansible directory/roles/boringguard. Create `configs` and `configs/wireguard` directories under the same path where your playbook\nis located. This role won't create them itself.\nMake your playbook (you can use the included [boringguard.yaml](boringguard.yaml) as an example) and include this role.\nYou can configure settings by adjusting role variables (see below for description) or by editing the locally saved config in the 'configs' directory later. This\nrole can also be selected by the tag `boringguard`.\n\n#### Run playbook:\n\n```shell\nansible-playbook [-v] [-i your_inventory_path] [-l target_hosts] [-t boringguard] playbook.yaml\n```\n\nAfter the first successful run, it will save the complete generated host config under the `configs` directory (named `boringguard-cfg-\u003cansible host\u003e.yaml`)\nwhere it will store all host parameters (generated keys, PSK, and settings). On the next run (if this config file exists), it will apply settings from it (unless\nthe `wg_override_config` variable is set to true) to make sure things like Wireguard keys won't change on successive runs (so you can adjust settings, like changing\nport or adding more peers). So, if you need to change some settings without generating new keys, you must edit this file.\n\nPeer (client) configs will be saved under the `configs/wireguard` directory. Named `\u003cansible host\u003e-PeerN.conf` and `\u003cansible host\u003e-qrcode.(txt|png)`. You can use\neither of them to add the config to the Wireguard client.\n\nRequirements\n------------\n\n- `qrencode` installed on the Ansible host.\n\nDependencies\n------------\n\n- [ansible.posix.sysctl module](https://docs.ansible.com/ansible/latest/collections/ansible/posix/sysctl_module.html)\n\nRole Variables\n--------------\n\nThese are either set to \"weak\" defaults or unset. So you can configure them anywhere you like - hostvars, group vars, playbook, etc.\nEven in the role vars file, or with the ansible-playbook command-line key `-e`. You can also modify the defaults file, but it's not recommended.\n\n- `wg_host`: hostname of your server (defaults to ansible hostname).\n- `wg_port`: listen port (default: 51820).\n- `wg_iface`: interface to listen on, must specify one (default: eth0).\n- `wg_npeers`: number of peers (clients) to create during initial setup (default: 1).\n- `wg_public_ip`: IPv4 address the host can be seen on the Internet. If you are behind NAT, this should still be set to the correct public IP (default: autodiscover).\n- `wg_use_public_ip`: use public IP instead of IP configured on interface `wg_iface` for setup (boolean, default: false).\n- `wg_override_config`: allow doing the initial install from scratch, overriding existing config (boolean, default: not set).\n\nExample Playbook\n----------------\n\nSee [boringguard.yaml](boringguard.yaml).\n\nLicense\n-------\n\nMozilla Public License Version 2.0\n\nBoringtun is licensed under the BSD-3-Clause license. See [LICENSE.boringtun-cli.txt](LICENSE.boringtun-cli.txt) for details.\n\nInspired by [Nyr wireguard-install script](https://github.com/Nyr/wireguard-install).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-storm%2Fboringguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn-storm%2Fboringguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-storm%2Fboringguard/lists"}