# Chapter 3 – Simple Configuration

#

The goal of this chapter is to demonstrate the setup of IPS services, access permissions, user accounts and user groups. More advanced configuration topics are covered in Chapter 4. From this point onward in this Chapter, it's assumed that IPS has been already been configured according to instructions found in Chapter 2.

## 3.1 – Introduction to Configuration Files (Cfs)

Configuration files provide IPS with the parameters and values that make it work. Every site personality CF contains three main sections, named GLOBAL, ACCESS and VFS. One or more service-specific sections exist too, but all site personality CFs share a common format. The files themselves should be edited with a plain text editor with it's word wrap turned off.

The figure below illustrates an abstract of a CF, in which comments are preceded by a pound (#) sign, section names are enclosed in square brackets ([]), parameters are found to the left of equal signs and the values for those parameters appear to the right. A description of what each CF parameter represents can be found in Chapter 4.

Example configuration file (CF)
    # Comment
    [SECTION1]
    Parameter1=A value

    [SECTION2]
    Parameter1=Some value

PLEASE NOTE
Parameter names are case sensitive and therefore you should take great care that the correct case are used when inserting new parameters not in the default files. List values are “words” separated with space.

## 3.2 – User Accounts

This section provides details on how to secure default user templates and create new accounts.

### 3.2.1 – Securing Default User Accounts

Out-of-the-box, IPS ships with pre-packaged user accounts. These can be handy tools in the creation of new accounts when used as templates. They have pre-packaged passwords too, so it's highly recommended that these passwords be changed immediately. This section is intended to be the how-to for this procedure.

The default accounts are "admin", "anonymous" and "user". Each of these accounts are stored in their own file, found in config\main\users. Open each of these files in a text editor and locate the line beginning with the "Password" parameter. Decide on a new password for the user, place a minus sign (-) in front of it, and enter it as a value for the parameter. IPS will encrypt this password the next time a user logs in.

PLEASE NOTE
Change the default "admin" and "user" account passwords, and then configure them for auto-encryption before doing any configuration whatsoever. The paragraph above describes how this can be accomplished. Neglecting to do so will leave the system open to intruders and vandals.

### 3.2.2 – Creating New User Accounts

User accounts are created within the context of a specific site personality. When a user account is created, it is only recognized in the context in which it was created. Five steps are required to bring a new user into a site personality's database, but these are straightforward and quite simple. These follow:

1. The first step is to think of a unique username and password. Any character that is valid throughout IPS's host file system is valid for a username, but good practice in Internet standards will limit the usable scope of characters to alphanumeric (A-Z, a-z, 0-9), underscores (_) and periods (.). In light of this, underscores and periods should be used in place of blank spaces. It is commonplace to find full names used as user names, with first, middle and last names separated by periods.

2. The next step is to make use of the user template to create the new user. This is accomplished by opening the file "config\main\users\user" in the text editor, and then immediately doing a "Save As" in the config\main\users directory, specifying the user name as the file name. Changes and additions to the file from that point onward will have a direct effect on the new user, because that user's account being modified directly.

3. Make the value for the Username parameter match the filename for the user account. The filename and Username must match exactly. Otherwise the account will be disabled. It follows such that to enable a user account, the value for the Username parameter must match the filename of the user account. To disable an account, the value for the Username parameter needs to be set to something other than the user account's file name.

4. Set the value for the FullName parameter in such a way that it reflects the user's real name.

5. Set the value for the Password parameter so that it meets the formatting detailed in Section 3.2.1.

PLEASE NOTE
For security reasons, when setting passwords, all passwords must be preceeded with a minus sign (-). Unencrypted passwords aren't supported (in other words, they don't work).

To test the newly created account, the user can attempt to log in through the FTP service. If this fails, then the user account should be reconfigured. Further assistance can be requested for configuration of user accounts through IPS Technical Support. Please consult Chapter 2 for details on this.

## 3.3 – Setting Up a Service

First, a description of what a service is. A service (also known as a "daemon"), is a program that provides the server-side functionality in the client-server model. IPS provides the server-side functionality, as well as client-side functionality when doing SMTP relaying.

Consider an FTP server as an example. An FTP server is merely a machine running software that lets clients connect to it and transfer files. That computer is known to be running an "FTP service" (or an "FTP daemon"). An FTP client cannot connect to other FTP clients, because FTP is founded on the client-server based model and as such an FTP client can only connect to an FTP server. By saying that IPS provides the server-side functionality, we mean that IPS provides the FTP server that the clients connect to.

