Class: Whm::Server

Inherits:
Object
  • Object
show all
Includes:
Parameters
Defined in:
lib/whm/server.rb

Overview

The Server class initializes a new connection with the cPanel WHM server, and contains all functions that can be run on a cPanel WHM server as of version 11.24.2.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Parameters

#booleans!, #requires!, #valid_options!

Constructor Details

#initialize(options = {}) ⇒ Server

Initialize the connection with WHM using the hostname, user and password/remote key. Will default to asking for a password, but remote_key is required if a password is not used.

Example

Password authentication with debugging enabled:

Whm::Server.new(
  :host => "dedicated.server.com",
  :username => "root",
  :password => "s3cUr3!p@5sw0rD",
  :debug => true
)

Remote key authentication with port 8000, and SSL to off (defaults to port 2087, and SSL on):

Whm::Server.new(
  :host => "dedicated.server.com",
  :username => "root",
  :remote_key => "cf975b8930b0d0da69764c5d8dc8cf82 ...",
  :port => 8000,
  :ssl => false
)



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/whm/server.rb', line 55

def initialize(options = {})
  requires!(options, :host, :username)
  requires!(options, :password) unless options[:remote_key]
  
  @host       = options[:host]
  @username   = options[:username] || "root"
  @remote_key = options[:remote_key].gsub(/(\r|\n)/, "") unless options[:password]
  @password   = options[:password] unless options[:remote_key]
  @debug      = options[:debug] || false
  @port       = options[:port] || 2087
  @ssl        = options[:ssl] || true
end

Instance Attribute Details

#attributes ⇒ Object

Returns the value of attribute attributes.



28
29
30
 
# File 'lib/whm/server.rb', line 28

def attributes
  @attributes
end

#debug ⇒ Object

If you’d like increased verbosity of commands, set this to true. Defaults to false



20
21
22
 
# File 'lib/whm/server.rb', line 20

def debug
  @debug
end

#host ⇒ Object (readonly)

Hostname of the WHM server (e.g., dedicated.server.com)



8
9
10
 
# File 'lib/whm/server.rb', line 8

def host
  @host
end

#password ⇒ Object (readonly)

WHM XML-API password. Use this, or the remote key, to authenticate with the server



14
15
16
 
# File 'lib/whm/server.rb', line 14

def password
  @password
end

#port ⇒ Object

By default, we connect on port 2087. Set this to another integer to change it.



26
27
28
 
# File 'lib/whm/server.rb', line 26

def port
  @port
end

#remote_key ⇒ Object (readonly)

WHM XML-API remote key. Use this, or the password, to authenticate with the server



17
18
19
 
# File 'lib/whm/server.rb', line 17

def remote_key
  @remote_key
end

#ssl ⇒ Object

By default, SSL is enable. Set to false to disable it.



23
24
25
 
# File 'lib/whm/server.rb', line 23

def ssl
  @ssl
end

#username ⇒ Object (readonly)

WHM XML-API username



11
12
13
 
# File 'lib/whm/server.rb', line 11

def username
  @username
end

Instance Method Details

#account(name) ⇒ Object

Find an account

Options

  • :user - Username associated with the acount to display (string)



80
81
82
83
 
# File 'lib/whm/server.rb', line 80

def (name)
  summary = self.(:user => name)
  (summary)
end

#account_summary(options = {}) ⇒ Object

Displays pertient account information for a specific account.

Options

  • :user - Username associated with the acount to display (string)



97
98
99
100
101
102
 
# File 'lib/whm/server.rb', line 97

def (options = {})
  requires!(options, :user)
  
  data = get_xml(:url => "accountsummary", :params => options)
  check_for_cpanel_errors_on(data)["acct"]
end

#account_total_bandwidth(options = {}) ⇒ Object

Displays the total bandwidth used (in bytes) used by an account

Options

  • :user - username associtated with the account to display (string)



107
108
109
110
111
112
113
 
# File 'lib/whm/server.rb', line 107

def (options = {})
  requires!(options, :user)
  
  params = { :searchtype => 'user', :search => options[:user] }
  data = get_xml(:url => "showbw", :params => params)
  check_for_cpanel_errors_on(data)["bandwidth"]["totalused"]
end

#accounts(options = {}) ⇒ Object

Finds all accounts



70
71
72
73
74
 
# File 'lib/whm/server.rb', line 70

def accounts(options = {})
  summary = self.list_accounts(options)
  summary = [summary] unless summary.is_a? Array
  summary.collect { |attributes| Account.new(attributes) }
end

#change_account_password(options = {}) ⇒ Object

