wireguard-install: A Bash Script That Sets Up a WireGuard VPN Server on Linux

What wireguard-install Does and the Problem It Solves

Setting up a WireGuard VPN server from scratch requires creating keys, writing interface configuration files, configuring the kernel module, enabling IP forwarding, setting up NAT rules with iptables or nftables, and creating a systemd service to start the tunnel at boot. Each step is documented in WireGuard's own manual, but the correct sequence and exact syntax differ by Linux distribution, kernel version, and IP configuration. wireguard-install collapses all of that into a single interactive script that asks a few questions and handles the rest.

The README defines the use case clearly: a VPN where the client forwards all its traffic through an encrypted tunnel to the server, which applies NAT so the client appears to browse with the server's IP address. This is a specific WireGuard topology, not a point-to-point mesh or a site-to-site connection. The script is designed for that personal or small-team VPN server scenario, not for configuring WireGuard as a network fabric between many peers.

WireGuard itself is a kernel-level VPN protocol. It is not a service that runs in userspace like OpenVPN; on Linux, the WireGuard kernel module handles packet encryption and routing directly. The installer script handles the kernel module installation alongside the WireGuard tools and generates the peer keys and configuration files that the WireGuard tooling needs.

The script also handles ongoing management. After the initial setup, running the script again presents options to add new client profiles or remove existing ones. This removes the need to manually edit configuration files when the client list changes.

Supported Linux Distributions and Version Requirements

wireguard-install works on nine Linux distributions. The README lists them with minimum version requirements:

- AlmaLinux 8 or later - Alpine Linux (no minimum version specified) - Arch Linux (no minimum version specified) - CentOS Stream 8 or later - Debian 10 or later - Fedora 32 or later - Oracle Linux (no minimum version specified) - Rocky Linux 8 or later - Ubuntu 18.04 or later

The distribution list covers the most widely deployed Linux families for cloud servers: the Debian/Ubuntu family, the RHEL-compatible family (AlmaLinux, CentOS Stream, Oracle Linux, Rocky Linux), and two rolling or semi-rolling distributions (Alpine, Arch). Fedora is included as a leading-edge test bed for what will appear in future RHEL-family releases.

Distributions not on the list are not supported. The script does not include logic for other Debian derivatives, older Ubuntu LTS releases, or distributions like openSUSE. The README points to the issue tracker for documentation of ongoing bugs and planned features, and to the discussions section for help.

The minimum versions matter because WireGuard support was added to the mainline Linux kernel at version 5.6. Older distribution releases require a DKMS backport or a third-party kernel package. The script's version minimums correspond to distribution releases that either include WireGuard in the mainline kernel or have an established package for it.

Running the Installer: Download, Permissions, and Execution

Installation requires downloading the script, making it executable, and running it. The README gives these three commands:

curl -O https://raw.githubusercontent.com/angristan/wireguard-install/master/wireguard-install.sh
chmod +x wireguard-install.sh
./wireguard-install.sh

The script runs interactively. It asks questions to determine the server's public IP address, the WireGuard interface name, the listening port, the DNS server to assign to clients, and details for the first client profile. After answering the questions, the script installs the WireGuard kernel module and tools for the detected distribution, writes the wg0.conf interface configuration, enables IP forwarding in the system's sysctl settings, configures NAT rules, creates a systemd service named wg-quick@wg0, and generates a client configuration file.

The client configuration file is what gets loaded on the user's device (phone, laptop, or other endpoint) via the WireGuard app. It contains the server's public key, the server's endpoint (IP and port), the allowed IP ranges to route through the tunnel, and the client's private key. The README describes the output: 'It will install WireGuard (kernel module and tools) on the server, configure it, create a systemd service and a client configuration file.'

To add or remove clients after the initial setup, run the script again with the same command. The script detects that WireGuard is already installed and presents a menu with options to manage clients rather than reinstalling from scratch.

What the Script Configures: NAT, systemd, and IPv4 and IPv6 Support

The README states that wireguard-install supports both IPv4 and IPv6. This matters because VPN servers that handle only IPv4 will cause IPv6 traffic to leak outside the tunnel, exposing the client's real IPv6 address even when the VPN is active. Supporting both protocols allows the server to tunnel all client traffic regardless of whether the destination uses IPv4 or IPv6.

The NAT configuration makes the server act as a masquerading router. Incoming encrypted packets from a client are decrypted by the WireGuard kernel module, then forwarded to the internet with the server's IP address substituted for the client's WireGuard address. Return traffic is routed back through the tunnel to the correct client. This is standard Linux NAT behavior using iptables or nftables, and it is what makes the server appear to be the origin of the client's traffic from the perspective of the destination.

The systemd service (wg-quick@wg0) ensures the WireGuard interface comes up automatically when the server boots and goes down cleanly when the server shuts down. Without the service, the VPN would need to be started manually after each reboot. The wg-quick tool, which systemd calls, reads the wg0.conf configuration file and applies all the interface settings, routing rules, and NAT rules in a single operation.

The script configures these components once during initial setup. Later changes to client lists do not require restarting the WireGuard interface or the systemd service; WireGuard supports hot-adding and hot-removing peers without dropping existing connections.

Limitations: Linux Servers Only, No Pre-Configuration, and Script Scope

wireguard-install is specifically for Linux servers. It cannot set up a WireGuard server on Windows or macOS, and the README does not address running a server on those platforms. The WireGuard project publishes separate apps for Windows, macOS, iOS, and Android to use as clients connecting to a WireGuard server, but those are client-side tools, not server installers.

The script is interactive, which means it cannot be run non-interactively as part of an automated provisioning pipeline without modification. It asks questions at runtime rather than reading configuration from environment variables or a config file. An operator who wants to automate WireGuard server setup as part of infrastructure-as-code would need to adapt the script or use a different approach such as a WireGuard Ansible role.

The script sets up a VPN in the full-tunnel topology described in the README, where all client traffic routes through the server. It does not configure split-tunnel routing (where only specific traffic goes through the VPN) out of the box. Split tunneling would require editing the generated client configuration file to change the AllowedIPs setting from the catch-all 0.0.0.0/0 to specific CIDR ranges.

The script also does not configure any additional access controls, firewall rules beyond what WireGuard requires, or monitoring. The VPN is a network-level construct: once a client has the configuration file, that client has VPN access. There is no authentication layer beyond possession of the private key.

For environments where WireGuard is not suitable, the README links to the companion project openvpn-install, also by angristan, which follows the same interactive script approach but sets up OpenVPN instead. OpenVPN is more widely supported on restrictive networks that block UDP traffic on non-standard ports.

Code Quality, Contribution Process, and Maintenance

The project enforces code quality through shellcheck and shfmt, two standard tools in the bash ecosystem. The README states these tools run on every commit and pull request via GitHub Actions, and the lint workflow configuration is linked directly. shellcheck is a static analysis tool for shell scripts that catches common bugs, undefined variables, and unsafe constructs. shfmt enforces formatting consistency according to a defined style.

For contributions, the README asks that significant changes be discussed in an issue before a pull request is submitted. This is a practical coordination mechanism for a single-file project where parallel pull requests could conflict.

The repository has one top-level file beyond the README and gitignore: wireguard-install.sh. There are no module boundaries or abstractions; the entire installer is one bash script. This means the full logic of what the installer does is visible in one file, which simplifies auditing the script before running it with root privileges. Running any script with root privileges on a server without reading it first is a risk; the single-file structure makes that review practical.

The last push to the repository was on 2026-05-02. The project is under the MIT licence. The repository has no GitHub releases; changes ship to the master branch directly.

Editorial conclusion

Operators who want a WireGuard VPN on a supported Linux distribution and do not need pre-configured parameters will find wireguard-install the fastest route from a bare server to a working VPN. Those running a non-supported distribution, or who need to set up WireGuard on Windows or macOS clients (rather than servers), should consult the WireGuard project's own documentation instead. The MIT licence permits free use and modification of the script. For environments where WireGuard is not a fit, the README points directly to the companion openvpn-install script.

Frequently asked questions

Official sources

1. angristan/wireguard-install on GitHub
2. Issues
3. License: MIT
4. Project website
5. README