TOCPREVNEXTINDEX

Ensim Corporation


Chapter 4
Customizing Ensim Pro

Introduction

This chapter provides information and instructions on customizing Ensim Pro.

Topics include:


Important icon

Ensim Pro relies on certain RPMs for the operation of its control panel and for virtualization. We recommend that you consult Ensim Support before you upgrade these RPMs. Refer to Table 4-1 for the list of non-customizable RPMs.

Some of the examples given below include the shell primitive \ which is used to enter a new line without the shell executing the command. This is included for reasons of clarity and can be omitted if your command fits in one line.


Customizing the Ensim Virtual Private File System

Ensim Pro creates a Virtual Private File System (VPFS) for each site created. When a site is created, the file system for that site is populated with a default set of services from a template. This is done using hard links.

Earlier versions of Ensim Pro contained a pre-built VPFS template that contained a copy of every service possible. This template could only be changed through an upgrade to the Ensim Pro version released by Ensim. In Ensim Pro, the template mechanism has been enhanced. It no longer contains a copy (that is, binaries) of the service. Instead the template contains a filter to select services from the root file system. This template is used during site creation and modification to dynamically generate the VPFS for any site. You can now modify the template without requiring a software upgrade from Ensim.

The following are the benefits of this change:

Procedure to update RPMs

In order to synchronize updated services (RPMs) into all site file systems, you need to take Ensim Pro through its “maintenance mode” state which causes it to update the sites. Run the following steps:

  1. Upgrade, or reinstall, any RPM.
  2. Run the following commands as root:
    • set_pre_maintenance
    • set_maintenance
    • set_post_maintenance
    • service webppliance restart

Advanced usage: If you want to add a new RPM to any service, edit the appropriate .sh file for that service in /etc/virtualhosting/filelists/<servicename>.sh. Follow the instructions included in that file. Ensure that you know exactly what you are doing when manipulating these files. After editing the file, make Ensim Pro go through maintenance mode (See Step 2 above).

Use of standard packages

Earlier versions of Ensim Pro customized a number of key services to resolve issues, enhance security, and improve the performance of hosting domains. While these customizations provided a superior hosting environment, they also impacted flexibility in managing these services and increased the latency period for releasing critical service security patches.

Ensim Pro removes customizations made by Ensim to critical services enabling self-managed deployment of services. However, Ensim Pro retains customizations to certain services. Since these are no longer available or supported, Ensim is providing these as a value added enhancement.

The services that are customized are those that are originally available in the tarball format. Ensim Pro uses the RPM format for managing services. However, certain services are released by vendors only in the tarball format requiring Ensim Pro to convert these services to the RPM format and thus customize them.

However, the source RPMs of these services (containing Ensim customizations) will be made available for download and use to customers whenever a security patch is released by the service vendor, prior to the official release from Ensim. This enables you to use the source RPMs and self-create the RPM packages for installation on to an Ensim Pro server as soon as a security patch for the service is released. Note that when you self-upgrade RPMs with a release from the service vendor, you must restart the service after the upgrade to ensure effective functioning of the service.

Table 4-1 provides the list of customized and non-customized RPMs.

Table 4-1. List of customized and non-customized RPMs 
Name of the customized RPM
Why you should not customize the RPM
cronolog
  • Converted the tarball into an RPM
  • Resolved issues concerning the date and time format of log file names
frontpage
Converted the tarball into an RPM
majordomo
  • Modified the configuration file
  • Included security fixes
  • Modified the build process so as to enable it to be built by non-root users
mod_jk
Modified for improved integration with Apache
perl-Quota
Changed to support quotas on multiple Linux kernel
versions
apache-mod_fastcgi
Resolved session timeout issues
poprelay
Created an RPM for the script
phpMyAdmin
Converted the tarball into an RPM
squirrelmail
Converted the tarball into an RPM
vacation
Converted the tarball into an RPM
mivaempressa
Converted the tarball into an RPM
mivamerchant_unl
Converted the tarball into an RPM
tomcat
Converted the tarball into an RPM
halcyon
Converted the tarball into an RPM
List of standard packages used (non-customized RPMs)
analog
xinetd
apache 2.0
net-snmp
gettext
quota
imap
sendmail
mod_perl (Apache 2.0)
mysql
mod_ssl (Apache 2.0)
gcc
mx
make
openssh
perl
openssl
php
postgresql
proftpd
python2
telnet
webalizer
 

Customizing domains

Ensim Pro creates a chroot (change root) environment for each domain you create. A chroot environment is a file system below the domain name directory of the directory tree (/home/virtual/<domain_name>). Effectively, the chroot file system limits the part of a file system a process can access, since the directory you specify becomes the root directory for all subsequent file system references. The chroot file system contains the Web pages, CGI scripts, users’ mailboxes and home directories, FTP, and other files.