Changes the password of a domain owner (cPanel) or reseller (WHM) account.

Options

  • :user - Username of the user whose password should be changed (string)

  • :pass - New password for that user (string)



120
121
122
123
124
125
 
# File 'lib/whm/server.rb', line 120

def (options = {})
  requires!(options, :user, :pass)
  
  data = get_xml(:url => "passwd", :params => options)
 check_for_cpanel_errors_on(data)["passwd"]
end

#change_package(options = {}) ⇒ Object

Changes the hosting package associated with an account. Returns true if it is successful, or false if it is not.

Options

  • :user - Username of the account to change the package for (string)

  • :pkg - Name of the package that the account should use (string)



134
135
136
137
138
139
140
141
 
# File 'lib/whm/server.rb', line 134

def change_package(options = {})
  requires!(options, :user, :pkg)
  
  data = get_xml(:url => "changepackage", :params => options)
  check_for_cpanel_errors_on(data)
  
  data["status"] == "1" ? true : false
end

#create_account(options = {}) ⇒ Object

Creates a hosting account and sets up it’s associated domain information.

Options

  • :username - Username of the account (string)

  • :domain - Domain name (string)

  • :pkgname - Name of a new package to be created based on the settings used (string)

  • :savepkg - Save the settings used as a new package (boolean)

  • :featurelist - Name of the feature list to be used when creating a new package (string)

  • :quota - Disk space quota in MB. Must be between 0-999999, with 0 being unlimited (integer)

  • :password - User’s password to access cPanel (string)

  • :ip - Whether or not the domain has a dedicated IP address, either "y" (Yes) or "n" (No) (string)

  • :cgi - Whether or not the domain has CGI access (boolean)

  • :frontpage - Whether or not the domain has FrontPage extensions installed (boolean)

  • :hasshell - Whether or not the domain has shell/SSH access (boolean)

  • :contactemail - Contact email address for the account (string)

  • :cpmod - cPanel theme name (string)

  • :maxftp - Maximum number of FTP accounts the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :maxsql - Maximum number of SQL databases the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :maxpop - Maximum number of email accounts the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :maxlst - Maximum number of mailing lists the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :maxsub - Maximum number of subdomains the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :maxpark - Maximum number of parked domains the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :maxaddon - Maximum number of addon domains the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :bwlimit - Bandwidth limit in MB. Must be between 0-999999, with 0 being unlimited (integer)

  • :customip - Specific IP for the site (string)

  • :language - Language to use in the account’s cPanel interface (string)

  • :useregns - Use the registered nameservers for the domain instead of the ones configured on the server (boolean)

  • :hasuseregns - Must be set to 1 if the above :useregns is set to 1 (boolean)

  • :reseller - Give reseller privileges to the account (boolean)



172
173
174
175
176
177
 
# File 'lib/whm/server.rb', line 172

def (options = {})
  requires!(options, :username)
  
 data = get_xml(:url => "createacct", :params => options)
 check_for_cpanel_errors_on(data)
end

#generate_ssl_certificate(options = {}) ⇒ Object

Generates an SSL certificate

Options

  • :xemail - Email address of the domain owner (string)

  • :host - Domain the SSL certificate is for, or the SSL host (string)

  • :country - Country the organization is located in (string)

  • :state - State the organization is located in (string)

  • :city - City the organization is located in (string)

  • :co - Name of the organization/company (string)

  • :cod - Name of the department (string)

  • :email - Email to send the certificate to (string)

  • :pass - Certificate password (string)



191
192
193
194
195
 
# File 'lib/whm/server.rb', line 191

def generate_ssl_certificate(options = {})
  requires!(options, :city, :co, :cod, :country, :email, :host, :pass, :state, :xemail)
  data = get_xml(:url => "generatessl", :params => options)
  check_for_cpanel_errors_on(data)
end

#hostname ⇒ Object

Displays the server’s hostname.



198
199
200
201
 
# File 'lib/whm/server.rb', line 198

def hostname      
  data = get_xml(:url => "gethostname")
  check_for_cpanel_errors_on(data)["hostname"]
end

#limit_bandwidth_usage(options = {}) ⇒ Object

Modifies the bandwidth usage (transfer) limit for a specific account.

Options

  • :user - Name of user to modify the bandwidth usage (transfer) limit for (string)

  • :bwlimit - Bandwidth usage (transfer) limit in MB (string)



208
209
210
211
212
213
 
# File 'lib/whm/server.rb', line 208

def limit_bandwidth_usage(options = {})
  requires!(options, :user, :bwlimit)
  
  data = get_xml(:url => "limitbw", :params => options)
  check_for_cpanel_errors_on(data)["bwlimit"]
