Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

cPanel AppConfig

For cPanel & WHM

Overview

In cPanel & WHM 11.32, we added the AppConfig system which provides the ability to specify two low-level attributes when cPanel, WHM, or webmail serves an application.

You can choose:

  1. Which user owns the runtime process. This is the system user that the process will run as.
  2. Which php.ini the PHP binary should use.

In cPanel & WHM 11.38.1, the AppConfig system was expanded. You can now use the AppConfig system to register and display WHM Plugins.

note Note: By default, registration is required for WHM addons and is strongly recommend for cPanel & Webmail addons.

note Note: Registration is only required if the admin has disabled the Allow apps that have not registered with AppConfig to be run when logged in as a reseller to WHM tweak setting (Home >> Server Configuration >> Tweak Settings). This option defaults to on in version 11.38.1.

Functionality

The AppConfig functionality requires a configuration file which has the following characteristics:

  • Exists in /var/cpanel/apps/.
  • Uses the .conf file extension. For example, an application that is named example will have a configuration file of example.conf
  • Contains at least 2 of the following key/value pairs:

Key Status Service First Available Description
url Required all 11.32 The url key is the URL at which the script appears. The script ignores the security token for this URL.
In order for your cPanel or Webmail application to be compatible with AppConfig, it must exist in the /usr/local/cpanel/base/3rdparty/ directory.
In order for your WHM application to be compatible with AppConfig, it should exist in the /usr/local/cpanel/whostmgr/docroot/3rdparty/ directory.
Applications in the /usr/local/cpanel/base/3rdparty/ or the /usr/local/cpanel/whostmgr/docroot/3rdparty/ directories are accessible to AppConfig. For example, a cPanel or Webmail application in the /3rdparty/Foo.php file will run an application called Foo.php in the /usr/local/cpanel/base/3rdparty directory.
service Required all 11.32 The service key specifies the service (cPanel, WHM, or webmail) in which the URL is served.
note Note:This key must contain one of three values: cpanel, whostmgr (WHM), or webmail.
note Note: This key may only contain one value. If your application is used in more than one service, you must create configuration files for each service.
user Optional all 11.32 This value should contain the system user that will run the application. This user must exist on the system but should not be a cPanel user. As a best practice, we strongly recommend that you prefix your username with cpanel. This will denote that the user is used to run an application inside of cPanel, but is not a cPanel user (For example, if you set this key's value to cpaneluser, the application will run as cpaneluser).
note Note: The application will not run as the specified user until cPanel has been restarted. To restart cPanel, run the /usr/local/cpanel/etc/init/startcpsrvd command as root user.
note Note: In 11.38.1 and later, you may use the special user '$authuser' which will cause the application to run with the associated system account of the logged in user.
note Note: For backwards compatibility with AppConfig 1.0, if you register your application with the whostmgr service to run as root, it is recommended that you omit the user key as this is the default.
phpHandler Optional all 11.32 This key's value is the path to the php.ini file that your application will use.
note Note: This value must contain the directory inside of /usr/local/cpanel/3rdparty/etc/ that contains the php.ini file your application will use (For example, if you specify Foo as this key's value, the application will use the file /usr/local/cpanel/3rdparty/etc/Foo/php.ini).
url2, url3, url4... Optional all 11.38.1 These are additional URLs through which your application can be accessed.
acls Optional or Required whostmgr 11.38.1 This is a comma-separated list of ACLs. The logged-in user must have at least one of these ACLs in order to access your application at the URL(s) provided.
note Note: A special any ACL is available to allow open access to the application for all authenticated resellers and root users.
features Optional or Required cpanel, webmail 11.38.1 This is a comma-separated list of features. The logged-in user must have at least one of these features in order to access your application at the URL(s) provided.
note Note: A special any feature is available to allow open access to the application for all authenticated users.
entryurl Optional whostmgr 11.38.1 This is the URL that will be used to enter your application though WHM. If you provide this option WHM will automatically create a link to your application (For example, addons/example/index.cgi).
note Note:You should not use this key if you use the legacy addon_.....cgi system. This will result in a duplicate link.
displayname Optional whostmgr 11.38.1 This is the name that will be displayed for your application in WHM.
note Note: This replaces the use of the #WHMADDON: comment, which was used to set the display name in previous versions.
upgradecall Optional all 11.38.1 This is the path to an upgrade script that will run each time cPanel is upgraded to a newer version. The script will be passed two arguments: the previous version of cPanel and the newly-installed version of cPanel (For example, /usr/local/youraddon/bin/upgrade 11.36.0.0 11.38.0.0).
note Note: You can use this script to convert an application that is installed on a system which uses version 11.38.1 or earlier.
icon Optional whostmgr 11.38.1 This is the filename of the icon that is used by the application (For example: myapp_icon.png).
note Note:The icon must be located in the /usr/local/cpanel/whostmgr/docroot/addon_plugins/ directory.

note Note: In cPanel & WHM version 11.38.1+, you should use register_appconfig to create the .conf file in /var/cpanel/apps/.

Example AppConfig file

The following example will run an application called Foo.php as cpaneluser with the php.ini file located at /usr/local/cpanel/3rdparty/etc/Foo/php.ini.

# Service that will serve this app
service=cpanel
 
# Physical path: /usr/local/cpanel/3rdparty/Foo.php
# Literal URL path: $server:$port/$cpsession/3rdparty/Foo.php
url=/3rdparty/Foo.php
 
# System user to run process as
user=cpaneluser
 
# Directory containing php.ini
# - must exist in /usr/local/cpanel/3rdparty/etc/
phpHandler=Foo

# Features required
features=any

How to Update your 11.32 appconfig file for 11.38.1+

Best Practices

If the application is for WHM, you should move your application into its own directory after the 11.38.1+ upgrade takes place.

  • For example, If your application is installed as /cgi/addon_securityadvisor.cgi, you should relocate it to /cgi/addons/securityadvisor/index.cgi when you upgrade to 11.38.1+. Run this with the upgradecall script to move your application to the new location when it detects that /usr/local/cpanel/bin/is_registered_with_appconfig is available.

Once 11.38.1+ is available, you should not attempt to install your application configuration manually. Instead, use the new tools that are available:

  • /usr/local/cpanel/bin/register_appconfig <appconfig_file> — This script registers an application with the path to the application's configuration file. After registration is complete, the configuration file will be moved to /var/cpanel/apps/. If registration is successful, you will see a registered message.

  • /usr/local/cpanel/bin/unregister_appconfig <appconfig_file|appname> — This script unregisters an application from AppConfig and removes the configuration file for that application from /var/cpanel/apps/. Only third-party applications can be unregistered. If unregistration is successful, you will see a unregistered message.

  • /usr/local/cpanel/bin/is_registered_with_appconfig <service> <appname> — This script indicates whether an application is registered with AppConfig for a specific service. The script will output 0 if the application is not registered and 1 if the application is registered.

  • /usr/local/cpanel/bin/update_appconfig_apps — This script attempts to call the upgradecall script of every application that is registered with AppConfig.

  • /usr/local/cpanel/bin/show_appconfig — This script displays a YAML-formatted list of applications that are registered with AppConfig and their settings.

    For example:
    ---
    cpanel:
      -
        features:
          - webmail
        name: horde
        phpConfig: horde
        url: /horde/
        user: cpanelhorde
      -
        features:
          - logaholic
        name: logaholic
        url: /3rdparty/Logaholic
        user: cpanellogaholic
    webmail:
      -
        features:
          - webmail
        name: roundcube
        phpConfig: roundcube
        url: /3rdparty/roundcube/
        user: cpanelroundcube
    whostmgr:
      -
        acls:
          - all
        name: internal_dnsclustering_root
        url:
          - /cgi/adjustclusterdns.cgi
          - /cgi/adjustclusteroptions.cgi
        user: root

Minimum Changes needed to make your AppConfig file work on 11.38.1+

If your application runs inside cPanel or Webmail, you only need to add the features key to the AppConfig file.

If your application runs inside WHM, you only need to add the acls key to the AppConfig file.

Test application

11.32+ test application

This test application allows you to test the 11.32 AppConfig functionality:

11.38.1+ test application

You can obtain the 11.38.1+ test application from the following sources:

Notes

Once your application has been registered, it will be displayed in the Apps Managed by AppConfig page of WHM version 11.38.1+. Apps_Managed_by_AppConfig_WHM_Screen.png

Topic revision: r41 - 18 Sep 2013 - 15:54:58 - Main.LaurenceSimon
SoftwareDevelopmentKit.AppConfig moved from Sandbox.AppConfig on 30 Nov 2011 - 19:59 by Main.JustinSchaefer - put it back