1)
Configuring the module
a. General
Settings: ( ensim.setup.php )
b. Crontab
Settings: ( ensim_cron.sh )
c. Copying the
files
2)
Copying the Files
3)
Crontab Configuration
4)
Setup the Module in HostAdmin
5)
Setup of Hosting Plans in HostAdmin
6)
Testing
If you are
reading this file, we can only assume you download and extracted the Ensim 3.1
Module for HA. That being said, let us lay out the requirements to finish
setting this module up. You will need:
a) A
server with Ensim Webppliance 3.1 Installed,
b) HostAdmin
v3.0 Installed.
c) Root
access on the Ensim machine, to create the crontab job.
The actions that can be automated
using HostAdmin with the Ensim Module:
-
Account Creation
-
IP Based Domain Creation
-
Virtual Domain Creation
-
Hosting Plan Update to Existing Domains
-
Suspension Of Existing Domains
-
Unsuspension of Existing Domains
-
Deletion of Existing Domains.
When you unzipped the Ensim Module download, it should have
created a directory containing this file and a license agreement file, as well
as a /provision/ directory.
In the
/provision/ directory, you will see the following files:
-
ensim.setup.php
-
provision_ensim_3.x.php
-
ensim_cron.sh
We will
need to change some of the configuration settings in ensim.setup.php. With a
text editor, open the "ensim.setup.php" file.
You need to
find the following lines for configuration and configure them as instructed.
define(ALLOWED_IP,
'127.0.0.1');
> Locate
this line and change '127.0.0.1' to the IP of the machine that HostAdmin is
installed on. Setting this variable limits access to the provisioning script to
that only IP address.
>
EXAMPLE: '207.44.147.144'
define(KEYCODE,
'test');
> Locate
this line and change 'test' to another password of your choice. This same
password will be entered into HostAdmin later, so write it down somewhere.
Setting this variable acts as further validation to prevent unauthorized access
to the provisioning script.
>
EXAMPLE: 'password-1’
define(BIN_PATH,
"/usr/local/bin/");
> This setting should
not need to be changed, unless for some reason your ensim commands are in
another directory. If they are not, do not change this setting.
define(JOB_PATH,”/home/virtual/<YOUR_SITE>/fst/var/www/html/wherever/");
> Locate this line and
change the path to wherever you will be copying these files after configuration
is complete. This has to be a web-accessible location, so that HostAdmin can post
the account/domain provisioning variables as needed. Write this down somewhere and make a note that it is the JOB PATH, because we will need it in little bit!
Also, as a consideration, this path will need to be writable by PHP, so It will
need CHMOD settings of 777. It should also be a path nobody will just stumble
across, it should be created for these files alone!
> EXAMPLE:
“/home/virtual/hostadmin.com/fst/var/www/html/hidden1/”
After
making these changes, close and save the file.
With a text editor, open the "ensim.cron.sh
" file. When this file has been configured, it will be set up as a crontab
job and will run all the provisioning task sent to it by the HostAdmin queue.
You will need to find the following lines in the file and
modify them.
> Locate
this line and change the path to the JOB PATH
from the from 1.a. This will be where the jobs_new file is written; it will
contain the commands to be sent to the PSA creation utilities.
>
Example: ““/home/virtual/hostadmin.com/fst/var/www/html/new/”
> This
will be where the completed jobs files are written, it will contain records of
all the commands that were sent to the PSA creation utilities. It can be the JOB PATH from 1.a, or another directory. This
directory will need to be writable by PHP, so CHMOD it to 777.
>
Example: ““/home/virtual/hostadmin.com/fst/var/www/html/old/”
After
making these changes, close and save the file.
Now we need to copy all the files in the provision directory
to the JOB PATH from steps 1.a and 1.b.
You can use and FTP program if they are being copied to a remote location, or
just using your server’s copy command if you are local to where the files are
going.
Be sure all
the following files get copied:
- ensim.setup.php
-
provision_ensim_3.x.php
-
ensim_cron.sh
Also, since PHP needs write
access to create the jobs_new file for the crontab job, make sure the directory
is set to CHMOD 777. You can do this with command line commands from
shell/telnet, or by FTP with most FTP programs.
This step explains how to setup HostAdmin so it can
communicate with the Ensim module.
Open your web browser and login to your HA3 admin area.
> Example: http://www.domain.com/hostadmin/admin/
Go to: Administration > Add Server
This will bring you to the “Server Details” form, where you
can configure your server details. An explanation of the required fields and
their usage are below:
Name:
> Usage: This will be the name used by
HostAdmin to reference this server.
You will be
able to select this server when adding/updating new hosting plans
in
HostAdmin.
> Example: Ensim
Server 1
> Required: Yes
Description:
> Usage: This is can be used to enter notes about this server,
only the admin can view this.
> Example: This
is our first Ensim Server
> Required: No
IP List:
> Usage: If you will be selling IP Based hosting plans on this
account, then you will need
to enter
your IP list here. HostAdmin will automatically maintain this list, removing
used IP
when new IP based domains are provisioned.
HostAdmin
uses this field so it knows the IP address of the IP based domain
when it emails the customer their account
details after provisioning.
Enter only
one IP per line, and leave no empty lines.
> Example: 127.0.0.1
127.0.0.2
127.0.0.3
> Required: Yes,
if you are selling IP based hosting.
Server Virtual IP:
> Usage: This will be the servers base IP
that it uses for virtual hosting accounts.
HostAdmin
uses this field so it knows the IP address of the virtual domain
when it emails the customer their account
details after provisioning.
> Example: 127.0.0.1
> Required: Yes
API Host Name:
> Usage: This will be the host name to
the JOB PATH were you copied the Ensim
Module in step 2.
All you
enter here is the hostname.
Assuming
you copied the module to http://www.domain.com/secret/
you would
enter
“domain.com” here.
> Example: domain.com
> Required: Yes
API Script Location:
> Usage: This will be the web-accessible script location of
the JOB PATH were you copied
the Ensim
Module in step 2. All you enter here is the hostname.
Assuming
you copied the module to http://www.domain.com/secret/
you would
enter “/secret/provision_ensim_3x.php”
here.
> Example: /secret/provision_ensim_3x.php
> Required: Yes
API Password:
> Usage: This needs to be the same value
as you defined in step 1.a.
> Example: password-1
> Required: Yes
Provisioning API:
> Usage: This associates this server with
a defined provisioning type, so HostAdmin will know
what actions the server is capable of, and which
ones must be done manually.
You must
select “Ensim 5.0” from the menu.
> Example: Ensim
3
> Required: Yes
Mode:
> Usage: Your options here are:
Provision Manually:
If you want
all the queue items sent to this server to be sent to the queue for manual
addition.
Test Mode:
All queue
items sent to this server will be automatically returned as “Complete” to
emulate a
successful transaction
Live (Full Automation)
All
queue items will be sent to the server for actual completion.
This is the
required selection if you want hostadmin to really do the provisioning.
> Example: Live
(Full Automation)
> Required: Yes
Debug:
> Usage: Selecting this box will echo the results returned
from the server.
We recommend you turn this on while in the testing stage,
then unselect it before your site goes live.
> Example: Checked
> Required: No
CP URL:
> Usage: This is where you enter the Ensim control panel URL
where your customers can
Login to the Ensim control panel
and view their account/domain details. This
URL will be included in the
email that is sent when provisioning is complete.
> Example: https://www.domain.com/
> Required: No,
but recommended!
MISC URL:
> Usage: This URL is included in the
email default email template sent to the customer
when their domain has been
provisioned. You can enter the URL to where your
customer service page, help
files, or other usage information for your hosting
is located.
> Example: http://webhost.com:19638/webhost/rollout/site
> Required: No,
but recommended!
Email Text:
> Usage: This optional field can be used
to send your customers specific details for this
server, in addition to the
standard email that is sent when a domain is
provisioned.
> Example: na
> Required: No
Now click the “submit” button to add your server to
HostAdmin.
In order to begin provisioning new domains, you must define
at least one hosting plan in HostAdmin that will be associated with server
record you created in the last step. This step will explain how to do so.
Open your web browser and login to your HA3 admin area.
> Example: http://www.domain.com/hostadmin/admin/
Go to: Administration > Add Hosting Plans
This will bring you to the “Hosting Plan Details” form,
where you can configure your new hosting plan details. An explanation of the
required fields and their usage are below:
> Usage: This will be the name of the
hosting plan displayed to your customers.
> Example: Standard
Plan
> Required: Yes
Description
> Usage: Description of the hosting plan
displayed to customers, HTML and PHP are ok.
> Example: Your hosting
plan information
> Required: Yes
Base Price
> Usage: This is the base price of the
hosting plan before any setup fees, if any. This will
also be the
price that is charged in a recurring basis if this is to be a recurring
charge.
> Example: 49.99
> Required: Yes
Setup Price
> Usage: This is the one-time setup fee
that will only be charged for this plan.
> Example: 14.99
> Required: No
Recurring Charge
> Usage: Check this box if this is to be
a recurring charge, or if you want this plan to expire after
a
predefined period of time.
> Example: Checked
> Required: No
Billing Frequency
> Usage: This defines how often the ‘base
price’ is to be re-billed for recurring charges, in days.
> Example: 30
(same as monthly)
> Required: Yes,
if recurring.
Billing Periods
> Usage: How many times the recurring
charge is to bill before this plan expires, if ever.
The plan to
expire after one billing period set the value to 1, if you want it
To expire after 12 billing
periods, set it to 12. If you want it to bill for infinity,
Set it to 9999
> Example: 36
> Required: Yes,
if recurring
Available to Shoppers
> Usage: Uncheck this if you want it to
be a special plan that your customers
do not have
access to. Then, it can only be setup from the admin area.
Also, your
can come back and uncheck it if you wish to discontinue the
Plan at a
later date.
> Example: Checked
> Required: Yes,
if you want it to display to your customers.
IP Based
> Usage: Check this if it is an IP based
plan, as apposed to a virtual hosting plan.
> Example: Checked
> Required: No
Provision On Server
>
Usage: From
the menu, select the server that this hosting plan is associated with.
When a
customer orders this plan, the provisioning will be sent to this
Server.
> Example: Select
the server you just set up in the previous step.
> Required: Yes
Corresponding Package
> Usage: This field is very important for
provisioning, you must enter the name of a
plan you
set up in the Ensim Admin area.
> Example: standard
> Required: Yes
Now click the “submit” button to add your new hosting plan
to HostAdmin.
Congratulations, you have finished the configurations!
You can now test your setup to see if you have everything configured correctly.
Open your web browser and login to your HA3 admin area.
> Example: http://www.domain.com/hostadmin/admin/
Go to: Domains > Add
Select an account from the menu, and then click select to continue.
In the hosting plan menu, select the plan you just added.
Enter any domain name (example: test.com )
Next, click the add button to continue.
You should see the debug info returned by the “ensim_provision_3x.php” script
on your server. If not, check that debug mode is turned on for the server you
added, and that the “API Host Name” and “API Script Location” in the server
details are both entered as instructed.
When you get a “TRUE” result from the server, the domain should be provisioned
after the cron job runs the next time.
If you get any error messages or are having trouble at this point, please post
your issues in the forum, or submit them to the dreamcost.com support team by
email support@dreamcost.com.