Magnia SG20 General Customization Guide

Software Developer's Kit

Technical White Paper

Magnia SG20 General Customization Guide

Topics in this document

Introduction
Customization Overview
User Accounts / Passwords
Server Setup Wizard
Network Configurations
Custom Image Backup
Software Upgrades Support
General System Architecture / Layout
Customizing the Firewall
Templatized Configuration Files
Triggers
Useful Files
LCD Panel Customization

By TAIS Computer System Engineering

Published 9/2002

Introduction

The Toshiba Magnia SG20 is a multi-function server appliance, designed to provide ease of use and a friendly setup and management environment for the end user. It is based on Red Hat Linux 7.31. Because the Magnia SG20 is an appliance, it contains the Red Hat 7.3 RPMs needed to provide its feature set, as well as a variety of tools that allow direct access and modification of the system for more experienced users. It does not contain the entire suite of Red Hat 7.3 RPMs.

The Magnia SG20 provides a number of features targeted for small workgroups, remote offices and small business. These features are configurable through its administrative web interface, and include:

• Second HDD option (customer installable)
• Built in 7 port local LAN switch
• Built in wireless access point option
• Built in modem for dial-in networking and dial out to Internet
• Ethernet port for broadband Internet connections
• Parallel port for printer sharing
• LCD panel to display status (configurable)
• Soft power shutdown
• Easy to use client setup CD
• System reports
• File sharing (SMB)
• Local email
• Internet email retrieval service
• Internet gateway (sharing of single Internet port, dialup or broadband)
• Firewall
• Internet caching and content filtering
• Backup and restore to clients or Internet
• Primary HDD snapshot to second HDD (optional)
• HDD used for additional space (optional)
• User accounts and security
• Disk quotas
• Software upgrade process over the Internet
• Internal hardware health monitoring
• Built in Intranet (customizable)
• Easy to use VPN for remote access
• FTP, Telnet
• Digital Central web site with picture, music sharing and camera monitoring
• Home automation controller interface

When customizing a Magnia SG20 image to create a new preinstall image for your customers, it is important to assure the preset factory configuration is not modified. Doing so can result in a custom image shipped from the Toshiba factory to your end users with modifications which may result in increased service calls and a reduced initial customer satisfaction with his new system. This white paper outlines some basic areas of which you should be aware, and provides some techniques for customizing the system while maintaining Magnia SG20's customer out of box experience.

The Magnia SG20 uses a proprietary web based interface and a set of middleware tools to allow the end user to manage the system. The internal mechanisms of this middleware use some unique methods of managing system configurations, such as templatized configuration files, and triggers. Direct modification of configuration files is not recommended. This document contains information on the internal management techniques and how you might take advantage of them during your application integration process.

Customization Overview

Overview

Before beginning the process of customizing a Magnia SG20 image, you may wish to capture the clean, unmodified image on another hard disk. This will allow you to re-install a factory fresh image if you need to restart the integration process. See the section on custom image backup for more information on how to do this.

Generally, the process of installing a custom application involves three basic steps:

• Identifying and installing added Linux based software needed to support your integration process, such as libraries, newer versions of standard Linux software, or custom support software.
• Moving your application on to the Magnia SG20 and installing it as necessary.
• Optionally, adding links or web pages to the Magnia SG20 web based administration or preinstalled intranet pages.

Accessing the Magnia SG20

Access to the Magnia SG20 is accomplished through three mechanisms.

First, for most customization, installation and modifications, you should directly access the system using Telnet. This will provide direct access to the system using a shell command prompt. You can accomplish almost any task from this environment.

To access the Magnia SG20 using telnet, set up a client computer connected to a private Ethernet port. Verify you can access the web administration pages using the URL http://192.168.1.1. Once this has been verified, bring up a command prompt and run Telnet :

telnet 192.168.1.1

