Host4Net Documentation v.102

Table of Contents

1. Introduction
2. Installation
3. How it works
3.1 How is developed
4. Operate with services
4.1 Create a new service type
4.2 Create a new service under service type
4.3 Service configuration
4.4 Service management
5. Add a new Client
5.1 Client's information data for invoicing
5.2 Add contracted services
5.3 Select payment method
5.4 Technical configuration setup
6. Client Management
7. Billing management

1. Introduction

Host4net is a Control Panel Management Solution dedicated for Web Hosting and ISP administration, with extended financial & commercial features, made to ease the process of administration in high density user environment. Nevertheless you should understand that for now this application is depending of Webmin. To use it you must install and use Webmin with all dependencies.

The application is developed on milestone system that will make the current documentation to change during the development process. We advise our clients to check for the new features that will be introduced in each version and from one milestone to another.

In MS1 introduces features that regard the close configuration of the ISP offer that includes both commercial and technical stuff and also the setup of new incoming clients with their home, email addresses, financial information.
Beside this, some general aspects of payment/billing and currencies will be included just to be able to start to use the module immediately.

2. Installation

Host4NET is written in Perl. Therefore you must have Perl 5 installed and functional.
However several Perl Modules are needed and must be installed manually or automatically.

Due to fast development of Webmin as well as the bug fix support, we recommend you to update your Webmin to the last version before installing Host4NET.

In order to install Host4NET go to Webmin Configuration in Webmin section. Click on the Webmin Modules and then you will see the form looking for the ftp server where lays the module's kit. Installation process take a few minutes and then you will find the module in the Others section.

Installation procedure is very simple:
- Install the module from webmin configuration section
- Execute the MySql database dump against a created database from /<your path to webmin>/host4net/sqlscripts/empty.sql
- From Module Configuration in Host4NET module setup the data base permissions to host4net data base.

Problems could occure if you use a non standard Webmin Theme or if you do not setup properly the DB access permissions. No other problems have been reported until now.

3. How it works

Host4NET is an easy to use Control Panel. Even if contains complex data for all the performed actions, each one is stored in sections. For example if you plan to customize your offer, you'll se three CGIs dealing with all financial and technical aspects.

Basically, all configurations must be started from service configuration and progressively operate in all three CGIs. Then you should configure the global financial settings of the application. This means that you must configure the VAT, the payment currency, payment methods and only after that you can proceed to add clients, email users and to configure accounts.

In other words all the configuration steps specified here are used to be attached to the new client profiles. You must take care with your financial data because it will affect all invoices and billing process and part of the user management.

Now let's move forward to see how you must properly configure this module.

3.1 How is developed

Host4NET is following an atomically model. It is very modular and highly scalable. Currently it has been reported to work properly on Fedora, RH9, Slackware, SuSE, MAC OSX, FreeBSD and SUN OS. For every sub module there are several configuration files that allow to integrate on the fly.

Every technical configuration interface has a configuration file that integrates on the fly in host4net and allow old clients to be upgraded in case on new module is installed.

Development of new sub modules is very easy and could use separate DB and can perform any task as long as it follows our integration model.

The current DB support is developed in Mysql. The access to DB is based on DAO (Direct Access Object), a solution that allows further development and portability on a different DB type (Postgres, Oracle, etc.).

For a better integration and flexibility, we have developed a function for exporting internal variables for each client by simply calling the Oder_ID. This function is used internally for cloning/replicating users over the cluster.

Host4NET is designed to interact with Webmin modules for service configuration and is not getting included in every configuration file on your OS (ex. Apache). This makes our application able to work on all Webmin supported OS.

4. Operate with services

This chapter will explain how you must configure your service types and subscribed services. You will understand how to configure in 4 steps the financial data that will be reflected in the billing process as well as the technical configuration for each service that will be applied to the new incoming clients.

4.1 Create a new service type

Service Type means any type of service you wish to provide to your clients.
To operate this option go to "Add New Service".
Use the first form and type any name you would like to identify that service by and then you also can add a comment that will reflect the meaning of the provided service.

To modify the service type, click on the edit button.
To delete service types, select and click on the delete button.

4.2 Create a new service under service type

