Immunix ISP Appliance Server
Package Release Notes

The Immunix ISP Appliance Server is WireX's product for ISPs who wish to supply servers to their customers. This includes WireX's Remote Network Administrator (RNA) software, a web-based administration tool for end customers to administrate their own domains. Its management is simple and intuitive, but scalable to a wide range of expertise and technical requirements.

The initial 1.0 release was a fully functional virtual hosting server that provided both web and mail services that work with multiple domains. This 2.0 release expands on the services by including full Domain Name Service (DNS) support. This service can be used by novice clients unfamiliar with traditional DNS services as well as by experienced network administrators (see the Features section below for details).

This document describes technical information about this product release (including bug fixes from the previous release). It is expected that the user has a copy of the "Installation and User's Guide" for directions on using this product.

About the 2.0.2 Release. Some minor bug fixes have been fixed since the 2.0.0 release and the following improvements:

• General speed improvement of the RNA
• Support for case-insensitive email addresses, i.e. Mail to john@foo.com and John@foo.com will both work.

Keep in mind these Release Notes describe the general 2.0 features and enhancements, however, the bug fixes only describe the fixes for the latest 2.0.2 release. This way, users will not have to have copies of earlier release notes for information on features.

This release includes new functionality and bug fixes (see the Bugs section for the list of open closed and workaround bugs). This section lists the improvements and features for this product.

DNS Service

RNA Integration with DNS services is the major feature enhancement for this release. Our approach to creating an administrative interface to DNS is somewhat novel because we do not assume the client user has prior DNS-specific knowledge. We expect that ISPs will be renting these servers to clients that know the concepts associated with DNS, but want to be able to administer their own domains without resorting to requesting help from their ISP system administrators.

The client user only needs to adjust their Preferences Level from simple to expert to increase his/her control over the DNS service, as well as increase the complexity of the product.

You will find all DNS settings under the Services | DNS Server. The first section of the menu items under this heading allow the user to create and manage DNS Domains, e.g. "Add Domain". Normally, when adding a domain, you can create some entries for individual hosts within the domain. Later, you can go under the Edit Domain Hosts menu item to further manage domain-specific hosts entries.

Important!
Keep in mind that doing any DNS domain work only affects the name resolution for domains. You must also set up a web or email server to answer requests for that domain. For instance, once you create a DNS entry for the domain, bobdog.com with a host of www.bobdog.com that points to the server, 167.32.233.32, you will need to to log onto the 167.32.233.32 server and set up a virtually hosted web domain for bobdog.com if you want the web pages to display when someone enters http:\\www.bobdog.com in their browser.

Limited MySQL Database Support

This release includes MySQL built to work with our version of Apache and PHP. This database server is automatically installed, but does not automatically run. There is no RNA interface support for MySQL in this release, so it must also be manually configured in order for applications to access and work with it (see the Support section below for details on how to log onto the box for database configuration).

Web services, such as PHP, JSP and CGIs, all have access to this version of MySQL. To access the database server from each of these services, you first need to create a database and a role account (a type of database user) with a password that has access to the created database. This information will be necessary when creating CGI, PHP and JSP scripts.

Perl CGI. When building CGI's to access MySQL, you will need to use the DBI/DBD modules, for instance:

	use DBI;
        $dsn = "DBI::mSQL::database=datebase_name;host=localhost";
        $dbh = DBI->connect($dsn, "rolename", "password");
	$sth = $dbh->prepare("SELECT * FROM foo WHERE blah...");

PHP. PHP supports MySQL directly, so embedded scripts with commands like the following will work:

	$db = mysql_connect("localhost", "rolename", "password");
	mysql_select_db("database_name",$db);
	$result = mysql_query("SELECT * FROM employees",$db);

Java Servlets and JSPs. A level 4 JDBC driver to access the MySQL server is included. This can be used by creating Java commands like the following:

	Class.forName("org.gjt.mm.mysql.Driver").newInstance();
	Connection con = DriverManager.getConnection("jdbc:mysql://localhost/database_name", 
				"rolename", "password");
	Statement stmt = con.createStatement();
	ResultSet rset = stmt.executeQuery("Select * from employees");

Tomcat 3.2.1 Upgrade

This release also includes the most recent production release of Tomcat, a Java servlet and JSP engine from the Apache Organization.

To install the Immunix ISP Appliance Server operating system, refer to the Installation and Getting Started Guide. But simply booting off of the supplied CD will erase the computer's hard disks and install the server appliance software. No interaction is required at this time.