When presented by the Linux login prompt, use the account 'telnetuser' with the default password 'toshiba'. Once at a shell prompt, you can switch to the root account using the su- command.

Once at a root command prompt, you can proceed to install, recompile or modify software as required for your application integration.

Copying Software to the Magnia SG20

Once you have access to the Magnia SG20, you will need to copy your application to the system, as well as possible additional Linux support software such as databases or other tools. There are two main ways of copying new software to the Magnia SG20.

• FTP
• SMB file sharing access (Samba)

To copy files using FTP, invoke a command prompt from any client attached to the Magnia SG20 built in Ethernet switch. When prompted, log in to FTP as an anonymous user (the default Magnia SG20 configuration only allows anonymous access). Use normal FTP commands to copy files to the 'incoming' directory. Once these files are transferred, use telnet to browse to the /home/ftp/incoming directory. You can then move and use these files as needed.

To copy files using file sharing, connect a client to the Magnia SG20 local network and browse the network neighborhood. The Magnia SG20 will appear in workgroup 'saworkgroup' and will have the (default) computer name of 'myserver'. Navigate to the share named 'public'. Copy files to this directory, then use telnet to move and use these files within Linux as needed. The 'public' share is mapped to the directory /home/public on the Magnia SG20.

Modifying the Magnia SG20 GUI

Once your application is installed and running on the Magnia SG20, you may wish to provide additional links or methods of accessing your application web interface. There are several ways of accomplishing this:

• Add descriptive text and a hyperlink to your own web pages.
• Add complete web pages to the existing web administration or preinstalled intranet
• Add your own intranet web site.

More detail on this type of modification is included in another document.

Listing Installed Linux Packages

To determine the list of Linux packages installed on your copy of the Magnia SG20 preinstall image, use the RPM command. This will allow you to determine what revision of each package has been installed on your working system. Use the following command to list the installed RPMs:

rpm -qa

User Accounts / Passwords

Default accounts and Passwords

The Magnia SG20 is delivered to the end user with three predefined accounts. These accounts are:

• applianceadmin: This account is the primary administrative account for the Magnia SG20. It has access to the entire Web Administration UI, as well as complete access to all files on the system. It cannot be deleted using the Web Administration.
• telnetuser: This account is used to log in to the system using telnet. While not encouraged for the typical end user, it represents an important method of access to the system.
• root: This is the standard linux root administrative account with complete system privileges.

All these accounts are assigned a default password of 'toshiba' when delivered from the factory. Changing this password is not recommended, as it can make it difficult or impossible for the end user to log in and administer the system.

Recommendation: Do not change the passwords of the system from the default.

Initial Account Creation

In order to assure that default password for critical privileged accounts such as 'applianceadmin' are changed from the default, the Magnia SG20 uses a specific mechanism to update the password on server initialization. When the user creates the first user account, the password to all three predefined accounts are changed to the password of this first account.

An example scenario is for the user to open his new Magnia SG20, turn it on, and connect a PC to the built in network. He would then run the Setup CD to configure his client PC. During the Setup CD setup process, the Setup CD software creates a new level 3 account for him on the server (for example, 'jsmith'). The user also selects a password at this time (for example 'maxmoney1'). This process changes the predefined accounts' passwords to be 'maxmoney1'.

This process of assigning the initial user account password to the three predefined accounts takes place only on the first user account creation. Subsequent user account creation will not affect the predefined privileged account passwords.

This process will take place when creating an account using either the Magnia SG20 Setup CD, or using the Administrative Web interface.

Recommendation: Do not create a new user on your Magnia SG20 using the Setup CD or the Administrative Web interface. Use the existing applianceadmin account for access to the Web Administration or for file system access (network neighborhood). Use the existing telnet and root accounts for access to the system using telnet. Direct modifications to the system internals can be accomplished using these accounts.

Server Setup Wizard

