Development Guides Home

Guide to cPanel Variables

Introduction

The LiveAPI system and dynamicui files can access cPanel's global variables. These variables return data about the server's configuration and the authenticated user.

• These variables are not compatible with WHM plugin development. Only use them in code for cPanel plugin development.
• The examples below use the following LiveAPI system methods:
  • The cpanelif()method evaluates a logic operator or cPanel variable as true or false.
  • The cpanelprint()method returns a cPanel variable's value.
  • To check the environment variables for a process, run the following command, where processname represents the name of the process:

    ps auxwwe | grep processname

Logic operators

!

Description: This logic operator reverses the action of another logic operator.

Example: The following code returns true if a does not equal b:

<cpanelif !a==b>

==

Description: This logic operator checks whether the first argument is equal to the second argument.

Example: The following code returns true if a equals b:

<cpanelif a==b>

=et=

Description: This logic operator checks whether the first argument is equal to the second argument.

Example: The following code returns true if 1 equals 1:

<cpanelif 1=et=1>

=gt=

Description: This logic operator checks whether the first argument is greater than the second argument.

Example: The following code returns true if 4 is greater than 3:

<cpanelif 4=gt=3>

=gtet=

Description: This logic operator checks whether the first argument is greater than or equal to the second argument.

Example: The following code returns true if 4 is greater than or equal to 3:

<cpanelif 4=gtet=3>

=lt=

Description: This logic operator checks whether the first argument is less than the second argument.

Example: The following code returns true if 3 is less than 4:

<cpanelif 3=lt=4>

=ltet=

Description: This logic operator checks whether the first argument is less than or equal to the second argument.

Example: The following code returns true if 3 is less than or equal to 4:

<cpanelif 3=ltet=4>

cPanel variables

$abshomedir

Description: This variable returns the absolute path to the authenticated user's home directory.

If the user's home directory is a symlink, this variable returns the absolute path to the symlink's target.

Example: The following code prints the absolute path to the authenticated user's home directory:

$cpliveapi->cpanelprint('$abshomedir'});

$appname

Description: This variable returns the current cPanel & WHM application.

For example, this variable returns cpanel if you call it from the cPanel interface, or webmail if you call it within a cPanel account's webmail interface.

Example: The following code prints the current cPanel & WHM application:

$cpliveapi->cpanelprint('$appname'});

$basedir

Description: This variable returns the absolute path to the current directory.

Example: The following code prints the current directory's path:

$cpliveapi->cpanelprint('$basedir'});

$basefile

Description: This variable returns the absolute path to the current file.

Example: The following code prints the current file's location:

$cpliveapi->cpanelprint('$basefile'});

$BRANDINGIMG{'KEY'}

Description: This variable returns the string cpanel_magic_revision_random, where random is a random integer, and the relative path to the specified image file (key).

This path is relative to the /usr/local/cpanel/base/ directory.

Example: The following code prints the relative path to the email-pass.gif file:

$cpliveapi->cpanelprint($BRANDINGIMG{'email-pass.gif'});

$brandingpkg

Description: This variable returns the user's current branding package.

Example: The following code prints the current branding package's name:

$cpliveapi->cpanelprint('$brandingpkg');

$CONF{'KEY'}

Description: This variable returns the value for a specific setting (key) in the /var/cpanel/cpanel.config file.

Example: The following code prints the server's mysql-version setting:

$cpliveapi->cpanelprint($CONF{'mysql-version'});

$CPDATA{'KEY'}

Description: This variable returns the value for a specific setting (key) in the authenticated user's data file.

The system retrieves this information from the hash of settings in the /var/cpanel/users/username file, where username is the cPanel or WHM account username.

Example: The following code prints the user's CONTACTEMAIL setting:

$cpliveapi->cpanelprint($CPDATA{'CONTACTEMAIL'});

$CPERROR{'module'}

Description: This variable returns most recent error that the specified module (module) returned.

Module names must be in lowercase.

Example: The following code prints the most recent error for the email module:

$cpliveapi->cpanelprint($CPERROR{'email'});

$CPVAR{'KEY'}

Description: This variable returns the value of a cPanel variable that you set elsewhere in the same page.

This variable will check any cPanel variables that you set with a cpanel function or a <cpanel setvar> tag.

