Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/k1meister/openvpn-status-api

Centralized API to monitor multiple OpenVPN servers. Securely connects via SSH to fetch real-time client connection data, supports IP whitelisting, rate limiting, and Redis caching for optimal performance.
https://github.com/k1meister/openvpn-status-api

koa monitoring nodejs openvpn openvpn-server vpn-server

Last synced: 27 days ago
JSON representation

Centralized API to monitor multiple OpenVPN servers. Securely connects via SSH to fetch real-time client connection data, supports IP whitelisting, rate limiting, and Redis caching for optimal performance.

Awesome Lists containing this project

README 

        
# VPN Status API



![Build Status](https://github.com/k1meister/openvpn-status-api/actions/workflows/node.js.yml/badge.svg)

![License](https://img.shields.io/github/license/k1meister/openvpn-status-api)

![Node Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)



Secure Koa.js API for monitoring OpenVPN client connections via SSH. Includes IP whitelisting, API key protection, rate limiting, and Redis caching.



## Table of Contents

- [Features](#features)

- [Requirements](#requirements)

- [Installation](#installation)

- [Configuration](#configuration)

  - [`.env` Example](#env-example)

- [Usage](#usage)

  - [Running the Application](#running-the-application)

  - [API Documentation](#api-documentation)

- [Contributing](#contributing)

- [License](#license)



## Features

- Connects to multiple OpenVPN servers via SSH

- Retrieves client connection statistics

- Caches responses using Redis

- Secure API access with API keys, IP whitelist and rate limiting



## Requirements

- Node.js v16+ (v20 recommended)

- Redis server (for caching)

- OpenVPN Access Server with SSH access enabled



## Installation

First, clone this repository:



``bash

git clone https://github.com/yourusername/vpn-status-api.git

cd vpn-status-api



## Install dependencies

``bash

npm install



## Configuration



.env Example

Create a .env file in the root directory with the following content:



### Server 1 Configuration

SERVER_1_HOST=1.2.3.4

SERVER_1_NAME=domain.com

SERVER_1_COUNTRY=country

SERVER_1_CITY=city

SERVER_1_USER=root

SERVER_1_PASSWORD=ssh_password



### Server 2 Configuration

SERVER_2_HOST=1.2.3.4

SERVER_2_NAME=serv2.domain.com

SERVER_2_COUNTRY=country

SERVER_2_CITY=city

SERVER_2_USER=root

SERVER_2_PASSWORD="ssh_password



### API and Server Config

API_KEY=your-secure-api-key

ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com

ALLOWED_IPS=localhost,127.0.0.1,::1

PORT=4000



### Redis Config

REDIS_HOST=localhost

REDIS_PORT=6379

REDIS_PASSWORD=your-secure-redis-password

CACHE_TTL=60



###  Environment Variables Explanation

SERVER_X_HOST: The IP address of your OpenVPN server.

SERVER_X_USER: The SSH username.

SERVER_X_PASSWORD: The SSH password.

API_KEY: A secure key to access the API.

ALLOWED_ORIGINS: Comma-separated list of allowed origins for CORS.

REDIS_HOST: Redis server host.

REDIS_PORT: Redis server port.

CACHE_TTL: Cache time-to-live in seconds.



## Usage

Running the Application

Build the TypeScript files:



``bash

npx tsc

Start the server:



``bash

node dist/app.js

The server will run on http://localhost:4000 by default.



## API Documentation



### GET /api/server-status

Fetches the status of all configured OpenVPN servers.

URL: /api/server-status



**Method:** GET



**Headers:**

Authorization: Bearer 



**Response:**



``json

{

  "status": "online",

  "servers": [

    {

      "name": "nl1.watch4.net",

      "host": "78.141.213.16",

      "country": "Netherlands",

      "city": "Amsterdam",

      "clients": 10

    },

    {

      "name": "de1.watch4.net",

      "host": "199.247.21.143",

      "country": "Germany",

      "city": "Frankfurt",

      "clients": 8

    }

  ],

  "updated_at": "2024-11-10T10:56:06.054Z"

}



# Errors:

401 Unauthorized: If the API key is missing or invalid.

500 Internal Server Error: If an error occurs while connecting to the OpenVPN servers.

Example Request (Using curl)

``bash

curl -H "Authorization: Bearer your-secure-api-key" http://localhost:4000/api/server-status



## How to Update the Servers

Modify the server configurations in servers.ts and .env file.

Rebuild the project using npx tsc.



## Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.