About This Document 3. Integration Overview 4. Prerequisites and Requirements 6

Transcription

1

2 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 Step 4. Enable Resellers to Limit the Number of Presence Builder Sites for Their Customers.. 11 Step 5. Select Who Should Access Presence Builder 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

3 C H A P T E R 1 About This Document 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.

4 C H A P T E R 2 Integration Overview 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).

5 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 addon domains.

6 C H A P T E R 3 Prerequisites and Requirements 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 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 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 or later.

7 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 /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 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 For instructions on how to install Presence Builder Standalone, refer to the section Installing Parallels Presence Builder Standalone at 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 handled entirely by the cpanel plugin.

8 8 Prerequisites and Requirements To learn more about cpanel & WHM, refer to the product documentation at

9 C H A P T E R 4 Installation Steps 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 /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.

10 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 = If Presence Builder is installed into a non-default directory, specify the URL accordingly. Example: url = 3. If your Presence Builder installation is configured to listen on nonstandard 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 = secure_url = 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.

11 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: 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. 3. Click Save.

12 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).

13 C H A P T E R 5 Upgrade Steps 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).

14 C H A P T E R 6 Verifying the Integration 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.

15 C H A P T E R 7 Setting Limits on the Number of Sites Users Can Create 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.

16 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. You will be able to reset the limit later by clicking the corresponding link Reset limit.

17 C H A P T E R 8 Troubleshooting Integration Issues 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).

18 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).

19 C H A P T E R 9 Localizing the cpanel & WHM Plugin User Interface 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 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.

20 C H A P T E R 10 Removing the Integration 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