wallenstein/algo
1
0
Fork 0
mirror of https://github.com/trailofbits/algo.git synced 2025-09-03 10:33:13 +02:00
Code Issues Projects Releases Wiki Activity

Add native Windows support with PowerShell script

Browse source 
- Create algo.ps1 for native Windows deployment
- Auto-install uv via winget/scoop with download fallback
- Support update-users command like Unix version
- Add PowerShell linting to CI pipeline with PSScriptAnalyzer
- Update documentation with Windows-specific instructions
- Streamline deploy-from-windows.md with clearer options

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Dan Guido 2025-08-06 04:50:10 -07:00
parent 2226e505a6
commit 51a913c4a5
5 changed files with 247 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
.github/workflows/lint.yml vendored
View file

@ -84,3 +84,47 @@ jobs:
sudo apt-get update && sudo apt-get install -y shellcheck
# Check all shell scripts, not just algo and install.sh
find . -type f -name "*.sh" -not -path "./.git/*" -exec shellcheck {} \;
powershell-lint:
name: PowerShell script linting
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- name: Install PowerShell
run: |
# Install PowerShell Core
wget -q https://github.com/PowerShell/PowerShell/releases/download/v7.4.0/powershell_7.4.0-1.deb_amd64.deb
sudo dpkg -i powershell_7.4.0-1.deb_amd64.deb
sudo apt-get install -f
- name: Install PSScriptAnalyzer
run: |
pwsh -Command "Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser"
- name: Run PowerShell syntax check
run: |
# Check syntax by parsing the script
pwsh -NoProfile -NonInteractive -Command "
try {
\$null = [System.Management.Automation.PSParser]::Tokenize((Get-Content -Path './algo.ps1' -Raw), [ref]\$null)
Write-Host '✓ PowerShell syntax check passed'
} catch {
Write-Error 'PowerShell syntax error: ' + \$_.Exception.Message
exit 1
}
"
- name: Run PSScriptAnalyzer
run: |
pwsh -Command "
\$results = Invoke-ScriptAnalyzer -Path './algo.ps1' -Severity Warning,Error
if (\$results.Count -gt 0) {
\$results | Format-Table -AutoSize
exit 1
} else {
Write-Host '✓ PSScriptAnalyzer check passed'
}
"

8
CLAUDE.md
View file

@ -94,6 +94,11 @@ select = ["E", "W", "F", "I", "B", "C4", "UP"]
- Quote all variables: `"${var}"`
- Use `set -euo pipefail` for safety
#### PowerShell Scripts (PSScriptAnalyzer)
- Use approved verbs (Get-, Set-, New-, etc.)
- Avoid positional parameters in functions
- Use proper error handling with try/catch
#### Ansible (ansible-lint)
- Many warnings are suppressed in `.ansible-lint`
- Focus on errors, not warnings
@ -130,6 +135,9 @@ ansible-lint
yamllint .
ruff check .
shellcheck *.sh
# PowerShell (if available)
pwsh -Command "Invoke-ScriptAnalyzer -Path ./algo.ps1"
```
## Common Issues and Solutions

17
README.md
View file

@ -43,12 +43,19 @@ The easiest way to get an Algo server running is to run it on your local system
3. **Set your configuration options.** Open `config.cfg` in your favorite text editor. Specify the users you want to create in the `users` list. Create a unique user for each device you plan to connect to your VPN. You should also review the other options before deployment, as changing your mind about them later [may require you to deploy a brand new server](https://github.com/trailofbits/algo/blob/master/docs/faq.md#i-deployed-an-algo-server-can-you-update-it-with-new-features).
4. **Start the deployment.** Return to your terminal. In the Algo directory, run `./algo` and follow the instructions:
4. **Start the deployment.** Return to your terminal. In the Algo directory, run the appropriate script for your platform:
**macOS/Linux:**
```bash
./algo
```
The first time you run `./algo`, it will automatically install the required Python environment (Python 3.11+). On subsequent runs, it starts immediately and works on all platforms (macOS, Linux, Windows). There are several optional features available, none of which are required for a fully functional VPN server. These optional features are described in the [deployment documentation](docs/deploy-from-ansible.md).
**Windows:**
```powershell
.\algo.ps1
```
The first time you run the script, it will automatically install the required Python environment (Python 3.11+). On subsequent runs, it starts immediately and works on all platforms (macOS, Linux, Windows). There are several optional features available, none of which are required for a fully functional VPN server. These optional features are described in the [deployment documentation](docs/deploy-from-ansible.md).
That's it! You can now set up clients to connect to your VPN. Proceed to [Configure the VPN Clients](#configure-the-vpn-clients) below.
@ -156,10 +163,16 @@ For IPsec users: You must have selected `yes` at the `Do you want to retain the
To add or remove users, first edit the `users` list in your `config.cfg` file. Add new usernames or remove existing ones as needed. Then navigate to the algo directory in your terminal and run:
**macOS/Linux:**
```bash
./algo update-users
```
**Windows:**
```powershell
.\algo.ps1 update-users
```
After the process completes, new configuration files will be generated in the `configs` directory for any new users. The Algo VPN server will be updated to contain only the users listed in the `config.cfg` file. Removed users will no longer be able to connect, and new users will have fresh certificates and configuration files ready for use.
## Additional Documentation