When the Magnia SG20 is delivered from the factory, it is internally flagged as an unconfigured, or uninitialized system. When the Setup CD is run on a client connected to the Magnia SG20, it will check to see if the server is in its unconfigured, uninitialized state. If it is connected to an uninitialized system, the Setup CD will (upon completion of the client setup) invoke the Server Setup Wizard.

Server Setup Wizard

Once the user has completed the Server Setup Wizard, the system is flagged as no longer uninitialized, and subsequently the Server Setup Wizard will no longer be presented to the end user.

Recommendation: Do not run the Client Setup CD. This will cause the Server Setup Wizard to be invoked, and the system will no longer be flagged as uninitialized.

Network Configurations

The Magnia SG20 is delivered with the Internet (public) connection set to 'none'. This allows the user to configure the system to their personal ISP requirements (Cable, DSL, modem).

When customizing the Magnia SG20, it may be desirable to configure the system to allow Internet or corporate LAN access. This can be done, but you should be aware that after changing networking configurations, they should be returned to their original state prior to shipping an image back to Toshiba. Failure to do so may result in unintended preset networking configurations being delivered to your end users.

If it is necessary to configure the public network for Internet or LAN access, the best method is to use the 'Corporate LAN or Cable Modem' option. This option can be reset to 'none' with little impact on the system.

Configuring public network access using the phone modem or DSL is less desirable. Some settings, such as phone number or user account / password, can be cached and may become part of your final customized image (this is an ease of use feature of the Magnia SG20 UI). This can result in the end user seeing your account (the password will be masked) if they configure modem access.

Recommendation: Avoid changing the networking configuration of the Magnia SG20 system while you are creating the custom image. If you require Internet or LAN access, use the 'Corporate LAN or Cable Modem' option. Reset the configuration to 'None' before shipping the customized image.

There are numerous other networking configuration options that may be changed while implementing a custom image. These can include:

• Internet Caching and Filtering
• Firewall settings
• High security mode
• Dial in access
• VPN settings
• Wireless settings

These settings can be safely changed, and then reset back to their factory defaults if required. You can even change these settings to your own preferred setting for shipment if desired.

Custom Image Backup

When implementing the custom image, it is easy to make a mistake and need to restore the system to a factory original state, or to recover from an earlier version of your custom image. The easiest and best way to accomplish this is to take the original Magnia SG20 SDK preinstall image, and create a copy of it prior to doing any work using the disk snapshot feature.

Second Disk Snapshot

The disk snapshot feature will take a complete snapshot of the entire disk and place it on the secondary disk in the second slot of the Magnia SG20. Work can then proceed; if you need to go back to the original image for any reason, simply switch the primary and secondary disks and boot from the snapshot backup.

With an additional hard disk, you can also take periodic snapshots to preserve your image in case you need to return to an earlier version during your customization process.

Recommendation: Take a snapshot of the original factory image before beginning work on a second disk. If needed, take periodic snapshots of your work on a third disk.

Software Upgrades Support

The standard retail version of the Magnia SG20 is supported with a Software Upgrades site that allows end users to view, download and apply new features and fixes. This site services only customers using the standard Toshiba preinstall image.

Because Toshiba does not control the changes or configuration of your preinstall image, each system integrator will have their own Software Upgrades site. Toshiba may occasionally inform you of a software upgrade available on the standard site which you might wish to make available to end users with your custom image. It is then up to you to decide whether Toshiba should deploy the upgrade for your customers.

In order to provide an Upgrade Site specific to your preinstall images, Toshiba will edit a file on your image to point to this custom site before release to the factory. If you wish to retest your image after this change or if you do not want Toshiba to make this change, please inform your Toshiba sales person.

General System Architecture

The Magnia SG20 is partitioned in the following manner:

The /home partition is where all user data is placed. It contains some infrastructure for the support of the Magnia SG20 system, but very little. User private data and the public share, as well as user posted Intranet information are stored here. The /home directory contains the following subdirectories:

