{"id":44723917,"url":"https://github.com/tldr-it-stepankutaj/openvpn-client","last_synced_at":"2026-02-15T16:43:00.398Z","repository":{"id":336920472,"uuid":"1108216406","full_name":"tldr-it-stepankutaj/openvpn-client","owner":"tldr-it-stepankutaj","description":"A Go-based client for integrating OpenVPN server with OpenVPN Manager API","archived":false,"fork":false,"pushed_at":"2026-02-06T19:12:46.000Z","size":73,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-07T05:19:59.486Z","etag":null,"topics":["client","golang","openvpn","openvpn-management","openvpn-server","security"],"latest_commit_sha":null,"homepage":"https://www.tldr-it.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tldr-it-stepankutaj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-02T07:14:39.000Z","updated_at":"2026-02-06T19:12:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tldr-it-stepankutaj/openvpn-client","commit_stats":null,"previous_names":["tldr-it-stepankutaj/openvpn-client"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tldr-it-stepankutaj/openvpn-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldr-it-stepankutaj%2Fopenvpn-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldr-it-stepankutaj%2Fopenvpn-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldr-it-stepankutaj%2Fopenvpn-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldr-it-stepankutaj%2Fopenvpn-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tldr-it-stepankutaj","download_url":"https://codeload.github.com/tldr-it-stepankutaj/openvpn-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldr-it-stepankutaj%2Fopenvpn-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29484662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T15:33:17.885Z","status":"ssl_error","status_checked_at":"2026-02-15T15:32:53.698Z","response_time":118,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","golang","openvpn","openvpn-management","openvpn-server","security"],"created_at":"2026-02-15T16:42:59.812Z","updated_at":"2026-02-15T16:43:00.393Z","avatar_url":"https://github.com/tldr-it-stepankutaj.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenVPN Client\n\nA Go-based client for integrating OpenVPN server with [OpenVPN Manager](https://github.com/tldr-it-stepankutaj/openvpn-mng) API.\n\n\u003e **Important:** This client is designed to work exclusively with [OpenVPN Manager](https://github.com/tldr-it-stepankutaj/openvpn-mng). OpenVPN Manager provides a web-based administration interface for managing VPN users, networks, and groups. This client connects your OpenVPN server to that management system.\n\n## Architecture\n\n```\n┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐\n│  OpenVPN Server │────▶│  OpenVPN Client │────▶│  OpenVPN Manager│\n│                 │     │   (this repo)   │     │   (openvpn-mng) │\n└─────────────────┘     └─────────────────┘     └─────────────────┘\n                               │                        │\n                               │                        ▼\n                               │                 ┌─────────────────┐\n                               │                 │    Database     │\n                               │                 │ (Users, Groups, │\n                               ▼                 │    Networks)    │\n                        ┌─────────────────┐      └─────────────────┘\n                        │ nftables/iptables│\n                        │   (firewall)    │\n                        └─────────────────┘\n```\n\n**OpenVPN Manager** handles:\n- User management (create, edit, delete VPN users)\n- Group management (organize users into groups)\n- Network management (define internal networks/subnets)\n- Access control (assign networks to groups)\n- Session monitoring (view active connections)\n\n**OpenVPN Client** (this repository) handles:\n- User authentication against OpenVPN Manager API\n- Dynamic route assignment based on user's group membership\n- VPN session tracking (connect/disconnect events, traffic stats)\n- Firewall rules generation based on user-network assignments\n\n## Features\n\n- **User Authentication** - Validates VPN user credentials against the API\n- **Client Connect** - Configures client IP, pushes routes based on group membership\n- **Client Disconnect** - Records session end and traffic statistics\n- **Firewall Rules** - Generates nftables or iptables rules based on user-network assignments\n- **Structured Logging** - JSON logging with `log/slog`\n- **Flexible Configuration** - CLI arguments, environment variables, and YAML config file\n\n## Quick Start\n\n### Build\n\n```bash\n# Build all binaries\nmake build\n\n# Build for Linux (deployment)\nmake build-linux\n```\n\n### Install\n\n```bash\n# Install to /usr/local/bin\nsudo make install\n\n# Or manually copy binaries\nsudo cp build/openvpn-* /usr/local/bin/\nsudo chmod 755 /usr/local/bin/openvpn-*\n```\n\n### Configure\n\n```bash\n# Create config directory\nsudo mkdir -p /etc/openvpn/client\n\n# Copy and edit configuration\nsudo cp config.example.yaml /etc/openvpn/client/config.yaml\nsudo chmod 600 /etc/openvpn/client/config.yaml\nsudo vim /etc/openvpn/client/config.yaml\n```\n\n## Binaries\n\n| Binary | Purpose | OpenVPN Directive |\n|--------|---------|-------------------|\n| `openvpn-login` | User authentication | `auth-user-pass-verify` |\n| `openvpn-connect` | Client connection setup | `client-connect` |\n| `openvpn-disconnect` | Client disconnection cleanup | `client-disconnect` |\n| `openvpn-firewall` | Firewall rules generator | Cron job |\n\n## Configuration\n\nConfiguration is loaded with the following priority (highest to lowest):\n\n1. CLI arguments (`-c` / `--config`)\n2. Environment variables (`OPENVPN_*`)\n3. Configuration file (default: `/etc/openvpn/client/config.yaml`)\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `OPENVPN_CLIENT_CONFIG` | Path to configuration file |\n| `OPENVPN_API_BASE_URL` | API base URL |\n| `OPENVPN_API_TOKEN` | API token (recommended) |\n| `OPENVPN_API_USERNAME` | Service account username (legacy) |\n| `OPENVPN_API_PASSWORD` | Service account password (legacy) |\n| `OPENVPN_API_TIMEOUT` | API request timeout |\n| `OPENVPN_SESSION_DIR` | Session files directory |\n| `OPENVPN_FIREWALL_TYPE` | Firewall type (nftables/iptables) |\n\n### Example Configuration\n\n```yaml\napi:\n  base_url: \"http://127.0.0.1:8080\"\n  token: \"your-api-token\"\n  timeout: 10s\n\nopenvpn:\n  session_dir: \"/var/run/openvpn\"\n\nfirewall:\n  type: \"nftables\"\n  nftables:\n    rules_file: \"/etc/nftables.d/vpn-users.nft\"\n    reload_command: \"/usr/sbin/nft -f /etc/sysconfig/nftables.conf\"\n```\n\n## Usage\n\n### Authentication (openvpn-login)\n\n```bash\n# Called by OpenVPN with auth file path\nopenvpn-login [-c /path/to/config.yaml] /tmp/auth.txt\n```\n\n### Client Connect (openvpn-connect)\n\n```bash\n# Called by OpenVPN with config file path\n# Requires environment variables: common_name, trusted_ip, trusted_port, ifconfig_pool_remote_ip\nopenvpn-connect [-c /path/to/config.yaml] /tmp/client-config.txt\n```\n\n### Client Disconnect (openvpn-disconnect)\n\n```bash\n# Called by OpenVPN\n# Requires environment variables: common_name, bytes_received, bytes_sent\nopenvpn-disconnect [-c /path/to/config.yaml]\n```\n\n### Firewall Rules (openvpn-firewall)\n\n```bash\n# Generate and apply firewall rules\nopenvpn-firewall [-c /path/to/config.yaml]\n\n# Dry run - print rules without applying\nopenvpn-firewall [-c /path/to/config.yaml] -n\n```\n\n## OpenVPN Server Configuration\n\nAdd to your OpenVPN server configuration:\n\n```conf\n# Authentication via API\nusername-as-common-name\nauth-user-pass-verify /usr/local/bin/openvpn-login via-file\nclient-connect /usr/local/bin/openvpn-connect\nclient-disconnect /usr/local/bin/openvpn-disconnect\nscript-security 2\n```\n\nSee [samples/openvpn/](samples/openvpn/) for complete examples.\n\n## Firewall Integration\n\n### NFTables\n\nInclude the generated rules file in your main nftables configuration:\n\n```nft\nchain forward {\n    type filter hook forward priority 0; policy drop;\n    ct state established,related accept\n    include \"/etc/nftables.d/vpn-users.nft\"\n}\n```\n\n### IPTables\n\nThe generated rules create/flush a custom chain (default: `VPN_USERS`).\n\n### Cron Job\n\n```bash\n# Update firewall rules every 5 minutes\n*/5 * * * * root /usr/local/bin/openvpn-firewall \u003e\u003e /var/log/openvpn-firewall.log 2\u003e\u00261\n```\n\n## Prerequisites\n\n1. **OpenVPN Manager** must be installed and running - see [openvpn-mng](https://github.com/tldr-it-stepankutaj/openvpn-mng)\n2. API token must be configured in OpenVPN Manager\n3. Users, groups, and networks must be configured in OpenVPN Manager\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [OpenVPN Integration Guide](help/openvpn_integration.md) | **Complete setup guide** - OpenVPN server, PKI, firewall, and integration |\n| [Installation Guide](help/installation.md) | Quick installation of this client |\n| [Client Integration Guide](help/client.md) | API reference and client details |\n| [Sample Configurations](samples/) | OpenVPN server/client configs, firewall examples |\n\n## Related Projects\n\n- [OpenVPN Manager](https://github.com/tldr-it-stepankutaj/openvpn-mng) - Web-based administration for VPN users, networks, and groups\n\n## Development\n\n```bash\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-coverage\n\n# Format code\nmake fmt\n\n# Run linter\nmake lint\n\n# Tidy dependencies\nmake tidy\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftldr-it-stepankutaj%2Fopenvpn-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftldr-it-stepankutaj%2Fopenvpn-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftldr-it-stepankutaj%2Fopenvpn-client/lists"}