Certain daemons (such as SMTP daemons), make connections to and accept connections from other daemons as well. Once the services are configured, they are self-maintaining. As luck would have it, these upcoming sections are the "how-to" guides for configuring a basic version of each of IPS's available services. Keep in mind that they have been written with the assumption that a fresh IPS install has been performed.

PLEASE NOTE
The following sections have been written with the assumption that a fresh install has been performed.

The configuration in this section involves editing of the ips\config\main\main.cfg file, which is the CF for the default site personality called "main".

Service instances can be "turned on" or "turned off" by changing the list of space-seperated values for the ServiceSections parameter in the [GLOBAL] section of the CF. For a service instance to be enabled, it's associated service section name needs to be in the list. For a service instance to be disabled, it's associated service section name needs to be omitted from the list. For example, if the FTP service associated with service section FTP-3 is to be "turned on", the text "FTP-3" must appear as one of the items (without the quotation marks) for the ServiceSections parameter.

The [GLOBAL] section of a Configuration File
    [GLOBAL]
    ServiceSections=FTP-1 HTTP-1 POP3-1 SMTP-1

    SiteAdminMail=admin@iq.to
    SiteAdminUser=admin
    SiteDescription=Example IPS powered site

    HomeDirectory=/home
    StatDirectory=.\config\main\stats
    UserDirectory=.\config\main\users

    GroupsDefined=users

The GLOBAL section of the site personality CF is the home of IPS's site-wide parameters. By site-wide, we mean that the parameters contained affect every aspect of the site personality (all service sections). An example of a site-wide parameter is the ServiceSections parameter mentioned in Section 3.3, which affects the state of entire service sections (turning them on or off). For the purpose of this chapter, the informational parameters SiteAdminMail, SiteAdminUser and SiteDescription should be set as follows:

SiteAdminMail - should contain the e-mail address of the site administrator. This doesn't have to be an address of a POP mailbox situated on the IPS system, but should be an e-mail address at which the site administrator can be reached. This parameter is for informational purposes.

SiteAdminUser - should be the username of the administrator for the site this CF is for. This parameter too is merely informational.

SiteDescription - should be the name of the site.

An example follows:

The SiteAdminMail, SiteAdminUser and SiteDescription parameters
    SiteAdminMail=admin@iq.to
    SiteAdminUser=admin
    SiteDescription=IQ Unlimited, Inc.

### 3.3.1 – File Transfer Server

This section will illustrate the setup of a simple FTP server. Those who successfully log in will be presented with a /pub and /incoming directory. Anonymous and regular IPS users will be able to list the contents of and download from the /pub directory and its subdirectories. They'll also be able to upload to and create subdirectories in the /incoming directory and its subdirectories. Optionally, downloads from the incoming directory can either be allowed or disabled. Details of how to do this are included in the steps shown below. File deletion permission will only be available to the administrator, who has access to everything, and this includes access to all local drives mapped as part of the default installation.

The service will allow connections to any of the IP interfaces available on the system (static or dynamic IPs including those bound to NICs, dial-up connections or loopback). This is a point where the default admin and user account passwords should already be changed. Administrative connections to this site will be allowed unrestricted access to a good chunk of the file systems on the IPS machine. This would include mapped network drives.

Found below, are the steps and "screenshot" examples showing how to configure this site:

- Create the directories config\main\vfs\ftp\incoming and config\main\vfs\ftp\pub.

- Make a backup copy of config\main\main.cfg. In the case that an error is made, the original "main" site personality can be restored.

- Open the main.cfg file in config\main for editing, and locate the ACCESS section.

- Locate the line .\config\main\vfs\ftp\*;admin;users;777;011;. Change the 777 on this line to 755.

- Insert two blank lines before the above line, and decide whether or not downloads from the /incoming directory should be allowed. If they are, put ".\config\main\vfs\ftp\incoming\*;admin;users;777;011;" on the top-most blank line. Otherwise, put in ".\config\main\vfs\ftp\incoming\*;admin;users;733;011;" on the top-most blank line. Remove any gaps between the lines.

- On the bottom-most blank line, put ".\config\main\vfs\ftp\pub\*;admin;users;755;011;".

After completing the 3 steps above (assuming /incoming downloads are enabled), the result should look like:

