API Reference¶

The WebFaction XML-RPC API provides methods to make many control panel tasks (and others) scriptable.

This documentation is a complete reference to all of the possible API calls. Please note that all arguments are positional and many are required. Arguments may be omitted if they have a default value (for example, arg_name=some_value) and follow any other arguments with which you have provided a value. The XML-RPC standard does not support keyword arguments.

General¶

login(username, password, machine=None)¶

Log in a user and return credentials.

Parameters:	username – a valid WebFaction control panel username password – a valid WebFaction control panel user’s password machine – the case-sensitive name of the machine to access (for example, `Web55`). This parameter applies to accounts with plans on multiple machines. The parameter may be omitted for accounts on one machine only.

The values returned are a session ID and a dictionary. The dictionary contains the following key-value pairs:

id: account ID
username: username
home: home directory path
web_server: Web server associated with the logged in account (for example, Web55)
mail_server: mail server associated with the logged in account (for example, Mailbox2)

Note

The session ID is required for all subsequent API calls.

Email¶

change_mailbox_password(session_id, mailbox, password)¶

Change a mailbox password.

Parameters:	session_id – session ID returned by `login()` mailbox – a valid mailbox name password – the new mailbox password

See also

See Strengthening Passwords for important information about choosing passwords.

create_email(session_id, email_address, targets, autoresponder_on=False, autoresponder_subject='', autoresponder_message='', autoresponder_from='', script_machine='', script_path='')¶

Create an email address which delivers to the specified mailboxes.

If autoresponder_on is True, then an autoresponder subject, message, and from address may be specified.

Parameters:

session_id – session ID returned by login()
email_address – an email address (for example, name@example.com)
targets (string) – names of destination mailboxes or addresses, separated by commas
autoresponder_on (boolean) – whether an autoresponder is enabled for the address
autoresponder_subject – subject line of the autoresponder message
autoresponder_message – body of the autoresponder message
autoresponder_from – originating address of the autoresponder message
script_machine – a machine name for specifying a path to a script
script_path – a path to a script

See also

update_email()

create_mailbox(session_id, mailbox, enable_spam_protection=True, discard_spam=False, spam_redirect_folder='', use_manual_procmailrc=False, manual_procmailrc='')¶

Create a mailbox and return a dictionary containing the following key-value pairs:

id: mailbox ID
name: name of mailbox created
enable_spam_protection: a boolean indicating whether spam protection is enabled for the mailbox
password: a generated password
discard_spam: a boolean indicating whether spam emails should be discarded
spam_redirect_folder: a string containing the path to an IMAP folder where the server stores spam messages
use_manual_procmailrc: a boolean indicating whether manual procmailrc rules are enabled
manual_procmailrc: a string containing the manual procmailrc rules

Parameters:

session_id – session ID returned by login()
mailbox – name of mailbox
enable_spam_protection (boolean) – whether spam protection is enabled for the new mailbox
discard_spam (boolean) – whether spam received by the new mailbox will be discarded. Warning: setting this to True may cause you to lose emails forever.
spam_redirect_folder – name of the folder where email identified as spam is be stored
use_manual_procmailrc (boolean) – whether a manual procmailrc file is to be used for the new mailbox
manual_procmailrc – the procmailrc rules for the new mailbox

See also

update_mailbox()

delete_email(session_id, email_address)¶

Delete an email address.

Parameters:	session_id – session ID returned by `login()` email_address – an email address (for example, `name@example.com`)

delete_mailbox(session_id, mailbox)¶

Delete a mailbox.

Parameters:	session_id – session ID returned by `login()` mailbox – name of mailbox

