Plugin structure
A single plugin is a set of configuration files and code stored in a single directory located at /usr/local/directadmin/plugins. For example plugin with a name hello_world would store all its files at /usr/local/directadmin/plugins/hello_world.
Each plugin is expected to have the following structure:
./plugin.conf- configuration file, it describes the plugin and plugin integration details../hooks- directory with scripts that are executed by DirectAdmin when some specific event happend (for example user is created). In addition to event hooks this directory also contains helper scripts for the plugin integration../scripts- directory with helper scripts that are executed by plugin manager at different plugin life-cycle stages../admin,./reseller,./user- directories with the plugin code for different types of user levels. Code in these directories are used for extending GUI../images- a directory for static images that can be used by plugin GUI. Contents of this directory are served as static files without being executed as scripts.
Configuration file plugin.conf
Inside the plugin directory, there must be a file plugin.conf with the basic information about the plugin. Without this file directory is not considered to be a valid DirectAdmin plugin.
Configuration contents is list of key=val entries. List of configuration options:
| Option name | Value example | Description |
|---|---|---|
name | Hello World | Human friendly plugin name visible in the plugin-manager. |
id | hello_world | Should match the name of plugin directory. |
author | JBMC-Software | Human friendly description of the plugin author. |
version | 1.0 | Opaque string used to compare different versions of the same plugin. |
update_url | http://www.directadmin.com/hello_world.tar.gz | Optional, if not empty allows plugin to be updated via plugin-manager. |
version_url | http://www.directadmin.com/hello_world_version.html | Optional, URL to check for new version availability. Response for this URL should be only version string. |
active | yes | If set to yes plugin is active and can be used by DA, when set to no plugin is not available. |
installed | yes | Managed by the plugin-manager, it is set to yes when plugin install script is executed and set to no after executing uninstall script. |
Example plugin.conf file:
name=Hello World
id=hello_world
author=JBMC-Software
version=1.0
update_url=http://www.directadmin.com/hello_world.tar.gz
active=yes
installed=yes
User level directories for plugin GUI
Files inside user level directories are executable scripts that should render plugin GUI.
Scripts inside the ./admin directory will be only available for users having admin level access on the server. Directory ./reseller script will be available for users having reseller access and ./user will be available for all the users.
Each user level directory must have a file named index.html it will be used as a starting point when user selects to access plugin via GUI.
Each file should be a script that when executed will produce HTML output that will be shown to the user accessing the plugins page. Files should be set to executable mode (755).
The scripts will be executed as the DirectAdmin/UNIX user account that triggered the request.
Main DirectAdmin service will pass data for the request via environment variables.
Example of ./user/index.html page:
#!/usr/local/bin/php
Hello World!<br>
This script is being run as <?=getenv('USERNAME')?><br>
<textarea rows=30 cols=85><?php phpinfo(INFO_ENVIRONMENT); ?></textarea>
When plugin script is executed all output on the stdout is inserted into the |OUTPUT| token on the skins page. No data from the strerr will be retrieved. The exit code of the script is not checked, so errors should be directed to the stdout.
Plugin GUI request mapping
This section describes a list of rules how HTTP requests to DirectAdmin web-server triggers execution of plugin GUI scripts:
- Requests to
/CMD_PLUGINS_ADMIN/{name}/...will execute scripts from/usr/local/directadmin/plugins/{name}/admin/...directory. - Requests to
/CMD_PLUGINS_RESELLER/{name}/...will execute scripts from/usr/local/directadmin/plugins/{name}/reseller/...directory. - Requests to
/CMD_PLUGINS/{name}/...will execute scripts from/usr/local/directadmin/plugins/{name}/user/...directory. - Plugin paths starting with
/images/...will return content from/usr/local/directadmin/plugins/{name}/images/...directory. It will not execute file as script but just return file contents. - Requests to root directory of plugin will execute script
index.html.
Examples of requests that execute plugin script and return its contents wrapped in a skin plage dedicated for showing plugin contents:
| Request | Executed script |
|---|---|
/CMD_PLUGINS_ADMIN/{name} | /usr/local/directadmin/plugins/{name}/admin/index.html |
/CMD_PLUGINS_ADMIN/{name}/ | /usr/local/directadmin/plugins/{name}/admin/index.html |
/CMD_PLUGINS_ADMIN/{name}/index.html | /usr/local/directadmin/plugins/{name}/admin/index.html |
/CMD_PLUGINS_ADMIN/{name}/test | /usr/local/directadmin/plugins/{name}/admin/test |
/CMD_PLUGINS_ADMIN/{name}/dir/file | /usr/local/directadmin/plugins/{name}/admin/dir/file |
| ... | ... |
/CMD_PLUGINS_RESELLER/{name} | /usr/local/directadmin/plugins/{name}/reseller/index.html |
/CMD_PLUGINS_RESELLER/{name}/ | /usr/local/directadmin/plugins/{name}/reseller/index.html |
/CMD_PLUGINS_RESELLER/{name}/index.html | /usr/local/directadmin/plugins/{name}/reseller/index.html |
/CMD_PLUGINS_RESELLER/{name}/test | /usr/local/directadmin/plugins/{name}/reseller/test |
/CMD_PLUGINS_RESELLER/{name}/dir/file | /usr/local/directadmin/plugins/{name}/reseller/dir/file |
| ... | ... |
/CMD_PLUGINS/{name} | /usr/local/directadmin/plugins/{name}/user/index.html |
/CMD_PLUGINS/{name}/ | /usr/local/directadmin/plugins/{name}/user/index.html |
/CMD_PLUGINS/{name}/index.html | /usr/local/directadmin/plugins/{name}/user/index.html |
/CMD_PLUGINS/{name}/test | /usr/local/directadmin/plugins/{name}/user/test |
/CMD_PLUGINS/{name}/dir/file | /usr/local/directadmin/plugins/{name}/user/dir/file |
| ... | ... |
Exmples of requests that serve static contents without executing the script and without wrapping its contents in skin template:
| Request | Returned static file contents |
|---|---|
/CMD_PLUGINS_ADMIN/{name}/images/logo.png | /usr/local/directadmin/plugins/{name}/images/logo.png |
/CMD_PLUGINS_RESELLER/{name}/images/logo.png | /usr/local/directadmin/plugins/{name}/images/logo.png |
/CMD_PLUGINS/{name}/images/logo.png | /usr/local/directadmin/plugins/{name}/images/logo.png |
| ... | ... |
/CMD_PLUGINS_ADMIN/{name}/images/dir/file | /usr/local/directadmin/plugins/{name}/images/dir/file |
/CMD_PLUGINS_RESELLER/{name}/images/dir/file | /usr/local/directadmin/plugins/{name}/images/dir/file |
/CMD_PLUGINS/{name}/images/dir/file | /usr/local/directadmin/plugins/{name}/images/dir/file |
| ... | ... |
Standard menu integration
For plugin to become visible in the DirectAdmin GUI a set of special files in ./hooks directory needs to be created:
| File | Description |
|---|---|
./hooks/admin_txt.html | HTML template to render menu link that opens plugin GUI on admin access level |
./hooks/reseller_txt.html | HTML template to render menu link that opens plugin GUI on reseller access level |
./hooks/user_txt.html | HTML template to render menu link that opens plugin GUI on user access level |
Other magic files:
| File | Description |
|---|---|
./images/admin_icon.svg | If present will be used as icon for plugin menu entry on admin access level |
./images/user_icon.svg | If present will be used as icon for plugin menu entry on user access level |
./images/reseller_icon.svg | If present will be used as icon for plugin menu entry on reseller access level |
Example HTML image template ./hooks/admin_txt.html:
<a href="/CMD_PLUGINS_ADMIN/hello_world">Hello World Plugin</a>
Template files are being evaluated using DirectAdmin template system. It means it is possible to use macros or execute external scripts inside them.