There may be instances where you might want to add enhanced capabilities to this chrooted environment. For example, you might want to install additional HTML or SHTML (SSI) pages, and other executable programs on the domain for users with Telnet or SSH access to the site. You can make these functions available through shell scripts and custom .tar files.

The scale of customizations possible depend on the security level set for the domain. Please read Overview of domain security before customizing domains.

Overview of domain security

When multiple domains are hosted on a single server, sharing system resources, there is a high possibility of sabotage or inadvertent activity that may compromise the integrity of data. Setting appropriate security levels for a domain can check misuse or malevolent activity.

Depending on the security level chosen, certain services for the domain run in protected mode within the restricted environment of the domain’s file system, technically referred to as a chrooted environment. This prohibits the resources of the secured domain from unauthorized access; also, the administrator and users of the secured domain cannot access data or resources pertaining to other domains on the Ensim Pro server.

Ensim Pro offers three security levels:

For details on each security level, please refer to the Appliance Administrator online Help (accessible through the Help option on the System Menu of the control panel.)

Customizing domains with virtDomain.sh

Ensim Pro allows you to customize any new domain that you create by using the customization script, virtDomain.sh. Once the customization is complete, all new domains you create reflect the changes made by your script. However, existing domains remain unchanged unless you manually execute the virtDomain.sh script (passing the correct arguments and password) for those domains.

To use this option, follow these steps before you create a domain.


Caution icon

The Apache Web server is compiled with suexec support, which is sensitive to security issues and does not run CGI scripts that do not conform to its standards.

If your
virtDomain.tar file installs scripts into the domain’s cgi-bin directory, you must set the cgi-bin permissions to ownership by the Site Administrator and turn off group and other write privileges by using the chmod 0755 command.

You must exercise caution while customizing domains using the virtDomain.sh script. Improper usage can adversely affect the functioning of all new domains that you create.


The customization process works as follows:

Once you have created a new domain and assigned services to it (using the Site Manager option on the Appliance Administrator page), Ensim Pro looks in the directory /etc/appliance/customization for the file virtDomain.tar. If it finds this file, it untars the file into the root directory of the chroot file system.

After the file is unpacked, Ensim Pro runs the executable script virtDomain.sh as root. On the command line, the script receives the following three arguments.

The script receives the password of the newly created domain from the standard input. If it encounters any errors, it displays them in the Details window of the Appliance Administrator control panel.


Important icon

CLI scripts reside in the directory /usr/local/bin. You must include the full path name for the CLI script that you are calling - that is, /usr/local/bin/<CLI script>. Using the script to automatically customize a domain will fail if the script calls the required CLI script without including the full path name.


Changing file permissions over to the new domain owner


Example icon

#!/bin/sh

DOMAIN=$1

WP_USER=`/usr/local/bin/sitelookup -d $DOMAIN wp_user`

#Assumes script alias is set to cgi-bin

chown -R $WP_USER:$WP_USER \

/home/virtual/$WP_USER/var/www/cgi-bin/

chmod -R 0755 /home/virtual/$WP_USER/var/www/cgi-bin/

Using script hooks

In addition to virtDomain.sh, you can take advantage of script hooks to customize Ensim Pro domains. Script hooks allow you to add custom scripts to augment the functionality of a script as desired. For example, when you modify a site, you can add a custom script that enables you to notify the Site Administrator of the change. If you deploy a centralized DNS server for various appliances, you can use script hooks to notify the central DNS server of any updates. The scripts must be located at /etc/appliance/customization.

On the command line the scripts receive site<n>, where <n> uniquely identifies the site, as the argument. For example, you can write a script that logs a detailed summary of an event whenever the corresponding action (edit domain/enable domain) is initiated, or you can send custom notifications.

editVirtDomain.sh

The editVirtDomain.sh script hook runs custom commands placed in the script file. The script will be run whenever the specified domain is modified.

Syntax: editVirtDomain.sh site<n>

where <n> is the site identifier of the site being modified. Information about the domain can be obtained by using the `sitelookup' API.

Notifying Site Administrators when sites are modified


Example icon

#!/bin/sh

#the site id is the first argument
siteid="$1"
# look up the site administrator name from the site id
siteadmin_email=`cat /home/virtual/$siteid/info/current/siteinfo |grep ^email |cut -d' ' -f3`
# send mail to the site admin
echo '<some email content>' |
mail -s 'your domain is being edited' $siteadmin_email
enableVirtDomain.sh

The enableVirtDomain.sh script hook runs custom commands placed in the script file. The script will be run whenever the specified domain is enabled.

Syntax: enableVirtDomain.sh site<n>

where <n> is the site identifier of the site being enabled. Information about the domain can be obtained by using the `sitelookup' API.