Example: The following code prints the test variable's most recent value:

$cpliveapi->cpanelprint($CPVAR{'test'});

$FORM{'KEY'}

Description: This variable returns the GET or POST data for a specific variable (key) that a user passes to a page as part of a form.

To return the URI-encoded version of the value, use the $URI_ENCODED_FORM{'KEY'} variable.

Example: The following code prints the test variable's value:

$cpliveapi->cpanelprint($FORM{'test'});

$formdump

Description: This variable returns the entire contents of the $FORM{} hash, which contains all of the GET or POST data that a user passes to a page.

Use this variable to debug an interface form.

Example: The following code prints the contents of the $FORM{} hash:

$cpliveapi->cpanelprint('$formdump'});

$hasanonftp

Description: This variable returns a Boolean value that indicates whether anonymous FTP is enabled on the server.

• A value of 1 indicates that anonymous FTP is enabled.
• A value of 0 indicates that anonymous FTP is disabled.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasanonftp'});

$hasdedicatedip

Description: This variable returns a Boolean value that indicates whether the authenticated account has a dedicated IP address.

• A value of 1 indicates that the account has a dedicated IP address.
• A value of 0 indicates that the account does not have a dedicated IP address.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasdedicatedip'});

$hasgem

Description: This variable returns a Boolean value that indicates whether RubyGems are enabled for the authenticated account.

• A value of 1 indicates that RubyGems are enabled.
• A value of 0 indicates that RubyGems are disabled.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasgem'});

$hasmoddeflate

Description: This variable returns a Boolean value that indicates whether the mod_deflate Apache module is available on the server.

• A value of 1 indicates that the module is available.
• A value of 0 indicates that the module is not available.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasmoddeflate'});

$hasmodproxy

Description: This variable returns a Boolean value that indicates whether the mod_proxy Apache module is available on the server.

• A value of 1 indicates that the module is available.
• A value of 0 indicates that the module is not available.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasmodproxy'});

$haspear

Description: This variable returns a Boolean value that indicates whether PHP PEAR is installed.

• A value of 1 indicates that PHP PEAR is installed.
• A value of 0 indicates that PHP PEAR is not installed.

Example:

The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$haspear'});

$haspostgres

Description: This variable returns a Boolean value that indicates whether PostgreSQL® is installed.

• A value of 1 indicates that PostgreSQL is installed.
• A value of 0 indicates that PostgreSQL is not installed.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$haspostgres'});

$haspureftp

Description: This variable returns a Boolean value that indicates whether the authenticated account uses the Pure-FTPd FTP server.

• A value of 1 indicates that the account uses Pure-FTPd.
• A value of 0 indicates that the account does not use Pure-FTPd.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$haspureftp'});

$hasrails

Description: This variable returns a Boolean value that indicates whether Ruby on Rails® is enabled for the authenticated account.

• A value of 1 indicates that Ruby on Rails is enabled.
• A value of 0 indicates that Ruby on Rails is disabled.

Ruby on Rails does not function on Amazon Linux servers.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasrails'});

$hasvalidshell

Description: This variable returns a Boolean value that indicates whether the authenticated account has shell access.

• A value of 1 indicates that the account has shell access.
• A value of 0 indicates that the account does not have shell access.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasvalidshell'});

$homedir

Description: This variable returns the absolute path to the authenticated user's home directory.

Example: The following code prints the authenticated user's home directory path:

$cpliveapi->cpanelprint('$homedir'});

$hostname

Description: This variable returns the server's hostname.

Example: The following code prints the server's hostname:

$cpliveapi->cpanelprint('$hostname'});

$httphost

Description: This variable returns the current HTTP host that connects to the cPanel daemon.

Example: The following code prints the current HTTP host:

$cpliveapi->cpanelprint('$httphost'});

$ip

Description: This variable returns the authenticated user's primary IP address.

Example: The following code prints the authenticated user's primary IP address:

$cpliveapi->cpanelprint('$ip'});

$isallowedssl

Description: This variable returns a Boolean value that indicates whether the authenticated user can use cPanel's SSL features.

• A value of 1 indicates that the following conditions are true:
  • The cPanel account has a dedicated IP address.
  • The server administrator has enabled the Allow cPanel users to install SSL hosts if they have a dedicated IP setting in WHM's Tweak Settings interface ( WHM >> Home >> Server Configuration >> Tweak Settings ).