end

#list_accounts(options = {}) ⇒ Object

Lists all accounts on the server, or allows you to search for a specific account or set of accounts.

Options

  • :searchtype - Type of account search ("domain", "owner", "user", "ip" or "package")

  • :search - Search criteria, in Perl regular expression format (string)



221
222
223
224
 
# File 'lib/whm/server.rb', line 221

def list_accounts(options = {})
  data = get_xml(:url => "listaccts", :params => options)
  check_for_cpanel_errors_on(data)["acct"]
end

#list_packages ⇒ Object

Lists all hosting packages that are available for use by the current WHM user. If the current user is a reseller, they may not see some packages that exist if those packages are not available to be used for account creation at this time.



230
231
232
233
 
# File 'lib/whm/server.rb', line 230

def list_packages
  data = get_xml(:url => "listpkgs")
  check_for_cpanel_errors_on(data)["package"]
end

#modify_account(options = {}) ⇒ Object

Modifies account specific settings. We recommend changing the account’s package instead with change_package. If the account is associated with a package, the account’s settings will be changed whenever the package is changed. That may overwrite any changes you make with this function.

Options

  • :CPTHEME - cPanel theme name (string)

  • :domain - Domain name (string)

  • :HASCGI - Whether or not the domain has CGI access (boolean)

  • :LANG - Language to use in the account’s cPanel interface (boolean)

  • :MAXFTP - Maximum number of FTP accounts the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :MAXSQL - Maximum number of SQL databases the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :MAXPOP - Maximum number of email accounts the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :MAXLST - Maximum number of mailing lists the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :MAXSUB - Maximum number of subdomains the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :MAXPARK - Maximum number of parked domains the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :MAXADDON - Maximum number of addon domains the user can create. Must be between 0-999999, with 0 being unlimited (integer)

  • :shell - Whether or not the domain has shell/SSH access (boolean)

  • :user - User name of the account (string)



255
256
257
258
259
260
261
262
263
 
# File 'lib/whm/server.rb', line 255

def (options = {})
  booleans!(options, :HASCGI, :LANG, :shell)
  requires!(options, :user, :domain, :HASCGI, :CPTHEME, :LANG, :MAXPOP, :MAXFTP, :MAXLST, :MAXSUB, 
    :MAXPARK, :MAXADDON, :MAXSQL, :shell)
    
  data = get_xml(:url => "modifyacct", :params => options)
  
  check_for_cpanel_errors_on(data)
end

#packages(options = {}) ⇒ Object

Finds all packages



87
88
89
90
91
 
# File 'lib/whm/server.rb', line 87

def packages(options = {})
  summary = self.list_packages
  summary = [summary] unless summary.is_a? Array
  summary.collect { |attributes| Package.new(attributes)}
end

#suspend_account(options = {}) ⇒ Object

Suspend an account. Returns true if it is successful, or false if it is not.

Options

  • :user - Username to suspend (string)

  • :reason - Reason for suspension (string)



271
272
273
274
275
276
277
278
 
# File 'lib/whm/server.rb', line 271

def (options = {})
  requires!(options, :user, :reason)
  
  data = get_xml(:url => "suspendacct", :params => options)
  check_for_cpanel_errors_on(data)
  
  data["status"] == "1" ? true : false
end

#terminate_account(options = {}) ⇒ Object

Terminates a hosting account. Please note that this action is irreversible!

Options

  • :user - Username to terminate (string)

  • :keepdns - Keep DNS entries for the domain (“y” or “n”)



285
286
287
288
289
290
291
292
293
294
 
# File 'lib/whm/server.rb', line 285

def (options = {})
  requires!(options, :user)
        
  data = get_xml(:url => "removeacct", :params => {
    :user => options[:user], 
    :keepdns => options[:keepdns] || "n"
  })
  
  check_for_cpanel_errors_on(data)
end

#unsuspend_account(options = {}) ⇒ Object

Unsuspend a suspended account. Returns true if it is successful, or false if it is not.

Options

  • :user - Username to unsuspend (string)



301
302
303
304
305
306
307
308
 
# File 'lib/whm/server.rb', line 301

def (options = {})
  requires!(options, :user)
  
  data = get_xml(:url => "unsuspendacct", :params => options)
  check_for_cpanel_errors_on(data)
  
  data["status"] == "1" ? true : false
end

#version ⇒ Object

Returns the cPanel WHM version.



311
312
313
314
 
# File 'lib/whm/server.rb', line 311

def version    
  data = get_xml(:url => 'version')
  check_for_cpanel_errors_on(data)["version"]
end