The Magnia SG20 system user interface, middleware and configuration are placed almost entirely in the /sa2 directory. The user interface and management general architecture is displayed below:

• The Perl based CGI uses the HTML templates, along with information from system configuration files, to create the final web based output for the user interface. In addition, it takes configuration changes from the user, applies them to the templatized configuration files, and invokes triggers to regenerate the system configuration files and restart any services as necessary.
• The HTML page templates contain the basic structure and graphics for the web based user interface. These files are combined with actual data to create the final web pages seen by the user.
• Triggers are Perl based scripts that are executed when certain types of events occur. Triggers are called by the user interface CGI, as well as being invoked by some system callback routines.
• Templatized configuration files contain the basic information about many of the system's actual configuration files. These templates are read by triggers, and used to regenerate the system configuration files when certain events occur.

The file system reflects these elements in its directory organization:

Customizing the Firewall

The Magnia SG20 is a Linux IP Tables based firewall. The default configuration for the firewall is established in the firewall template in /sa2/templates/etc/rc.d/init.d/iptables. In addition, there are custom firewall rules defined which the user can select or deselect as desired. These rules are accessible through the web based remote administration screens, in the advanced firewall page. These rules can be checked on or off (the default is off). These custom rules open holes in the firewall for items such as FTP access, Cisco VPN pass through, and Internet gaming. Adding custom firewall rules in this area is the preferred method for customization of the Magnia SG20 firewall.

Modifying the firewall rules is not recommended unless you are experienced with IP Tables and firewall definitions. Inappropriate rules added to the firewall can result in your system becoming completely inaccessible, requiring the disk be returned to the factory for re-imaging. Use care when establishing new firewall rules.

Recommendation: take a disk snapshot before changing or adding custom firewall rules, so that you can restore the system if needed.

Adding a custom firewall rule that can be selected and deselected using the web administration is simple. By simply creating a new directory under the /sa2/firewall directory, and placing several simple files in this directory, a new user selectable firewall rule is added to the user interface.

To add a new custom firewall rule, connect to the SG20 as root using telnet, and perform the following steps.

1. Create a new directory under /sa2/firewall, using a name relating to the new rule you are adding. For example, a new directory may be added:

/sa2/firewall/vpnport500

2. In this new directory, create a new file named 'rule' which contains the IP Tables command for the rule you wish to add. You can use other rule files in /sa2/firewall as examples. For example, you might add the following contents to a rule file :

[% IF firewall.enabled -%]

# allow Sonic VPN clients through

# Note that port 500 is the source port, not destination port.

$IPTABLES -A FORWARD -p udp -s ANY/0 --sport 500 -i $INTIF -o $EXTIF -j

ACCEPT

[% END -%]

3. Next, create a new file 'description' in the directory, containing a short (less than one line) description of the rule to be added. This description will be displayed on the user interface next to the check box. An example description might be:

en=Custom VPN Client

The 'en=' indicates this text description is used for any English based display. For other languages, you can specify sp, de, it, fr, and du for Spanish, German, Italian, French and Spanish. If a language is invoked on the user interface, and there is no corresponding language text in the description file, English will be used as the default.

4. Next, create a new file called 'index' which specifies the location of the firewall within the firewall table. Location can be important, so be sure to review the other custom rules as well as the default rules to understand placement of the rule. The index file should simply contain a number, such as:

70

5. Finally, create a new file called 'type' in the directory, containing the word 'client',' server' or 'both' which is used to describe who the firewall rule applies to. An example type file might be:

client

Once these steps have been performed, a new selectable firewall rule will be added to the user interface.

A very easy way to get started with a new firewall rule is to use on of the existing firewall rule directories. Simply copy it and its contents to a new directory name, and then begin modification of the individual files to change the rule's display name and IP Tables rule.

Templatized Configuration Files

Many of the configuration files in the Magnia SG20 are managed using templates. With this methodology, a set of templates for each configuration file is maintained. Then, when a change is made to the configuration file by the Magnia SG20 user interface or other mechanism, the configuration file is regenerated using these templates.