For example, you could use the script provided to notify Site Administrators whenever their sites are enabled. See Notifying Site Administrators when sites are modified for more information.

disableVirtDomain.sh

The disableVirtDomain.sh script runs custom commands placed in the script file. The script will be run whenever the specified domain is suspended.

Syntax: disableVirtDomain.sh site<n>

where <n> is the site identifier of the site being disabled. Information about the domain can be obtained by using the `sitelookup' API.

For example, you could use the script provided to notify Site Administrators whenever their sites are disabled. See Notifying Site Administrators when sites are modified for more information.

deleteVirtDomain.sh

The deleteVirtDomain.sh script hook runs custom commands placed in the script file. The script will be run whenever the specified domain is deleted.

Syntax: deleteVirtDomain.sh site<n>

where <n> is the site identifier of the site being deleted. Information about the domain can be obtained by using the `sitelookup' API.

Fo example, you could use the script provided to notify Site Administrators whenever their sites are deleted. See Notifying Site Administrators when sites are modified for more information.

Customizing subdomains

You can customize subdomains by using subdomain hooks. Subdomain hooks enable you to perform additional actions when a subdomain is added or deleted. For example, you can use subdomain hooks to notify the Site Administrator whenever a subdomain is added for any site. The subdomain scripts are not domain specific and apply to all subdomains of all corresponding root domains on Ensim Pro.

In order to do this, you must write the script hook and place it in the /etc/appliance/customization/ directory, set executable permissions for the script, and place the commands to be executed in the script file.

createSubDomain.sh

The createSubDomain.sh script hook can be used to run custom scripts whenever a subdomain is created.

Syntax: createSubdomain.sh

See Table 4-1 for the list of parameters that can be used with the script. These parameters are not specified on the command line. The script can be called with these parameters on standard input.

Notifying the Site Administrator when a subdomain is added

#!/bin/sh
# get all the parameters passed on standard input
export `cat /dev/stdin`
# get the root domain name for which this subdomain is being added.
parent_domain=$psi_domain
subdomain=$lsd_domain
subdomain_name=$lsd_name
# now email the appliance administrator about this
appliance_admin_email=`cat /etc/appliance/appliance.ini |grep adminemail |cut -d' ' -f3`
echo 'A subdomain $subdomain is being created for $parent_domain' |mail -s 'subdomain creation'
$appliance_admin_email

The following parameters can be passed to the script on the standard input.

Table 4-1. List of parameters for subdomain hooks
Parameter
What it indicates
Parent Site Info
psi_domain
The name of the root domain.
For example, myco.com
psi_version
The Ensim Pro version on which the root domain is hosted
For example, 3.7.0-13
psi_admin_user
The name of the Site Administrator
For example, myadmin
psi_admin
The Unix account information of the Site Administrator
For example, admin1
psi_passwd1
The encrypted password of the Site Administrator
For example, ***
psi_email
The email address of the Site Administrator
For example, example@example.com
psi_passwd2
The encrypted password of the Site Administrator
For example, ***
Parent IP Address Info
pip_ipaddrs
The IP address of the root domain
For example, 1.2.3.4
pip_namebased
The type of domain; indicates whether the root domain is name based.

Note: The value “1” indicates a name-based domain.

pip_version
The version of Ensim Pro on which the root domain is hosted.
For example, 3.7.0-13
pip_nbaddrs
The IP address of the root domain
For example, 1.2.3.4
Global Subdomain Info
gsd_wildcards
A boolean value indicating whether wildcard subdomains are enabled for the root domain.

Note: The default value is 0.

gsd_max
The maximum number of subdomains that can be created.
gsd_version
The Ensim Pro version on which the subdomain is hosted
gsd_enabled
A Boolean value indicating whether subdomains are enabled for the root domain.

Important: The value for this argument must be 1.

gsd_base
The base directory for subdomains created on the root domain.
For example, /var/www
Local Subdomain Info
lsd_cgi
A Boolean value indicating whether CGI service is enabled for the subdomain.
lsd_cgi_root
The CGI directory where CGI scripts for the subdomain are placed.
For example, /var/www/test2/cgi-bin
lsd_cgi_extensions
The script extensions permissible for CGI scripts
For example, cgi,pl
lsd_user_subdomain
A Boolean value indicating whether the subdomain is a user subdomain
lsd_owner
The owner of the subdomain
For example, myadmin
lsd_aliases
A Boolean value indicating whether aliases are enabled for the subdomain.
lsd_bind
A Boolean value indicating whether the subdomain has a DNS entry.
lsd_document_root
The document root of the subdomain.
For example, /var/test2
lsd_domain
The host name of the subdomain.
For example, example.example1.com
lsd_name
The lower-level subdomain name. For example, the subdomain name example in the host name example.example1.com

