title: Add configuration backup and rollback

description: Create backup functions: backup_config() (creates timestamped backups), restore_config(), auto-backup before destructive operations (add, remove, install). Store backups in /etc/wg-admin/backups/ with retention policy (e.g., keep last 10).

status: closed

issue_type: task

created_by: Calmcacil

close_reason: Implemented configuration backup and rollback functionality: added backup_config() function (creates timestamped backups in /etc/wg-admin/backups/), restore_config() function (interactive restore from backup), apply_retention_policy() (keeps last 10 backups), and auto-backup before destructive operations (install, add, remove commands).


title: Remove hardcoded sensitive information

description: Identify and remove all hardcoded sensitive values from wireguard.sh. Replace with config file reads. Remove: SERVER_DOMAIN (velkhana.calmcacil.dev), VPN_IP_RANGES, any other identifiable information. Document config file structure in README.

close_reason: Removed all hardcoded sensitive information: SERVER_DOMAIN, VPN_IPV4_RANGE, VPN_IPV6_RANGE, DNS_SERVERS now configurable via /etc/wg-admin/config.conf. Added load_config() function. Created config.example template. Updated README with configuration documentation. All IP ranges in script now reference config variables.


title: Implement backup operations

description: Create backup functionality that saves WireGuard configs, client configs, and metadata to /etc/wg-admin/backups/ with timestamp. Set proper permissions (600 for sensitive files).

status: open

type: blocks


title: Update documentation for refactored scripts

description: Update README.md and all documentation to reflect new architecture. Document: wg-install.sh usage (interactive prompts, WGI_ env vars), wg-client-manager commands (add, remove, list, show, qr), environment variable reference, security hardening features, backup/restore procedures. Update examples with new patterns.

close_reason: Documentation updated on main branch. README.md reflects new wg-install.sh and wg-client-manager scripts, WGI_ environment variables, and all usage patterns.

depends_on_id: wg-admin-slj


title: Improve nftables firewall configuration

description: Enhance firewall rules based on best practices: add TCP MSS clamping for MTU issues, add connection tracking bypass (notrack) for WireGuard traffic, implement proper rate limiting, ensure ICMPv6 neighbor discovery is allowed, validate rules before applying with nft check.

close_reason: Improved nftables firewall configuration with TCP MSS clamping (1360), connection tracking bypass (notrack) for WireGuard UDP traffic, rate limiting for SSH (3/min) and WireGuard (10/s), ensured ICMPv6 neighbor discovery (including nd-router-* messages), and added nft check validation before applying rules.


title: Add security hardening

description: Implement: client name sanitization with regex, pre-shared key (PSK) support option, proper temporary key cleanup with trap handlers, atomic config file operations (write to temp then mv), chmod 0600 for all key files, verify no hardcoded secrets in generated files.

close_reason: Implemented all security hardening features: client name sanitization with regex (validate_client_name function), pre-shared key (PSK) support with --psk option, proper temporary key cleanup with trap handlers (cleanup_handler), atomic config file operations (mktemp + mv), chmod 0600 for all key files, and verified no hardcoded secrets (keys generated dynamically or read from files)


title: Implement configuration loading system

description: Implement configuration system to load /etc/wg-admin/config.conf using native Go or Viper library. Support environment variable overrides. Validate required config (SERVER_DOMAIN, WG_PORT, VPN_IPV4_RANGE, VPN_IPV6_RANGE, DNS_SERVERS). Provide clear error messages for missing config.

close_reason: Configuration system implemented in internal/config/config.go. Loads from /etc/wg-admin/config.conf, supports environment variable overrides with WGI_ prefix, validates required fields (SERVER_DOMAIN, WG_PORT, CIDR formats). Provides helper methods for network extraction.


title: Set up basic TUI skeleton with Bubble Tea

description: Create main TUI application entry point implementing Bubble Tea's Model-Update-View pattern. Set up root check and logging. Create empty screen types (list, add, detail, qr, help). Implement basic keyboard navigation (q=quit). Add status bar with version and help shortcut (?).

close_reason: TUI skeleton implemented with Model-Update-View pattern. Main entry point in cmd/wg-tui/main.go with root check, configuration loading integration, basic keyboard navigation (q quit), status bar with version and help. Creates clean separation between TUI model (internal/tui) and main program. Successfully builds.


title: Initialize Go module and project structure

