Skip to main content

Crate cpanel_rs

Crate cpanel_rs 

Source
Expand description

§cpanel-rs

An unofficial Rust client for the cPanel & WHM APIs. This crate lets you manage hosting accounts, DNS records, email, databases, files, SSL certificates, and backups programmatically via UAPI and WHM JSON API endpoints.

This project is not affiliated with or endorsed by WebPros.

§Quick Start

# Cargo.toml
[dependencies]
cpanel-rs = "0.3"
use cpanel_rs::{CpanelClient, CpanelBuilder};

// Simple construction
let client = CpanelClient::simple("server.example.com", 2087, "root", "yourpass").unwrap();

// Or with the builder for full control
let client = CpanelBuilder::new("server.example.com", 2087, "root")
    .password("secret")
    .timeout(std::time::Duration::from_secs(30))
    .disable_tls_verification()
    .build()
    .unwrap();

§Supported Operations

ModuleFunctionality
accountList, create, delete, suspend, modify accounts (WHM)
backupBackup creation, listing, restoration, scheduling (UAPI)
cronList, add, edit, delete scheduled cron jobs (UAPI)
databaseMySQL databases, users, and privileges (UAPI)
dnsList, add, delete DNS records; import/export zones (UAPI)
domainsAddon domains, parked domains (aliases), and subdomains (UAPI)
emailEmail accounts, forwarders, autoresponders, mailing lists (UAPI)
filemanagerList, create, delete, upload, download, compress files (UAPI)
ftpFTP account management: list, create, modify, delete (UAPI)
securityModSecurity rules and IP blocker (blacklist/whitelist) (UAPI)
sslSSL certificate management and Let’s Encrypt issuance (UAPI)
resourcesDisk/quota usage, PHP version management (UAPI)

§Authentication

Three auth methods are supported:

  • Password — Basic HTTP auth. Works for both cPanel (2083) and WHM (2087).
  • Raw Key — WHM user:key header. Requires WHM access and a raw access key generated in WHM > Manage Remote Access Key.
  • API Token — Authorization: cpanel <user>:<token>. Generates granular, scoped permissions without requiring a full account password or root access. Create tokens in cPanel > Home > Security Center > API Tokens.
use cpanel_rs::CpanelBuilder;

// Password auth
let client = CpanelBuilder::new("myhost.com", 2087, "user").password("pass").build().unwrap();

// Raw key auth (WHM only)
let client = CpanelBuilder::new("myhost.com", 2087, "root").key("abc123...").build().unwrap();

// API Token auth (cPanel UAPI)
let client = CpanelBuilder::new("myhost.com", 2083, "user").token("uI7fX2aB9cD...").build().unwrap();

§Retry & Backoff

Enable the retry feature for automatic exponential backoff on transient errors (429 rate limits, 503 service unavailable, connection resets):

[dependencies]
cpanel-rs = { version = "0.3", features = ["retry"] }
use cpanel_rs::{CpanelClient, RetryPolicy};

let client = CpanelClient::simple("server.example.com", 2087, "root", "pass").unwrap();
let client = client.with_retry_policy(
    RetryPolicy::default().max_retries(5).base_delay(std::time::Duration::from_millis(500)),
);

§Auto-Paginating Streams

Enable the stream feature to use async streams for large listings:

[dependencies]
cpanel-rs = { version = "0.3", features = ["stream"] }
#[cfg(feature = "stream")]
{
    use cpanel_rs::CpanelClient;
    use futures::StreamExt;

    #[tokio::main]
    async fn main() -> Result<(), cpanel_rs::CpanelError> {
        let client = CpanelClient::simple("server.example.com", 2087, "root", "pass").unwrap();

        // Stream all accounts without manual pagination
        let mut stream = client.stream_accounts();
        while let Some(acct) = stream.next().await {
            let acct = acct?;
            println!("{} @ {}", acct.username, acct.domain);
        }
        Ok(())
    }
}

§Streaming File Operations

Upload large files from an async reader without loading them entirely into memory:

use cpanel_rs::CpanelClient;
use tokio::fs::File;
use tokio::io::AsyncReadExt;

#[tokio::main]
async fn main() -> Result<(), cpanel_rs::CpanelError> {
    let client = CpanelClient::simple("server.example.com", 2083, "user", "pass").unwrap();
    let mut file = File::open("large_upload.zip").await?;
    client.upload_file_from_reader("user", "/public_html/large_upload.zip", &mut file, "large_upload.zip", 1024 * 1024).await?;
    Ok(())
}

§Environment Variables (opt-in)

Enable the dotenv feature to load credentials from a .env file:

[dependencies]
cpanel-rs = { version = "0.3", features = ["dotenv"] }

Then create a .env file:

CPANEL_HOST=server.example.com
CPANEL_PORT=2087
CPANEL_USER=root
CPANEL_PASSWORD=yourpass

§Error Handling

All methods return Result<_, CpanelError>. Errors fall into these categories:

Use CpanelError::ApiError to inspect structured failure details including all error messages, warnings, and stack traces.

Re-exports§

pub use client::AuthMethod;
pub use client::CpanelBuilder;
pub use client::CpanelClient;
pub use client::RetryPolicy;
pub use types::CpanelError;

Modules§

account
cPanel & WHM account management (WHM API). Account management via WHM API.
backup
Backup management (UAPI). Backup management via cPanel UAPI.
client
Core client: CpanelClient, CpanelBuilder, AuthMethod, and RetryPolicy.
cron
Cron job management (UAPI). Cron job management via cPanel UAPI.
database
MySQL database management (UAPI). MySQL database management via cPanel UAPI.
dns
DNS record management (UAPI). DNS management via cPanel UAPI.
domains
Domain and subdomain management (UAPI). Domain and subdomain management via cPanel UAPI.
email
Email account management (UAPI). Email management via cPanel UAPI.
filemanager
File manager operations (UAPI). File manager operations via cPanel UAPI.
ftp
FTP account management (UAPI). FTP account management via cPanel UAPI.
models
Data models shared across modules. Data models used throughout the crate.
resources
Resource usage and PHP version management (UAPI). Resource usage and PHP management via cPanel UAPI.
security
Security: ModSecurity rules and IP blocker (UAPI). Security: ModSecurity rules and IP blocker via cPanel UAPI.
ssl
SSL certificate management (UAPI). SSL certificate management via cPanel UAPI.
types
Core types: errors, response envelopes, and query builders. Core types shared across the crate.