deleteSubDomain.sh

The deleteSubDomain.sh script can be used to run custom scripts whenever a subdomain is deleted.

Syntax: deleteSubdomain.sh

See Table 4-1 for the list of parameters that can be used with the script. These parameters are not specified on the command line. The script can be called with these parameters on standard input.

Additional executable files

When Ensim Pro creates the chroot environment, it makes the following executable Linux commands available to users who can then access the newly created domain using Telnet or SSH.

Table 4-2. Executable Linux commands 
/bin/awk
/bin/more
/usr/bin/find
/usr/bin/troff
/bin/bash
/bin/mv
/usr/bin/groff
/usr/bin/uncompress
/bin/cat
/bin/ping
/usr/bin/grotty
/usr/bin/whois
/bin/chmod
/bin/rm
/usr/bin/gtbl
/usr/bin/fwhois
/bin/chown
/bin/sed
/usr/bin/gzip
/usr/bin/makemap
/bin/cp
/bin/sh
/usr/bin/head
/usr/bin/newaliases
/bin/date
/bin/su
/usr/bin/id
/usr/bin/procmail
/bin/egrep
/bin/tar
/usr/bin/less
/usr/bin/vacation
/bin/false
/bin/touch
/usr/bin/man
/usr/bin/ftp
/bin/gawk
/bin/true
/usr/bin/passwd
/usr/bin/ncftp
/bin/grep
/bin/vi
/usr/bin/perl
/usr/bin/ncftpget
/bin/gzip
/bin/zcat
/usr/bin/python
/usr/bin/ncftpput
/bin/gunzip
/bin/dnsdomainname
/usr/bin/run-parts
/usr/bin/analog
/bin/ln
/bin/hostname
/usr/bin/tail
/usr/bin/nslookup
/bin/ls
/usr/bin
/usr/bin/tbl
 
/bin/mkdir
/usr/bin/compress
 
 

Customizing the administrator navigation bars

The Ensim Pro control panel has a navigation bar on the left side of each administrator’s page. You can customize this navigation bar to add links to other HTML pages or CGI scripts you have created. For example, you can add a navigation bar item that displays a page containing an administrator’s contact information, or an item that invokes a script you have created to write to a database.


Important icon

You can only customize the administrator navigation bar if the skin has been set to Classic. See Classic skin for more information on this skin.



Procedure icon

To customize an administrator navigation bar

  1. Move the HTML files or CGI scripts you have created into the following directories.
    • Store HTML files in /var/www/html/
    • Store CGI scripts in /var/www/cgi-bin/
  2. Use HTML to create a file for the administrator page you want to customize.
  3. This link file will point to the HTML file(s) or CGI script(s) you stored in the directories noted above. Name this link file as listed below, and place it in the directory /etc/appliance/customization.

    • For the Appliance Administrator navigation bar: /etc/appliance/customization/appliancemenu.dtml
    • For the Site Administrator navigation bar: /etc/appliance/customization/sitemenu.dtml
    • User Administrator navigation bar: /etc/appliance/customization/usermenu.dtml
    • To refer to your document in /var/www/html, use the placeholder https://<dtml-var hostname>/menu/<YOUR_DOCUMENT> in your dtml file where <YOUR_DOCUMENT> is the document path.

      To refer to a CGI script in /var/www/cgi-bin, use the placeholder https://<dtml-var hostname>/menu/cgi-bin/<YOUR_SCRIPT> where <YOUR_SCRIPT> is the path of your CGI script.

      See Example 1 for a sample code using these placeholders.

      The string “<dtml-var hostname>” will be replaced by the Ensim Pro server name and port number (19638) when the page is displayed on the browser.

  4. Restart Ensim Pro by logging on as the root user and typing the command,
    /etc/rc.d/init.d/webppliance restart.

Examples

The following section includes two examples of link pages.


Example icon

1

In this example, the customized navigation bar on a Site Administrator page has a link which displays support contact information. The link file is named sitemenu.dtml and stored in the directory /etc/appliance/customization.

Its contents are as follows:

<tr><td>

<a href=”https://<dtml-var hostname>/menu/contact.html”

  target=”main”

  class=”menu”>Support</a>

</td></tr>


Note icon

The contact.html page with the support contact information was created beforehand and stored in the /var/www/html/ directory.


The <dtml-var hostname> is a placeholder for the Ensim Pro server name. When the browser displays the customized file, this variable is replaced with the host name of the server on which Ensim Pro resides.

