MiniPortal Tutorial

Topics:

• Introduction
• Home Page
• MiniPortal Directory Layout
• Multiple Page Web Site (with simple links)
• Multiple Page Web Site (with frames)
• Dynamic Pages
• Perl Script: Time-of-Day
• Perl Script: CGI Forms
• Web Server Log Files
• Setting Up a Subdomain
• MiniPortal Administrator
• Using FTP to Publish
• Setting Up a Domain
• Perl Application: WWW to Email Gateway
• High Performance Perl with mod_perl
• MiniPortal Plug-ins
• Explore Further

Introduction

The MiniPortal Tutorial walks you through the process of creating and hosting a web site using MiniPortal. We assume that you already have (or will be creating) your own site, so only basic examples are used for site content. The emphasis is on getting the site up and running, setting up a trial subdomain and domain names, site administration, publishing, and creating dynamic content (with scripts).

In the first part of the Tutorial, we will access MiniPortal directly, as 'http://127.0.0.1/'. This uses the local or 'loopback' IP address of the computer, and avoids all of the messy issues with Domains and DNS servers. For most computers 'localhost' can be substituted for '127.0.0.1' but in some cases that does not work. So, we will use the numbers here (if you have any problem using 'http://127.0.0.1' check that your browser is not setup to use a proxy server).

Once we have a few basic pages of content in place, we will setup a subdomain so the site can be accessed from the internet. Although a domain name can be used instead, a subdomain is actually faster and easier to setup, and can be replaced by a domain name later.