description: Initialize Go project with go mod init. Create directory structure following plan: cmd/, internal/config, internal/wireguard, internal/tui (screens, components, theme), internal/validation, internal/backup. Add README with project setup instructions.

close_reason: Go module initialized, directory structure created (cmd/, internal/ subdirectories), dependencies added (bubbletea, lipgloss, bubbles, huh, qrterminal), basic TUI skeleton with Model-Update-View pattern implemented. Root check added. Builds successfully.


title: Implement WireGuard client parsing

description: Parse WireGuard client configuration files from /etc/wireguard/conf.d/client-*.conf. Extract client name, IPv4, IPv6, public key, and PSK status. Create Client struct. Handle file read errors and malformed configs. Validate config syntax.

close_reason: Implemented WireGuard client parsing: Created Client struct with Name, IPv4, IPv6, PublicKey, HasPSK, and ConfigPath fields. Implemented ParseClientConfig() to parse individual client config files from /etc/wireguard/conf.d/client-*.conf, extracting client name from filename and parsing INI-style [Peer] sections. Implemented ListClients() to find and parse all client configs. Added parseAllowedIPs() helper to extract IPv4/IPv6 from AllowedIPs field. Proper error handling for file read failures, malformed configs, and missing required fields. Logs parsing warnings for malformed lines. Successfully builds with no errors.


title: Create wg-client-manager script

description: Create new wg-client-manager script for client operations: add, remove, list, show, qr. Implement proper command parsing, use interactive 'read' with 'WGI_' environment variable overrides, call validation functions, use atomic config updates.

close_reason: Created wg-client-manager script with all required commands (add, remove, list, show, qr). Implements interactive prompts with WGI_ environment variable overrides, uses validation functions, and performs atomic config updates.

issue_id: wg-admin-abw

depends_on_id: wg-admin-cwb

depends_on_id: wg-admin-lzl

depends_on_id: wg-admin-wsk


title: Implement real-time status checking

description: Implement real-time connection status using 'wg show wg0' command. Check if client public key appears in peers list. Update status in table: Connected (active peer) or Disconnected (not in peers list). Add auto-refresh every 30 seconds using tea.Tick. Manual refresh with 'r' key.

close_reason: Implemented real-time status checking functionality: Created status.go with GetClientStatus() and GetAllPeers() functions that parse 'wg show wg0' output to determine connection status. Added PeerStatus struct with PublicKey, Endpoint, AllowedIPs, LatestHandshake, TransferRx, TransferTx, and Status fields. Created tea_messages.go with Tick() command for auto-refresh and ManualRefresh() command for immediate refresh using tea.Tick and custom messages. Status is 'Connected' if handshake is within 3 minutes, otherwise 'Disconnected'.

issue_id: wg-admin-bay

depends_on_id: wg-admin-xum


title: Implement input validation functions

description: Create robust validation functions: validate_client_name() (regex check for [a-zA-Z0-9_-]), validate_ip_availability(), validate_dns_servers(), validate_port_range(), validate_config_syntax(). Add validation before client creation and config changes.

close_reason: Implemented all validation functions: validate_client_name(), validate_ip_availability(), validate_dns_servers(), validate_port_range(), validate_config_syntax(). Added validation calls in cmd_add and cmd_load_clients.


title: Implement client detail view

description: Create detailed view for selected client showing name, IPs, public key, connection status, last handshake time, and transfer stats. Include copy to clipboard functionality and delete button with confirmation.


title: Implement color themes

description: Add support for color themes using lipgloss. Create default theme with primary, success, warning, and error colors. Support theme switching through config file or environment variable.


title: Create Go TUI epic

description: Epic: Convert wg-client-manager bash script to a modern, responsive Go TUI application using Bubble Tea framework. Provides better UX with interactive forms, real-time status updates, and intuitive keyboard navigation.

issue_type: feature


title: Add search and filter clients

description: Implement client search functionality with keyboard shortcut (/). Allow filtering by client name, IP address, or status. Highlight matching results in real-time as user types.


title: Add keyboard shortcuts help

description: Create help screen displaying all keyboard shortcuts. Show on '?' key press or in status bar. Include shortcuts for navigation (j/k, arrows), actions (a=add, d=delete, q=quit), and help (?).


title: Generate QR codes for clients

description: Generate ANSI-colored QR codes from client configs using qrterminal library. Support both inline and fullscreen QR display modes. Handle terminal resize events for optimal QR rendering.


title: Create configuration file format for WireGuard settings

