Friday 30 November 2012

Use Cpanel and WHM API's In Rails


  WHM 
       WebHost Manager (WHM) is a web-based tool used by server administrators and resellers to manage hosting accounts on a web server.
       WHM listens on ports 2086 and 2087 by default.

   cPanel
      cPanel is a Unix based web hosting control panel that provides a graphical interface and automation tools designed to simplify the process of hosting a web site. cPanel utilizes a 3 tier structure that provides functionality for administrators, resellers, and end-user website owners to control the various aspects of website and server administration through a standard web browser.
     cPanel is commonly accessed on port 2082, with an SSL-secured server operating on port 2083.

  Use cpanel and Whm API's in Rails
        Panelbeater gem  is used for communicating with the cPanel and WHM API's.
        Ruby library for the WHM & cPanel API.
   
  Installation
       Github path https://github.com/BeenaShetty/panelbeater
       Specify gem 'panelbeater' in gemfile

 Usage
   Create a server object and connect to WHM using host and secure hash:

      server = Panelbeater::Whm::Commands.new(
                           :url => url,
                           :api_key => secure_hash,
                           :port => port,
                           :user => username
                        )

   Now,you can access the modules of WHM by calling server.module


Example
    Creating a new account
        Requires only a username and domain

        result = server.createacct(
                  :username => 'newuser',
                  :domain   => 'newuser.com'
                )

Output

  createaact  =>  {result  => { :status  =>  boolean,  :statusmsg  =>  "" }}

  status (boolean) — Status of the operation.
      1 — success.
      0 — failure.

  statusmsg (string) — Status or error message.

  Reference CreateAccount

    Delete account
        Requires only username

      result = server.removeacct(:user => 'newuser')

Output

  removeacct  => {result  => { :status  =>  boolean,  :statusmsg  =>  "" }}

  status (boolean) — Status of the operation.
      1 — success.
      0 — failure.

statusmsg (string) — Message about the status of the operation.

ReferenceRemoveAccount


  Using Cpanel methods
    Connect to cpanel using server.cpanel
     domain = Domain.find(5)
     server.cpanel(domain.username, {
                   :cpanel_jsonapi_module => api_module,
                   :cpanel_jsonapi_func => api_function,
                   :cpanel_jsonapi_apiversion => api_version
       })


Note: If you use a cPanel port (2082 or 2083) to access the XML or JSON API, you can only use it to run API1 and API2 functions. Native XML and JSON API calls will not work. The ports are assigned as follows:

    2082 — cPanel (unsecured).
    2083 — cPanel (secured).
    2086 — WHM (unsecured).
    2087 — WHM (secured).



Fast Mode

  Fast Mode is a newer way to use the cpanel function call in the XML or JSON API. This method is preferred, since it simplifies building the request, no longer requiring you to enter XML tags as input. The server-side processing of Fast Mode requests is also much quicker than the processing of XML requests.

XML Input

  The cpanel XML function call in Fast Mode takes the following variables as input.

  The following variables are required:

      cpanel_xmlapi_user (string) — The user as whom you wish to call the function.
      cpanel_xmlapi_module (string) — Name of the module to access.
      Important: API1 and API2 variables are case-sensitive. For example, specifying Email is different from specifying email.
      cpanel_xmlapi_func (string) — Name of the function to access.

  The following variables are optional, depending on the call:

      cpanel_xmlapi_apiversion (integer) — Version of the API to access.
          1 — API1.
          2 — API2.
          No input — Defaults to API2.
      arg (string) — List of arguments. These variables are numbered such that the first is arg-0, the second is arg-1, and so on.
        Example: arg-0=username&arg-1=somepass

JSON Input
    The cpanel JSON function call in Fast Mode takes the following variables as input.

  The following variables are required:

      cpanel_jsonapi_user (string) — The user as whom you wish to call the function.
      cpanel_jsonapi_module (string) — Name of the module to access.
    Important: API1 and API2 variables are case-sensitive. For example, specifying Email is different from specifying email.
      cpanel_jsonapi_func (string) — Name of the function to access.

  The following variables are optional, depending on the call:

      cpanel_jsonapi_apiversion (integer) — Version of the API to access.
          1 — API1.
          2 — API2.
          No input — Defaults to API2.
    API1: arg (string) — List of arguments. These variables are numbered such that the first is arg-0, the second is arg-1, and so on.
          Example: arg-0=username&arg-1=somepass
      API2: arg (string) — List of arguments. These variables are given by name.
          Example: email=bob&domain=fred.com

Output

    cpanelresult — Container for the result of the cPanel operation.
        apiversion (string) — Version of API accessed (1 or 2).
        module (string) — Name of the module accessed.
        func (string) — Name of the function accessed.
        type (string) — Type of function.
        source (string) — Source of the call (internal or external).
        data — Data provided by the function.
         result (string) — Result of the function

Reference: Cpanel

Example
1. Email::listpopswithdisk
      List email accounts associated with a particular domain.

     server.cpanel(domain.username, {
                   :cpanel_jsonapi_module => "Email",
                   :cpanel_jsonapi_func => "listpopswithdisk",
                   :cpanel_jsonapi_apiversion => 2
       })


2. Email::addpop
     Add(create) an e-mail account.
 
     server.cpanel(domain.username, {
                   :cpanel_jsonapi_module => "Email",
                   :cpanel_jsonapi_func => "addpop",
                   :cpanel_jsonapi_apiversion => ,
                   :domain => "user.com",
                   :email => "test",
                   :password => "12345",
                   :quota => 10
       })


Output

   <data>
     <reason> A string value that contains the email address if the function completes successfully. This value will contain a reason for failure if the function encounters an error.
    </reason>
    <result> A boolean value that indicates success or failure. '1' indicates that the function completed successfully.
    </result>
   </data>


Reference: API1 Version , API2 Version