WHMCS-ArkhostVPSAG/README.md

# WHMCS VPS Management Module - ArkHost VPSAG

A WHMCS server module for VPSAG/EVPS VPS management with multi-language support.

**Note:** VPSAG has rebranded to [EVPS.net](https://evps.net). The API remains unchanged at `vpsag.com`.

Originally based on [andretunes/whmcs-module-vpsag](https://github.com/andretunes/whmcs-module-vpsag). Current version has been substantially rewritten.

## Features

- VPS provisioning and lifecycle management
- VPS control (start/stop/restart/shutdown)
- Backup management (create/restore/delete)
- Firewall configuration
- OS reinstallation with SSH key injection and post-install scripts
- Resource monitoring with graphs
- VNC console access
- Hostname and rDNS management
- ISO mounting
- 8 language support (English, Dutch, French, German, Italian, Portuguese, Russian, Spanish)
- Responsive client area design

## Requirements

- WHMCS 8.9+
- PHP 7.4+
- VPSAG/EVPS reseller account with API access

## Installation

1. Upload the `ArkhostVPSAG` folder to `/modules/servers/` in your WHMCS installation
2. Navigate to **Setup > Products/Services > Servers** in WHMCS admin
3. Add a new server with:
   - **Module:** ArkhostVPSAG
   - **Hostname:** `www.vpsag.com`
   - **Username:** Your VPSAG API username
   - **Password:** Your VPSAG API key
4. Click **Test Connection** to verify credentials

## Product Configuration

### Creating a Product

1. Go to **Setup > Products/Services > Products/Services**
2. Create a new product or edit an existing one
3. Under **Module Settings** tab:
   - **Module Name:** ArkhostVPSAG
   - **Server Group:** Select your VPSAG server group

### Configurable Options

The module uses two primary configurable options that are dynamically populated from the VPSAG API:

| Option | Config Key | Description |
|--------|------------|-------------|
| **Plan ID** | `configoption1` | VPS plan - dropdown populated from `/api/v1/plans` showing plan names with prices |
| **OS ID** | `configoption2` | Operating system - dropdown populated from `/api/v1/os/plan/{plan_id}` based on selected plan |

#### Setting Up Configurable Options

You can override the default product options using WHMCS Configurable Options:

1. Go to **Setup > Products/Services > Configurable Options**
2. Create a new group and link it to your VPSAG product(s)
3. Add options with these exact names:
   - `planid|Plan` - To allow customers to select different plans
   - `osid|Operating System` - To allow customers to select their OS during order

**Option format:** `{api_id}|{display_name}`

The numeric ID before the pipe is the API ID from VPSAG/EVPS.

#### Finding the IDs

The module displays IDs directly in the dropdowns (format: `ID | Name`):

1. Go to **Setup > Products/Services > Products/Services**
2. Edit any product using the ArkhostVPSAG module
3. Go to the **Module Settings** tab
4. The **Plan** and **Operating System** dropdowns show: `{id} | {name}`

Use those IDs when creating Configurable Options.

**API terminology:**
- `planid` = Package/Plan ID from VPSAG API
- `osid` = Operating System ID from VPSAG API

**Note:** OS availability varies by plan - you must select a Plan first before the OS dropdown populates.

The module checks for configurable options first, then falls back to product-level settings.

### Callback URL

For automatic provisioning updates (IP, password delivery), configure your callback URL in VPSAG:

```
https://yourdomain.com/modules/servers/ArkhostVPSAG/callback.php
```

The callback handler:
- Validates requests using SHA256 signature verification
- Updates service with username, password, IPs (IPv4/IPv6)
- Sets VPS label to `WHMCS {service_id}` for easy identification

## Module Functions

### Client Area Actions

| Action | Description |
|--------|-------------|
| Start/Stop/Restart | Basic power controls |
| VNC Console | Browser-based console access |
| Reinstall OS | Fresh install with optional SSH key and post-install script |
| Reset Root Password | Generate new root password |
| Hostname/rDNS | Set hostname and reverse DNS |
| Graphs | View CPU, RAM, disk, network usage over time |
| Backups | Create, restore, and delete backups |
| Firewall | Add/remove rules, commit changes |
| ISO | Mount/unmount ISO images |

### Admin Actions

| Action | Description |
|--------|-------------|
| Start/Stop/Reboot | Power controls from admin panel |
| VNC Console | Direct VNC link |
| Suspend/Unsuspend | Service suspension management |
| Terminate | Cancel VPS at VPSAG |
| Change Package | Upgrade to higher plan |

### Sidebar Buttons

The module adds custom sidebar buttons to the client area:
- Start, Stop, Restart, VNC Console

## API Integration

Base URL: `https://www.vpsag.com/api/v1/`

Authentication headers:
- `X_API_USER`: API username
- `X_API_KEY`: API key

The module handles all API communication internally with:
- TLS 1.2 enforcement
- 15-second timeout
- Full request/response logging via WHMCS module log

## VPS ID Storage

The VPS ID is stored in WHMCS service properties with key `vpsag|VPSAG ID` in format `VPSAG-{numeric_id}`.

## Language Customization

Override translations by creating files in:
```
/modules/servers/ArkhostVPSAG/lang/overrides/{language}.php
```

## Screenshots

### Overview
![Main Dashboard](screenshots/vpsag1.png)

### Graphs
![Graphs](screenshots/vpsag2.png)

### Backups
![Backups](screenshots/vpsag3.png)

### Firewall
![Firewall](screenshots/vpsag4.png)

### Settings
![Settings](screenshots/vpsag5.png)

## Changelog

### Version 1.4
- Fixed firewall rule duplication bug when adding new rules
- Added validation warning for ANY protocol with specific port numbers
- Redesigned firewall interface with modern card-based layout
- Created standalone Firewall tab for better organization
- Completely redesigned VPS Overview section with:
  - Server Status Card (hostname, IPs, OS, status, uptime, server type)
  - Resource Allocation Card (CPU cores, Memory, Storage, Traffic)
  - Resource Usage Card (RAM, Bandwidth, CPU)
  - Quick Actions Card (Start/Stop, Restart, VNC Console)
- Fixed Quick Actions button functionality
- Completed all language translations (8 languages)
- Enhanced UI styling with gradient backgrounds and smooth animations
- Improved responsive design and layout consistency

### Version 1.3
- Enhanced API integration
- Performance improvements
- Bug fixes

### Version 1.2
- Custom notifications replace browser popups
- Confirmation dialogs for critical actions
- Multi-language support for all notifications
- Smart post-installation script examples based on OS
- Fixed firewall rules not displaying after creation
- Improved UI styling and animations

### Version 1.1
- Basic VPS management
- Backup operations
- Firewall rules
- OS reinstall

### Version 1.0
- Initial release

## Credits

Originally based on work by [andretunes](https://github.com/andretunes/whmcs-module-vpsag)
Substantially rewritten and extended by ArkHost

## License
MIT License
© 2025 ArkHost