Note: During installation, an erroneous message displays stating that turning on user and group Disk Quotas fails because it cannot find the appropriate directory. You can ignore this message because the quotas are set up appropriately.

After installation, you should log into the Console in order to initially configure the network settings. This is done using a monitor or keyboard connected to the standard ports. The console is accessible via a null-modem cable connected to first serial port as well (see the Installation and Getting Started Guide for details). The account name is root and the password is wirex.

A series of dialog boxes will be displayed. Answer the questions requested to set up the server's network as well as changing the root password and setting up the date and time.

After going through the "Console" instructions, you should now be able to use a standard web browser, for example, Internet Explorer or Netscape Navigator, to connect to the box.

The following are necessary to use the RNA software:

• WireX recommends using Internet Explorer 5.5 or Netscape 4.75 to browse to the RNAEngine software. If Internet Explorer 5.5 is used, deselect "Use SSL 3.0" in the Security Section found by clicking Tools, Internet Options, and the Advanced Tab. Be sure that the Use SSL 2.0 checkbox HAS a checkmark in it.
  
  
• When you log in to RNAEngine software, use the root user account name with the password that was set on the console.

Follow these steps to access the Remote Network Administrator (RNA):

1. Go to a computer on the same network as the previously setup RNAEngine Immunix ISP Appliance Server.
   
   
2. Using the IP address that you established during the installation of the product, type the following into the Address or Location field in the browser. Remember to replace "system-name" with the IP address used.

	http://system-name:6080/

Although this connection is not secure there is a small redirection script listening on port 6080 that redirects the browser to the secured port:

	https://system-name:6081/Admin

Open Bugs with Workarounds

The following is the current list of known bugs. All known bugs have workarounds.

When using the "console" program, the user can leave the address field blank. This signifies that the program should attempt to query a DHCP server for an address. This should never be done to a machine that is connected directly to the Internet.

When the "console" program attempts set up the network settings, it will error out when no DHCP server is available, and require the user to re-enter the network settings.

Workaround: This is just a warning. The program will not allow itself to be configured incorrectly.

The product sets up a "direct-connection console" on the first serial port. However, the kernel is sometimes unable to detect the serial port settings (like IRQ) on some hardware. This causes the kernel to output the following warning message:

        ID s1 respawning too fast disabling for 5 minutes.

When this software is released to an OEM directly, we will configure the software to work on their specific hardware. (This bug is simply a problem with auto-detecting generic hardware).

Workaround: To get rid of these warnings on your demo, follow these steps:

1. Log into the Console (see Support below)
2. At the menu, select L for a Linux Shell
3. At the prompt, type setserial /dev/ttyS0 irq # port # uart # baud_rate +38400
   Where the # characters are the following:
   1. The IRQ for the first serial port (i.e. 4)
   2. The I/O Port (i.e. 0x03f8)
   3. The UART (i.e. 16550A)
   For instance: setserial /dev/ttyS0 irq 4 port 0x03f8 uart 16550A baud_rate 38400

For users who are upgrading from either the ISP 1.0 release or the ISP 2.0 beta release, there is a small bug that makes some users unable to log into the RNA.

Workaround: After upgrading your system, connect to the box (see the Support section below) and execute the following command:

