Scripted addition of domains, subdomains and databases

[TStackhouse]

Hi all,

I'm working on a deploy script to use as a template for new projects for my company and I'm currently looking at ways to speed the initial spinup, specifically the following:

* Adding a new domain account, if the project calls for it, or adding a subdomain to an existing account
* Adding subdomains for different stages, e.g. staging.example.com or production.someapp.example.com
* Adding a database and a user for each stage in the proper cPanel friendly format

If I wasn't running cPanel I'd be a little more cavalier and have at it, but I want to do due diligence with this so I don't get anything screwed up on the server we're operating on or in cPanel.

EDIT: I've looked at some of the stuff in /scripts/ and it might be a good starting point, but at minimum I'd need to edit them, for example, the mysqladduserdb script assumes that there is no password for the root mysql user. I'm not above making my own utility scripts and sticking them in /opt/scripts/

[Infopro]

You might find the links under the Plugin/API Developer block on this page helpful:
Where should I go for support? - cPanel Inc.

[cPanelDavidN]

Hi TStackHouse,

Don't know how your deployed script would work, but you should definitely look at the API and Hook functionality.

You'll want to take a look at the XML-API for sure:
XML and JSON APIs
It was designed for system integration (say to a billing system or UI run on a different machine). Within the XML-API, you can make API1 and API2 calls:
WebHome < ApiDocs < TWiki
API1&2 were specifically designed so that one could tie into the cPanel process itself (say for make your own UI on the cPanel box itself).

So, with the XML-API, you can do ALOT! There are things that you must do within the WHM interface or at the CLI, but I think XML-API is a good start.

While you're spec.ing out the scope of you project, you should also take a look at the various hook functionality:
Hooking into cPanel Functionality

1) Script hooks are triggered when a /script/* is run (say drop a courtesy email into a freshly created pop address).

2)Function hooks are triggered when an API module/function is called, separate process. language agnostic.

3)EventHandlers are triggered when an API call is made, but can stipulate the API call success/failure (as if you wanted account terminate to only succeed if it was during the weekday hours of 7-10am, so that Customer Service would have all day to handle them).


-Dave

[TStackhouse]

Thanks for the tips, that may be what I need to do. I've been doing some more research, and since I'm not using the DNS functions on the server itself but relying on my colo's (more robust) DNS services adding (sub)domains via the API would be quicker for sure, but I would still have to spin up the DNS by hand, unless I could find a separate API for their panel. However I think I will continue to investigate database options.

Looking over the API docs, I don't see anything that would indicate how to interact with the database as far as adding users and databases is concerned... Any tips? Should I just make a copy of the mysqladduserdb script and modify it to suit so I can call it from my Capistrano recipe?

[cPanelDavidN]

You should make an API1 call:

https://example.com:2083/xml-api/cpanel?user=username&cpanel_xmlapi_module=Mysql&cpanel_xmlapi_func=adduserdb&cpanel_xmlapi _apiversion=1&arg-0=dbname&arg-1=dbuser&arg-2=create,delete,lock

The above is an example of making an API1 call via the XML-API binary, specifically the adduserdb function which creates user grants for a mysql database; in this case the user 'dbuser' will get CREATE, DELETE, and LOCK TABLES for database 'dbname.'

The Mysql::* API1 functions are documented here:
ApiMysql < ApiDocs < TWiki

I you need to make the call to localhost, there's more efficient ways than making a an HTTP request; their outlined at docs.cpanel.net too. The forum should have more about that...and I help you too

Regards,
-Dave

PS. I highly recommend utilizing any functionality that is provided in regards to integration. cPanel does not always follow convention with regard to *nix sub-systems or the tools used to manage them. Add like any other software, can change it's methodologies at will. Therefore, if you start writing code that directly handles sub-systems, like the MySQL server, you may find your self in a rabbit hole; deep in a rabbit hole. However, having said that, I encourage you make cPanel work for you!
PSS. Like I stated before, cPanel handles somethings 'their own way' as you've touched on with the mysql root user. If you work with the various APIs you won't have to worry too much about that sort of thing provided you have valid credentials to the cPanel/WHM interface...or better the root hash access (which was designed for system-to-system integrations...it's found in WHM's "Main >> Cluster/Remote Access >> Setup Remote Access Key")

[TStackhouse]

Dave,

Thanks for the tip, that's what I ended up doing. I wrote this script (#882585 - Pastie) and dropped it in /opt/scripts It first validates the cPanel user account, than calls the proper API's to make a DB, make a DB user, and grant access.

Since I'm running that script locally on the server, if there's a better approach than what I have (which seems to be the case) let me know or point me in the right direction. I'm working now to make it work in the cPanel way, since MySQL has a hard limit of 16 chars for user names and cPanel has an artificial limit of 16 chars for DB names. (I have legacy databases that are much longer in name and cPanel picks them up just fine...)

Hopefully with some more tweaking my Capistrano file will be able to spin up stages properly, though its still going to take some legwork on the DNS side of things...

[cPanelDavidN]

Yeah, your script should certainly do the job. I've placed a query in-house about another method of making the API call locally; we'll see what comes of that. However, the method you've take will be the easiest to maintain (and for others to understand).

I think I mentioned it before, but you can take your script and relocate it to the /scripts directory, naming it postwwwacct or postwwwacctuser and it will execute automatically when a new cPanel account is created.
cPanel/WHM Script Hooks
(postwwwacctuser just gets passed the user, postwwwacct gets a slew of other data)

Don't know if you desire that script to run every time, but wanted to make sure you knew

If you write a CustomEvent Handler, CustomEventHandler < DevHooks < TWiki, you can do the same automation, but instead of just tacking on the db stuff afterwards, you could force account creation to fail if the db stuff failed. In this manner, you should never have an account without the db criteria that you need.

-Dave

PS. cPanel limits database names to 16 because we have legacy support for MySQL 4. However, as you've pointed out, it's entirely possible for cPanel to use databases with name lengths greater than that.

[TStackhouse]

Thanks for looking into that Dave. I'll likely stick with what I have. You did mention that, but I'm not going to put that in /scripts because that's exactly the opposite of what I want. I only want to spin up DB's in that fashion for a certain class of projects.

-Tim

PS That makes sense, I've only ever worked with MySQL 5, so I didn't know that limit was there. Still, I'm taking the shortened name for the db user and using that as the db name, so I can make cPanel's API happy.