{"id":13496012,"url":"https://github.com/psyhomb/wireguard-tools","last_synced_at":"2025-03-28T17:34:41.665Z","repository":{"id":45284106,"uuid":"270302282","full_name":"psyhomb/wireguard-tools","owner":"psyhomb","description":"Wireguard helper scripts","archived":false,"fork":false,"pushed_at":"2023-11-10T09:29:42.000Z","size":139,"stargazers_count":185,"open_issues_count":2,"forks_count":25,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-31T11:36:50.802Z","etag":null,"topics":["linux","scripts","tools","vpn","wg","wireguard"],"latest_commit_sha":null,"homepage":"https://gitlab.com/psyhomb/wireguard-tools","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/psyhomb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"psyhomb","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2020-06-07T12:38:58.000Z","updated_at":"2024-10-23T10:33:00.000Z","dependencies_parsed_at":"2024-01-14T09:09:44.689Z","dependency_job_id":"09290ea3-7899-4daa-8674-89d11d685435","html_url":"https://github.com/psyhomb/wireguard-tools","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/psyhomb%2Fwireguard-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psyhomb%2Fwireguard-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psyhomb%2Fwireguard-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psyhomb%2Fwireguard-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/psyhomb","download_url":"https://codeload.github.com/psyhomb/wireguard-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246069805,"owners_count":20718795,"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":["linux","scripts","tools","vpn","wg","wireguard"],"created_at":"2024-07-31T19:01:40.714Z","updated_at":"2025-03-28T17:34:41.368Z","avatar_url":"https://github.com/psyhomb.png","language":"Shell","readme":"wireguard-tools\n===============\n\nFull documentation about manual Wireguard installation and configuration process can be found [here](https://gitlab.com/snippets/1897102).\n\nwgcg.sh\n-------\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"images/wgcg.png\" /\u003e\n\u003c/div\u003e\n\n### About\n\nThis script is created to ease manual process of Wireguard configuration and will help you to automatically generate all the required configuration files (client and server), PKI key pairs and preshared key.\n\n### Install dependencies\n\n**Arch**\n\n```bash\npacman -S wireguard-tools gnupg qrencode\nyay grepcidr\n```\n\n**Ubuntu**\n\n```bash\napt-get install wireguard-tools gpg qrencode grepcidr\n```\n\n**MacOS**\n\n```bash\nbrew install wireguard-tools gpg qrencode grepcidr\n```\n\nMake sure to append following line to [wgcg.conf](./wgcg.conf) file only if using MacOS.  \nBy doing this we will force script to use GNU instead of BSD command line utilities (e.g. `grep`) and prevent any possible incompatibility issues.\n\n```bash\necho -e '\\n# Make sure script is using GNU command line utilities on MacOS\\nexport PATH=\"/usr/local/opt/grep/libexec/gnubin:${PATH}\"' \u003e\u003e wgcg.conf\n```\n\n### Usage\n\nBefore running the script we'll have to update [wgcg.conf](./wgcg.conf) configuration file.  \nFor most use cases the only variable we'd have to modify is `WGCG_SERVER_PUBLIC_IP`.\n\n```bash\n# Server name (wireguard interface name e.g. wg0 || wg1 || wg2)\nWGCG_SERVER_NAME=\"wg0\"\n\n# HostMin to HostMax range can be used to assign IP addresses to WireGuard clients\n# e.g. ./wgcg.sh -c foo 10.0.0.2\n#\n# Network: 10.0.0.0/22\n# HostMin: 10.0.0.1\n# HostMax: 10.0.3.254\n# HostIDs: 1022\n#\n# WireGuard server private IP address (with optional CIDR - default: 22)\nWGCG_SERVER_WG_IP=\"10.0.0.1\"\n\n# Static server port\nWGCG_SERVER_PORT=\"52001\"\n\n# Server's public IP or FQDN\nWGCG_SERVER_PUBLIC_IP=\"wg.yourdomain.com\"\n\n# SSH server IP address (default: ${WGCG_SERVER_PUBLIC_IP}) (optional)\n# Note: This option can be used in case SSH server is listening on different IP address,\n#       if not specified, ${WGCG_SERVER_PUBLIC_IP} will be used instead\nWGCG_SERVER_SSH_IP=\"\"\n\n# SSH server port (optional)\nWGCG_SERVER_SSH_PORT=\"22\"\n\n# Space separated list of DNS IPs (default: 1.1.1.1 1.0.0.1) (optional)\nWGCG_CLIENT_DNS_IPS=\"1.1.1.1 1.0.0.1\"\n\n# Space separated list of subnets (with CIDR) required for split-tunneling (default: 0.0.0.0/0) (optional)\nWGCG_CLIENT_ALLOWED_IPS=\"0.0.0.0/0\"\n\n# All configuration and key files will be stored in this directory\nWGCG_WORKING_DIR=\"${HOME}/wireguard/${WGCG_SERVER_NAME}\"\n```\n\nCopy [wgcg.conf](./wgcg.conf) and [wgfw.rules](./wgfw.rules) files to `wgcg` directory.\n\n```bash\nmkdir -p ${HOME}/wireguard/wgcg\ncp wgcg.conf ${HOME}/wireguard/wgcg/\ncp wgfw.rules ${HOME}/wireguard/wgcg/\n```\n\nCopy [wgcg.sh](./wgcg.sh) script to `/usr/local/bin` directory.\n\n```bash\ncp wgcg.sh /usr/local/bin/\n```\n\nIt is also possible to specify custom configuration file by passing `WGCG_CONFIG_FILE` environment variable.\n\n```bash\nWGCG_CONFIG_FILE=\"${HOME}/wireguard/wgcg/wgcg.conf\" wgcg.sh\n```\n\nPrint help and current default options.\n\n```bash\nwgcg.sh -h\n```\n\nOutput:\n\n```plain\nUsage:\n  wgcg.sh options\n\nOptions:\n  -P|--sysprep filename.sh                                  Install WireGuard kernel module, required tools and scripts (will establish SSH connection with server)\n  -s|--add-server-config                                    Generate server configuration\n  -c|--add-client-config client_name client_wg_ip           Generate client configuration\n  -B|--add-clients-batch filename.csv[:rewrite|:norewrite]  Generate configuration for multiple clients in batch mode\n                                                            Supported action modes are 'rewrite' or 'norewrite' (default)\n                                                            'rewrite' action mean regenerate ALL, 'norewrite' mean generate only configs and keys for new clients\n  -e|--encrypt-config client_name [passphrase]              Encrypt configuration file by using symmetric encryption (if passphrase not specified it will be generated - RECOMMENDED)\n  -d|--decrypt-config client_name                           Decrypt configuration file and print it out on stdout\n  -r|--rm-client-config client_name                         Remove client configuration\n  -q|--gen-qr-code client_name [-]                          Generate QR code (PNG format) from client configuration file, if - is used, QR code will be printed out on stdout instead\n  -l|--list-used-ips                                        List all clients IPs that are currently in use\n  -S|--sync                                                 Synchronize server configuration (will establish SSH connection with server)\n  -h|--help                                                 Show this help\n\nCurrent default options:\n  WGCG_SERVER_NAME=\"wg0\"\n  WGCG_SERVER_WG_IP=\"10.0.0.1\"\n  WGCG_SERVER_PORT=\"52001\"\n  WGCG_SERVER_PUBLIC_IP=\"wg.yourdomain.com\"\n  WGCG_SERVER_SSH_PORT=\"22\"\n  WGCG_CLIENT_DNS_IPS=\"1.1.1.1 1.0.0.1\"\n  WGCG_CLIENT_ALLOWED_IPS=\"0.0.0.0/0\"\n  WGCG_WORKING_DIR=\"/home/username/wireguard/wg0\"\n```\n\n[wgcg-install-wireguard.sh](./modules/wgcg-install-wireguard.sh) module will do all required system preparations on the WireGuard server (running the module is idempotent operation):\n\n- Install `wireguard` kernel module and tools\n- Load the module\n- Generate `wgfw.sh` script\n- Enable IP forwarding (routing)\n\n**Note:** You have to run it only once!\n\n```bash\nwgcg.sh --sysprep modules/wgcg-install-wireguard.sh\n```\n\nGenerate server keys and config.\n\n```bash\nwgcg.sh -s\n```\n\nGenerate client config, PKI key pairs and update server config (add new Peer block)\n\n```bash\nwgcg.sh -c foo 10.0.0.2\n```\n\nor to generate multiple client configs at once, create `client-configs.csv` file\n\n```bash\ncat \u003e client-configs.csv \u003c\u003c'EOF'\nfoo,10.0.0.2\nbar,10.0.0.3\nEOF\n```\n\nand run.\n\n```bash\nwgcg.sh -B client-configs.csv\n```\n\nBy default `-B` will only generate client config and key files for newly added clients, if you plan to regenerate config and key files for ALL clients that are specified in the csv file,\nyou'll have to use `rewrite` action mode, globally or per client line, in case both are specified last one has precedence.\n\nGlobal `rewrite` action mode\n\n```bash\nwgcg.sh -B client-configs.csv:rewrite\n```\n\nor per client line.\n\n**Note:** It is also possible to protect individual client from regenerating config and key files by specifying `norewrite` action.\n\n```bash\ncat \u003e client-configs.csv \u003c\u003c'EOF'\nfoo,10.0.0.2,rewrite\nbar,10.0.0.3,norewrite\nEOF\n```\n\nRemove client config, PKI key pairs and update server config (remove Peer block).\n\n```bash\nwgcg.sh -r foo\n```\n\nSynchronize local server configuration file with server (live update).\n\n```bash\nwgcg.sh --sync\n```\n\nIn order to send client configuration file to a person safely, you can use GPG symmetric encryption to encrypt data before sending it, then you can send configuration file to a person via one channel ([webwormhole](https://webwormhole.io)) and passphrase via different channel ([ots](https://github.com/sniptt-official/ots)).\n\nEncrypt configuration file.\n\n```bash\nwgcg.sh -e foo\n```\n\nTo test passphrase just run decrypt command, if everything is OK client configuration will be printed out on the standard output.\n\n```bash\nwgcg.sh -d foo\n```\n\n### Multi-Configuration\n\nIt is also possible to manage multiple clusters with single script.  \nCreate configuration file and command alias for every cluster.\n\n**Note:** Append following lines to `~/.zshrc` or `~/.bashrc` file.\n\n```bash\nalias wgcg-office1.sh=\"WGCG_CONFIG_FILE=${HOME}/wireguard/wgcg/office1.conf wgcg.sh\"\nalias wgcg-office2.sh=\"WGCG_CONFIG_FILE=${HOME}/wireguard/wgcg/office2.conf wgcg.sh\"\n```\n\n```bash\nsource ~/.zshrc\n# or\nsource ~/.bashrc\n```\n\n```bash\nwgcg-office1.sh -h\n```\n\n### Firewall rules\n\nCustom firewall rules, in iptables compatible format, can be added using [wgfw.rules](./wgfw.rules) file. All rules from this file are going to be applied in idempotent manner on the server side at server startup time or each time `wgcg.sh --sync` command is executed.\n\n### Demo\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/1824874/87230971-8a97fc00-c3b3-11ea-98eb-309591c0b616.gif\" /\u003e\n\u003c/div\u003e\n\n### Docker\n\nIt is also possible to run the script inside of Docker container with already preinstalled dependecies.\n\nBuild docker image.\n\n```bash\ndocker build --no-cache --force-rm --build-arg USER=${USER} --build-arg UID=${UID} -t wgcg .\n```\n\nRun the script.\n\n```bash\n./wgcg-docker.sh -h\n```\n\nor if you are not using default configuration filename (`wgcg.conf`).\n\n```bash\nWGCG_CONFIG_FILE=\"${HOME}/wireguard/wgcg/wg0.conf\" ./wgcg-docker.sh -h\n```\n\n### Monitoring\n\n#### Prometheus\n\n- [prometheus_wireguard_exporter](https://github.com/MindFlavor/prometheus_wireguard_exporter)\n\n#### Grafana\n\n- [wireguard-dashboard.json](./monitoring/wireguard-dashboard.json)\n","funding_links":["https://ko-fi.com/psyhomb"],"categories":["Shell","Projects"],"sub_categories":["User Interface"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsyhomb%2Fwireguard-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpsyhomb%2Fwireguard-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsyhomb%2Fwireguard-tools/lists"}