The Perl based middleware and CGI code interfaces may need to modify the system configuration files(as when a user is added or a configuration changed). When a change has been made, a trigger is invoked, which will regenerate the corresponding system configuration file using the configuration file templates.

Because these templatized configuration files are regenerated periodically, changes to the files must be made in the templates, not in the file itself. Changing the configuration file directly will not work.

Templates are stored in /sa2/templates. Each file's templates are located under this directory based on the file's location in the system. For example, the /etc/passwd template files are located in /sa2/templates/etc/passwd. The contents of this directory are shown below.

As you can see, the configuration file may be broken up in to several templates. Each template represents one part of the configuration file, and the order in which they are used is determined by the alphabetical sorting order of the template file name. This is why a two-digit number, which determines its placement within the final configuration file when it is regenerated, precedes each template file name.

To place added elements in the configuration file, such as a new user in the password file, you can add a new template file in the configuration files template directory. Add the text desired for placement in the configuration file in a new template file. The file name should contain two leading digits that will determine your additions placement within the regenerated configuration file.

Note that adding a template file will not necessarily cause the configuration file to be regenerated. Regeneration of a configuration file from its templates is only performed when the system determines there has been a change requested by the user in the user interface (in some cases system events may cause a file to be regenerated, but this is rare). For example, the password files are not regenerated unless the user adds, deletes or modifies a user account using the web administrative user interface.

Configuration changes can be announced to the system using triggers. Triggers are the Magnia SG20s method of assuring whatever actions are appropriate for a configuration change are taken. Execution of a trigger will cause the appropriate configuration files to be regenerated. Please see the separate section of this document describing triggers for more detail.

The following configuration files are templatized, and should not be modified directly. This list is current as of the time of writing. Please check your system for the actual list.

Template Perl Programming Interface

The template processor has both a Perl object-oriented interface and a command line wrapper. Each of these take two parameters: filename and mode.

The usage statement of the proctmpl command-line wrapper is:

usage: /sa2/bin/template -f <filename> -m <octal mode> -o <owner>

Output from the command-line wrapper is generated to STDOUT so a redirect is required to overwrite the current configuration file.

Where filename is the name of the actual file you want to generate. Call it like this:

[/sa2/bin]# ./template -f /etc/sysconfig/ipchains -m 700 -o root > /etc/sysconfig/ipchains

The perl object interface works like this:

use SA::Template;

my $tmpl = new SA::Template;

$tmpl->process('/etc/sysconfig/ipchains', '0700') or

die "Couldn't process firewall";

$tmpl->process('/etc/sysconfig/network', '0700') or

die "Couldn't process network globals";

This will take the template files contained in the relative path under /sa2/templates/, concatenate them, and process the concatenated value using the Template Toolkit and the values contained in the /sa2/conf/main.conf.

System Startup Scripts

There are a couple of different methods of having services or scripts run at boot time. The Magnia SG20 supports the standard RC boot scripts common on several Linux and Unix distributions. Depending on when your service or script needs to be run during the boot sequence, you can use two methods of execution:

1. Create a standard RC script and create the proper links under /etc/rc.d/rc3.d to enable your script to be executed at a certain point in the boot.
2. Add a Perl script to the /sa2/triggers/started directory to be executed during the 'started' trigger which is executed near the end of ever boot. This method is not recommended for starting daemon tasks.

If you are starting daemon or application processes at boot time, you need to make sure that they are shutdown properly when an orderly shutdown is started on the SG20. You should create an RC script for starting and stopping your daemon processes. There are several examples in the /etc/rc.d/init.d directory on the SG20 of scripts that stop and start daemon tasks.