113
algo.ps1 Normal file
View file

@ -0,0 +1,113 @@
# PowerShell script for Windows users to run Algo VPN
param(
[Parameter(ValueFromRemainingArguments)]
[string[]]$Arguments
)
# Function to install uv via package managers
function Install-UvViaPackageManager {
Write-Host "Attempting to install uv via system package manager..."
# Try winget (Windows Package Manager)
if (Get-Command winget -ErrorAction SilentlyContinue) {
Write-Host "Using winget..."
try {
winget install --id=astral-sh.uv -e --silent
return $true
} catch {
Write-Host "winget installation failed: $($_.Exception.Message)"
}
}
# Try scoop
if (Get-Command scoop -ErrorAction SilentlyContinue) {
Write-Host "Using scoop..."
try {
scoop install uv
return $true
} catch {
Write-Host "scoop installation failed: $($_.Exception.Message)"
}
}
return $false
}
# Function to install uv via download (with user consent)
function Install-UvViaDownload {
Write-Host ""
Write-Host "⚠️ SECURITY NOTICE ⚠️"
Write-Host "uv is not available via system package managers on this system."
Write-Host "To continue, we need to download and execute an installation script from:"
Write-Host " https://astral.sh/uv/install.ps1 (Windows)"
Write-Host ""
Write-Host "For maximum security, you can install uv manually instead:"
Write-Host " 1. Visit: https://docs.astral.sh/uv/getting-started/installation/"
Write-Host " 2. Download the binary for your platform from GitHub releases"
Write-Host " 3. Verify checksums and install manually"
Write-Host " 4. Then run: .\algo.ps1"
Write-Host ""
$consent = Read-Host "Continue with script download? (y/N)"
if ($consent -ne "y" -and $consent -ne "Y") {
Write-Host "Installation cancelled. Please install uv manually and retry."
exit 1
}
Write-Host "Downloading uv installation script..."
try {
Invoke-RestMethod https://github.com/astral-sh/uv/releases/download/0.8.5/uv-installer.ps1 | Invoke-Expression
return $true
} catch {
Write-Host "Error downloading or executing uv installer: $($_.Exception.Message)"
return $false
}
}
# Function to refresh PATH environment variable
function Update-PathEnvironment {
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" +
[System.Environment]::GetEnvironmentVariable("PATH", "User")
}
# Main execution
try {
# Check if uv is installed
if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
Write-Host "uv (Python package manager) not found. Installing..."
# Try package managers first (most secure)
$packageInstalled = Install-UvViaPackageManager
# Fall back to download if package managers failed
if (-not $packageInstalled) {
$downloadInstalled = Install-UvViaDownload
if (-not $downloadInstalled) {
throw "uv installation failed"
}
}
# Refresh PATH to find uv
Update-PathEnvironment
# Verify installation worked
if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
throw "uv installation failed. Please restart your terminal and try again."
}
Write-Host "✓ uv installed successfully!"
}
# Run the appropriate playbook
if ($Arguments.Count -gt 0 -and $Arguments[0] -eq "update-users") {
$remainingArgs = $Arguments[1..($Arguments.Count-1)]
& uv run ansible-playbook users.yml @remainingArgs -t update-users
} else {
& uv run ansible-playbook main.yml @Arguments
}
} catch {
Write-Host "Error: $($_.Exception.Message)" -ForegroundColor Red
Write-Host "Or install manually from: https://docs.astral.sh/uv/getting-started/installation/"
exit 1
}

108
docs/deploy-from-windows.md
View file