The target tag instructs the browser to display the contact information in the right frame of the Administrator page (that is, the content area) as opposed to the navigation bar area at the left.

The class tag instructs the browser to display the word Support in the navigation bar, using the same font as used for the other items. The browser inserts the new item into the navigation bar just above the Help option.

When the user clicks Support in the navigation bar, the content area on the right displays the contact information (that is, the file /var/www/html/contact.html).


Example icon

2

In this example, the link file invokes a Perl script for the Site Administrator page.

#!/usr/bin/perl

use strict;

use CGI::Cookie;

print "content-type: text/html\n\n\n";

my(%cookies);

my($id);

%cookies = fetch CGI::Cookie;
# fetch cookie

$id = $cookies{'ocw_username'}->value;

# remove quotes from beginning and end

$id =~ s/^\"//g;

$id =~ s/\"$//g;

print "<html><body bgcolor=\"#ffffff\">\n";

print "<form method=post action=\"submit_ticket.pl\">";

# print welcome message with username of site admin

print "Welcome to Acme Trouble Ticketing System, $id:\n";

print "<form method=post action=\"submit_ticket.pl\">";

print "<textarea name=\"description\" cols=50 rows=5>";

print "</textarea>\n";
# pass username to submit_ticket cgi as hidden value

print "<input type=\"hidden\" name=\"customer\" value=\"$id\">\n";

print "<p><input type=\"submit\">\n";

print "</form>\n";

print "</html></body>\n";

exit 0;

Customizing the Web site welcome pages

You can customize your Web site welcome pages in the following ways.

Inserting custom welcome pages

When you create a new Web site, Ensim Pro assigns a default welcome page (index.html) to it. To replace the default page with your own custom welcome page, replace the file index.html in the directory /etc/virtualhosting/templates/apache/var/www/html/ with your own index.html file.

Assigning custom home pages to users

When you create a new Web site, Ensim Pro assigns a default home page (index.html) for users on the site. This home page is located in the directory, /home/virtual/<domain name>/etc/skel/public_html/, where <domain name> is the domain name of the new Web site.

You can replace the default page with your own home page, replace the file index.html in this directory with your own index.html file.


Tip icon

The most efficient way to assign a custom home page to each user is to create a script that replaces the default file index.html in the directory /home/virtual/<domain_name>/etc/skel/public_html with your custom index.html file.


Inserting links to login screens

To make logging on quick and convenient for administrators, you can add a link from your custom welcome page to the login screens for both Site Administrators and User Administrators.

To insert a link to the Site Administrator login screen, add the following code to the custom welcome page in /etc/virtualhosting/templates/apache/var/www/html/index.html.

Access to your Site Administrator: <a href=”http://ENSIM_DOMAINNAME/admin/”>http://ENSIM_DOMAINNAME/admin/</a>

When you create a domain and install the custom welcome page, Ensim Pro replaces ENSIM_DOMAINNAME with the name of the domain.

To insert a link to the User Administrator login screen, add the following code to the custom welcome page in /etc/virtualhosting/templates/apache/var/www/html/index.html.

Access to your User Administrator: <a href=”http://ENSIM_DOMAINNAME/user/”>http://ENSIM_DOMAINNAME/user/</a>

When you create a domain and install the custom welcome page, Ensim Pro replaces ENSIM_DOMAINNAME with the name of the domain.

Replacing the Ensim logo with a custom logo

To brand Ensim Pro with your own logo, create a file named logo.gif and move it to the directory /etc/appliance/customization.


Procedure icon

To replace the Ensim logo with a custom logo:

  1. Size your custom logo to 73 x 46 pixels and save it as a .gif file called logo.gif.
  2. Using FTP, transfer the file logo.gif to the server.
  3. Use any Telnet or SSH client to access your server and log on as any user.
  4. Type su - to assume root user privileges.
  5. Use the move (mv) command to move the file logo.gif to the directory
    /etc/appliance/customization.
  6. Example:

    mv /home/<admin user>/logo.gif \

    /etc/appliance/customization/logo.gif

  7. Restart Ensim Pro by logging on as the root user and typing the command,
    /etc/rc.d/init.d/webppliance restart
  8. If you are viewing the Ensim Pro control panel in a browser window, force reload (refresh) the page contents to see the new logo.
    • In Internet Explorer press Ctrl-F5.
    • In Netscape Navigator press Shift and Reload at once.

Changing the message of the day (motd)

When users use Telnet to access the server, you can display a message on the terminal screen above the prompt. This message allows you to inform users of temporary system outages, changes that might occur in their Service Plans, or any other information of your choice.