A simple and straightforward example of an application start and stop script is the /etc/rc.d/init.d/snmpd startup script. This script starts and stops the SNMPD system daemon on the SG20. As in this example, if your startup script creates an empty file in /var/lock/subsys/ then your startup script will also get called with a 'stop' argument when the system is shutting down. It is recommended that you implement code in your start/stop script to handle the stop parameter and shut down your application tasks in an orderly manner. This will help avoid possible killing of the application tasks and loss of data when the system is shutdown.

You need to make sure that all of your running tasks and daemons are stopped when your startup script is called with a 'stop' command. Your start / stop script should send signals to your application and daemon tasks, arranging for an orderly shutdown and cleanup of temporary files. Tasks that are not shutdown in an orderly manner at this time will be terminated by the operating system during the last stage of system shutdown.

Triggers

The internal middleware supporting the web administration and internal operations of the Magnia SG20 are based on a trigger mechanism. Triggers are scripts (or sets of scripts) that are executed when certain events occur on the system. Though triggers may perform other tasks, the two primary tasks performed are typically the regeneration of templatized configuration files, and the stopping and starting of various related system services. Magnia SG20 trigger scripts are written in Perl.

Events that cause triggers to be executed usually involve any detected change in the state or configuration of a specific system area or service. For example, the networking triggers may be executed when there is a change in the IP address of the public port (such as when a DHCP address is acquired). Triggers are also executed when a change is made through the web administration user interface. For example, adding or deleting a user could execute the mod_users trigger to regenerate various password and user configuration files.

Triggers can be useful when integrating your application in the Magnia SG20 system.

• If you change configuration file templates, you can regenerate all the effected configurations and have the change become effective by launching the associated trigger.
• You can add your own triggers scripts to existing triggers.

The core of the trigger mechanism is a series of directories, one per trigger (named after the trigger), that are organized under /sa2/triggers. These directories may be nested as deeply as desired for organization purposes, but the trigger name will be the portion of the directory path relative to /sa2/triggers. Each directory contains scripts that execute actions that are tied to the trigger. The actions will most likely include, but are not limited to, regenerating the template files for each dependent application, then restarting the dependent service. The scripts in each trigger directory should be indexed by zero-padded numeric string in a manner similar to the templates. The scripts will be executed in the order that ls -l [0-9]* produces, so the filename of each script must start with a number.

Trigger Interface

The most common use of triggers when creating custom applications is to assure that templatized configuration changes are applied to the system after modification. In this case, executing the proper trigger from the command line is all that is needed. The usage statement of the trigger command is:

usage: trigger <trigger name> <args>

Use it like this:

[/sa2/bin]# ./trigger network/mod_config

If you are writing custom Perl code and need to execute a trigger, you can do so using the trigger object. The Perl object oriented interface works like this:

use SA::Trigger;

my $trigger = new SA::Trigger;

$trigger->('network/mod_config') or

die 'Couldn't trigger mod_confign';

The code above will sort the scripts in the /sa2/triggers/network/mod_config directory, execute them one-by-one, wait for exit status, and return an exit status to the caller. It is important to note that trigger scripts should always return 0 unless there is a serious failure. If a trigger script returns anything other than 0, the trigger script execution chain is stopped and the return code is passed back to the caller.

The trigger parameter correlates to the pre-defined trigger directory under the /sa2/triggers directory. args are passed directly on the argv stack to the action scripts beneath that directory which might need to do their jobs in a more granular way, i.e. you might design a trigger called 'network/mod_config' and pass it the name of the interface on argv so that it only has to do the work correlating to the change of that specific interface. Or you might design a trigger called 'add_user' and pass it the username so that the relevant configuration and password files would not have to be regenerated in their entirety; only the information relating to that user would need to be added.

However, every action script should assume it could be fired by a trigger without any data and should be designed in such a way that in this instance, it regerates all of its configuration files and restarts all services that use those files. The developer must be very careful not to fire recursive events! Also, the developer must know (most likely through consulting the centralized configuration file through SA::Config) whether or not his service is