WHM Plugin functionality

[teknosoul]

Hi everyone,

It appears that a WHM plugin, since it runs as root, can add / remove .conf files for individual domains via the directories listed here. I'm assuming that the system administrator as well as resellers can access these (provided ACLs are set) through the plugin.

Are these plugins only meant to be the backend logic (say getting the list of domains for the person executing it and returning it?) or is it also meant for the presentation?

Basically, what I want to do is for the reseller / admin using the plugin, provide a list of domains being managed and have a checkbox next to it. A submit button would call some code and run necessary updates on the backend through my plugin logic. Is this feasible? Are there any good example plugins out there that I can just hack at?

Thanks

[cpanel_lee]

Hi there,

WHM plugins run using the system perl/php installation, and pretty much like any other script running on the server as that user. The only real cpanel hook is the ACL check, and then only if you're using perl.

So it can do pretty much anything you want, which of course also means you'll need to take that into consideration when coding it.

Does that help at all? Basically it's just a CGI script with full root access when run as root, and full user-level access if run by a reseller.

[cPanelDavidN]

Hi teknosoul,

Like Lee stated, these are basically cgi scripts that run as root. You can make them point to more complicated scripts or just do something simple, something self contained.

You will need to implement ACL to enforce the level of control the user is granted inside you plugin script.

There's a great pair of example here:
CreatingWhmPlugins < AllDocumentation/AutomationIntegration < TWiki
that show the basics of ACL in WHM Plugins in Perl and PHP.

For clarity, ACL is the same for Perl and PHP: YOU must implement methods that determine who is allowed and in what places within you plugin. For Perl developers, we have a convenient module, WHostmgr, that can be used. If you're using PHP, you can use the function we provide on the documentation page. It does essentially the same thing as the Perl subroutine of the same name.

Cheers,
-David


Note: I was reviewing the WHM Plugin documentation and noticed there was a typo in the PHP code block at the bottom of the page, the "checkacl" example. "$ac" should be "$acl" in the last 'if' statement. Documentation has been informed; wanted to give you the heads up in case you used it

[teknosoul]

That's great information. I assume I can use the CGI module when running as perl?

Since I'm writing a form in my script (by printing out the HTML of the form and such) what is the URL of the action parameter to specify if I want my script to handle it? I assume it would be ./addon_myplugin.cgi ? If using CGI, I can just use the defaults for the start_form call which is fine as well.

Thanks

[cpanel_lee]

Yes, you can use the CGI module.

The base URL will resemble:

https://<yourserver>:2087/cgi/addon_yourplugin.cgi

so just add the 'cgi' directory in the url :-)

[teknosoul]

This seems to imply that I can execute these commands remotely as well, but through the cPanel interface.

If I wanted to automate some of the actions of a plugin, is this best done by developing a module and using the xml/json API to call it remotely as described here? What user do the modules run as when making calls to WHM? Is it still root? I will need to be able to create/delete my specific conf files in

/usr/local/apache/conf/userdata/(ssl|std)/(1|2)/<user>/<domain>/

What is the <user> variable in this case?

[cpanel_lee]

Basically the entire cpanel API is designed to run remotely. If you think about it this makes sense, since WHM and cpanel use a web browser interface.

Within your WHM addon CGI, the easiest way to make these calls is using /usr/local/cpanel/Cpanel/Accounting.pm. You'll see a php version there as well. Basically it makes it easy to build a URL to make API calls, which will return XML, which you can then turn into a native Perl/PHP object.

If you mess around with it it will start to make sense pretty quick, it's really pretty straightforward.

When you call the API, you'll always be logging in as somebody. So if you use root's credentials to make an API call, you'll be root in WHM. More often than not you'll find yourself making API1 and API2 calls specifying a user:

CallingAPIFunctions < AllDocumentation/AutomationIntegration < TWiki

[teknosoul]

Thanks for the info. I'm still struggling getting it installed, so that's why I haven't been able to take a more hands on approach. I'm working with techs on the install issues.

In terms of setting configuration up for a specific virtual host, does it matter what the <user> part of the tree is set to? Is it done like that so each cPanel user can keep track of his/her modifications to a virtual host or is the <user> supposed to be the user the domain is associated with?

[cpanel_lee]

Hmm, I'm not exactly sure what you're trying to do, so it's hard to say. Generally speaking, you really want to avoid editing httpd.conf if at all possible. It is better to use either our API's to do the equivalent action, or our httpd.conf configuration tools:

cPanel - The Easy Apache Configuration System - Adding Custom Directives to httpd.conf

For example, this tells you where to put include files which will be automatically picked up by cpanel and included, if they exist :-)

The more detail you can give about what you're trying to do, the more we can help.

[teknosoul]

Hey lee,

That's exactly what I'll be doing is putting the directives in the appropriate directory. My plugin will simply include some Apache directives on a per virtual host basis.

My question was related to that link and the path listed:

/usr/local/apache/conf/userdata/(ssl|std)/(1|2)/<user>/<domain>/

What is the <user> variable in this case?

[cpanel_lee]

Oh I see. That is the user's name that owns the domain of the virtualhost.

ie. if you do:

/scripts/whoowns <domain.com>

the username that it returns.

[teknosoul]

I've got it installed and have been playing with it a bit.

I'm trying to figure out why I can do something like:

https://myserver.com:2087/xml-api/listaccts

but not

https://myserver.com:2087/xml-api/getranddata

getranddata is in Rand.pm under /usr/local/cpanel/Cpanel. It has an api2 method, so it seems that it exposes an API2 call. Is there no way to call this directly through https? It seems there may be something special about the XMLAPI.pm module under the Accounting folder.

I would like to expose something easy for a script to just point at for automation purposes, so I'm just wondering what the proper syntax is if I wanted to call this from a Perl script, and not within a <?cp tag.

Edit: Just discovered
Fast Mode

However, calling

xml-api/cpanel?user=root&cpanel_xmlapi_module=Rand&cpanel_xmlapi_func=getranddata

against WHM fails with an XML parse error (11.25). I am already authenticated as root. Looking at the page source, seems like an internal server error occurred. There is a <hr> tag without a corresponding </hr> that is causing the problem.

This worked: https://localhost:2222/xml-api/cpane...nc=getranddata

I'll go from there.