The ACCESS section of main.cfg - after changes
    [ACCESS]
    !admin;admin;users;100;777;
    .\config\main\vfs\drives\*;admin;users;700;077;
    .\config\main\vfs\ftp\incoming\*;admin;users;777;011;
    .\config\main\vfs\ftp\pub\*;admin;users;755;011;
    .\config\main\vfs\ftp\*;admin;users;755;011;
    .\config\main\vfs\home\*;admin;users;700;077;
    .\config\main\vfs\html\cgi-bin\*;admin;users;111;033;
    .\config\main\vfs\html\*;admin;users;755;055;
    .\documentation\*;admin;users;555;555;
    *;admin;users;700;044;

- Locate the FTP-1 section in the CF and remove the value for the Address parameter. The end result should be such that the value section of the line should be blank, like this:

config\main\main.cfg - Removal of the Address parameter's value
    [FTP-1]
    Address=
    Port=
    Protocol=ftpd

Save the main.cfg file and then shutdown and restart the IPS server.

That does it for the setup!

#### Verifying Proper Operation

Making sure the FTP site is in working order, has been simplified according to the following steps:

- Using the command appropriate for the IPS machine's OS, start up IPS.

- Using an FTP client, a connection to the IPS host must be made using the anonymous account, the admin account and any accounts created. Non-existent user accounts should be tested as well.

Testing can now be done to ensure the site specifications outlined at the top of this section are met, by testing upload, download, directory creation and file deletion abilities for each user (including the anonymous user). If it's found that any of the desired functionality has not been met, then a shutdown of IPS must be performed (with Alt-X at the console window) and the changes made to the ACCESS and FTP-1 sections need to checked over again, against the changes instructed in this section.

If technical assistance is required, it can be acquired through methods described in Chapter 2.

### 3.3.2 – Web Server

This section describes how to configure a simple web site and test it. The configuration is simple. an overview, it involves changing one line in the main site personality CF, moving out the default front page and then dropping in the new one. Details of how this can be accomplished follows:

- First, ensure that IPS is running and that the existing web service is working by connecting to http://127.0.0.1/. If a page with a few links pops up (including those for administration and documentation), it's okay to continue with the following steps. If this page doesn't show up, verify again that IPS is running and try again. If at this point the page still doesn't show up, please consider obtaining technical support as describe in methods in Chapter 2.

- Open the file config\main\main.cfg and locate the Address parameter in the HTTP-1 service section. Remove the loopback address value (127.0.0.1) and leave this blank. This will allow for connections to the site from any IP interface. An example of how the main.cfg file should look follows:

HTTP-1 section of main.cfg (after changes)
    [HTTP-1]
    Address=
    Port=
    Protocol=httpd

- The index.html file (shipped with IPS and stored in config\main\vfs\html) is the current front page for the default web site. It's good practice in Internet standards to use this filename. Preserve the contents of the file by making a backup of it (it may be needed later), and then save the desired front page over the old one.

- Save the changes to the main.cfg file, and then shutdown and restart IPS.

That's it for the web site configuration!

#### Verifying Proper Operation

Test the connection to the website by loading up a web browser and using the address http://<IP_or_FQDN_of_the_IPS_Server>. If the web service has been configured properly, the front page will be displayed and the address will change to http://<IP_or_FQDN_of_the_IPS_Server>/index.html.

If things aren't operating the way they should be at this point, please verify the configuration again. If after that there are still difficulties, technical support can always be obtained through methods described in Chapter 2.

#### A Footnote Regarding CGI

Access is presently pre-configured within IPS to allow CGI style applications and scripts to be run from the cgi-bin directory. For information on configuring a site for CGI applications, please refer to Chapter 4.

### 3.3.3 – E-mail Server

This section will describe how to get a basic e-mail server up and running with the basics: Simple Mail Transfer Protocol (SMTP) and Post Office Protocol (POP3) services. The difference between the two services are such that POP3 provides users with access to their mailboxes, whereas SMTP handles the actual reception and deliverance of messages. Should mailbox access not be needed, POP3 can be disabled and SMTP can operate by itself to relay mail. This and other advanced topics are covered in Chapter 4.

PLEASE NOTE
The steps outlined here are geared to provide a basic mail server configuration. It is not an Internet standard configuration, so there is a possibility that it may not work. Internet standard e-mail server configurations and other advanced topics are covered in detail in Chapter 4.

This section has been written with the following environmental assumptions:

- A static IP address exists for the IPS mail server.

- The main CF sections POP3-1 and SMTP-1 are in "out-of-the-box" condition.

Setup of the mail server is simple. Open the main CF - config\main\main.cfg - and carry out these easy steps:

- Remove the value for the Address parameter in the POP3-1 and SMTP-1 sections.

