Contents
About This Document
3
Integration Overview
4
Prerequisites and Requirements
6
Meeting the Requirements of the cPanel Plugin ... 6 Meeting the Requirements of Presence Builder Standalone ... 6
Installation Steps
9
Step 1. Obtain and Run the Installer Package ... 9 Step 2. Configure the Connection Settings ... 9 Step 3. Specify the Presence Builder Redirection URLs ... 10 Step 4. Enable Resellers to Limit the Number of Presence Builder Sites for Their Customers.. 11 Step 5. Select Who Should Access Presence Builder ... 12
Upgrade Steps
13
Verifying the Integration
14
Setting Limits on the Number of Sites Users Can Create
15
Troubleshooting Integration Issues
17
Localizing the cPanel & WHM Plugin User Interface
19
Removing the Integration
20
This document is intended for hosting service providers who use cPanel and want to provide their customers with the website creation and maintenance tools offered by Parallels Presence Builder.
C
H A P T E R1
Presence Builder can be integrated with cPanel by means of a special plugin, which is installed on cPanel-managed servers. The supported integration scheme is suitable only for providers of shared hosting services. VPS hosting with cPanel VPS Optimized is not currently supported.
The following figure illustrates interaction of cPanel & WHM and Presence Builder using the plugin.
Integration of Parallels Presence Builder Standalone with cPanel involves the following steps:
1. Install and configure Presence Builder on a separate server. Presence Builder
cannot be installed on the same server where cPanel & WHM are installed. Learn more about this in the section Prerequisites and Requirements (on page 6).
2. Configure the cPanel server to ensure that it meets the hosting requirements
described in the section Prerequisites and Requirements (on page 6).
3. Obtain the installer package called wpb_cpanel.run from the Parallels site and
run it on the cPanel server. The installer does the following:
a Installs the cPanel plugin, which will manage your Presence Builder installation
by means of the API.
b Adds the Presence Builder option to all existing feature lists and packages. This
enables all user accounts to have access to the editor: the Presence Builder button becomes available in cPanel > Home > Software/Services group. You will be able to restrict access to Presence Builder by modifying the feature lists,
packages, and accounts in WHM.
Learn more about obtaining and installing the plugin in the section Installation Steps (on page 9).
C
H A P T E R2
Integration Overview 5
4. Specify the URL and credentials that cPanel will use for connecting to the server
where Parallels Presence Builder is installed. You can do this either in WHM >
Plugins > Presence Builder > Settings tab, or by editing the configuration file
/usr/local/cpanel/etc/webpresencebuilder.ini.
If you do not specify the URL and credentials, cPanel will not be able to connect to Presence Builder and your customers will not be able to use Presence Builder.
5. Specify the web page to which users should be redirected when their session
expires or when they remove their site.
After the integration is successfully completed, users will be able to create and edit sites with Presence Builder under their cPanel domain names, subdomains, and add-on domains.
Before running the integration utility, you need to do the following:
1. Configure the cPanel installation to ensure that it is compatible with Presence
Builder and with the cPanel plugin.
2. Install Presence Builder Standalone on a separate server and configure it, as
described in Parallels Presence Builder 11.5 Standalone: Installation and Administration
Guide at http://download1.parallels.com/WPB/Doc/11.5/en-US/pdf/presence-builder-11.5-standalone-installation-administration-guide.pdf.
Important: Do not install Presence Builder Standalone on the same server where
cPanel is installed.
Meeting the Requirements of the cPanel Plugin
The cPanel plugin requires that the following components be installed on the server where sites will be hosted:
cPanel & WHM 11.38.0 with the x3 theme. The plugin cannot work with themes other than x3.
PHP 5.2.x or later.
The cURL PHP extension.
Installation of the cPanel plugin requires superuser privileges.
To ensure that the latest PHP version is used by cPanel & WHM and that
the cURL PHP extension is installed:
1. Log in to your cPanel server as root via SSH.
2. Issue the command /usr/local/cpanel/scripts/makecpphp.
After doing this, PHP will be rebuilt with support for the cURL extension. This operation will take some time to complete.
Meeting the Requirements of Presence Builder
Standalone
Presence Builder Standalone requires that the following components be installed on the cPanel server:
PHP 5.2.x or later.
ionCube Loader 3.1.15 or later.
C
H A P T E R3
Prerequisites and Requirements 7
PHP extensions: dom, mbstring, zlib, and gd.
To check whether your cPanel hosting environment meets the Presence
Builder's requirements:
1. Download the file
http://download1.parallels.com/WPB/Integration/cPanel
/latest/check.php.
2. Set up a web hosting account in cPanel. For example, let's assume that
the hosting account will be associated with the domain name
example.com.
3. Using cPanel's File Manager, upload the file check.php to the hosting
account's document root to make that script accessible by HTTP.
4. Using a web browser, visit http://example.com/check.php.
The script will show a report on the availability of the necessary hosting features.
To install or switch on PHP and the necessary extensions for website
hosting in cPanel:
1. Go to WHM > Main > Software > EasyApache (Apache Update).
2. In Step 1. Profile, click Start customizing based on profile.
3. In Step 2. Apache Version, click Next Step.
4. In Step 3. PHP Major Version, select the PHP version 5.2 or 5.3 and click Next
Step.
5. In Step 4. Short Options List, click Exhaustive Options List.
6. In Step 5. Exhaustive Options List, select the options IonCube Loader, Mbstring,
Zlib, GD, and click Save and Build.
This process may take up to 30 minutes.
To learn about prerequisites and installation requirements for Presence Builder Standalone, refer to the section Preparing for Installation at
http://download1.parallels.com/WPB/Doc/11.5/en-US/online/presence-builder-standalone-installation-administration-guide/69646.htm.
For instructions on how to install Presence Builder Standalone, refer to the section
Installing Parallels Presence Builder Standalone at
http://download1.parallels.com/WPB/Doc/11.5/en-US/online/presence-builder-standalone-installation-administration-guide/69641.htm.
Note that you do not need to read the sections about integration in Parallels Presence
Builder Standalone Installation and Administration Guide because integration with cPanel is
8 Prerequisites and Requirements
To learn more about cPanel & WHM, refer to the product documentation at
Step 1. Obtain and Run the Installer
Package
1. Using SSH, log in to the cPanel server as root.
2. Download the self-extracting installer package from parallels.com by
issuing the following command:
wget
http://download1.parallels.com/WPB/Integration/cPanel
/latest/wpb_cpanel.run
3. Set the Execute permission for wpb_cpanel.run:
chmod 755 wpb_cpanel.run
4. Run the script:
./wpb_cpanel.run
Note: Hosting providers who do not want the pages related to the Presence Builder
plugin to be shown in WHM, can run the installer with the option -- --no-whm. After the installation is finished, you need to configure the plugin: specify the settings that cPanel will use for connecting to Presence Builder Standalone.
Step 2. Configure the Connection Settings
You can configure the connection settings in either of the following ways: Through the WHM web interface.
By modifying a configuration file on the cPanel server's file system. This method may be useful if you do not have access to WHM.
To set up the connection through WHM:
1. Go to WHM > Plugins > Presence Builder > Settings tab.
2. Specify the URL of the server where Presence Builder Standalone is
installed.
3. Specify the administrator's password for Presence Builder Standalone.
4. Click Save Changes.
C
H A P T E R4
10 Installation Steps
The changes will be saved to the configuration file
/usr/local/cpanel/etc/webpresencebuilder.ini.
Note: After the integration is completed, you can track the number of websites created
by your customers in WHM > Plugins > Presence Builder > Sites tab, and view a report about failed operations in WHM > Plugins > Presence Builder > Log tab.
To set up the connection by editing the configuration file:
1. Open the following file for editing:
/usr/local/cpanel/etc/webpresencebuilder.ini.
2. By using the url option, specify the URL of the server where Presence
Builder is installed.
Example:
url = http://sitebuilder.yourdomain.com
If Presence Builder is installed into a non-default directory, specify the URL accordingly.
Example:
url = http://sitebuilder.yourdomain.com/editor/
3. If your Presence Builder installation is configured to listen on
non-standard HTTP or HTTP Secure ports (different from 80/443) then you
must additionally specify the ports in the url and secure_url
parameters.
Examples:
url = http://sitebuilder.yourdomain.com:8880
secure_url = https://sitebuilder.yourdomain.com:8443
4. By using the password option, specify the administrator’s password for
your Presence Builder installation.
Example:
password = your_admin_password
5. Save changes to the webpresencebuilder.ini file.
Step 3. Specify the Presence Builder
Redirection URLs
This section describes how to redirect users to the cPanel login page in the following cases:
After users remove their websites from the Presence Builder editor.
After removing a site from the editor, users are taken back to the editor and, if the trial mode is switched on, a trial site is automatically created for them. If the trial mode is switched off, then the users are taken to a blank page.
Installation Steps 11
On attempting to use the editor after their sessions expire.
If users edit a site, leave the browser window open for a long time without
performing any actions, their session expires. On attempting to resume editing in the browser they will be taken to a blank page.
On attempting to access the editor without authorization.
If users attempt to go to the editor by typing a URL in their browser, they will be taken to a blank page.
In all of these cases, the page URL is set to sitebuilder.<hostname>/. We suggest that you change the URL to point to the cPanel login page.
To set up a redirection to the cPanel’s login page:
1. On the Presence Builder server, open the configuration file
/usr/local/sb/config.
2. In the [general] section of the file, add the following lines:
unauthorized_access_redirect_url = <URL to the cPanel web interface>
session_expired_redirect_url = <URL to the cPanel web interface>
removed_site_redirect_url = <URL to the cPanel web interface> where <URL to the cPanel web interface> is the URL of the cPanel login page. For example: http://cp.example.com.
3. Save the file.
Step 4. Enable Resellers to Limit the
Number of Presence Builder Sites for
Their Customers
If you want to enable your resellers to use WHM for limiting the number of sites that their customers can create with Presence Builder, do the following:
1. Log in as root to WHM.
2. Go to Server Configuration > Tweak Settings > Security tab, and switch on the
option Allow PHP to be run by resellers in WHM.
12 Installation Steps
Step 5. Select Who Should Access
Presence Builder
By default, the Presence Builder option is added to all feature lists in WHM’s Feature Manager (Packages > Feature Manager). If you want to restrict access to Presence Builder, we recommend that you log in to WHM, review the existing feature lists, packages, and accounts, and make the corresponding adjustments. To learn about how to set limits on the number of available Presence Builder sites for packages and user accounts, see the chapter Setting Limits on the Number of Sites Users Can Create (on page 15).
If you already have an earlier version of the plugin installed, you can upgrade it to the latest version by running the installation script. The plugin will be updated.
For instructions on how to obtain and run the installation script, see Installation Steps,
Step 1. Obtain and Run the Installer Package (on page 9).
C
H A P T E R5
To verify that the integration was completed successfully, do the
following:
1. Log in as root to your WHM panel.
2. Go to Packages > Feature Manager.
3. Create a new feature list or open any of the existing feature lists for
editing. At the bottom of the feature list, the Presence Builder option must
be shown and the corresponding checkbox must be selected by default.
4. If you do not have any configured packages, create at least one
package with a feature list that includes the Presence Builder option.
5. Go to Account Functions > Create a New Account.
6. When creating a user account, select a package whose feature list
includes the Presence Builder option.
7. Log in to cPanel under the user account you have created. Under the
Software/Services group, the Presence Builder icon must be shown.
Note: Do not attempt to log in under the user account by clicking the link to cPanel
in WHM > Account Information > List Accounts. In such a case, the cPanel & WHM security policy will not let Presence Builder obtain the user's FTP password and set the website publishing settings. This will result in the following error: "The site cannot be published to the specified location. Site publishing settings are not defined."
8. Click the Presence Builder icon. The Presence Builder editor will open in a
new browser window or tab, and you will be taken to the Select Your
Website Topic page.
9. Select a website topic and click Create Site.
10. Click the Publish button to publish the website to the customer’s
webspace.
11. Open the website in a browser.
C
H A P T E R6
By default, all user accounts that are allowed to access Presence Builder can create an unlimited number of websites.
You can limit the number of Presence Builder websites available to users by using the following methods:
Set a limit for a package. Setting a limit for a package defines how many sites can be created by users subscribed to that package.
Set a limit for a user account. Individually defined limits supersede any limits that may be defined in package limits.
Viewing Statistics on the Use of Presence Builder for Websites
To view a list of domain names for which websites were created with
Presence Builder:
Go to WHM > Plugins > Parallels Presence Builder > Sites tab.
All domain names registered in the system are listed in the Website column. Websites created with Presence Builder and published on hosting accounts are listed in the
Published column.
Viewing and Setting Limits for Packages
To view the limits defined for packages:
Go to WHM > Plugins > Parallels Presence Builder > Package Limits tab.
All packages for which limits were defined are listed under Packages with Defined Limits.
To set a limit for a package:
1. Go to WHM > Plugins > Parallels Presence Builder > Package Limits tab.
2. Select the package, specify the number of allowed sites, and click Set
Limit.
You will be able to reset the limit later by clicking the corresponding link Reset limit.
C
H A P T E R7
Setting Limits on the Number of Sites
Users Can Create
16 Setting Limits on the Number of Sites Users Can Create
Viewing and Setting Limits for User Accounts
To view the limits individually defined for user accounts:
Go to WHM > Plugins > Parallels Presence Builder > Account Limits tab.
All user accounts for which limits were defined are listed under Accounts with Defined
Limits.
To set a limit for a user account:
1. Go to WHM > Plugins > Parallels Presence Builder > Account Limits tab.
2. Select the account, specify the number of allowed sites, and click Set
Limit.
Issue: The Presence Builder option is not shown in the Feature List in WHM or the Presence Builder icon is not shown in cPanel.
Resolution: This could happen due to a plugin installation failure. To discover the cause
of the issue, see the plugin’s log file webpresencebuilder.log. It should be located in the directory from which you ran the installation.
Issue: The Select Your Website Topic page of Presence Builder does not open.
Resolution: To see a detailed error message about the cause of the problem, do the
following:
1. Enable the debugging mode by adding the line debug = true to the configuration file /usr/local/cpanel/etc/webpresencebuilder.ini.
2. Click the Presence Builder icon again. 3. See the log file on the cPanel server -
/usr/local/cpanel/logs/webpresencebuilder.log. This log is also available in WHM > Plugins > Presence Builder > Log.
After resolving the issue, set the option debug = false in the configuration file.
Issue: On attempting to publish a website, the following error occurs: “The site cannot
be published to the specified location. The specified site location does not have ionCube Loader support. Please contact the server administrator.”
Resolution: You need to install or switch on IonCube Loader for PHP, as described in
the chapter Prerequisites and Requirements (on page 6).
Issue: On attempting to publish a website, the following error occurs: “The site cannot
be published to the specified location. The specified site location does not support the required PHP extensions. Please contact the server administrator.”
Resolution: You need to install or switch on the mbstring, zlib, and gd extensions for
PHP, as described in the chapter Prerequisites and Requirements (on page 6).
Issue: On attempting to publish a website, the following error occurs: “The site cannot
be published to the specified location. An internal server error has occurred on the remote server. Please contact the server administrator.”
Resolution: Check that PHP is operating properly on the hosting account by running the
check.php script, and then resolve any issues revealed by the script. This procedure is described in the chapter Prerequisites and Requirements (on page 6).
C
H A P T E R8
18 Troubleshooting Integration Issues
Issue: On attempting to publish a website, the following error occurs: “The site cannot
be published to the specified location. The site publishing settings are not defined.”
Resolution: Make sure that you are logged in to cPanel as a customer, and that you did
not use the option to log in to cPanel from WHM > Account Information > List Accounts.
Issue: CAPTCHA is not shown in contact forms on published websites.
Resolution: You need to switch on the GD PHP extension as described in the chapter Prerequisites and Requirements (on page 6).
The plugin supports the following interface languages: American English British English Brazilian Portuguese Dutch French German Italian Japanese Korean Polish Russian Spanish Simplified Chinese Traditional Chinese
If your language is not on this list, you can translate the plugin locale into your language:
1. Log in to the cPanel & WHM server over SSH.
2. Go to the directory
/usr/local/cpanel/base/frontend/x3/webpresencebuilder
/translations/.
3. Make a copy of the en_US.xml file and save it as <locale
code>.xml, where <locale code> is your locale code, as specified
in the table at
http://download1.parallels.com/WPB/Doc/11.5/en-US/online/presence-builder-localization-guide/about.htm
.
4. Translate the contents of the newly created XML file. The phrases that
you need to translate are enclosed in <phrase> tags.
C
H A P T E R9
Localizing the cPanel & WHM Plugin
User Interface
Removal of the integration results in disconnecting of cPanel from Presence Builder and removal of all Presence Builder-related icons from cPanel.
The Presence Builder installation is not automatically removed, and users’ websites remain in the editor’s database and in users' webspaces.
You will be able to easily restore the integration later; however, the sites that were previously created and published from the Presence Builder editor will no longer be manageable through the editor.
To remove the integration, run the following command in the console:
./wpb_cpanel.run -- --uninstall
