Python cPanel

A Python client for the cPanel API and CSF.

• Installation
• Authentication
  • Basic user/password authentication
  • Access hash authentication
  • Connection Options
• cPanel External API
  • External API without params
  • External API with params
• cPanel API Functions
  • API 2 Function without params
  • API 2 Function with params
  • Using cPanel API 1
• ConfigServer Firewall API
  • Unblock IP Address
  • Block IP Address
  • Allow IP Address
  • Ignore IP Address

Installation

Using pip:

$ pip install pycpanel

Authentication

You may use either remote access hash or basic user/password authentication. Remote access hash authentication is the prefered method.

Basic user/password authentication

Warning: Do not perform authentication this way over an unsecured connection (ssl=False). The use of this method over an unsecured connection can compromise your server.

import pycpanel

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

Access hash authentication

http://docs.cpanel.net/twiki/bin/view/AllDocumentation/WHMDocs/RemoteAccess

import pycpanel

hash = remote_access_hash
server = pycpanel.conn(hostname='myserver.com.au', hash=hash)

Connection Options

The default options connect to the server as root using SSL on port 2087 without verifying the SSL certificate.

import pycpanel

server = pycpanel.conn(hostname, username='root', hash=None, password=None, ssl=True, verify=False, check_conn=False)

• hostname (required) - the hostname or ip address of the cPanel server.
• username (optional, default='root') - the authenticating user's username.
• hash (optional) - The remote access hash for the cPanel server. If not provided a password must be provided instead.
• password (optional) - The password for the authenticating user. If not provided the remote access hash must be provided instead.
• ssl (optional, boolean, default=True) - If set to False pycpanel will connect on HTTP port 2086 rather than HTTPS port 2087.
• verify (optional, boolean, default=False) - If set to True the SSL certificate of the server will be verifying to ensure it is valid.
• check_conn (optional, boolean, default=True) - If set to True pycpanel will test and authenticate against the server after setting up the connection.

cPanel External API

Detailed documentation for the cPanel External API can be found here: http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/XmlApi

pycpanel.api(function, params=None)

External API without params

This example will print a dict with all the cPanel accounts on the server. No additional params are passed in this example.

import pycpanel

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')
print server.api('listaccts')

External API with params

This exmaple will adjust the cPanel account with username 'user1' to have a limit of 10 addon domains.

import pycpanel

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

params = {
    'user'      : 'user1',
    'MAXADDON ' : 10,
}

server.api('modifyacct', params=params)

cPanel API Functions

Detailed documentation for the cPanel API 2 Functions can be found here: http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api2/WebHome

pycpanel.cpanel_api(module, function, user, params=None, version=2)

API 2 Function without params

This example retrieves a list of email accounts associated with a cPanel account with username 'user1'.

import pycpanel

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

print server.cpanel_api('Email', 'listpops', 'user1')

API 2 Function with params

This example creates a new email account ([email protected]) for the user account 'user1'.

import pycpanel

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

params = {
    'domain'    : 'mydomain.com.au',
    'email'     : 'steve',
    'password'  : '@#fwefq122442',
    'quota'     : 0
}

server.cpanel_api('Email', 'addpop', 'user1', params=params)

Using cPanel API 1

You can cPanel API 1 calls by specifically making the API call as version 1.

import pycpanel

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

params = {
    'arg-0' : 'username',
    'arg-1' : 'password',
    'arg-2' : 'domain.tld',
}

server.cpanel_api('Email', 'addpop', 'user1', params=params, version=1)

ConfigServer Firewall API

To use the ConfigServer Firewall (CSF) API, the CSF cPanel plugin must be installed and active on your cPanel server.

Unblock IP Address

This function will remove an IP address from the firewall (temp and perm blocks).

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

server.csf.unblock('192.168.0.1')

# Returns True if succesfull.

Block IP Address

This function will block an IP address on the firewall and add it to the deny file (csf.deny).

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

server.csf.deny('192.168.0.1')

# Returns True if succesfull.

Optionaly, a comment may be left to explain why the IP address was blocked:

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

server.csf.deny('192.168.0.1', comment='Why the IP was blocked")

# Returns True if succesfull.

Allow IP Address

This function will allow an IP address through the firewall and add it to the allow file (csf.allow).

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

server.csf.allow('192.168.0.1')

# Returns True if succesfull.

Optionaly, a comment may be left to explain why the IP address was allowed through the firewall:

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

server.csf.allow('192.168.0.1', comment='Why the IP was allowed")

# Returns True if succesfull.

Ignore IP Address

This function will ignore an IP address in lfd and add it to the ignore file (csf.ignore) and restart lfd.

server = pycpanel.conn(hostname='myserver.com.au', password='mypassword')

server.csf.ignore('192.168.0.1')

# Returns True if succesfull.