- Carry out the following steps in a command line session on the IPS machine:

  1Enter the following command:

      nslookup <IP_address_of_the_IPS_machine>

  Make note of the fully qualified domain name returned with the IP address from this step. This name is the Fully Qualified Domain Name (FQDN) of the mail server, as seen by the IPS machine.

  2Enter the following command:

      nslookup <FQDN_of_the_IPS_machine>

The IP address returned with the here should match the one that was entered as part of the command in step (i). If not, the needed DNS entries to run the simple e-mail setup.

An example of the nslookup output follows. Note that the Name: & Address: pair are the ones that should be considered for the steps in this section - not the Server: & Address:. There are a few assumptions for this example. First, the IP of the mail server is assumed to be 192.168.123.45. Second, the FQDN of the IPS mail server is mail.iq.to. Here's the example:

nslookup example
    C:\IPS>nslookup 192.168.123.45
    Server:  ns.iq.to
    Address:  192.168.123.54

    Name:  mail.iq.to
    Address:  192.168.123.45

- Locate the ForwardAddress parameter in the SMTP-1 section and replace the value with:

      <1st_three_octets_of_IP_address2>.* *.<domain1> 127.0.0.1 localhost !*

  Note that the above should all be on one line. A copy & paste of the line above is suggested, to ensure proper spacing is present between values for the parameter. Following our example above this line would read:

      ForwardAddress=192.168.123.* *.iq.to 127.0.0.1 localhost !*

- Locate the LocalDomain parameter in the same section, replacing it's value with the FQDN of the mail server in 1. Our example follows:

      LocalDomain=mail.iq.to

- Locate the LocalDomains parameter in the same section and replace it's value with:

      @<FQDN_(i)> @[IP_address_(i)] @localhost @[127.0.0.1]

Note that the above too, should all be on one line. A copy & paste of the line above is suggested, to ensure proper spacing is present between values for the parameter. And, again our example would turn result in:

    LocalDomains=@mail.iq.to @[192.168.123.45] @localhost @[127.0.0.1]

An example of the main.cfg file, configured with the IP and FQDN as returned in part 2 above, follows:

main.cfg file
    [POP3-1]
    Address=
    Port=
    Protocol=pop3d

    ...

    [SMTP-1]
    Address=
    Port=
    Protocol=smtpd

    ...

    ForwardAddress=192.168.123.* *.iq.to 127.0.0.1 localhost !*

    ...

    LocalDomain=mail.iq.to
    LocalDomains=@mail.iq.to @[192.168.123.45] @localhost @[127.0.0.1]

#### Verifying Proper Operation

This section will verify the current configuration of mail services for basic operation. It assumes that mail client software is installed that allows for sending of messages via SMTP, and receiving via POP3. It will be configured to use the admin account, the admin account's password and the FQDN as returned in 1.

Ensure IPS's services are running and carry out the following steps:

- Configure a new account in the mail client, specifying the FQDN of the IPS mail server for both incoming and outgoing mail server properties. Specify POP3 for the incoming server type and SMTP for the outgoing mail server type. Specify the user name admin, the correct password for that account, and the email address of admin@<FQDN_of_the_IPS_server>.

- Test the client's ability to correctly check for mail, by forcing it to check for mail. If errors are returned, check the user name, password and server settings on the mail client for typos and try again.

- Using the IPS mail account, send an email to admin@<FQDN_of_the_IPS_server>. Some mail clients may require a Send/Receive button to be pressed in order to do an immediate send. Force an immediate send, and then some time after that, have the mail client check for new mail for the admin account. The mail that was sent should appear in the admin account's in-box.

- Reply to the message (forcing an immediate send again if need be) as indicated in and then check for mail again. The reply should appear in the admin account's inbox.

- Send an email to a valid mail account that is not being hosted by this IPS installation, and verify the receipt of that message by checking the in-box of that account. Between sending and receiving e-mail, take into consideration the possibility of delivery delays between sites (ie: network/WAN/internet traffic). The e-mail should be present in the inbox of that account. Reply to the message, using that account, and then verify the receipt of the message in the admin account's inbox.

This concludes the testing. If everything works ok, the server is ready for basic operation in the current environment. If not, keep in mind that as mentioned earlier that this is a non-standard mail server configuration, and therefore an Internet Standard configuration may be required. This topic is covered in detail in Chapter 4.

In either case, Technical Support can be obtained through methods described in Chapter 2.

This document is the exclusive property of Terje Flaarønning.