You can customize the message of the day in one of two ways. You can create a separate message for each domain, or you can create a common message across all domains.

Creating a separate message for each domain


Procedure icon

To create a separate message for each domain

  1. Use any Telnet or SSH client to access your server and log on as any user.
  2. Type su - to assume root user privileges.
  3. Create the file /home/virtual/<domain_name>/etc/motd with the message of the day, where <domain_name> is the name of the domain for which you want the message of the day to be displayed.
  4. Change the ownership of the file, motd, to the Site Administrator and group using chown and then set the permissions to 0644. The Site Administrator cannot create or delete this file but can edit it. If you do not want the Site Administrator to change this file, set the ownership to root.

Creating a common message across all domains


Procedure icon

To create a common message across all domains:

  1. Use any Telnet or SSH client to access your server and log on as any user.
  2. Type su - to assume root user privileges.
  3. Use vi or any other editing utility to edit the message of the day in the file /etc/motd at the root level of the server on which Ensim Pro is installed.
  4. Save the changes to the file.
  5. Use the ln command to hard link the file /etc/motd individually to each domain.
  6. For example, to create a hard link from the Ensim Pro server to the domain mycompany.com enter the command,
    ln /etc/motd /home/virtual/mycompany.com/etc/motd

Customizing the online Help files


Important icon

This section applies to you only if you are an Ensim® ServerXchange® customer (that is, you have installed Ensim Pro on an Ensim ServerXchange-managed Linux server). If you are a storefront customer (that is, you have installed Ensim Pro on a regular Linux server), you can ignore this section.


You can customize the Ensim Pro online Help by substituting your own online Help files; however, you must know how to create an RPM package to complete the customization.

For information on creating RPM packages, access the Ensim ServerXchange 3.1 Server & Application Manager Online Help and refer to the topic “Creating applications”. You will find this topic in the Application Management book.

This section explains how to prepare an application so that it can be uploaded to ServerXchange 3.1; however, it does not provide information on creating RPMs. For information on creating RPMs, see http://www.rpm.org/RPM-HOWTO.

Customizing the online Help files consists of the following steps.

Step 1: Creating an RPM package with the customized online Help files

Step 2: Uploading the RPM package to ServerXchange

Step 3: Revising the Ensim Pro service suite to include the new RPM package

Step 1: Creating an RPM package with the customized online Help files

The online Help files are referenced by Ensim Pro using specific file names. The most convenient way to retain the correct file names is to directly edit the Help files.


Procedure icon

To directly edit the Help files

  1. Under the directory /etc/appliance/customization, create a directory called OnlineHelp; and under it, create four sub-directories: one for each level of administration - Appliance, Reseller, Site, and User.
  2. Copy the Help files from /usr/share/doc/webppliance-docs-3.5.0 to the directory that you just created.
  3. Edit the Help files.
  4. Edit the file /usr/lib/opcenter/fastcgi/extras/webppliance-docs to look in the following directories for the Help sets. Replace <lang> with the corresponding language ID, for example, en_US for English or de_DE for German.
    • Alias /docs/<lang>/appliance /etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/appliance
    • <Directory “/etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/appliance”>

      DirectoryIndex appliance_help.htm

      </Directory>

    • Alias /docs/<lang>/reseller /etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/reseller
    • <Directory “/etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/reseller”>

      DirectoryIndex reseller_help.htm

      </Directory>

    • Alias /docs/<lang>/site /etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/site
    • <Directory “/etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/site”>

      DirectoryIndex site_help.htm

      </Directory>

    • Alias /docs/<lang>/user /etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/user
    • <Directory “/etc/appliance/customization/OnlineHelp/<your help file directories>/<lang>/user”>

      DirectoryIndex user_help.htm

      </Directory>

  5. Test your Help files by restarting Ensim Pro, then clicking the Help icon in the control panel.
  6. Ensim Pro should load the files from the locations you specified in step 1. When you are satisfied with the Help files, create an RPM package containing the following:

    • Your Help files in /etc/appliance/customization/OnlineHelp/
    • The edited file /usr/lib/opcenter/fastcgi/extras/webppliance-docs
    • You can now upload the RPM package to ServerXchange.

Step 2: Uploading the RPM package to ServerXchange


Procedure icon

To upload the RPM package to ServerXchange:.

  1. Log on to ServerXchange.
  2. On the left navigation bar, click .
  3. Click the Applications tab.
  4. Under the Applications tab, click Register.
  5. On the Register page, click Upload Binary.
  6. To upload the application from your local workstation:

    1. Enter the name of the file or click Browse to locate the file.
    2. Click Upload.
    3. When the upload is complete, click Close.
    4. The application appears in the Archive list on the Register page, although you might need to refresh your browser, or reload the page in your browser, to see it.

  7. Click the Applications tab to reload the page.
  8. You can now revise the Ensim Pro service suite to include the new RPM package.

