cPanel AppConfig

For cPanel & WHM 11.32

This document describes a cPanel subsystem that can allow you to affect a PHP application served from within cPanel, WHM, or webmail.

Introduction

In cPanel & WHM 11.32, we added the ability to specify two low-level PHP handling attributes when cPanel, WHM, or webmail serves a PHP application. You can choose:

1. Which user owns the runtime process
2. Which php.ini the PHP binary should utilize

These are useful features when writing an application that, for example, grants database access to a single system user. This new functionality is called AppConfig and requires a simple configuration file to work.

The configuration file must:

• Exist in /var/cpanel/apps/.
  • Note: This directory does not exist by default on your system. If no other AppConfig files exist, you will need to create this directory.
• Use the .conf file extension.
• Contain at least 2 of the following 4 key/value pairs.

Keys

url (Required)

The URL is the path to the application you wish to run. In order for your application to be compatible with AppConfig, it must exist in /usr/local/cpanel/base/3rdparty/. Only applications in /usr/local/cpanel/base/3rdparty/ are accessible to AppConfig.

For example, specifying /3rdparty/Foo.php will run an application called Foo.php in /usr/local/cpanel/base/3rdparty.

service (Required)

The service key specifies the service (cPanel, WHM, or webmail) in which the URL is served. This key must contain one of three values: cpanel, whostmgr (WHM), or webmail. If your application is used in more than one service, you will need to create configuration files for each service. This key may only contain one value.

user (Optional)

This value should contain the 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 prefixing 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, setting this key's value to cpanelUser will run the application you specified in URL as cpanelUser.

phpHandler (Optional)

This key's value should be the path to the php.ini file your application will use. 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, specifying Foo as this key's value will use the file /usr/local/cpanel/3rdparty/etc/Foo/php.ini to run the application specified in url as the user specified in user.

Example

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