cpanel-rs
An unofficial, async Rust client for the cPanel & WHM APIs. Manage hosting accounts, DNS zones and records, email accounts and forwarders, databases, cron jobs, domains/subdomains, FTP, file manager operations, SSL certificates, backups, security rules, and server resources programmatically.
Disclaimer: This project is an unofficial open-source library and is not affiliated with, endorsed by, or sponsored by WebPros / cPanel, L.L.C.
Features
- WHM API v1 — Account management, package listing, suspension/unsuspension, termination
- cPanel UAPI — Complete coverage: Cron, Databases, DNS, Domains/Subdomains, Email, File Manager, FTP, Resources, Security (ModSecurity & IP Blocker), and SSL
- Triple Authentication — HTTP Basic (Username + Password), WHM API Key (
WHM user:key), and cPanel API Token (cpanel user:token) - Resilient Client — Configurable exponential retry policy with jitter for transient errors (429, 503, connection drops)
- Auto-Paginating Streams — Async streams over large account and file listings powered by
futures::Stream - Memory-Bounded Streaming — Upload large files directly from async readers (
AsyncRead) - Flexible Builder — Custom timeouts, TLS verification toggle (for self-signed certs), and custom HTTP headers
- Async & Fast — Built on top of
tokioandreqwest0.12 with JSON serialization viaserde - Optional Dotenv & Tracing — Load credentials from
.envfiles and enable structured diagnostics
Installation
Add cpanel-rs to your Cargo.toml:
[]
= "0.3"
Feature Flags
| Feature | Description | Default |
|---|---|---|
retry |
Enables exponential backoff retry support via RetryPolicy |
No |
stream |
Enables async streaming paginators (stream_accounts, stream_files) |
No |
dotenv |
Enables loading credentials from .env files via CpanelClient::from_env() |
No |
full |
Enables all features (retry, stream, dotenv) |
No |
[]
= { = "0.3", = ["full"] }
Quick Start
use CpanelClient;
async
Authentication & Client Configuration
1. Simple Constructor (Password Auth)
use CpanelClient;
// Automatically selects HTTPS if port is 2083 or 2087
let client = simple?;
2. Client Builder (Advanced Options)
Use CpanelBuilder for full control over auth methods, TLS verification, timeouts, and headers:
use Duration;
use CpanelBuilder;
// cPanel API Token Authentication
let client = new
.token
.timeout
.disable_tls_verification // Useful for servers with self-signed SSL
.build?;
3. Retry Policy (Exponential Backoff)
use Duration;
use ;
let client = simple?;
let client = client.with_retry_policy;
4. Loading from Environment Variables
Enable the dotenv feature:
# .env
CPANEL_HOST=server.example.com
CPANEL_PORT=2087
CPANEL_USER=root
CPANEL_PASSWORD=your_password
# Or use CPANEL_TOKEN / CPANEL_KEY:
# CPANEL_TOKEN=your_token
CPANEL_SSL=true
use CpanelClient;
let client = from_env?;
API Modules Overview
| Module | Target API | Description |
|---|---|---|
account |
WHM API 1 | Create, list, modify, suspend, unsuspend, and terminate hosting accounts |
backup |
UAPI | Create backups, restore backups, configure automated backup schedules |
cron |
UAPI | List, add, edit, and delete scheduled cron jobs |
database |
UAPI | Create and manage MySQL databases, database users, and grant privileges |
dns |
UAPI | Manage DNS records (A, CNAME, TXT, MX), export and import zone files |
domains |
UAPI | Manage addon domains, parked domains (aliases), and subdomains |
email |
UAPI | Manage email accounts, forwarders, autoresponders, and mailing lists |
filemanager |
UAPI | List files, create directories, upload, download, compress, and extract archives |
ftp |
UAPI | List, create, change passwords/quotas, and delete FTP accounts |
resources |
UAPI | Retrieve disk usage, bandwidth consumption, and manage PHP versions |
security |
UAPI | Toggle ModSecurity rules and manage IP blocker blacklist/whitelist |
ssl |
UAPI | List and install SSL certificates, issue Let's Encrypt certificates |
Usage Examples
Streaming Accounts (Paginator)
use CpanelClient;
use StreamExt;
async
Managing Cron Jobs (UAPI)
use ;
async
Adding an Addon Domain (UAPI)
use ;
async
Streaming File Upload (AsyncRead)
use CpanelClient;
use File;
async
Building and Testing
# Clone the repository
# Build the crate
# Run unit and documentation tests
# Run linter
# Build documentation
Contributing
Contributions are welcome! Please check out CONTRIBUTING.md for guidelines on development and submitting pull requests.
License
This project is licensed under the MIT License.