perl -p -i -e 's/^password=.*$/password=/;' /home/web/wirex/rna/WEB-INF/users/*.user

If a user creates multiple host entries with the same name, i.e. the host mail resolves to both 216.99.213.80 and 216.99.213.81, removing one of the particular entries is not intuitive, as the list contains two like entries to select from. In any event, both are removed if either one is selected for removal.

Workaround: There is no workaround. The user will end up deleting both entries and then have to manually re-enter one of them. This bug will be fixed in the next release.

If a user creates a backup of their domains, and then reinstalls the appliance and attempt to restore the original domains, they will receive an error:

	usermod: unknown group 1003 Use of uninitialized value in
	concatenation (.) at /home/web/wirex/rna/WEB-INF/perl/WireX.pm
	line 673. must specify a domain

Workaround: A complete "System" level backup must be restored prior to restoring an individual (or group) of domains.

Bugs Fixed since Last Release

The following are a list of all bugs fixed since the previous release. For details on any of the following, please contact your WireX sales representative.

This section contains information concerning the following:

• Disk Quotas
• Domain Limits
• Mail System
• Backing Up the System

Disk Quotas

Disk quotas assigned to virtual domains currently only apply to web content and files owned by domain users. They do not apply to mail usage or to any other files created by the domain owner.

Limitations on the Virtual Domain System

A domain owner is limited to only owning 30 domains. If you assign more than 30 domains to a user, an error message will appear. This does not make the domain unusable, but there could possibly be unpredictable behavior. This limitation is due to a fundamental limitation of the Linux operating system, which limits a user to belonging to a maximum of 32 system groups. Since virtual domains are identified by their system group, a domain owner is limited to only 30 domains (the other two are taken up by default system groups which identify the user as a domain owner).

Notes for Using the Mail System:

Refer to the Install and Getting Started Guide for detailed information about setting up email for your system.

1. IMAP clients: The mail server does not let IMAP clients create folders at the same level as the INBOX. Please create any folders as sub-folders of the INBOX. In order for this to work correctly with Outlook Express, edit your server properties. There will be an entry there for the IMAP server account that you entered. Click on it, then choose "Properties". Click on "Advanced". Enter "INBOX" (without the quotes) in the "Root folder path" field, and make sure that "Only show subscribed folders" is NOT checked. This functionality should work in Netscape Messenger 4.x with no additional configuration.
   
   
2. IMAP clients: The IMAP server uses a period (.) to seperate subfolders. So, if you create a folder called "some.stuff", the server will create a folder called "some" with a subfolder of "stuff". For this reason, you should not use periods in your folder names.
   
   
3. Domain users with shell access via ssh can not use command line mail clients (such as pine or mutt) to read their mail, unless those clients use IMAP or POP3 to grab the mail. All domain mail is kept in a secure section of the server which can only be accessed by root.
   
   

Notes on the Backup System

Refer to the Install and Getting Started Guide for detailed information about backing up and restoring your system. RNA Immunix ISP Appliance Server has two separate types of backup functions, as follows:

• System-Level Backup: Makes a copy of all virtual hosting data and configuration and basic system configuration.
  
  
• Domain-Level Backup: Makes a copy of the configuration and data of one or more virtually hosted domains.
  
  

Under certain conditions the restore may fail due to changes made to the system after the backup has been performed that make the restored data incompatible with the system.

The following steps show an example of how a failed restore could happen:

1. A virtual domain is created as an IP based host (say foo.com) using ipaddress 192.168.0.1.
   
   
2. A domain backup is created for this domain.
   
   
3. The domain is subsequently deleted from the system.
   
   
4. A new domain, bar.com, is created as an IP based host and uses the same ipaddress 192.168.0.1, which is now available as the domain that was using this address previously has now been removed from the system.
   
   
5. A domain admin selects to restore the domain foo.com. An error occurs as the restoration process will attempt to configure the ipaddress that foo.com wishes to use but it is being used by bar.com.
   
   

The Remote Network Adminstrator (RNA) is designed to be easy to use, and as such, it doesn't contain every possible configuration that a user may need. WireX provides the following two ways to access the underlying Linux architecture. Both methods require a user to enter the "root" password in order to login. This password defaults to wirex until this is changed.

1. Console Shell. When you log in through the Console (using a monitor and keyboard or through a null-modem cable connected to the serial port), you will enter the server appliance Console application. Once using the program, select the "Linux Shell" option.
   
   
2. Remote Secure Shell (SSH). You can not use telnet to access the server appliance remotely. You must use an SSH client (like PuTTY for Windows).
   
   If you are using PuTTY, we suggest using the following settings:
   • Under the "Connection" tab, check the "SSH" radio button.
   • Under the "SSH" tab, enter "xterm-color" for the "Terminal-type string" field.
   • Under the "SSH" tab, enter "root" for the "Auto-login username" field.
   • Under the "Terminal" tab, select radio button "Use font in OEM mode only".

Once you are working within a shell session, you can type in Linux commands. Editors, like emacs, vi and pico are installed and can be used to edit files.

Keep in mind that most commonly used commands are accessible through the "Console" menus.

This product is being offered as a complete solution (a server appliance) and includes Immunix System7, the Remote Network Administration tool (a web-based system administration program) and some integrated services.

A complete list of packages would be beyond the scope of this document, but the following list the packages that extend what would be normally found in a standard server installation of the RedHat 7.0 distribution:

The most widely used Web server on the Internet. (Version: 1.3.12.25.8)

Apache is a powerful, full-featured, efficient and freely-available Web server. Apache is also the most popular Web server on the Internet. Install the apache package if you need a Web server.

apache-1.3.12-25.8.i386.rpm

Development tools for the Apache Web server. (Version: 1.3.12.25.8)

The apache-devel package contains the APXS binary and other files that you'll need to build Dynamic Shared Objects (DSOs) for Apache. If you are installing the Apache Web server, and you want to be able to compile or develop additional modules for Apache, you'll need to install this package.

apache-devel-1.3.12-25.8.i386.rpm

Documentation for the Apache Web server. (Version: 1.3.12.25.8)

The apache-manual package contains the complete manual and reference guide for the Apache Web server. If you need Apache documentation installed on the local machine, install this package. The information can also be found on the Web at http://www.apache.org/docs/.

apache-manual-1.3.12-25.8.i386.rpm

Java Modules Collection (Version: 1.0.10)

A collection of Java modules that include the standard extensions as well as some other useful libraries. These are all installed in /usr/local/java-mods.

java-mods-1.0-10.noarch.rpm

HTTPS (HTTP over SSL) support for the Apache Web server. (Version: 2.6.6.25.8)

The mod_ssl package contains mod_ssl 2.6.6, the server module that adds SSL support to the Apache Web server. If you need a secure web server, install this package and read http://localhost/manual/mod/mod_ssl/ for documentation about how to configure the SSL support.

mod_ssl-2.6.6-25.8.i386.rpm

Perl Module Collection (Version: 1.0.8)

Perl modules that include commonly used modules not included in the base Perl package. These modules include XML parsers, password generators and date parsing routines that can be used by CGI programs (as well as the RNA and Unconsolable Engines).

perl-mods-1.0-8.noarch.rpm

Remote Network Administrator (RNA) (Version: 1.0.30)

The WireX Remote Network Adminstration (RNA) engine that serves as the framework for configuration of the WireX appliance modules and components.

rna-1.0-30.noarch.rpm

Anonymous FTP extension to the RNA (Version: 1.0.8)

A system extension to the standard RNA that adds anonymous FTP support.

rna-anonftp-1.0-8.noarch.rpm

RNA Extension for the Apache Web Server. (Version: 1.0.14)

Scripts and configuration files for extending the RNA to configure and administrate a standard Apache web server. This works with the Apache RPM included with Immunix System 7 or RedHat 7.0 (It is not compatible with previous Apache releases).

rna-apache-1.0-14.noarch.rpm

Courier Mail management module for the RNA (Version: 1.0.13)

RNA module to manage the courier mail server.

rna-courier-1.0-13.noarch.rpm

RNA Configuration for DNS services. (Version: 1.0.16)

RNA extension for configuring DNS services.

rna-dns-1.0-16.noarch.rpm

RNA Initialization (Version: 1.0.30)

Contains scripts and programs which are executed one-time and one-time only for the RNA. It should be run at install time, and then never again.

rna-init-1.0-30.noarch.rpm

RNA Extension to support ISP Virtual Domain Hosting (Version: 1.0.38)

RNA extension that adds virtual domain hosting and other features to an ISP Server. It adds a "Domains" menu at the top level.

rna-isp_domains-1.0-38.noarch.rpm

RNA Extension for Generic Networks (Version: 1.0.14)

Scripts and configuration files for extending the RNA to configure and administrate a network specifically geared to work with a single network interface card (NIC), e.g. as a departmental or workgroup server connected to an internal LAN, or as a public server connected to the Internet.

rna-net_dept-1.0-14.noarch.rpm

Skeleton files used by the RNA (Version: 1.0.2)

A system extension to the standard RNA that adds skeleton files used as templates by various components of the RNA.

rna-skel-1.0-2.noarch.rpm

RNA Utility and Maintenance Programs (Version: 1.0.1)

Utilities to be used for maintaining the RNA and its service configuration. This includes the program, apacheRnaSync.pl, which is used to synchronize the Apache configuration with the LDAP repository.

rna-utils-1.0-1.noarch.rpm

Jakarta Servlet/JSP Engine (Version: 3.2.1)

Sun reference Servlet Engine for the Servlet 2.2 API. This is part of the Jakarta project, which is a joint effort between Sun and Apache. Note: Jakarta is the project, and Tomcat is the implementation.

tomcat-3.2-1.i386.rpm

Tomcat Installation used by WireX RNA (Version: 3.2.1)

This package is a copy of the Tomcat servlet engine wich is used exclusively to run servlets that are components of the WireX RNA.

tomcat-wirex-3.2-1.i386.rpm

Server Appliance Console (Version: 1.0.9)

A console shell to make the server appliance easier to use, and more like a server appliance. It contains a menu-driven interface to utilities to setup the network interface, view log files shut down the system, etc. It is useful when the RNA is not available.

unconsolable-1.0-9.noarch.rpm