A lightweight and robust CLI automation toolset for managing AmneziaWG and WireGuard configuration files. It handles structured copying, renaming, sorting, listing, and network traffic status checking.
The project architecture relies on an externalized backend library wg_conf_core to handle pure business logic, while this repository acts as the clean execution interface.
Before installing and running the scripts, ensure your Linux system meets the following requirements:
The system must have the active AmneziaWG kernel module and its associated CLI tools installed and configured:
- Kernel Module:
amneziawg(See AmneziaWG Kernel Module Installation) - CLI Tools:
amneziawg-tools(providingawgandawg-quickbinaries, see AmneziaWG Tools)
You must already possess valid, working .conf configuration files provided by an AmneziaWG-compatible VPN provider.
- Place these initial raw files into your designated local
source_dirbefore starting the automation flow.
-
Clone this repository to your target machine:
git clone https://github.com/dneverov/wg_conf.git cd wg_conf -
Configure your local paths in
config.yml. -
Install all toolset dependencies including the core gem via Bundler:
bundle install
Copies a single specified configuration file from the source directory to the system target directory (defined in config.yml). It safely copies the file, automatically creates missing directories, and updates target paths.
ruby copy.rb <source_file.conf> [target_file.conf]<source_file.conf>— Required. The exact name of the file in your source directory that you want to copy.[target_file.conf]— Optional. A new name for the file in the target directory. If omitted, the script automatically formats the name using the project's internal naming scheme (viaNamer).
# Copy a file and automatically determine its optimized target name
ruby copy.rb SerbiaBelgradeS3.conf
# Copy a file and explicitly force a specific target name
ruby copy.rb SerbiaBelgradeS3.conf wg2_ser_bel_S3.confApplies downloaded VPN configuration files from your local directory into the system target folder (e.g., /etc/amnezia/amneziawg/). Source and target paths are defined in config.yml.
ruby apply.rb [options]-p, --period <value>— Specifies the cutoff period for filtering files.- Integer (e.g.,
0,3) — Applies files modified within the last N days. all— Applies all available configuration files regardless of their age.- Default value:
0(applies today's files only).
- Integer (e.g.,
-h, --help— Prints the helper banner and tool usage instructions.
# Apply only today's configurations (default)
ruby apply.rb
# Apply configurations added/modified in the last 3 days
ruby apply.rb -p 3
# Apply all configuration files from the source directory
ruby apply.rb -p all
# Show full help information
ruby apply.rb -hScans your system target directory and displays all available VPN configurations in clean, vertically-aligned columns without the .conf extension.
ruby list.rb [options]-n, --name— Sorts configurations alphabetically by name in 3 columns. This is the default behavior.-t, --time— Sorts configurations by modification date, placing the newest files at the top (3 columns).-d, --details— Sorts configurations by modification date and appends a clean, right-aligned timestamp (YYYY-MM-DD HH:MM) next to each name. Automatically switches the layout to 2 columns for optimal readability.-h, --help— Prints the helper banner and tool usage instructions.
# List all configurations alphabetically in 3 vertical columns (default)
ruby list.rb
# List configurations by date, freshest first (3 columns)
ruby list.rb -t
# List configurations with dates aligned cleanly to the right (2 columns)
ruby list.rb -d
# Show help information
ruby list.rb -hManages your AmneziaWG/WireGuard connections using configuration files from the system target directory. It handles stopping previous connections, dynamic configuration resolution, interface diagnostics, features an integrated Kill Switch to prevent unencrypted traffic leaks, and automatically requests sudo privileges if launched by a regular user.
ruby vpn_run.rb [options] [config_name][config_name]— Optional. The name of a specific VPN configuration file (without the.confextension) to start. If omitted, the script automatically detects and starts the latest (most recently modified) configuration file in the directory.
-s, --stop— Stops all currently active systemd units matching your project's VPN service prefix and cleanly flushes all Kill Switch firewall rules, restoring pristine network states.-i, --status— Explicitly prints the live interface diagnostic summary map right after the connection is established.-k, --kill-switch— Activates strictiptables-nftprotection. Automatically blocks all outbound system traffic except for the active VPN tunnel loop and the target server's endpoint IP.-h, --help— Prints the helper banner and tool usage instructions.
# Start the most recent configuration file (auto-escalates to sudo if needed)
ruby vpn_run.rb
# Start a specific configuration interface explicitly and display status diagnostics
ruby vpn_run.rb -i wg2_net_ams_H16
# Securely launch a tunnel with full traffic leak protection (Kill Switch active)
ruby vpn_run.rb -k
# Stop active connections and safely restore network and firewall states
ruby vpn_run.rb -s
# Show help information
ruby vpn_run.rb -hVerifies the active VPN status and tests real data flow through the tunnel using an isolated ping check. It bypasses TSPU/ISP interference by forcing traffic strictly through the active interface.
ruby vpn_check.rb [options]The script returns system codes instantly, allowing scripts or status bars to monitor connection health:
0— Success: Service is active, the interface is parsed correctly, and traffic flows successfully.1— Error: The service is down, the interface is missing, or traffic is blocked by TSPU/ISP filters.
-v, --verbose— Prints a complete diagnostic summary map (systemd state, interface name, fallback host, ping validation) using an optimized single-pass check.-h, --help— Prints the helper banner and tool usage instructions.
# Quietly check the connection (returns exit code 0 or 1, prints a single result line)
ruby vpn_check.rb
# Run an extended live diagnostic breakdown when troubleshooting connection drops
ruby vpn_check.rb -v
# Show help information
ruby vpn_check.rb -hSequentially tests all available VPN configurations by temporarily bringing up each tunnel and verifying the real data flow. It automatically suppresses underlying systemd output, tracks results interactively, and safely restores your initial network state upon completion.
# Sequentially test all configurations (automatically requests sudo privileges)
ruby ping_all.rbThe project includes an isolated integration testing infrastructure running inside the Bundler environment to spawn real CLI subprocesses.
Integration tasks are managed via Rake alongside minitest-rg to provide clean visual test evaluations.
# Run the integration test suite
bundle exec rake test