OpenVPN Client

A Node.js wrapper for OpenVPN client that provides a simple and programmatic way to manage OpenVPN connections.

TODO

• [ ] Config Validation - Validate .ovpn files before connecting
• [ ] Multiple Connections - Support multiple simultaneous connections
• [ ] Retry Logic - Automatic retry with configurable attempts and delays
• [ ] Error Handling - Custom error types and specific error codes
• [ ] Connection Stats - Real-time connection metrics and monitoring
• [ ] Config Builder - Programmatic configuration creation
• [ ] Logging - Configurable log levels and file output
• [ ] Health Checks - Connection testing and health monitoring
• [ ] Config Templates - Pre-built templates for common VPN providers
• [ ] Event History - Connection history and event logging
• [ ] Credential Management - Secure credential storage and retrieval
• [ ] Certificate Management - Automatic certificate renewal and validation
• [ ] Performance Metrics - Connection performance and throughput metrics

Features

• 🔌 Easy Connection Management - Connect and disconnect from OpenVPN servers programmatically
• 📡 Event-Driven Status Updates - Real-time status monitoring with event emitters
• 🔐 Authentication Support - Handle username/password authentication automatically
• 🖥️ Cross-Platform - Works on Windows, macOS, and Linux
• 📝 Config Management - Support for both file-based and string-based configurations
• 🧹 Auto Cleanup - Automatic cleanup of temporary configuration files
• ⚡ Process Management - Automatic detection and cleanup of OpenVPN processes

Installation

npm install openvpn-client-ts
# or
pnpm add openvpn-client-ts
# or
yarn add openvpn-client-ts

Prerequisites

This library requires OpenVPN to be installed on your system:

Windows

• Install OpenVPN from https://openvpn.net/community-downloads/
• The library will automatically detect OpenVPN in Program Files or Program Files (x86)

macOS

# Using Homebrew
brew install openvpn

# Or download from https://openvpn.net/community-downloads/

Linux

# Ubuntu/Debian
sudo apt-get install openvpn

# CentOS/RHEL
sudo yum install openvpn

# Arch Linux
sudo pacman -S openvpn

Quick Start

import { OpenVpn } from 'openvpn-client-ts'

// Create an instance with a config file
const openVpn = new OpenVpn('/path/to/config.ovpn', 'username', 'password')

// Listen for status changes
openVpn.on('status', (status) => {
  console.log('Status:', status)
})

// Listen for logs
openVpn.on('log', (log) => {
  console.log('Log:', log)
})

// Connect to VPN
try {
  await openVpn.connect()
  console.log('Connected to VPN!')
} catch (error) {
  console.error('Connection failed:', error)
}

// Disconnect
await openVpn.disconnect()

Usage Examples

Using Configuration File

import { OpenVpn } from 'openvpn-client-ts'

const openVpn = new OpenVpn(
  '/path/to/your/config.ovpn',
  'your_username',
  'your_password'
)

openVpn.on('status', (status) => {
  switch (status) {
    case 'connecting':
      console.log('Connecting to VPN...')
      break
    case 'connected':
      console.log('Successfully connected!')
      break
    case 'disconnected':
      console.log('Disconnected from VPN')
      break
    case 'error':
      console.log('Connection error occurred')
      break
  }
})

await openVpn.connect()

Using Configuration String

import { OpenVpn } from 'openvpn-client-ts'

const configContent = `
client
dev tun
proto udp
remote vpn.example.com 1194
resolv-retry infinite
nobind
persist-key
persist-tun
remote-cert-tls server
cipher AES-256-CBC
auth SHA256
key-direction 1
verb 3
<ca>
-----BEGIN CERTIFICATE-----
... your CA certificate ...
-----END CERTIFICATE-----
</ca>
<cert>
-----BEGIN CERTIFICATE-----
... your client certificate ...
-----END CERTIFICATE-----
</cert>
<key>
-----BEGIN PRIVATE KEY-----
... your private key ...
-----END PRIVATE KEY-----
</key>
`

const openVpn = OpenVpn.createFromConfig(
  configContent,
  'username',
  'password'
)

await openVpn.connect()

Advanced Usage with Error Handling

import { OpenVpn } from 'openvpn-client-ts'

async function connectToVpn() {
  const openVpn = new OpenVpn('/path/to/config.ovpn', 'user', 'pass')
  
  // Set up event listeners
  openVpn.on('status', (status) => {
    console.log(`VPN Status: ${status}`)
  })
  
  openVpn.on('log', (log) => {
    console.log(`VPN Log: ${log}`)
  })
  
  try {
    await openVpn.connect()
    console.log('VPN connection established')
    
    // Do your work here...
    await someWork()
    
  } catch (error) {
    console.error('Failed to connect to VPN:', error)
  } finally {
    await openVpn.disconnect()
    console.log('VPN disconnected')
  }
}

API Reference

Constructor

new OpenVpn(configPath, username, password)

• configPath: Path to the OpenVPN configuration file (.ovpn)
• username: Optional username for authentication
• password: Optional password for authentication

Static Methods

createFromConfig(config: string, username?: string, password?: string)

Creates an OpenVpn instance from a configuration string instead of a file.

const openVpn = OpenVpn.createFromConfig(configString, 'user', 'pass')

Instance Methods

connect(): Promise<void>

Connects to the VPN server. Returns a promise that resolves when connected or rejects on error.

disconnect(): Promise<void>

Disconnects from the VPN server and cleans up resources.

getProcesses(): Promise<Process[]>

Returns a list of running OpenVPN processes.

killProcesses(): Promise<void>

Forcefully kills all OpenVPN processes.

Events

The OpenVpn class extends EventEmitter and emits the following events:

status event

Emitted when the connection status changes. Possible status values:

• 'connecting' - Attempting to connect
• 'connected' - Successfully connected
• 'disconnected' - Disconnected from VPN
• 'reconnecting' - Reconnecting after connection loss
• 'stopped' - Process stopped
• 'error' - An error occurred
• 'auth' - Authentication required
• 'auth_username' - Username authentication requested
• 'auth_password' - Password authentication requested
• 'auth_success' - Authentication successful
• 'auth_failed' - Authentication failed

log event

Emitted with OpenVPN log messages.

openVpn.on('status', (status) => {
  console.log('Status changed to:', status)
})

openVpn.on('log', (message) => {
  console.log('OpenVPN:', message)
})

Environment Variables

OPENVPN_BIN_PATH

If OpenVPN is not found in the default locations, you can specify a custom path:

export OPENVPN_BIN_PATH=/custom/path/to/openvpn

Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• OpenVPN installed on your system

Setup

# Clone the repository
git clone https://github.com/ho3einwave/openvpn-client.git
cd openvpn-client

# Install dependencies
pnpm install

# Build the project
pnpm build

Available Scripts

• pnpm build - Build the project
• pnpm dev - Build in watch mode
• pnpm test - Run tests
• pnpm lint - Run ESLint
• pnpm lint:fix - Fix ESLint issues
• pnpm typecheck - Run TypeScript type checking
• pnpm format - Format code with Prettier

Testing

To run tests, you'll need to set up environment variables:

# Create a .env file
OVPN_USERNAME=your_username
OVPN_PASSWORD=your_password
OVPN_CONFIG_PATH=/path/to/your/config.ovpn

Then run the tests:

pnpm test

License

MIT © ho3einwave

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on GitHub.