Each new service must be attached to a service type. There is no other way.
To add a new service click on the main page on "Add New Service" and then look on the last form.

You must understand that here you will not add new clients or users. Do not make any confusion even if you see properties that usually belong to a user. The only thing you can do here is to configure the properties of a new service that will be attached to a new client. This system is not similar to any other similar product on the market, but provides extended scalability in managing new services and transparence in adding new clients.

The second concept you must understand is how permissions for Unix user and Webmin user works. First you should understand how Webmin ACLs works for Webmin Users. For this you should check the webmin documentation where customization process for ACL's is explained. Also I recommend you to read Jamie's book about Webmin.

Host4Net uses a Webmin user to clone its ACLs for the new client that will be created under any service you add. This means that every ACL you configure on the model user, will be applied for new client profiles. This concept will be optionally applied even for email users if you want to grant them any kind of access to the Webmin interface.

Therefore any configuration you setup here will be just stored in the database in order to be attached to newly added clients.

In order to extend the flexibility of your configuration, the clone users could store any data in ACLs. For this you could use our internal variables in order to create custom configuration for each package you offer. To do this, simply click on every network/system service attached to clone Webmin users and setup paths or permissions by using the following variables that are stored in DB for each client and Order ID:

From ADDSERVICE.CGI:

$SERVICE_TYPE_NAME
$SERVICE_NAME
$ADMIN_CLONE_USER - user that will be cloned as Webmin User (Master User)
$EMAIL_CLONE_USER - user that will be cloned for email accounts
$EMAIL_CLONE_GROUP - group that will be cloned for email accounts
$ADMIN_USER_UNIX_GROUP - UNIX (Master User) that will manage that account
$EMAIL_USER_UNIX_GROUP
$ADMIN_USER_HOME_PATH - home path for

From SERVICEMANAGEMENT.CGI:

$SERVICE_LAUNCH_DATE
$SERVICE_EXPIRY_DATE

From CLIENT.CGI:

$CLIENT_ID
$COMPANY_NAME
$COMPANY_COUNTRY
$COMPANY_EMAIL
$COMPANY_REGISTRATION_ID
$COMPANY_PAYMENT_METHOD
$PERSON_NAME
$PERSON_COUNTRY
$PERSON_EMAIL
$PERSON_SECURITY_ID

From CONTRACTED_SERVICES.CGI:

$ORDER_ID

From MAIN.CGI:

$DOMAIN_NAME

This data could be pop-up from DB by calling in the shell the geninfovars.pl script. This will return all this data for a specific Order ID. This script is locate in ./host4net/scripts .

Further aspects of this section are pretty easy to understand.


4.3 Service configuration

This section is made only for configuring the financial aspects of services and has impact only on billing process and suspension of unpaid invoices.

The listing process of added services is linked to service type. First time you open this page you'll see the first added service type listed on the top table drop down menu.
Select from here what services under service type you want to see and configure.

The tool tip that follows the mouse pointer displays the comments you have added under the above section and can not be modified in this section.

Two types of fees are now available:
Installation Fee - the tax your client pays for a new service installation
Periodic Fee - the monthly, weekly or yearly tax that clients pay for provided services.

Further fields are made to control the status of invoicing for each service.
Invoicing Period - specify here the period of time in days until the next invoice will be sent to your clients
Grace Period - how many days after invoicing will go until any penalty will be applied to your clients
Delay Penalty - specify the penalty percentage applied for unpaid invoices after the grace period expires.
Notify by Email - automatically notify by email your clients that this account will be soon disabled
Disable Account - how many days after the grace period will take until a client account will be disabled.

After you configure all this fields, make sure you have checked the modified services and then choose from the drop down menu on the bottom of the table
the function "Update checked services" then click the Go button.

4.4 Service management

Service management is the last section where you can configure your services. Here you are able to display configured services, delete them or modify the properties defined in "Add New Service" section.

Besides in this section you must validate a service by specifying the date when a service will become available on the market and the date when the service will expire. In other words this is the setup place for the life time of your services.
This concept, as far as we know it has not been yet implement in other commercial applications. Also this method will allow you to create promotional services. Please note that this data will not be attached in any way to your old clients or new clients.