list_emails(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: an email ID
email_address: an email address (for example, name@example.com)
targets: mailboxes or email addresses to which the address is set to deliver
autoresponder_on: a boolean indicating whether an autoresponder is enabled for the address
autoresponder_subject: the autoresponder subject line (if applicable)
autoresponder_message: the autoresponder message body (if applicable)
autoresponder_from: the autoresponder from address (if applicable)

Parameters:	session_id – session ID returned by `login()`

list_mailboxes(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: a mailbox ID
mailbox: the name of mailbox
enable_spam_protection: a boolean indicating whether spam protection is enabled for the mailbox
discard_spam: a boolean indicating whether spam emails are discarded
spam_redirect_folder: a string containing the path to an IMAP folder where the server stores spam messages
use_manual_procmailrc: a boolean indicating whether you want to use your own .procmailrc file
manual_procmailrc: a string containing the text that should go in the .procmailrc file

Parameters:	session_id – session ID returned by `login()`

update_email(session_id, email_address, targets, autoresponder_on=False, autoresponder_subject='', autoresponder_message='', autoresponder_from='', script_machine='', script_path='')¶

Change an existing email address. The email address must exist. A dictionary containing the following key-value pairs will be returned:

id: email ID
email_address: email address (for example, name@example.com)
targets: mailboxes or email addresses to which the address is set to deliver

Parameters:

session_id – session ID returned by login()
email_address – an email address (for example, name@example.com)
targets (list, tuple) – names of destination mailboxes
autoresponder_on (boolean) – whether an autoresponder is enabled for the address
autoresponder_subject – subject line of the autoresponder message
autoresponder_message – body of the autoresponder message
autoresponder_from – originating address of the autoresponder message
script_machine – a machine name for specifying a path to a script
script_path – a path to a script

See also

create_email()

update_mailbox(session_id, mailbox, enable_spam_protection=True, discard_spam=False, spam_redirect_folder='', use_manual_procmailrc=False, manual_procmailrc='')¶

Change an existing mailbox. The mailbox must exist.

Parameters:

session_id – session ID returned by login()
mailbox – name for new mailbox
enable_spam_protection (boolean) – whether spam protection is enabled for this mailbox
discard_spam (boolean) – whether spam received by this mailbox will be discarded
spam_redirect_folder – name of the folder where email identified as spam is be stored
use_manual_procmailrc (boolean) – whether a manual procmailrc setting is to be used for this mailbox
manual_procmailrc – the procmailrc rules for this mailbox

See also

create_mailbox()

Websites and Domains¶

create_domain(session_id, domain, *subdomains)¶

Create a domain entry. If domain is an exisitng domain, subdomains can be created with subsequent parameters.

Parameters:	session_id – session ID returned by `login()` domain – a domain name in the form `example.com`

Example:

Create a domain entry for widgetcompany.example:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.create_domain(session_id, 'widgetcompany.example', 'www', 'design')
{'domain': 'widgetcompany.example',
 'id': 47255,
 'subdomains': ['www', 'design']}

create_website(session_id, website_name, ip, https, subdomains, *site_apps)¶

Create a new website entry.

Parameters:

session_id – session ID returned by login()
website_name – the name of the new website entry
ip – IP address of the server where the entry resides
https (boolean) – whether the website entry should use a secure connection
subdomains – a list of the (sub)domains to be associated with the website entry.
site_apps – parameters after subdomains are tuples or lists of a valid application name and a path (for example, ('htdocs', '/') or ['mydjangoapp', '/myapp/']).

Example:

Create a website entry for widgetcompany.example‘s new Django project over HTTPS:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.create_website(session_id,
... 'widgets_on_the_web',
... '174.133.82.194',
... True,
... ['widgetcompany.example', 'www.widgetcompany.example'],
... ['django', '/'])
{'https': True,
 'id': 67074,
 'ip': '174.133.82.194',
 'name': 'widgets_on_the_web',
 'site_apps': [['django', '/']],
 'subdomains': ['widgetcompany.example', 'www.widgetcompany.example']}

update_website(session_id, website_name, ip, https, subdomains, *site_apps)¶

Update a new website entry.

Parameters:

session_id – session ID returned by login()
website_name – the name of the new website entry you want to update; this parameter can’t be updated
ip – IP address of the server where the entry resides
https (boolean) – whether the website entry you want to update uses a secure connection; this parameter can’t be updated
subdomains – a list of the (sub)domains to be associated with the website entry.
site_apps – parameters after subdomains are tuples or lists of a valid application name and a path (for example, ('htdocs', '/') or ['mydjangoapp', '/myapp/']).

Example:

Update a website entry for widgetcompany.example‘s new Django project over HTTPS:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.update_website(session_id,
... 'widgets_on_the_web',
... '174.133.82.195',
... True,
... ['widgetcompany.example', 'dev.widgetcompany.example'],
... ('django', '/'), ('wordpress', '/blog'))
{'https': True,
 'id': 67074,
 'ip': '174.133.82.195',
 'name': 'widgets_on_the_web',
 'site_apps': [['django', '/'], ['wordpress', '/blog']],
 'subdomains': ['widgetcompany.example', 'dev.widgetcompany.example']}

delete_domain(session_id, domain, *subdomains)¶

Delete a domain record or subdomain records.

If subdomains are specified with parameters after domain, delete only those subdomains and not the domain entry.

Parameters:	session_id – session ID returned by `login()` domain – name of the domain to be deleted or the parent domain of the subdomains to be deleted

delete_website(session_id, website_name, ip=None, https=None)¶

Delete a website entry.

Parameters:	session_id – session ID returned by `login()` website_name – name of website entry to be deleted ip – IP address of the server where the entry resides https (boolean) – whether the entry uses a secure connection

list_domains(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: domain ID
domain: domain (for example, example.com)
subdomains: list of subdomains for that domain (for example, ["www", "www2"])

Parameters:	session_id – session ID returned by `login()`

list_websites(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: website ID
name: website name
ip: website IP address
https: whether the website is available over https
subdomains: list of subdomains for that website
website_apps: list of apps and their paths served by that website; each item in the list is a 2-item list [<app name>, path]

Parameters:	session_id – session ID returned by `login()`

Applications¶

create_app(session_id, name, type, autostart, extra_info, script_code='')¶

Create a new application.

Parameters:

session_id – session ID returned by login()
name – name of the application
type – type of the application (for example, django102_mp331_25 or static)
autostart (boolean) – whether the app should restart with an autostart.cgi script
extra_info – additional information required by the application (for example, a file path). If extra_info is not required or used by the application, it is ignored.

Note

For a complete list of possible applications and their associated extra_info parameters, please see the Home > App types (login required) page on the WebFaction control panel.

delete_app(session_id, name)¶

Delete an application.

Parameters:	session_id – session ID returned by `login()` name – name of the application

list_apps(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: app ID
name: app name
type: app type
autostart: whether the app uses autostart or not
port: contains the port number if the app listens on a port; contains 0 otherwise
extra_info: contains the extra info for the app if any
machine: name of the machine where the app resides

Parameters:	session_id – session ID returned by `login()`

list_app_types(session_id)¶

Return a list of dictionaries with the following key-value pairs:

description: description of the application type
name: short identifier for the application type
autostart: applicable or an empty string, indicating whether the application uses an autostart.cgi file
extra_info: description of any additional information required by the application installer’s extra_info field

See also

create_app()

Parameters:	session_id – session ID returned by `login()`

Cron¶

create_cronjob(session_id, line)¶

Create a new cron job.

Parameters:	session_id – session ID returned by `login()` line – crontab line to be added

See also

For more information about the cron syntax, please see the Wikipedia entry on cron.

delete_cronjob(session_id, line)¶

Remove an existing cron job.

Parameters:	session_id – session ID returned by `login()` line – crontab line to be removed

DNS¶

create_dns_override(session_id, domain, a_ip='', cname='', mx_name='', mx_priority='', spf_record='')¶

Create DNS records and return a list of the new records (as in the form of list_dns_overrides()).

Parameters:	session_id – session ID returned by `login()` domain – domain name to be overridden (for example, `sub.example.com`) a_ip – A IP address cname – CNAME record mx_name – Mail exchanger record host name mx_priority – Mail exchanger record priority spf_record – TXT record

delete_dns_override(session_id, domain, a_ip='', cname='', mx_name='', mx_priority='', spf_record='')¶

Delete DNS records and return a list of the deleted records (as in the form of list_dns_overrides()).

Parameters:	session_id – session ID returned by `login()` domain – domain name override to be deleted (for example, `sub.example.com`) a_ip – A IP address cname – CNAME record mx_name – Mail exchanger record host name mx_priority – Mail exchanger record priority spf_record – TXT record

list_dns_overrides(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: domain ID
domain: domain name to be overridden (for example, sub.example.com)
a_ip: A IP address
aaaa_ip: AAAA IP address (for IPv6)
cname: CNAME record
mx_name: Mail exchanger record host name
mx_priority: Mail exchanger record priority
spf_record: TXT record
srv_record: Service record

Parameters:	session_id – session ID returned by `login()`

Databases¶

change_db_user_password()¶

Change a database user’s password.

Parameters:	session_id – session ID returned by `login()` username (string) – a databse user’s username password (string) – the new password db_type (strings `mysql` or `postgresql`) – the database type
Returns:	A struct containing information about the database and user. The struct contains member names `username`, `machine`, `db_type`, `database`.

create_db(session_id, name, db_type, password)¶

Create a database.

Parameters:	session_id – session ID returned by `login()` name – database name db_type (strings `mysql` or `postgresql`) – the database type password – password for the default database user

Note

MySQL database names may not exceed 16 characters.

create_db_user()¶

Create a database user.

Parameters:	session_id – session ID returned by `login()` username (string) – the new database user’s username password (string) – the new database user’s password db_type (strings `mysql` or `postgresql`) – the database type
Returns:	A struct containing information about the new database user. The struct contains member names `machine`, `username`, and `db_type`.

delete_db(session_id, name, db_type)¶

Delete a database.

Parameters:	session_id – session ID returned by `login()` name – database name db_type (strings `mysql` or `postgresql`) – the database type

delete_db_user()¶

Delete a database user.

Parameters:	session_id – session ID returned by `login()` username (string) – the database user’s username db_type (strings `mysql` or `postgresql`) – the database type
Returns:	A struct containing information about the former database user. The struct contains member names `machine`, `username`, and `db_type`.

enable_addon()¶

Enable a database addon.

Note

This method applies to PostgreSQL databases only.

Parameters:	session_id – session ID returned by `login()` database (string) – a database name db_type (string `postgresql`) – the database type addon (string) – the addon to enable (`tsearch` or `postgis`)
Returns:	A struct containing information about the database and addon. The struct contains member names `machine`, `db_type`, `addon`, and `database`.

grant_db_permissions()¶

Grant full database permissions to a user with respect to a database.

Parameters:	session_id – session ID returned by `login()` username (string) – a databse user’s username database (string) – a database name db_type (strings `mysql` or `postgresql`) – the database type
Returns:	A struct containing information about the database and user. The struct contains member names `username`, `machine`, `db_type`, `database`.

list_dbs(session_id)¶

Return a list of dictionaries with the following key-value pairs:

id: database ID
name: database name
db_type: database type (mysql or postgresql)
machine: name of the machine where the app resides

Parameters:	session_id – session ID returned by `login()`

list_db_users()¶

Return an array of structs containing information about database users.

Parameters:	session_id – session ID returned by `login()`
Returns:	An array of structs containing information about the database users associated with the account. The structs contain member names `username`, `machine`, and `db_type`.

make_user_owner_of_db()¶

Assign ownership of a database to a user.

Parameters:	session_id – session ID returned by `login()` username (string) – a databse user’s username database (string) – a database name db_type (strings `mysql` or `postgresql`) – the database type
Returns:	A struct containing information about the database and user. The struct contains member names `username`, `machine`, `db_type`, `database`.

revoke_db_permissions()¶

Revoke a user’s permissions with respect to a database.

Parameters:	session_id – session ID returned by `login()` username (string) – a databse user’s username database (string) – a database name db_type (strings `mysql` or `postgresql`) – the database type
Returns:	A struct containing information about the database and user. The struct contains member names `username`, `machine`, `db_type`, `database`.

Files¶

replace_in_file(session_id, filename, *changes)¶

Find and replace a string in a file in the users’s home directory tree.

Parameters:	session_id – session ID returned by `login()` filename – path to file from the user’s home directory

Any parameters after filename are tuples or lists containing a pair of strings where the first is the string to be replaced and the second is the replacement text.

Example:

Find all appearances of the word “eggs” in a file in the user’s home directory and replace them with the word “spam.”

$ cat myfile.txt
eggs, spam, spam, and spam.
spam, spam, spam, and eggs.

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.replace_in_file(sid, 'myfile.txt', ('eggs', 'spam'))
''
>>> exit()

$ cat myfile.txt
spam, spam, spam, and spam.
spam, spam, spam, and spam.

write_file(session_id, filename, str, mode = 'wb')¶

Write a string to a file in the user’s home directory tree.

Parameters:	session_id – session ID returned by `login()` filename – path to file to be written from the user’s home directory. str – string to be written mode – write mode

Note

Commonly, the write mode is w for plain text and wb for binaries. a and ab can be used to append to files.

See also

For more information about write modes, please see open().

Shell Users¶

list_users(session_id)¶

Return a list of shell users represented as dictionaries with the following key-value pairs:

username: username
machine: the user’s server (for example, Web100)
shell: the user’s configured command line interpreter (for example, bash or tcsh)
groups: a list of extra permissions groups of which the user is a member

Parameters:	session_id – session ID returned by `login()`

change_user_password(session_id, username, password)¶

Change a shell user’s password and return a dictionary of the new user in the manner of list_users().

Parameters:	session_id – session ID returned by `login()` username – username password – a new passowrd

create_user(session_id, username, shell, groups)¶

Create a new shell user and return a dictionary of the new user in the manner of list_users().

Parameters:

session_id – session ID returned by login()
username – username
shell – the user’s command line interpreter. Acceptable values are none, bash, sh, ksh, csh, or tcsh. A user with none as the configured shell has FTP access, but does not have SSH access.
groups – a list of extra permissions groups of which the new user is to be a member. All users are automatically a member of their own group; do not include the user’s own group in the list. Use an empty list to specify no extra groups.

delete_user(session_id, username)¶

Delete user username and return a dictionary of the deleted user in the manner of list_users().

Parameters:	session_id – session ID returned by `login()` username – username

Servers¶

list_machines(session_id)¶

List all of the machines associated with the account. The method returns a list of dictionaries with the following key-value pairs:

name: A system’s name (for example, Web100).
id: The system’s identifying number.
operating_system: The machine’s operating system (for example, Centos6-64bit).
location: The machine’s location (for example, USA).

list_ips(session_id)¶

List all of the machines associated with the account and their IP addresses. This method returns a list of dictionaries with the following key-value pairs:

machine: A system’s name (for example, Web100).
ip: The system’s IP address.
is_main: A True or False value indicating whether the IP address is the primary IP address for the server (True) or an extra IP address provisioned to the account (False).
id: The IP’s identifying number.

Miscellaneous¶

run_php_script(session_id, script, code_before='')¶

Run PHP code followed by a PHP script. The PHP code and script is run as the user.

Parameters:	session_id – session ID returned by `login()` script – an absolute path to script to be run or the path to the script starting from the user’s home directory code_before – PHP code to be executed before script

set_apache_acl(session_id, paths, permission='rwx', recursive=False)¶

Grant the machine-wide Apache instance access to files or directories.

Parameters:	session_id – session ID returned by `login()` paths (string, list) – path from home directory permission – `r`, `w`, or `x` or a combination thereof recursive (boolean) – whether Apache’s access is granted recursively

system(session_id, cmd)¶

Execute a command as the user, as if through SSH. If an application was installed previously in the session, the command will be run from the directory where that application was installed.

Note

If cmd prints anything to standard error, the API method will return an XML-RPC fault. Many XML-RPC libraries will express the fault as an exception.

Parameters:	session_id – session ID returned by `login()` cmd – a shell command to be executed

API Reference¶

General¶

Email¶

Websites and Domains¶

Applications¶

Cron¶

DNS¶

Databases¶

Files¶

Shell Users¶

Servers¶

Miscellaneous¶

Table Of Contents

Previous topic

Search the documentation

PDF download

Feedback

Navigation

API Reference¶

General¶

Email¶

Websites and Domains¶

Applications¶

Cron¶

DNS¶

Databases¶

Files¶

Shell Users¶

Servers¶

Miscellaneous¶

Table Of Contents

Previous topic

Search the documentation

PDF download

Feedback

Navigation