Step 3: Revising the Ensim Pro service suite to include the new RPM package


Procedure icon

To revise the Ensim Pro service suite to include the new RPM package:

  1. Log on to ServerXchange.
  2. On the left navigation bar, click .
  3. Click the Applications tab.
  4. Under the Applications tab, click Suites.
  5. In the Suites list, locate Ensim Control Panel and click (in the Action column).
  6. Under the application overview area, click Revise Suite.
  7. The Revise Application wizard opens.

Note icon

When using a wizard, avoid clicking the browser's Back button, because this might cause you to lose information you have entered on a form. To go back to a previous page, click Previous.


  1. Select the Package you want to revise by clicking the button in the Select column, then clicking Next.
  2. Select the version of the Package that will replace the existing Package by clicking Select column buttons for those Packages, then clicking Next.

Note icon

If this list is empty, there are no other versions of the Package available, and you cannot revise the application. Click Cancel to return to application information page.


  1. Review the summary page. Click Previous to make any changes, then click Next to return to the summary page.
  2. To complete the revision, click Finish.
  3. The application is revised, and the Info and Revision History forms are displayed. To upgrade existing installations to the revision, reinstall the application. The old version is replaced by the revision. All new installations use the revised application.


Important icon

If you upgrade Ensim Pro in the future, the upgrade will overwrite your custom Help files. Before you upgrade, save your Help files in a different directory; then revise the Ensim Pro service suite after the upgrade.


Customizing services

In order to customize the services you will find the custom.py file specific to each service, located under the folder, /usr/share/doc/webppliance-SERVICENAME-SERVICEVERSION/


Important icon

Do not modify the original copy of the custom.py file.


The customization can either be global or site-specific. The list of the services that can be customized is as follows:

Global customizations

Global customizations affect the way certain services (such as Apache) are configured for all sites on the Ensim Pro server. For example, in the case of Apache, you can customize the way the VirtualHost container is written.

Each service that can be globally customized has a file explaining its variables in the file,
/usr/share/doc/webppliance-<servicename>/custom.py.

To globally customize any service, you must copy the file /usr/share/doc/webppliance-<servicename>/custom.py into /usr/lib/ensim-python/site-packages/vh3/custom/<servicename>.py

For example, to globally modify the behavior of the Apache service on Ensim Pro, you must run the following command:

cp /usr/share/doc/webppliance-apache-3.5.0/custom.py /usr/lib/ensim-python/site-packages/vh3/custom/apache.py

Then, modify the file, /usr/lib/ensim-python/site-packages/vh3/custom/apache.py as required. The significance of each of the customizable variables is given in the custom.py file.

Global customizations are retained when you back up and subsequently restore the Ensim Pro server.


Procedure icon

To apply global customizations

  1. Copy /usr/share/doc/webppliance-<SERVICENAME>/custom.py as
    /usr/lib/ensim-python/site-packages/vh3/custom/<SERVICENAME>.py.
  2. In the <SERVICENAME> field enter the name of the service you want to customize.

    For example, to customize the anonftp service, copy /usr/share/doc/webppliance-anonftp/custom.py as /usr/lib/python2.1/site-packages/vh3/custom/anonftp.py.

  3. Modify the file <SERVICENAME>.py as per your requirements.
  4. Save the file.
  5. To restart Ensim Pro, type the command
    /etc/rc.d/init.d/webppliance restart.

Site-specific customizations

Site-specific customizations affect the way services (such as Apache) are configured for a particular site on the Ensim Pro server.

Each service that can be customized for a site has a file explaining its variables in the file,
/usr/share/doc/webppliance-<servicename>/custom.py.

To customize any service for a site, you must copy the file /usr/share/doc/webppliance-<servicename>/custom.py into /home/vitual/site<n>/info/custom/<servicename>.py, where <n> represents the unique site number.

For example, to modify the behavior of the Apache service for a site, you must run the following command:

cp /usr/share/doc/webppliance-apache-3.5.0/custom.py /home/vitual/site12/info/custom/apache.py

Then, modify the file, /home/vitual/site12/info/custom/apache.py, as required. The significance of each of the customizable variables is given in the custom.py file.


Procedure icon