When the service expires you will not be able to add a new client under it. The only way it would be to modify the expiry date or to create a new service (recommended).
We advise you to setup up the name of your services accordingly to eliminate any confusion or in the system that might appear during the time.

After you configure the time period select the modified services and select "Update checked services" from the table bottom in the drop down menu and then click on Go button.

5. Add a new Client

This the point you start to add your clients and to attach the configured services you added in the upper sections.

In four steps you will configure your client information for invoicing and contact, select and configure the payment method, add or modify client's contracted services and finally to setup technical settings.

5.1 Client's information data for invoicing

This form is pretty understandable, but you must understand how the system will submit data and will enable controls.

First let's clearify few terms used here:
Company Registration ID - this is the registration code of the client's company. This will be used in invoicing
VAT ID - this is the VAT code of each Europen company. This is only working for EU Community Members.
Client ID - this will be automatically generated
Security ID - this is the security number of Contact Person. In USA is the SSN in other countries could be found on ID Card.

After introducing all data about your client click on ADD button. The submit process will automatically generate a Client ID and will enable the Configure button from "Select Payment Method" and the link to Contracted Services.
After reload notice that the generated Client ID appear on buttom of form and
the ADD button has been transformed in UPDATE.

5.2 Add contracted services

This part looks like a shopping cart. Just add contracted services, insert the quantity of contracted services and click ADD. Please notice that bellow, this service will be displayed read-only and the only thing you can modify will be the quantity. Also if you will try to add again the same service as one allready contracted only the quantity will change.

After adding the first service in the list of contracted services, by pressing on Details button, a pop-up window will open showing all Order IDs and a Config button on every row used for technical configuration. In this pop-up you can click on every checkbox and select which Order ID to be deleted.

This system was designed to be able to handle further reseller option that will be implemented in Host4NET.

5.3 Select payment method

TO DO in MS2

5.4 Technical configuration setup

The modular solution implemented for technical configuration makes Host4NET powerful software. This solution consists in an on-the-fly integration method developed in the core of Host4NET which allows every new technical configuration module for network services or system services (ex. Apache, Quota) to be added easily and make it operational immediately.

Once enabled you will be able to add it to your new or old hosting packages or other services you sell. Also old clients, who contracted that package, will have the new network service enabled.

In order to technically configure an Order ID, first you must add it to the list of contracted services and then to press the Details button and choose from the pop-up window an Order ID you intend to configure. Then Host4NET will read the IDs of each network or system service attached to the package linked to Order ID
and will display the main configuration interface and a drop down menu with all attached services. From here you can select a configuration interface for each service.

In the header of the form you will see the Order ID, list of attached services, and the status of the current interface.

Main Configuration form is the first interface that is included by default and has the ID 0, which means it cannot be deleted or disabled. Here you will have to create the Webmin user (called Master User) and the Unix user. There could be two users: one for Webmin control and one for ftp access or something similar.
We recommend to do not assign this user to use email or any other network service. Use/Create Master User only to give access to your client and to let him to administrate his own services.
Also do not forget to use our internal variables described here at chapter 4. This is your way toward a flexible configuration and customization. By using variables like $COMANY_NAME you will be able to create unique users for each Order ID in a unique format (ex. user.$COMPANY_NAME). The password can be generated in the same way.

How do you replace these variables with the real data?? There is no need to do such thing. Host4NET is asking for the clone user and you have specified and attached to the current package and is here, in Main Configuration listed and preloaded from DB. After choosing the server on which you want to create the account and other services, then by pressing the update button, the internal clone function will replace all variables from this form and from all ACLs attached to the clone user. Thus you can fully customize hundreds of clone users and groups and create special configurations for each separate package or service you want to offer.

To customize the user formats available in the drop down list, you can manually change the text, variables and order by simply editing the file from /<your webmin path>/host4net/techconfig/main/template .

The structure and format of the Main Configuration as well the directory three and techconf.info, is recommended to all those who want to develop new technical configuration sub modules. Remember to increment the order ID or you will get in serious troubles and never change the IDs of other interfaces!!!.

Further explanations will be added to this section during the introduction of new sub modules for other network services.

6. Client Management

TO DO

7. Billing Management

TO DO in MS2