Next, we will show how to use the MiniPortal Administrator (http://127.0.0.1/admin) to configure and check the status of the web server.

Then, we will describe how to setup a live Domain with DNS support.

We will also explore some more advanced scripting issues with Perl and PHP.

You may find it easier to use the Tutorial by opening several browser windows: one for the Tutorial, one to access files given in the Tutorial, and one to access the MiniPortal Administrator.

Now, if you have not already done so, run MiniPortal (by double-clicking the MiniPortal desktop icon) and let's get started...

Make sure the web server is running, as follows:

• right-click the small MiniPortal Manager '!' icon in the lower right of the screen
• select Manage Servers
• use the Start button to run the web server

When you first start the web server, a browser window will automatically be opened to a setup page. You can ignore this for now as we will be covering the setup process in detail below. At the moment, we focus on creating some basic content.

Home Page

The first example shows how to make a very simple homepage:

There are two things to note about this page:

• the contents of the page (what gets displayed), and
• how the page is accessed on the web server.

Page Contents and Display

If you know HTML, this page is completely trivial. If you do not know HTML, the important information is that this is an 'html' page and the content in the 'body' section is what gets displayed (by a web browser) when the page is accessed on the web server. Also note that this is a 'static' page; the contents of the file are sent to the web browser exactly as is. Later, we will see how 'dynamic' pages can be made to display information 'on-the-fly'.

Page Access on the Web Server

The name of the page is 'index.html'. This name was not chosen at random, but is the name of the default page accessed when only the directory name is used. To see this, copy the file whose name is given in the box above to your MiniPortal default document directory (C:\Program Files\InstantServers\MiniPortal\Apache\htdocs) and then access it in your browser as:
http://127.0.0.1/
or as
http://127.0.0.1/index.html

You can see that these URLs produce the same page.

Now, about that 'default document directory'. Let's take a step back and look at the MiniPortal directory structure to see where different types of files are located.

MiniPortal Directory Layout

This is the basic MiniPortal directory structure. We've left out some of the less important sub-directories so as not to confuse the picture (which is confusing enough).

The MiniPortal directory is located under the pathname used to install MiniPortal. The default pathname for this directory is: "C:\Program Files\InstantServers\MiniPortal".

Directly below MiniPortal are the following directories and files:

• Apache (the web server, web site documents, etc.)
• bin (FTP and Dynamic IP servers, support .dlls)
• Dnsclient (MiniPortal dynamic DNS configuration information)
• ftpsvr (MiniPortal FTP server configuration)
• mplog.txt (MiniPortal general log file)
• Perl (Perl script interpreter directory)

We'll focus mainly on the Apache directory.

The homepage we just created was copied to 'Apache\htdocs\index.html' to appear as the default homepage using the default document directory. In other words, the default document directory is: 'Apache/htdocs'. That directory can be changed with the MiniPortal Administrator.

We will come back to this directory structure later, but first, let's make a slightly more complicated web site and see how the web server handles multiple pages.

Multiple Page Web Site (with simple links)

As soon as more than one page is used on a web site, navigating between the pages becomes an issue. Here is a simple way to navigate between two pages, 'pageone.html' and 'pagetwo.html': the first page has a link to the second page, and the second page has a link to the first page.

Again, copy these files into the default document directory, and then access 'http://127.0.0.1/pageone.html'. Click the link to see the other page. Click again to get back to the original page.

There is no limit to the number of pages that can be connected this way, but you will find that adding pages and keeping track of the site structure gets tedious very quickly. So, the next step is to use a still simple, but more powerful scheme: navigation with frames.

Multiple Page Web Site (with frames)

The following files used to make the site that uses frames. The first file, 'frame.html', is a container for the frames themselves: it sets up the size of each frame and refers to the files that are initially displayed in each frame. It also produces a message if the user have a very old browser that does not display frames.

The second page, 'nav.html', is the 'navigation bar'. It contains links to other pages, which are displayed in the frame on the right-hand side of the page, which is identified by the frame name 'Main'. The navigation bar appears on the left-hand side of 'index.html'.

The third and fourth pages, 'fp1.html' and 'fp2.html' have actual content.

These files can be named whatever you want but note that the container page must include the source file name (src) and textual name (name) of both the navigation bar and the initial content frames. The source file name specifies the file to place within the frame, and the textual name specifies the particular frame to use within the frameset.

Copy these files into the default document directory, and then access 'http://127.0.0.1/frame.html'. Click the links in the navigation frame to see the content pages.

While frames are a convenient way to organize a site, they have some problems and limitations which make them less used than you might think. Many search engines, for example, have problems with frames so to get maximum exposure for your site, you might want to avoid frames. Fortunately, there are good graphics tools available for web site design (which are beyond the scope of this Tutorial) that will allow you to easily create navigation structures that look like frames but are not frames. The tools will take care of the messy stuff for you.

Now that you have an idea of what it takes to create some simple static HTML pages, let us look at generating content on the fly with some examples of dynamic page creation.

Dynamic Pages

There are many pages which have variable or dynamic content that cannot be represented by a simple .html file. Examples range from simply displaying the time of day to personalizing page content on a per-user basis.

A variety of methods have sprung up for creating dynamic pages, most based upon 'scripting' methods. Scripting has become popular because of the ease of writing scripts (compared to writing programs in languages such as C++). Although many scripts are executed by a web server ('server-side' scripts), some scripts can be run by the web browser ('client-side' scripts), and still others can be run on either the server or the client-side.

Some server-side scripting methods are: PHP, Perl, Java (servelets, JSPs), VBScript. Client-side scripting methods include JavaScript, Java, and VBScript.

Perl Script: Time-of-Day

Since MiniPortal contains a web server, we will focus on server-side scripting. Our first example is a simple Perl script that displays the time of day:

Although this is a very basic script, a few words about how it is run under the web server are in order. Perl uses CGI (Common Gateway Interface) to communicate with the web server. CGI requires that the web server knows to execute the script (as compared to just display its contents like a .html file), and that the web server uses the right script interpreter, Perl, to execute the script.

Script files are most easily specified by placing them into a common script directory. The 'MiniPortal\Apache\cgi-bin' directory is used to contain scripts. So, this script must first be copied to 'MiniPortal\Apache\cgi-bin' and then accessed as: http://127.0.0.1/cgi-bin/tod.pl

The web server must also be instructed to use Perl to run the script. The CGI convention for doing this is to specify the full pathname of the script interpreter on the first line of the script, following the '#!" (also known as 'shebang') characters. In this example, the Perl interpreter is found by searching the MiniPortal default directory paths (which include the Perl directories). If the shebang line is not present, an Internal Server Error will be displayed, and the web server error log (see Web Server Log Files) will indicate:

• couldn't spawn child process: c:/program files/instantservers/miniportal/apache/cgi-bin/tod.pl

This is the single most common error that occurs when running scripts for the first time.

Lastly, what does this script do? First, the script outputs the content type to the browser. This tells the browser how to display the data that will be sent. In this case, a plain text format is used (not HTML). Then, the script accesses a built-in function to find the time-of-day, and displays the result as hour, minute, and second.

Perl Script: CGI Forms

Here is another example of using Perl as a CGI script. This time, a simple form is displayed, and the text entered by a user is then displayed. Since some knowledge of Perl is required to understand this example, we refer you to the Perl web site for further information.

Copy the file to the cgi-bin directory and access it as 'http://127.0.0.1/cgi-bin/form.pl'.

This example uses the Perl CGI module (which knows about the web server CGI) to help in managing the form. When the form is accessed for the first time, the 'Type some text' string and a text box are displayed. When you enter text and hit the Enter key or the 'Go' button, the text is displayed instead of the form.

Later on we will look at a full Perl-based web application: a WWW to email gateway. But now that we have created some basic content, it is time to look at a really useful feature of the web server: Log files.

Web Server Log Files

During the development of CGI scripts (or even .html files), you are bound to encounter web server errors. There are a variety of ways to find and fix errors, but the best place to start is usually the web server log files.

The 'MiniPortal\Apache\logs' directory contains two log files: access.log and error.log. The access log lists all requests sent to the web server. The error log lists errors encountered processing requests.

Access Log

A typical access.log entry looks like this:

127.0.0.1 - - [04/Feb/2002:17:15:47 -0800] "GET / HTTP/1.0" 200 12071

The access log fields for this entry are shown in the following table.

This format is known as CLF (Common Log Format) and is the default log format setting for MiniPortal. It can be changed to include additional information with the MiniPortal Administrator (see Web Site Traffic Statistics).

The Remote Host is the IP address of the client. For some IPs, it is possible to find the domain name matching the IP, but since it takes a significant amount of time to do this reverse lookup, it is not done during logging. The MiniPortal Statistics can do this lookup under Administrator command.

The Remote Identity field is not used.

The Remote User identifies the user if a login was processed. A login is required, for example, to use the MiniPortal Administrator from a remote machine, or to access a web site directory that has been protected.

The Time includes the date and time in the local timezone, and is enclosed in brackets.

The Request line is the first line of the HTTP request sent from the client, and is enclosed in quotes.

The Status code is the HTTP code sent back to the client after processing the request. The '200' code means 'OK'.

The Bytes sent is the number of bytes returned to the client, but does not include any HTTP headers.

Error Log

Two error log entries are produced when the 'shebang' line is deleted from the tod.pl CGI script:

[Mon Apr 01 12:26:21 2002] [error] [client 127.0.0.1] c:/program files/instantservers/miniportal/apache/cgi-bin/tod.pl is not executable; ensure interpreted scripts have "#!" first line

[Mon Apr 01 12:26:21 2002] [error] [client 127.0.0.1] couldn't spawn child process: c:/program files/instantservers/miniportal/apache/cgi-bin/tod.pl

The fields displayed are the time, severity of the error (warning, error, etc.), client IP address, and a detailed error string.

From these error messages, we can determine that the source of the error was indeed a missing 'shebang' line in the script file 'tod.pl'.

Setting Up a Domain (using a Trial Subdomain Name)

Now that we have both .html files and CGI scripts in place, let's access them from the internet.

In order to easily access the web server from the internet, it is necessary to have a Registered domain (or subdomain) name. We will first use a subdomain name because it is easier and faster to setup than a domain name. This is true even if you already own one or more domain names because the DNS information will need to be changed; the trial subdomain name setup will take care of that for us. A subsequent section will describe how to use an actual domain name instead of a subdomain name.

Ideally, all you need to do to setup a subdomain name is to choose it, enter subdomain account information, and configure the subdomain into MiniPortal. However, depending upon your network configuration and ISP, there may be a few other steps required to get a subdomain working. Let's go through an example with the following steps:

• Test the Server for Internet Access
• Choose a Subdomain Name
• Enter Account Information
• Select MiniPortal Configuration Information
• Configure MiniPortal
• Access Web Site using Subdomain Name

1. Test the Server for Internet Access

It turns out that the biggest problem in using a subdomain is in getting internet access to the web server machine. There are a number of ways that access can be blocked:

• Router: connects one or more computers to the internet [but hides their IPs]. Also, sometimes blocks access to subdomain names from machines on the local area network (LAN).
• Firewall Software: protects computers from malicious attack [but blocks ports]
• ISP Proxy Servers: speeds up internet browsing [but partially hides port 80]
• ISP Port Blocking: reduces traffic due to virus-infected web servers [but blocks ports, usually port 80]
• Mis-configured Internal Network: default network setup may use valid internet IP addresses instead of 'private' IPs [this confuses the MiniPortal dynamic DNS client]
• ISP Network Drivers: makes broadband service configuration easy [but confuses the MiniPortal dynamic DNS client]

The MiniPortal Basic Access Test will help to identify these and offer solutions. Run it now. If the test succeeds, proceed to step 2. If a problem is found, follow the information reported by the test to find and fix the source of the problem.

If you cannot get the Basic Access Test to pass at all, Contact Technical Support.

2. Choose a Subdomain Name

The subdomain name is based on an existing and Registered internet domain name: instantws.com. You can choose any valid prefix to that name which is not already taken (e.g. choosing 'test' would try to setup 'test.instantws.com').

To begin, Create a Subdomain Account then follow the instructions for choosing a subdomain name.

3. Enter Account Information

As part of the subdomain name registration process, a subdomain account is setup. The account contains a user name, password, and the subdomain name. Enter this information and save it.

4. Select MiniPortal Configuration Information

Now that the subdomain has been setup, MiniPortal must be configured to use it. The 'Configure MiniPortal' navigation link should be selected to check the configuration information.

If you are using a Router of any kind, you should select a 'Heartbeat' period, and click 'Set Option'. In many cases, IP addresses do not change very frequently (e.g. when you reboot), so 120 minutes should be fine. If you later have problems accessing your subdomain (due to changes in the IP address), you can select a shorter period (down to every 5 minutes), and update the MiniPortal configuration.

If you have a static (or fixed) IP address, you should enter it in the 'Static IP' boxes and 'Set Option'.

If you are running MiniPortal on a port other than 80 (default), you should enter this port number in 'Alternate Port' and click 'Set Option'.

Your configuration options should now all appear at the top of the page. If not, repeat the steps above, making sure to use the 'Set Option' button for each option chosen.

5. Configure MiniPortal

Click the 'Save Configuration' button.

This will activate a script on your system (using your local IP address), passing the subdomain configuration information. It will configure MiniPortal to use your subdomain name (although you can still access locally with 'http://127.0.0.1').

6. Access Web Site using Subdomain Name

Normally, it takes a few minutes for the subdomain registration to take effect across the internet.

In the meantime, exit and re-run MiniPortal. This ensures that MiniPortal processes the subdomain configuration information (which it will do when it is re-run).

Now try accessing your new subdomain using a browser.

If this does not work and you are behind a router, your router may be preventing you from going 'out' to the internet and then back 'in' to you local area network. In this case, you may need to use your IP address (shown by rolling the mouse over the '!' icon) as your subdomain name, or use a machine not connected to your internal network to access your subdomain.

You can also run the MiniPortal Basic Access Test with Subdomain Name to make sure that the subdomain was properly setup.

MiniPortal Administrator

Now that you have used MiniPortal to setup and host a web site, this is a good time to check out some of the Administration capabilities of the system.

First, access the MiniPortal administrator (on the machine running MiniPortal) using: http://127.0.0.1/admin/. Click the 'Login' link. No password is required when accessing the Administrator from the server machine through the local '127.0.0.1' IP address.

The MiniPortal servers and your subdomain name should be displayed on the initial status page along with some information about the server machine and your network configuration.

The 'Web Server' link will display more details about the web server configuration.

Now, let's look at some of the other capabilities of the MiniPortal Administrator.

Web Server: Configuration: Accounts - Administrator

To administer MiniPortal remotely, you will need an administration account. Click the 'Accounts' link to set one up. Click the 'New' button to add an account. Since we are setting up an administration account (which applies to all domains), enter a user name and select Domain 'ALL'. Enter a password, and re-type it to make sure of spelling. Select the 'Web Account Type' of 'Admin'. Ignore the 'FPSE Account Type' for now. Then select the 'FTP Account Type' of 'Author'. You do not need to edit any other fields. Click 'Save'.

Click the 'View' button next to 'Domain' to see your new administration account.

You can add as many administration accounts as you like. Note that these will always apply to all domains.

Accounts - Visitors ('Other')

You can also add accounts for visitors. For example, when you protect a directory (see Authenticated Access), you will normally create one or more accounts with 'Web Account Type' of 'Other' and 'FTP Account Type' of 'None'. A visitor will login using one of these accounts to view a protected directory.

To create a visitor account, click the 'Accounts' link. Click 'New'. Enter a user name, a domain, and a password, re-typing the password to make sure of spelling. Select the 'Web Account Type' of 'Other'. You do not need to edit any other fields. Click 'Save'.

Then access the protected directory to see the login box.

Authenticated Access

If you would like to restrict access to part (or all) of your web site, you can use the 'Directory Authentication' feature of MiniPortal Administrator. Enabling Authentication requires that a visitor login in order to access the contents of a 'protected' directory.

To protect access to a directory, open the 'Web Server' folder, 'Configuration' sub-folder and click 'Directory Authentication'. A list of directories for your domain(s) will appear, including '.' , which is the directory containing the contents of the entire web site (except the script files which are stored separately in 'cgi-bin'). Select the checkboxes for the directories you wish to protect (or '.' if you want to protect the entire site) and click 'Save'. When you go to access any protected directory, you will be prompted for a user name and password. Any user defined for this domain (or for domain 'ALL') can be used. Note that Authentication also applies to the domain 'localhost', which is only accessible from the server machine, so be careful if you protect its directories.

Custom Error Handling

There are a set of standard error numbers and messages displayed when the web server encounters an error. You can customize these by supplying your own message text, or you can re-direct the user to a URL. Error handling can be done globally (for all domains), or on a domain by domain basis.

Open the 'Web Server' folder, 'Configuration' sub-folder and click 'ErrorDocument'. Under the 'Global Settings' heading, select number '404'. Enter:

"oops...cannot find that file!

Be sure to include the leading '"' character (it tells the web server that the text is a message and not a URL). Click 'Save'.

Now, access a non-existent URL: http://127.0.0.1/foobar.html

The message you previously entered is displayed instead of normal error message. To restore the default behaviour, just click the 'Delete' button next to the '404' under the 'Global Settings' heading.

If you want to re-direct the user to a URL when an error is encountered, just enter the URL instead of the text message. Relative URLs (i.e. URLs in the same domain name) begin with a '/' and absolute URLs (using any domain name) begin with 'http'.

FrontPage 2000 Server Extensions

Users of Microsoft FrontPage may wish to add the FrontPage Server Extensions to a domain. Although not every feature of the FrontPage Extensions is supported, MiniPortal will allow you to publish your web site from FrontPage, add hit counters, discussion groups, setup mail addresses, and use many other FrontPage-specific items.

Only the FrontPage 2000 Server Extensions are supported, but these are compatible with FrontPage 98/2000/2002.

To use the FrontPage 2000 Server Extensions, you must first install them on your server machine. You may find the Extensions on your operating system, Office 2000, or FrontPage 2000 CD, or you may download them from the Microsoft web site. Once you have the Extensions installed, you must configure MiniPortal to use them for your domain .

Open the 'Web Server' folder, 'Configuration' sub-folder, and click 'Domains'. Select your domain name and click 'Edit' (Note: you will already be looking at your domain if you are running MiniPortal SOHO). Check the FrontPage Server Extended Web 'Enabled' box and click 'Save'.

To publish from FrontPage, must add an Account with FrontPage Authoring permissions. If you wish to add a new account for this, click 'Accounts', and 'New'. Enter the user information, and check the 'FPSE Account Type' of 'Author' and click 'Save'. You can now publish from FrontPage to your domain using its URL (i.e. http://your-domain.com).

If you have any problems with the Server Extensions, run the diagnostic test under the 'Diagnostics' link, or see the MiniPortal FAQ.

Multiple Domains using Trial Subdomain Name (MiniPortal Standard Edition)

If you want to host multiple web sites but do not yet have multiple domain names (or have not configured MiniPortal to use them), you can try this out by basing new 'domain' names on your subdomain name. For example, if your subdomain is named 'test.instantws.com', you can create 'one.test.instantws.com' and 'two.test.instantws.com'.

Each domain can have its own web site; its own document root, log files, etc.

Open the 'Web Server' folder, 'Configuration' sub-folder, and click 'Domains'. Then, click 'New'. Enter the new 'domain' name (e.g. one.test.instantws.com) and document directory. Make sure that the document directory is not contained within an existing document directory (e.g. if 'Apache\htdocs' is used by your original subdomain name, use 'Apache\one' for this domain). Click 'Save'.

You now need to add some content files to the document directory of this domain. You can copy one of the example files for this purpose. Then you should be able to access it immediately (e.g. http://one.test.instantws.com).

Web Site Traffic Statistics

Although it is a little early to be expecting hits on your web site, MiniPortal Administrator can display site activity in several graphical formats.

In the 'Web Server' folder and click 'Statistics'. The domain (or subdomain) for which statistics will be displayed is shown, and should be your subdomain name. Statistics can be grouped in various ways, but for now, just click 'Activity' to view the traffic for today. A bar graph is displayed showing 3 types of 'hits' on your web site. 'Sessions' indicates hits from unique IP addresses. This is probably 1 since you are the only visitor to the site so far. 'Page Hits' shows accesses to the underlying pages on your web site, and 'URL Hits' shows accesses to the actual URLs on your web site, including .jpg and .gif graphics files.

On the statistics page, 'Sessions' is the best indicator of unique site visitors, and 'Page Hits' is the best indicator of site activity. 'Page Hits' divided by 'Sessions' indicates the average number of pages viewed by a visitor.

You can select other time periods over which to display the site activity by changing the 'Report Cycle/Period' values. The 'Cycle' groups (day, week, month, and year) specify the type of graph to display (daily, weekly, monthly, or yearly). The 'Period' (exactly one cycle, or multiple cycles) controls the time frame over which data is analyzed. By choosing a Cycle of 'Weekly' and a date Period of, say, 2 weeks, you can see the site hits displayed by day-of-the-week for the 2 week period. By setting the 'Report Format', you can also control whether the values displayed are the Averages for 1 Cycle, or the Totals for all Cycles combined.

In addition to site activity, statistics are kept for errors and referring pages, and the domains' from which visitors originated may be determined.

Click the 'Error' button to see what errors, if any, have occurred over the time period currently selected. For the most common error codes, a count is kept of the number of times each error code has appeared. The URL of each page accessed that resulted in an error is also kept along with the number of times that error occurred.

The 'Referrer' and 'Visitor' buttons require additional log information to be recorded, indicating the URL previously viewed by a visitor. To change the log information recorded, open the 'Web Server' folder, and 'Configuration' sub-folder and select 'Statistics' . Choose 'Referrer' for your domain. then hit 'Submit'. Now you can return to the Statistics viewing link and click 'Referrer' or 'Visitor' to display additional information about visitors to your site. 'Referrer' shows the URL of the previous page accessed (which may be a page on your site), and 'Visitor' shows the domain name corresponding to the IP address of the visitor. Note that the domain name information may not be very specific since visitors can be on ISP dial-up lines, located behind firewalls or proxy servers, or coming from a variety of sources about which domain information either cannot be determined or is not useful.

And, it is important to caution that, as with all statistics, the numbers here should not be relied upon to be accurate. Other sources should be consulted to verify the data.

WWW Prefix to Domain Name

It is common, thought not required, to add a 'www' prefix to when accessing domain names. In order for MiniPortal to respond correctly to URLs using this notation, a 'Domain Alias' must be created for the domain.

In the 'Web Server' folder, 'Configuration' sub-folder, click 'Domains'. Enter '*.yourdomain.com' in the 'Domain Alias' field, where 'yourdomain.com' is the domain name appearing at the top of the page. Click 'Save'.

This will enable all prefixes to your domain name (e.g. www, www2, xyz) to go to your web site.

Using FTP to Publish

MiniPortal has a built-in FTP server to enable web sites to be published directly from web site development programs, or using an external FTP client. The FTP server is automatically started together with the MiniPortal web server.

An FTP account and login are required, except when accessing the 'localhost' (127.0.0.1) from the server machine, where the username 'anonymous' and no password can be used. You can either use the FTP Author'ing capability of the Administrator account previously setup, or you can create a new account with FTP Author rights via the 'Accounts' link.

Configure your web site development application or FTP client to use your subdomain name, FTP account name, and account password to login.

You should be able to view and publish your files to the subdomain's document directory.

Setting Up a Domain

There are three steps to set up a domain name on MiniPortal:

1. Register a Domain Name on the Internet.

If you already own a domain name, proceed to the next step. Otherwise, find a Domain Name Registrar, and register a new domain name. Note that it may take 24-72 hours for your domain name to become active.

2. Setup the DNS

Each domain is associated with a Domain Name Server which keeps track of the domain's IP address. In this case, the IP address is that of your server machine or extenal router.

If you have a Static IP address, you can use the domain administration tools provided by your Domain Name Registrar to set the IP address. Note that some Domain Name Registrars do not provide Domain Name Servers or the ability to set the IP address. In this case, you will need to obtain DNS services for your domain. You can purchase this from InstantServers, or obtain it from a number of other DNS services.

If you have a dynamic IP address, you will need to use a dynamic DNS service to keep the IP address of your domain in sync with the IP address given to you by your ISP (which can change from time to time). You can either purchase dynamic DNS support from InstantServers, or obtain it from a number of other dynamic DNS services.

If you purchase static or dynamic DNS support from InstantServers, you can Configure MiniPortal as part of the DNS setup process, completing the domain name setup. If you obtain dynamic DNS support elsewhere, proceed to the next step to manually Configure MiniPortal for your domain name.

3. Configure MiniPortal

When you configure MiniPortal with a domain name, it is also a good time to delete all of your subdomains since they will eventually expire, and are only taking up space.

Open the 'Web Server' folder, 'Configuration' sub-folder, and click 'Domains'. Choose your subdomain name and click 'Delete'. Repeat for each subdomain. Now click 'New'. Enter your Domain name, Domain Alias (if you wish to use 'www' to access it), select 'Default Domain', and click 'Save'.

As soon as your DNS setup has propagated across the internet, you will be able to access your domain. You can run the MiniPortal Basic Access Test with Domain Name to check the status of your domain name's Registration and DNS IP address.

Perl Application: WWW to Email Gateway

Earlier, we showed several examples of using Perl to produce dynamic pages. Here, we show how to use Perl in a web application: a form that sends an email message based on user entries.

Although any form will do, this example is based on the popular FormMail.pl script from Matt's Script Archive. FormMail.pl was not originally written for Windows, but with some minor modifications (which we will make here), it can be made to run on Windows requiring only Perl and the Net::Smtp package (which is included in MiniPortal).

We will first go through the FormMail.pl modifications and configure FormMail.pl, and then create a 'wrapper' file that uses FormMail.pl to send a test email message.

FormMail.pl modifications

1. Download the latest version of FormMail.pl to the 'Apache\cgi-bin' directory. We will use FormMail 1.9 in this example, but use a later version if available. If you download the .zip file, a 'formmail' subfolder will be created. Copy 'FormMail.pl' from the 'formmail' subfolder directly into the 'cgi-bin' directory.

2. Make sure you have a 'c:\temp' directory . The 'temp' directory will be used to store mail messages as they are composed.

3. Open your favourite text editor, and modify the shebang line (the first line in the script), changing it from:

#!/usr/bin/perl

to

#!perl

4. Insert the following lines before the code starts (around line 29 in FormMail.pl 1.9):

# BEGIN: Perl Net::Smtp mods
my $USE_NET_SMTP = 1;
my $mailHost = 'your.mailhost.com';
my $tmpMailFile = 'c:/temp/formmail.$$';
# END: Perl Net::Smtp mods

These lines will be used when we configure FormMail.pl to use the Perl Net::Smtp package to send email messages.

5. Replace these lines (around line 385 in FormMail.pl 1.9):

# Open The Mail Program
open(MAIL,"|$mailprog -t");

with these lines:

if (defined($USE_NET_SMTP)) {
  # Open The Mail Program
  open(MAIL, ">$tmpMailFile") or die "Can not open temp mail file $!";
} else {
  # Open The Mail Program
  open(MAIL,"|$mailprog -t");
}

6. Replace this line (at the end of the 'sub send_mail' subroutine around line 455 in FormMail.pl 1.9):

close (MAIL);

with these lines:

close (MAIL);

# BEGIN: Perl Net::Smtp mods
if (defined($USE_NET_SMTP)) {
    use Net::SMTP;
    use CGI;

    my $q = new CGI;
    die "Server unidentified" if !defined($q->server_name);

    my %options = ( Hello => $q->server_name );
    my $smtp = Net::SMTP->new( $mailHost, %options );
    my $success = 0;

    if (defined($smtp) and $smtp) {
      $success = $smtp->mail( $Config{'email'} );
      $success &&= $smtp->recipient( $Config{'recipient'} );
      open(MAIL, "<$tmpMailFile") or die "No temp mail file found $!";
      my @data = <MAIL>;
      close MAIL;
      unlink $tmpMailFile;
      $success &&= $smtp->data( \@data );
      $smtp->quit;
    }

    # Display a 'missing_fields' error message if any send errors
    &error('missing_fields') if !$success;
}
# END: Perl Net::Smtp mods

Configuring FormMail.pl

1. Edit the $mailHost variable to replace the 'your.mailhost.com' value with the name of your (outgoing) mail server. This can be found by looking in your email client program (e.g. in Outlook, select Tools->Accounts, choose your mail server, click Properties and check under the Servers tab).

2. Edit the '@referers' line to use the domain name of the email address you are sending from:

e.g. @referers = ('mysendingdomain.com','1.2.3.4');

If you are accessing the script using 'localhost' or '127.0.0.1', use these.

e.g. @referers = ('localhost', '127.0.0.1');

3. Edit the '@recipients' line to use the domain name of the email address you are sending to. If this is the same domain as in '@referers', you do not need to edit it.

Creating a Wrapper script to send a test message

Copy 'tutorial\examples\scripts\wrap_formmail.pl' to the '\Apache\cgi-bin'

Sending a test email message

• access http://127.0.0.1/cgi-bin/wrapformmail.pl
• fill in the message fields and click 'Go'

A test message will be sent to the Recipient email account. If you do not receive the test message, check the @recipients and @referers lines above, and make sure valid Recipient and Sender email addresses were given. Also check the error.log file (see Log Files).

Note: the README file that comes with FormMail.pl should be consulted to see how to further customize the wrapformmail.pl

High Performance Perl with mod_perl

We would be remiss in this Tutorial if we did not mention the existence of 'mod_perl'. Although clearly an advanced topic, you should be aware that mod_perl can be used to speed up Perl script processing dramatically. Up until now, we have been using the standard CGI interface to run Perl scripts. Every time a Perl script runs using CGI, the entire Perl interpreter must be loaded, started, and the script compiled before it is run. With mod_perl, the Perl interpreter is only loaded and started once, and scripts that are compiled are cached for later (re)use.

The only downside to using mod_perl is that it behaves a bit differently from Perl under CGI. It is harder to debug, and requires some programming discipline. So, we recommend that scripts be developed under CGI, and then 'ported' to use mod_perl once they are running well.

By default, any Perl scripts placed into the 'Apache\mod_perl' directory will be run under mod_perl. You can see this by copying the 'tod.pl' example from 'cgi-bin' into 'mod_perl'. Try running it several times in both directories. Even a script as simple as this runs faster uder mod_perl!

For a lot more information on mod_perl we highly recommend that you see the mod_perl web site and peruse the excellent mod_perl Guide found therein.

MiniPortal Plug-ins

As we said earlier, Perl is by no means the only scripting language available. And, as it turns out, the underlying design of MiniPortal supports a set of 'plug-in' extensions, one of these being the MiniPortal-PHP plug-in. This plug-in is a complete PHP system, and is configured for use with MiniPortal. We will use this plug-in to demonstrate how to run PHP scripts under MiniPortal.

In order to install the plug-in, MiniPortal must be exited.

Then, Download and install the latest PHP plug-in. The plug-in installation directory is within the MiniPortal directory tree and should not be changed. The plug-in is pre-configured to work with the CGI interface.

Next, re-run MiniPortal and copy the script below (reproduced from the PHP Tutorial) to the domain's Document Directory. Then, access it through your web browser (i.e. http://127.0.0.1/hello.php).

The script will display a simple 'Hello World' message.

To get information about the PHP configuration, copy the following script (also reproduced from the PHP Tutorial) into the domain's Document Directory and access it through your web browser:

This script will display PHP configuration data.

Additional information, including the PHP Tutorial, PHP Manual, and lots of references are available from the makers of PHP.

Explore Further

Additional information about MiniPortal is available in:

• MiniPortal User Guide
• MiniPortal FAQ