Last updated 11 minutes ago

Development Guides Home >> Guide to WHM Plugins

Guide to WHM Plugins - AppConfig Configuration File

Introduction

AppConfig configuration files store each plugin's or application's AppConfig settings.

Warning:
  • The system will not apply changes to AppConfig configuration files until the cpsrvd service restarts. For more information, read our How to Restart Services documentation.
  • Configuration files must exist in the /var/cpanel/apps/ directory and must use the .conf file extension.

File contents

When you create an AppConfig file, use the key=value pairs from the tables below.

Note:

The AppConfig configuration file supports comments.

All applications

Key Type Description Possible values Example
service string Required
The service that will serve the application.
  • cpanel — cPanel.
  • whostmgr — WHM.
  • webmail— Webmail.
Supply multiple values as a pipe-separated list (for example, cpanel|whostmgr|webmail).
cpanel
user string The system account that runs the application. For WHM applications, this value defaults to root.
  • A valid WHM username on the server.
  • $authuser — Use this value to run the application as the authenticated user.
username
phpConfig string The directory that contains the application's php.ini file. A valid directory name, relative to the /usr/local/cpanel/3rdparty/ directory. Example
url* string Additional URLs through which the system can access your application.
  • Increment the parameter name to specify multiple URLs (for example, url2 and url3 ).
A valid application location. http://www.example.com/application.php

WHM applications

Key Type Description Possible values Example
url string Required
The application's location.
A valid location, relative to the /usr/local/cpanel/whostmgr/docroot/ directory. You must prefix the URL with a slash (/), or your WHM plugin will not function. /cgi/example.cgi
acls string Required
A list of ACLs. The authenticated user must possess at least one of these ACLs to access the application.
  • A comma-separated list of one or more ACLs.
  • any — Allow all authenticated users to use the application.
any
entryurl string The URL to access the application through the WHM interface.
  • If you use this key, WHM creates a link to the application from the WHM interface.
  • If you do not use this key, no menu entry for the item will appear. We strongly recommend that you include this key.
A valid location, relative to the /usr/local/cpanel/whostmgr/docroot/ directory. addons/example/index.cgi
displayname string The application's display name in the WHM interface. A valid string. My Application
icon string The application's icon's filename. A valid WHM icon filename. For more information, read our Guide to WHM Plugins - Plugin Files documentation. example_icon.png
target string The targeted browser window in which to open the application link.
  • This value defaults to _blank.
A valid target attribute.
  • In cPanel & WHM version 64, specify mainFrame to open in the current browser tab.
  • In cPanel & WHM version 66 and later, specify _self to open in the current browser tab.
_blank

cPanel and Webmail applications

Key Type Description Possible values Example
url string Required
The URL to access the application through the cPanel or WHM interface.
  • A valid script location that exists in the /usr/local/cpanel/base/3rdparty/ directory, relative to the /usr/local/cpanel/base/ directory.
  • You must prefix the URL with a slash (/), or your WHM plugin will not function.
3rdparty/example.php
features string Required
  • A list of features.
  • The authenticated user must possess at least one of these features to access the application.
  • A comma-separated list of one or more feature names.
  • any — Allow all authenticated users to use the application.
any

Example

# The application's service.
service=cpanel

# Physical path: /usr/local/cpanel/3rdparty/Example.php
# Literal URL path: $server:$port/$cpsession/3rdparty/Example.php
url=/3rdparty/Example.php

# System user to run process as
user=cpaneluser

# Directory that contains the php.ini file.
# (in the /usr/local/cpanel/3rdparty/ directory)
phpHandler=Example

# Features required
features=any