description: Design and implement /etc/wg-admin/config file to replace hardcoded values. Include: SERVER_DOMAIN, WG_PORT, VPN_IPV4_RANGE, VPN_IPV6_RANGE, WG_INTERFACE, DNS_SERVERS, and other configurable parameters. Support both file-based and environment variable override.

close_reason: Config file approach replaced with interactive prompts using 'read', with 'WGI_' prefixed environment variable overrides. No persistent config file needed.


title: Add improved error handling and traps

description: Implement: EXIT trap for cleanup on script interruption, pre-install validation (disk space, port availability, root check), rollback mechanism for failed operations, better error messages with actionable guidance, log all operations with timestamps.

close_reason: Implemented all error handling and trap features: EXIT trap for cleanup (cleanup_handler catches EXIT,INT,TERM,HUP), pre-install validation (pre_install_validation checks disk space, port availability, root), rollback mechanism (rollback_installation function with BACKUP_DIR), better error messages with actionable guidance (all errors include specific fix suggestions), and logging with timestamps (log_info, log_error, log_warn functions)


title: Implement WireGuard key generation

description: Implement WireGuard key generation using wg genkey and wg pubkey commands. Generate client private key, public key, and optional pre-shared key (PSK). Ensure atomic file writes and proper permissions (0600).

depends_on_id: wg-admin-wod


title: Refactor installation into wg-install.sh

description: Extract install logic from wireguard.sh into dedicated wg-install.sh script. Handle: dependency checks, package installation, firewall setup (nftables), server key generation, interface initialization, systemd service setup. Use interactive 'read' prompts for settings with 'WGI_' prefixed environment variable overrides.

close_reason: Created wg-install.sh script with complete installation logic extracted from wireguard.sh. Script includes dependency checks, package installation, nftables firewall setup, server key generation, interface initialization, and systemd service setup. Uses interactive prompts with WGI_ prefixed environment variable overrides. All validation and error handling maintained with atomic operations and proper cleanup. Test suite (test-wg-install.sh) created with 35 tests all passing.

issue_id: wg-admin-qpy


title: Refactor WireGuard scripts into modular architecture

description: Refactor monolithic wireguard.sh into two separate scripts: wg-install.sh for initial setup, wg-client-manager for client operations. Use interactive 'read' prompts with 'WGI_' prefixed environment variable overrides. Add validation functions, security hardening, and remove all hardcoded sensitive information from repository.

close_reason: Refactoring complete: wg-install.sh (921 lines) and wg-client-manager (545 lines) scripts have been created and are functional. wireguard.sh retained for backwards compatibility.

issue_id: wg-admin-slj

depends_on_id: wg-admin-abw

depends_on_id: wg-admin-qpy


title: Add client delete functionality

description: Implement delete client workflow with confirmation modal. Remove client config from server, delete client files, auto-backup before deletion, and reload WireGuard configuration.


title: Create server and client config files

description: Generate WireGuard configuration files for both server and client. Server config includes PublicKey and AllowedIPs. Client config includes PrivateKey, Address, DNS, Endpoint, and AllowedIPs. Use atomic writes (temp file + mv).


title: Implement restore functionality

description: Add restore capability to load backups from /etc/wg-admin/backups/. Include backup list view, restore confirmation, and pre-restore safety backup. Handle missing backups gracefully.

issue_id: wg-admin-wjj


title: Create add client form with huh

description: Implement form for adding new WireGuard clients using the huh library. Include fields for client name, DNS servers, and PSK toggle. Add validation for client name format, IP availability, and DNS format.

issue_id: wg-admin-wod


title: Add configuration validation and syntax checking

description: Implement validate_config_syntax() to check WireGuard config format before applying: verify [Interface] and [Peer] sections, check key format (44 base64 characters), validate IP addresses and CIDR notation, validate DNS format, ensure no duplicate public keys.

close_reason: validate_config_syntax() implemented in previous task with full WireGuard config format validation: [Interface]/[Peer] sections, key format (44 base64 chars), IP/CIDR notation, DNS format, duplicate public key detection. Integrated into cmd_load_clients.


title: Create client list table with bubble-table

description: Implement interactive client list table using bubble-table library. Columns: Name, IPv4, IPv6, Status (Connected/Disconnected). Add sorting by column (name or status). Support keyboard navigation (j/k, arrows, Enter to select). Highlight selected row.

issue_id: wg-admin-xum