• A value of 0 indicates that at least one of these conditions is not true and the authenticated user cannot use cPanel's SSL features.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$isallowedssl'});

$isreseller

Description: This variable returns a Boolean value that indicates whether the authenticated user has reseller privileges.

• A value of 1 indicates that the user has reseller privileges.
• A value of 0 indicates that the user does not have reseller privileges.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$isreseller'});

$isresellerlogin

Description: This variable returns a Boolean value that indicates whether the current session used the root password or a reseller account password to authenticate.

• A value of 1 indicates that the current session authenticated with the root password or a reseller account password.
• A value of 0 indicates that the current session did not authenticate with the root password or a reseller account password.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$isresellerlogin'});

$isresold

Description: This variable returns a Boolean value that indicates whether the a reseller account owns the authenticated account.

• A value of 1 indicates that a reseller account owns the authenticated account.
• A value of 0 indicates that the root user owns the authenticated account.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$isresold'});

$mailactionhost

Description: This variable returns the mail host's configuration from WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).

Example: The following code prints the server's mail host configuration:

$cpliveapi->cpanelprint('$mailactionhost'});

$mainhttpdport

Description: This variable returns the port on which Apache is currently listening. Typically, this is port 80.

Example: The following code prints the port on which Apache is listening:

$cpliveapi->cpanelprint('$mainhttpdport'});

$mysqlversion

Description: This variable returns the server's MySQL® version number.

Example: The following code prints the server's MySQL version:

$cpliveapi->cpanelprint('$mysqlversion'});

$NVDATA{'KEY'}

Description: This variable returns the contents of the specified file (key) in a user's home/.cpanel/nvdata/ directory.

Example: The following code prints the contents of the home/.cpanel/nvdata/test file:

$cpliveapi->cpanelprint($NVDATA{'test'});

$random

Description: This variable generates a random number that is between 1 and 1,000,000.

Example: The following code prints a random number:

$cpliveapi->cpanelprint('$random');

$sslhttpdport

Description: This variable returns the port on which Apache currently listens for SSL connections. Typically, this is port 443.

Example: The following code prints the SSL port on which Apache is listening:

$cpliveapi->cpanelprint('$sslhttpdport'});

$URI_ENCODED_FORM{'KEY'}

Description: This variable returns the GET or POST data for a specific variable (key) that a user passes to a page as part of a form, in a URI-encoded format.

To return the non-URI-encoded version of the value, use the $FORM{'KEY'} variable.

Example: The following code prints the value that the user passes in for the test variable, in a URI-encoded format:

$cpliveapi->cpanelprint($URI_ENCODED_FORM{'test'});

$user

Description: This variable returns the authenticated account's username.

Example: The following code prints the authenticated user's username:

$cpliveapi->cpanelprint('$user'});

$version

Description: This variable returns the server's current cPanel & WHM version.

Example: The following code prints the server's current cPanel & WHM version:

$cpliveapi->cpanelprint('$version');

Deprecated and removed variables

$hasurchin

Description: This variable returns a Boolean value that indicates whether Urchin is installed on the server.

• A value of 1 indicates that Urchin is installed.
• A value of 0 indicates that Urchin is not installed.

We deprecated Urchin support in cPanel & WHM version 11.42. Urchin is no longer available for purchase, or supported, as of March 2012.

Example: The following code prints a Boolean value, as described above:

$cpliveapi->cpanelprint('$hasurchin'});

$lang

Description: This variable returns the authenticated user's language setting.

This cPanel variable is part of the deprecated lang system. Do not use this system. Instead, use our Locale System.

Example: The following code prints the authenticated user's language setting:

$cpliveapi->cpanelprint('$lang');

$LANG{'KEY'}

Description: This variable returns a string in the user's selected language that corresponds to the key value in the /usr/local/cpanel/locale file.

Example: The following code prints the key's string in the user's locale:

$cpliveapi->cpanelprint($LANG{'hd'});

$password

Description: This variable returns the authenticated user's password.

We removed this variable in cPanel & WHM version 11.40.

Example: The following code prints the authenticated user's password:

$cpliveapi->cpanelprint('$password'});