To apply site-specific customizations

  1. Copy /usr/share/doc/webppliance-<SERVICENAME>/custom.py as
    /home/virtual/site<n>/info/custom/<SERVICENAME>.py
  2. where:

    n in site<n> stands for the site-specific number and <SERVICENAME> refers to the name of the service you want to customize.

    For example, to customize the anonftp service, copy /usr/share/doc/webppliance-anonftp/custom.py as /home/virtual/site1/info/custom/anonftp.py.

  3. Modify the file <SERVICENAME>.py as per your requirements.
  4. Save the file.
  5. To restart Ensim Pro, type the command
    /etc/rc.d/init.d/webppliance restart.

Changing the Appliance host name and IP address

Use netconf to change the host name and IP address, (which is included in the linuxconf rpm in the Fedora 1 distribution). Note that another utility netconfig is usually present on Fedora 1 servers. The netconfig utility allows you to set the IP address, but not the hostname.

After setting the new hostname and IP address, verify that the /etc/hosts file contains the new entry. Restart your server to complete the change.

Adding and removing virtual DNS servers for Reseller Administrators

Ensim Pro supports the addition and removal of virtual DNS for Reseller Administrators. In order to allow Reseller Administrators to satisfy the dual DNS server requirements of their customers, you must add the virtual DNS server.

Adding a virtual DNS server


Procedure icon

To add a virtual DNS server

  1. Note down the name and IP address of the new virtual DNS server. For example, ns1.reseller.com 1.2.3.4
  2. Access the server and log on as root user.
  3. To add an IP alias to the Appliance server, enter the command,
    #/sbin/applifconfig alias 1.2.3.4
  4. To get the IP address aliased each time you start Ensim Pro, add the appropriate lines to the end file rc.local, located at /etc/rc.d/.
  5. /sbin/applifconfig alias 1.2.3.4

    ...

    where 1.2.3.4 is your reseller’s DNS IP address.

  6. Modify the file options.conf.wp, located at /etc/bind/, and add the IP address to the
    listen-on option.
  7. Example:

    //This file stores the options statement maintained by Ensim

    options {

    directory “/var/named”;

    listen-on {127.0.0.1; 1.2.3.4;};<--add the IP address here

    };

  8. Add the line, ns1.reseller.com 1.2.3.4, to the file virtualDNS, located at /var/named/.
  9. To restart the name server, enter the command, #/etc/init.d/named restart
  10. Using the Appliance Administrator control panel, create zone record for reseller.com.

Note icon

While creating reseller.com make sure that ns1.reseller.com points to 1.2.3.4 and new NS records are added.


  1. To test the new virtual DNS server, run a query (dig/nslookup) on it.

Note icon

The newly added virtual DNS server will not be displayed in the virtual DNS page of the Appliance Administrator control panel.


Removing a virtual DNS server


Procedure icon

To remove a virtual DNS server

  1. Note down the host name and IP address of the virtual DNS server to be removed. For example: ns1.reseller.com 1.2.3.4
  2. Access the server and log on as root user.
  3. To remove an IP address bound to the server or network card, enter the following command.
  4. #/sbin/applifconfig delete 1.2.3.4

  5. Remove the following lines from the file rc.local, which is located at /etc/rc.d/.
  6. /sbin/applifconfig alias 1.2.3.4

    ...

    where 1.2.3.4 is your reseller’s DNS IP address.

  7. Remove the IP addresses from the file options.conf.wp.
  8. Example:

    //This file stores the options statement maintained by Ensim

    options {

    directory “/var/named”;

    listen-on {127.0.0.1; 1.2.3.4;}; //<--remove this IP address.

    };

  9. Remove the following line from the file virtualDNS located at /var/named/.
  10. ns1.reseller.com 1.2.3.4

  11. Through the Appliance Administrator control panel, modify the zone record for reseller.com.

Note icon

While modifying reseller.com make sure that ns1.reseller.com does not point to 1.2.3.4 and new NS records are set.


  1. To restart named, enter the following command.
  2. #/etc/rc.d/init.d/named restart

  3. To restart virtual hosting, enter the following commands.
  4. #/etc/rc.d/init.d/virtualhosting stop

    #/etc/rc.d/init.d/virtualhosting start

Passing additional environment variables to CGI programs

Apache's suexec cgi-wrapper has been modified so that it can be configured to pass additional environment variables apart from those considered "safe" at the time it is compiled.

In order to add additional variables to this list of "safe" variables, place the names of the additional environment variables in the file, /etc/suexec.env.ensim, one variable per line.


Important icon

To ensure security, this file must be owned by root, with only user read and write permissions enabled (indicated by 0600 UNIX permission).



Example icon

If you want to allow Apache to pass an environment variable named

MY_TRUSTED_ENV to a cgi program, place the following line in the file, /etc/suexec.env.ensim
MY_TRUSTED_ENV

Ensim Corporation
www.ensim.com

Contact Ensim
www.ensim.com/about/contact.html

TOCPREVNEXTINDEX