@ -1,74 +1,100 @@
# Deploy from Windows
The Algo scripts can't be run directly on Windows, but you can use the Windows Subsystem for Linux (WSL) to run a copy of Ubuntu Linux right on your Windows system. You can then run Algo to deploy a VPN server to a supported cloud provider, though you can't turn the instance of Ubuntu running under WSL into a VPN server.
You have three options to run Algo on Windows:
To run WSL you will need:
1. **PowerShell Script** (Recommended) - Native Windows support
2. **Windows Subsystem for Linux (WSL)** - Full Linux environment
3. **Git Bash/MSYS2** - Unix-like shell environment
* A 64-bit system
* 64-bit Windows 10/11 (Anniversary update or later version)
## Option 1: PowerShell Script (Recommended)
## Install WSL
The easiest way to run Algo on Windows. Simply download the repository and run:
Enable the 'Windows Subsystem for Linux':
```powershell
git clone https://github.com/trailofbits/algo
cd algo
.\algo.ps1
```
1. Open 'Settings'
2. Click 'Update & Security', then click the 'For developers' option on the left.
3. Toggle the 'Developer mode' option, and accept any warnings Windows pops up.
The script will automatically:
- Install the Python package manager `uv` via winget or scoop
- Set up the required Python environment
- Run Algo with full functionality
Wait a minute for Windows to install a few things in the background (it will eventually let you know a restart may be required for changes to take effect—ignore that for now). Next, to install the actual Linux Subsystem, you have to jump over to 'Control Panel', and do the following:
## Option 2: Windows Subsystem for Linux (WSL)
1. Click on 'Programs'
2. Click on 'Turn Windows features on or off'
3. Scroll down and check 'Windows Subsystem for Linux', and then click OK.
4. The subsystem will be installed, then Windows will require a restart.
5. Restart Windows and then install [Ubuntu 22.04 LTS from the Windows Store](https://www.microsoft.com/store/productId/9PN20MSR04DW).
6. Run Ubuntu from the Start menu. It will take a few minutes to install. It will have you create a separate user account for the Linux subsystem. Once that's done, you will finally have Ubuntu running somewhat integrated with Windows.
For users who prefer a full Linux environment or need advanced features:
## Install Algo
### Prerequisites
* 64-bit Windows 10/11 (Anniversary update or later)
Run these commands in the Ubuntu Terminal to download Algo scripts to your home directory. Note that when using WSL you should **not** install Algo in the `/mnt/c` directory due to problems with file permissions.
### Setup WSL
1. Install WSL from PowerShell (as Administrator):
```powershell
wsl --install -d Ubuntu-22.04
```
You may need to follow [these directions](https://devblogs.microsoft.com/commandline/copy-and-paste-arrives-for-linuxwsl-consoles/) in order to paste commands into the Ubuntu Terminal.
2. After restart, open Ubuntu and create your user account
```shell
cd
umask 0002
### Install Algo in WSL
```bash
cd ~
git clone https://github.com/trailofbits/algo
cd algo
./algo
```
The first time you run `./algo`, it will automatically install the required Python environment (Python 3.11+) and all dependencies. No manual package installation required!
**Important**: Don't install Algo in `/mnt/c` directory due to file permission issues.
## Post installation steps
### WSL Configuration (if needed)
These steps should be only if you clone the Algo repository to the host machine disk (C:, D:, etc.). WSL mount host system disks to `\mnt` directory.
You may encounter permission issues if you clone Algo to a Windows drive (like `/mnt/c/`). Symptoms include:
### Allow git to change files metadata
- **Git errors**: "fatal: could not set 'core.filemode' to 'false'"
- **Ansible errors**: "ERROR! Skipping, '/mnt/c/.../ansible.cfg' as it is not safe to use as a configuration file"
- **SSH key errors**: "WARNING: UNPROTECTED PRIVATE KEY FILE!" or "Permissions 0777 for key are too open"
By default, git cannot change files metadata (using chmod for example) for files stored at host machine disks (https://docs.microsoft.com/en-us/windows/wsl/wsl-config#set-wsl-launch-settings). Allow it:
If you see these errors, configure WSL:
1. Start Ubuntu Terminal.
2. Edit /etc/wsl.conf (create it if it doesn't exist). Add the following:
```
1. Edit `/etc/wsl.conf` to allow metadata:
```ini
[automount]
options = "metadata"
```
3. Close all Ubuntu Terminals.
4. Run powershell.
5. Run `wsl --shutdown` in powershell.
### Allow run Ansible in a world writable directory
2. Restart WSL completely:
```powershell
wsl --shutdown
```
Ansible treats host machine directories as world writable directory and do not load .cfg from it by default (https://docs.ansible.com/ansible/devel/reference_appendices/config.html#cfg-in-world-writable-dir). For fix run inside `algo` directory:
```shell
3. Fix directory permissions for Ansible:
```bash
chmod 744 .
```
You'll be instructed to edit the file `config.cfg` in order to specify the Algo user accounts to be created. If you're new to Linux the simplest editor to use is `nano`. To edit the file while in the `algo` directory, run:
```shell
nano config.cfg
**Why this happens**: Windows filesystems mounted in WSL (`/mnt/c/`) don't support Unix file permissions by default. Git can't set executable bits, and Ansible refuses to load configs from "world-writable" directories for security.
After deployment, copy configs to Windows:
```bash
cp -r configs /mnt/c/Users/$USER/
```
After editing your configuration, simply run `./algo` again to deploy your VPN server. Once finished, you can use the `cp` command to copy the configuration files from the `configs` directory into your Windows directory under `/mnt/c/Users` for easier access.
## Option 3: Git Bash/MSYS2
If you have Git for Windows installed, you can use the included Git Bash terminal:
```bash
git clone https://github.com/trailofbits/algo
cd algo
./algo
```
**Pros**:
- Uses the standard Unix `./algo` script
- No WSL setup required
- Familiar Unix-like environment
**Cons**:
- May have compatibility issues with some Ansible modules
- Less robust than WSL or PowerShell options
- Requires Git for Windows installation