From a4e647ce71480e7ff18ac805fd293ed700d5fc3b Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Sun, 3 Aug 2025 17:20:58 -0400 Subject: [PATCH] docs: Add Windows client documentation and common error fix (#14787) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added comprehensive Windows client setup guide (docs/client-windows.md) - Documented the common "parameter is incorrect" error in troubleshooting.md - Added step-by-step solution for Windows networking stack reset - Included WireGuard setup instructions and common issues - Added Windows documentation links to README.md This addresses the frequently reported issue #1051 where Windows users encounter "parameter is incorrect" errors when connecting to Algo VPN. The fix involves resetting Windows networking components and has helped many users resolve their connection issues. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude --- README.md | 3 +- docs/client-windows.md | 95 +++++++++++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 38 +++++++++++++++++ 3 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 docs/client-windows.md diff --git a/README.md b/README.md index 2bcf2d04..b1939169 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ WireGuard is used to provide VPN services on Android. Install the [WireGuard VPN WireGuard is used to provide VPN services on Windows. Algo generates a WireGuard configuration file, `wireguard/.conf`, for each user defined in `config.cfg`. -Install the [WireGuard VPN Client](https://www.wireguard.com/install/#windows-7-8-81-10-2012-2016-2019). Import the generated `wireguard/.conf` file to your device, then setup a new connection with it. +Install the [WireGuard VPN Client](https://www.wireguard.com/install/#windows-7-8-81-10-2012-2016-2019). Import the generated `wireguard/.conf` file to your device, then setup a new connection with it. See the [Windows setup instructions](docs/client-windows.md) for more detailed walkthrough and troubleshooting. ### Linux WireGuard Clients @@ -210,6 +210,7 @@ After this process completes, the Algo VPN server will contain only the users li * Deploy from a [Docker container](docs/deploy-from-docker.md) ### Setup VPN Clients to Connect to the Server +* Setup [Windows](docs/client-windows.md) clients * Setup [Android](docs/client-android.md) clients * Setup [Linux](docs/client-linux.md) clients with Ansible * Setup Ubuntu clients to use [WireGuard](docs/client-linux-wireguard.md) diff --git a/docs/client-windows.md b/docs/client-windows.md new file mode 100644 index 00000000..8bc03db7 --- /dev/null +++ b/docs/client-windows.md @@ -0,0 +1,95 @@ +# Windows Client Setup + +This guide will help you set up your Windows device to connect to your Algo VPN server. + +## Supported Versions + +- Windows 10 (all editions) +- Windows 11 (all editions) +- Windows Server 2016 and later + +## WireGuard Setup (Recommended) + +WireGuard is the recommended VPN protocol for Windows clients due to its simplicity and performance. + +### Installation + +1. Download and install the official [WireGuard client for Windows](https://www.wireguard.com/install/) +2. Locate your configuration file: `configs//wireguard/.conf` +3. In the WireGuard application, click "Import tunnel(s) from file" +4. Select your `.conf` file and import it +5. Click "Activate" to connect to your VPN + +### Alternative Import Methods + +- **QR Code**: If you have access to the QR code (`wireguard/.png`), you can scan it using a mobile device first, then export the configuration +- **Manual Entry**: You can create a new empty tunnel and paste the contents of your `.conf` file + +## IPsec/IKEv2 Setup (Legacy) + +While Algo supports IPsec/IKEv2, it requires PowerShell scripts for Windows setup. WireGuard is strongly recommended instead. + +If you must use IPsec: +1. Locate the PowerShell setup script in your configs directory +2. Run PowerShell as Administrator +3. Execute the setup script +4. The VPN connection will appear in Settings → Network & Internet → VPN + +## Troubleshooting + +### "The parameter is incorrect" Error + +This is a common error that occurs when trying to connect. See the [troubleshooting guide](troubleshooting.md#windows-the-parameter-is-incorrect-error-when-connecting) for the solution. + +### Connection Issues + +1. **Check Windows Firewall**: Ensure Windows Firewall isn't blocking the VPN connection +2. **Verify Server Address**: Make sure the server IP/domain in your configuration is correct +3. **Check Date/Time**: Ensure your system date and time are correct +4. **Disable Other VPNs**: Disconnect from any other VPN services before connecting + +### WireGuard Specific Issues + +- **DNS Not Working**: Check if "Block untunneled traffic (kill-switch)" is enabled in tunnel settings +- **Slow Performance**: Try reducing the MTU in the tunnel configuration (default is 1420) +- **Can't Import Config**: Ensure the configuration file has a `.conf` extension + +### Performance Optimization + +1. **Use WireGuard**: It's significantly faster than IPsec on Windows +2. **Close Unnecessary Apps**: Some antivirus or firewall software can slow down VPN connections +3. **Check Network Adapter**: Update your network adapter drivers to the latest version + +## Advanced Configuration + +### Split Tunneling + +To exclude certain traffic from the VPN: +1. Edit your WireGuard configuration file +2. Modify the `AllowedIPs` line to exclude specific networks +3. For example, to exclude local network: Remove `0.0.0.0/0` and add specific routes + +### Automatic Connection + +To connect automatically: +1. Open WireGuard +2. Select your tunnel +3. Edit → Uncheck "On-demand activation" +4. Windows will maintain the connection automatically + +### Multiple Servers + +You can import multiple `.conf` files for different Algo servers. Give each a descriptive name to distinguish them. + +## Security Notes + +- Keep your configuration files secure - they contain your private keys +- Don't share your configuration with others +- Each user should have their own unique configuration +- Regularly update your WireGuard client for security patches + +## Need More Help? + +- Check the main [troubleshooting guide](troubleshooting.md) +- Review [WireGuard documentation](https://www.wireguard.com/quickstart/) +- [Create a discussion](https://github.com/trailofbits/algo/discussions) for help \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 5d6d4881..e695857e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -19,6 +19,7 @@ First of all, check [this](https://github.com/trailofbits/algo#features) and ens * [Azure: The client xxx with object id xxx does not have authorization to perform action Microsoft.Resources/subscriptions/resourcegroups/write' over scope](#azure-deployment-permissions-error) * [Windows: The value of parameter linuxConfiguration.ssh.publicKeys.keyData is invalid](#windows-the-value-of-parameter-linuxconfigurationsshpublickeyskeydata-is-invalid) * [Docker: Failed to connect to the host via ssh](#docker-failed-to-connect-to-the-host-via-ssh) + * [Windows: "The parameter is incorrect" error when connecting](#windows-the-parameter-is-incorrect-error-when-connecting) * [Error: Failed to create symlinks for deploying to localhost](#error-failed-to-create-symlinks-for-deploying-to-localhost) * [Wireguard: Unable to find 'configs/...' in expected paths](#wireguard-unable-to-find-configs-in-expected-paths) * [Ubuntu Error: "unable to write 'random state'" when generating CA password](#ubuntu-error-unable-to-write-random-state-when-generating-ca-password) @@ -294,6 +295,43 @@ You need to add the following to the ansible.cfg in repo root: control_path_dir=/dev/shm/ansible_control_path ``` +### Windows: "The parameter is incorrect" error when connecting + +When trying to connect to your Algo VPN on Windows 10/11, you may receive an error stating "The parameter is incorrect". This is a common issue that can usually be resolved by resetting your Windows networking stack. + +#### Solution + +1. **Clear the networking caches** + + Open Command Prompt as Administrator (right-click on Command Prompt and select "Run as Administrator") and run these commands: + ```cmd + netsh int ip reset + netsh int ipv6 reset + netsh winsock reset + ``` + + Then restart your computer. + +2. **Reset Device Manager network adapters** (if step 1 doesn't work) + + - Open Device Manager + - Find "Network Adapters" + - Uninstall all WAN Miniport drivers (IKEv2, IP, IPv6, etc.) + - Click Action → Scan for hardware changes + - The adapters you just uninstalled should reinstall automatically + + Try connecting to the VPN again. + +#### What causes this issue? + +This error typically occurs when: +- Windows networking stack becomes corrupted +- After Windows updates that affect network drivers +- When switching between different VPN configurations +- After network-related software installations/uninstallations + +Note: This issue has been reported by many users and the above solution has proven effective in most cases. + ### Error: Failed to create symlinks for deploying to localhost You tried to run Algo and you received an error like this one: