The Community Forums

Interact with an entire community of cPanel & WHM users!
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

Privileges necessary for remote cPanel / WHM usage

Discussion in 'cPanel Developers' started by Jason B, Feb 15, 2012.

  1. Jason B

    Jason B Member

    Joined:
    Feb 15, 2012
    Messages:
    10
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    DataCenter Provider
    Good evening,

    I'm a veteran Linux developer, but only marginally familiar with Web technologies. I've been reading through the cPanel and WHM API discussion in the documentation (and on some forum threads), and I have a question on access privileges.

    All of the examples using the WHM API to create cPanel accounts on a remote server (the XML and JSON 'createacct' API function) authenticate to WHM on the target server using root access. Is it necessary to authenticate as root to execute all of the remote API commands?

    I assume it is not necessary to run the script (the PHP script, say) as root on the local server in any case. Is that true? Basically I would like to be able to use a PHP script back-ending a Web GUI to manage a remotely hosted website via WHM, with that script having minimal access.

    Thanks for considering my questions, and please let me know if there's anything I'm not thinking of and should be!

    Jason
     
  2. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    Hi Jason,

    You are correct: the local sever (which makes the remote call to the cPanel server) can run your PHP (Perl, or otherwise) code as whoever is appropriate, be it 'www', 'apache', a user, or root. That's entirely up to your implementation, aka your Web GUI. cPanel provides a PHP client class, as well as a Perl one, just for this; see our GitHub page.

    When you authenticate into the cPanel server, using the cPanel Remote API (aka XML/JSON API), you authenticate in a similar fashion as you would with the normal interfaces, the only difference really is how you send the credentials (POST form vs HTTP headers).

    Server and Accounts Management
    If you were to use the UI and wanted to perform administrative actions, you must use WHM portion of the cPanelserver, as a privileged user. WHM is on ports 2087/2086. When making a Remote API call, you will use port 2087 (or 2086). The privileged user credentials that you authenticate with will determine what API functions are permitted. The root user obviously can do anything, however a reseller account may only have a limited set of privileges (or he could have the 'all' reseller privilege, which essentially grants root-like authority).


    cPanel Account Management
    If you can leverage the cPanel APIs using the Remote API interface. So, normally you'd browse the cPanel UI on ports 2083/2082 and use the end-user credentials. The Remote API call will be the same: port 2083 (or 2082) and user credentials. This means that all API1 and API2 functions, which drive the entirety of the cPanel UI, are available to you remotely!

    Masquerading as Account
    Just like it's possible for a reseller or root to log into the GUI and change their user context to that of a different cPanel account they own, the Remote API can do this too. So, when you wish to perform cPanel API actions, masquerade as the user, you'd use the administrative port 2087 (or 2086) and authenticate as your privileged administrative account; the construction of the cPanel API call within the Remote API URL parameter syntax will let you specify which cPanel account your wanting the functionality to affect.

    Knowing What Admin Functions You Can Use
    The Remote API's administrative functions (often referred to 'native' functions, as opposed to the 'proxied' cPanel API calls that are possible) each will be tied to a reseller ACL. The Remote API documentation should specify which ACL is required. Alternative, you should be able to perform the applist Remote API call which will return a list of functions the authenticated use can perform (I personally haven't use this in a long time, so let me know if you find anything funny about it)


    Best Regards,
    -DavidN
     
  3. Jason B

    Jason B Member

    Joined:
    Feb 15, 2012
    Messages:
    10
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    DataCenter Provider
    David, your response was very helpful. I really appreciate the time you took to post such a detailed answer.

    One more question, if I may - once we have created the cPanel account remotely, we were told that there exists an API to migrate a website from a folder on the local server to the remote cPanel account. I scanned the list of APIs in the documentation and didn't find an obvious match, can you point me in the right direction?

    Thanks again and have a nice evening.

    Jason
     
  4. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    Hi Jason,

    If I understand you correctly (or more precisely, what you've been told), we do not have such a robust API call. There are two broad areas of the product that are, however, applicable to the conversation:

    Account Migration:
    cPanel supports migrating accounts from one cPanel machine to another cPanel machine. This migration would package up the account (which would include it's domain configurations, home directory, and databases) into a custom tarball structure that can be extracted into the destination cPanel machine, completely restoring the account. We also support a nearly identical migration for accounts that are on non-cPanel control panels that which to move to the cPanel control panel.

    Both of those types of migration can be performed in the WHM UI. They can also be perform for CLI, but the WHM UI is typically easier to use due to the heavy amount of contextual information needed by the monolithic code that does all the work. IIRC, the UI can allow you to migrate in batches if you have more than one account. You can contact our Migration team for more information and assistance (support.cpanel.net, you can open a complementary ticket as well as other options)

    cPanel APIs:
    The cPanel APIs provide all that you would need to programmatically create or restore a previous website. The primary concern is what exactly the website needs. Most often, you'll need to establish the domain, the files that are to be served (the folder you speak of), and possibly databases or other website resources.

    The domain:
    If the domain is the same as the primary domain for the cPanel account, there's nothing to do here. If the domain that you wish to server is not the primary domain, you'll need create the additional domain. Options include creating subdomains, parked domains, or addon domains; which one is entirely up to you and how you which to have the domains structured/managed.

    The files:
    Once you have determined how the domain is setup, you'll know which folder to place your website files into. The simplest scenario would be if you we using the primary domain, you just drop your website files into ~/public_html/. However, many websites nowadays implement a filesystem layout that makes a clear distinction between public and private/backend/config files and will only place the public files (index, css, images, etc) in public_html. So, it really depends on how your website file layout was designed to work. This can be compounded with the use of sub/park/addon domains, which typically will have their own folder somewhere descendent of ~/public_html/.

    Moving the folder from the original server to the destination server theoretically should be possible using the cPanel APIs, however I'd recommend using a file transfer protocol such as FTP, SFTP, SCP, etc. This will be much more efficient than copying files via HTTP that must go through the cPanel API layer. It will be a lot easier to code and verify. Plus, the file transfer API were originally designed for use by web code running in the cPanel UI, and not so much via a proxied call using the Remote API.

    PHP has many built-ins for such protocols. As well, there are many pure PHP class implementations of those sorts of protocols.

    The databases:
    If you have databases, you'll need to (re)create them with the cPanel API. Creating MySQL/Postgres databases (for use by a cPanel account) but not using the cPanel APIs will be problematic due to the abstraction layer required for accounting purposes of shared webhosting (read database limits, size quotas, ownership schema/tracking/enforcement). Once the databases have been created, you have a few options:
    1) you can use the API to grant remote access to them; from there you can stream a dump of the old database to the new
    2) you can simply dump the old file, copy it to the account and then import the data. Basically, programmatic use the `mysql` client. (recommended)
    3) you can use something like phpMyAdmin that will help you export/import data
    Whichever method you choose, it will be up to you to implement that MySQL routine for exporting/import the data. cPanel does not offer APIs that manage database contents, only the bare database and it's permissions and users.

    ---.---
    You will likely find posts in the forum on these API topics. As well, googling can help find other posts about this stuff, be it nestled away in the depths of docs.cpanel.net or on other forum websites. If you need specific info, just ask and we'll do our best to oblige.

    Regards,
    -DavidN
     
  5. Jason B

    Jason B Member

    Joined:
    Feb 15, 2012
    Messages:
    10
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    DataCenter Provider
    Once again, David, thank you for your detailed reply.

    I don't think the UI is going to work for us in this case as we would like everything to be automatic. I think we will take your recommendation of using a file transfer protocol such as SFTP or SCP, via PHP.

    The WHM API gives us 'createacct', which we can use to create the cPanel account remotely. We can add subdomains to that account, for example, with the cPanel API2 call 'SubDomain::addsubdomain'. (I believe we will need to do this.) Then we SFTP the file from our local Drupal folder to somewhere under $HOME/public_html (still need to figure out where).

    I'm not sure if the remote websites will have their own databases. If they do you have given us a few options, thanks.

    All of the above will happen in our PHP script back-ending the admin Web GUI. If I left anything out, please let me know.

    One specific question I do have relates to backward-compatibility. Will upgrades to the WHM or cPanel version on the remote server ever break these API calls? Are we guaranteed that the interfaces will not change, or at least that the old versions will be maintained.

    Thanks a lot, David, and have a great weekend.

    Jason
     
  6. Jason B

    Jason B Member

    Joined:
    Feb 15, 2012
    Messages:
    10
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    DataCenter Provider
    Oh, yeah, one more thing, David, if you don't mind. When I call 'createacct' to set up a cPanel account, does the new account get a separate Linux account with its own home directory? That's how I read your reply, meaning that ~ would be something like /usr/cpanelacct1. Does that make sense?

    Thanks again,
    Jason
     
  7. KostonConsulting

    KostonConsulting Well-Known Member

    Joined:
    Jun 17, 2010
    Messages:
    255
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    San Francisco, CA
    cPanel Access Level:
    Root Administrator
    Jason,
    Each new cPanel account will be created with a linux user using a home directory based on your setting for 'home directory prefix' in WHM. If the prefix is set to usr, then accounts will be as suggested like /usr/cpanelacct1. The home directory is not customizable on a per account basis (unfortunately).
     
  8. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    The API are reliable. Once API call is created, it rarely changes. If anything, addition values or agrument options might be added. Because the cPanel and WHM UIs utilized these same APIs that are provide to developers, like yourself, you can have some comfort in the fact that cPanel developers don't won't the same headache that you're describing...having to modify existing scripts and UIs: maintain something that worked yesterday due to a whimsical, (non-)design decision by a backend developer. cPanel goes to great lengths to maintain a stable and consistent API. When changes do occur, we publicize the change to many venues, including the integration blog, the forums, as well as the general product changelog. I recommend that you follow the blog and changelog.

    -DavidN
     
  9. Jason B

    Jason B Member

    Joined:
    Feb 15, 2012
    Messages:
    10
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    DataCenter Provider
    Thanks, guys.

    Dave, I assume 'cpanelacct1' would be the username I specified in the 'createacct' API call.

    David, your message made me smile, I develop APIs myself as part of my job and I know the headaches of which you speak, and understand how an API developer would bend over backwards to keep things consistent!

    Have a nice night,
    Jason
     
  10. KostonConsulting

    KostonConsulting Well-Known Member

    Joined:
    Jun 17, 2010
    Messages:
    255
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    San Francisco, CA
    cPanel Access Level:
    Root Administrator
    That's correct. It's definitely best to set the home directory prefix to '/usr' for all accounts rather than having certain accounts modified. Things could get out of sync with home directories on a partition other than matched by the home directory prefix and this could cause issues when cPanel rebuilds configurations.
     
Loading...

Share This Page