Toshiba SG20 - Magnia - Web Server User manual

1
Magnia®SG20
General
Customization Guide
Contacting Toshiba
If you need assistance:
❖support.toshiba.com
Download the latest drivers, view detailed installation instructions, and access the
latest server information
❖InTouch™ Center
Calling within the United States [phone]
Calling from outside the United States [phone]
SV142-1002M1
TOSHIBA

About This Guide 2
Copyright
This guide is copyrighted by Toshiba America Information Systems, Inc., with all rights reserved. Under the copyright
laws, this guide cannot be reproduced in any form without the prior written permission of Toshiba. No patent liability is
assumed, however, with respect to the use of the information contained herein.
©2002 by Toshiba America Information Systems, Inc. All rights reserved.
Disclaimer
The information contained in this manual, including but not limited to any instructions, descriptions, and product
specifications, is subject to change without notice.
TOSHIBA CORPORATION AND TOSHIBA AMERICA INFORMATION SYSTEMS, INC. (TOSHIBA) PROVIDE NO
WARRANTY WITH REGARD TO THIS MANUAL OR ANY OTHER INFORMATION CONTAINED HEREIN AND
HEREBY EXPRESSLY DISCLAIM ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE WITH REGARD TO ANY OF THE FOREGOING. TOSHIBA ASSUMES NO LIABILITY
FOR ANY DAMAGES INCURRED DIRECTLY OR INDIRECTLY FROM ANY TECHNICAL OR TYPOGRAPHICAL
ERRORS OR OMISSIONS CONTAINED HEREIN. IN NO EVENT SHALL TOSHIBA BE LIABLE FOR ANY
INCIDENTAL, CONSEQUENTIAL, SPECIAL, OR EXEMPLARY DAMAGES, WHETHER BASED ON TORT,
CONTRACT, OR OTHERWISE, ARISING OUT OF OR IN CONNECTION WITH THIS MANUAL OR ANY OTHER
INFORMATION CONTAINED HEREIN OR THE USE THEREOF.
Some states do not allow the exclusion of incidental or consequential damages so the above limitation or exclusion
may not apply to you.
Trademarks
Magnia®is a registered trademark and InTouch™is a trademark of Toshiba America
Information Systems, Inc.
Acrobat®Reader Copyright ©1987-2001 Adobe Systems Incorporated. All rights
reserved. Adobe, the Adobe logo, Acrobat, and the Acrobat logo are trademarks of
Adobe Systems Incorporated.
Microsoft, its logos, MS-DOS, Windows, Windows XP, Windows 2000, and Windows NT,
and MS are registered trademarks of Microsoft Corporation.
Other product names and trademarks belong to the individual companies concerned.
About This Guide
This guide introduces the internal design of the Magnia®SG20 appliance server and
provides information on how you might integrate your own software applications into a
Magnia®SG20 preinstall image. Before using your Toshiba software, refer to this guide to
gain an overall understanding of operating procedures.

About This Guide 3
Icons used in this guide
The following icons are used in this guide to indicate important information.
NOTE: This icon indicates information that relates to the safe operation of the
equipment or related items.
CAUTION: This icon indicates the existence of a hazard that could result in the
damage to equipment or property if the safety instruction is not observed.

4
Contents
About This Guide......................................................................................... 2
Chapter 1: Customization..................................................................... 6
Introduction.................................................................................................. 6
Customization overview .............................................................................. 8
Accessing the Magnia SG20.............................................................. 8
Copying software to the Magnia SG20 .............................................. 8
Modifying the Magnia SG20 GUI ....................................................... 9
Listing installed Linux packages......................................................... 9
User accounts and passwords .................................................................. 10
Default accounts and passwords ..................................................... 10
Initial account creation ..................................................................... 10
Server setup wizard................................................................................... 11
Network configurations.............................................................................. 12
Custom image backup............................................................................... 13
Software upgrades support ....................................................................... 14
General system architecture ..................................................................... 14
Customizing the firewall............................................................................. 17
Template-based configuration files............................................................ 19
Template Perl programming interface .............................................. 23
System startup scripts............................................................................... 24
Triggers...................................................................................................... 25
Trigger interface ............................................................................... 26
Manually executing a trigger ............................................................ 27
Adding trigger scripts ....................................................................... 27
Implemented Triggers....................................................................... 28
Useful files................................................................................................. 32
LCD panel customization .......................................................................... 32
LCD interface technical overview ..................................................... 33
LCD panel direct access .................................................................. 34
Direct LCD message display............................................................ 34
LCD Control Codes.......................................................................... 35
Button status codes.......................................................................... 36

5
Magnia SG20 queued LCD message interface................................ 36
Direct command line interface.......................................................... 37
Queued LCD messages................................................................... 38
Adding LCD messages .................................................................... 38
LCD message display options.......................................................... 40
Reader Response Questionnaire ....................................................... 42

6
Chapter 1
Customization
Introduction
The Toshiba Magnia SG20 is a multifunction server appliance, designed to provide ease
of use and a friendly setup and management environment. The appliance is based on
Red Hat Linux 7.3. 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 a single Internet port, dialup or broadband)
❖Firewall

Customization Introduction 7
❖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 ensure that the preset factory configuration is not modified
without care. 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 the new system. This guide outlines some basic
areas of which you should be aware, and provides some techniques for customizing the
system while maintaining a favorable customer out-of-box experience.
The Magnia SG20 uses a custom Web-based interface and a set of middleware tools to
enable the end user to manage the system. The internal mechanisms of this middleware
use unique methods to manage system configurations, such as template-based
configuration files and triggers. Direct modification of configuration files is not
recommended. This guide contains information about the internal management
techniques and how you might take advantage of them during your application
integration process.

Customization Customization overview 8
Customization overview
Before beginning the process of customizing a Magnia SG20 image, you can capture the
clean, unmodified image on another hard disk. Doing so enables you to reinstall a
factory-fresh image if you need to restart the integration process. See Custom image
backup on page 13 for more information.
Generally, the process of installing a custom application involves three basic steps:
❖Identifying and installing added Linux-based software to support your integration
process, such as libraries, newer versions of standard Linux software, or custom
support software.
❖Moving your application files onto the Magnia SG20 and installing it if necessary.
❖Optionally, adding links or Web pages to the Magnia SG20 Web-based administration
or preinstalled intranet pages.
Accessing the Magnia SG20
For most customization, installation and modifications access the system directly using
Telnet, using a shell command prompt. You can accomplish almost any task from this
environment.
Access the Magnia SG20 by performing the following steps:
1Set 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. When this has been
verified, bring up a command prompt and run Telnet:
telnet 192.168.1.1
2When the Linux login prompt appears, use the account “telnetuser” with the default
password “toshiba”.
3When at a shell prompt, you can switch to the root account using the su command.
4When at a root command prompt, you can install, recompile or modify software for
your application integration.
Copying software to the Magnia SG20
When 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. You can copy new software to the Magnia SG20 by using one of the following
protocols:

Customization Customization overview 9
❖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 the 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. When 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 the 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
When 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.
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

Customization User accounts and passwords 10
User accounts and passwords
Default accounts and passwords
The Magnia SG20 is delivered with three predefined accounts:
❖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 logs in to the system using Telnet. While not encouraged for
the typical end user, for developers it represents an important method of access to
the system.
❖root: This is the standard linux root administrative account with complete system
privileges.
All accounts are assigned a default password of “toshiba” when delivered from the
factory. Changing this password is not recommended, because doing so can make it
difficult or impossible for the end user to log in and administer the system.
Initial account creation
To assure that the default password for critical privileged accounts such as
applianceadmin are changed, the Magnia SG20 uses a specific mechanism to update
the password when the server is initialized. 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 a new Magnia SG20, turn it on, and connect
a PC to the built-in network. The user then runs the Setup CD to configure the client PC.
During the Setup CD setup process, the Setup CD software creates a new level 3
account on the server (for example, “jsmith”). The user also selects a password at this
time (for example “maxmoney1”). This process changes the passwords for the
predefined accounts to “maxmoney1”.
NOTE: Do not change the default passwords of the system.
NOTE: Do not create a new user on your Magnia SG20 using the Setup CD or the
Administrative Web interface. Use the existing applianceadmin account to access
the Web Administration or to access Network Neighborhood. Use the existing Telnet
and root accounts to access the system using Telnet. Modifications to the system
internals can be accomplished using these accounts.

Customization Server setup wizard 11
This process of assigning an initial user account password to the three predefined
accounts takes place when the first user account is created. The creation of subsequent
user accounts does not affect account passwords.
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, the software checks to see if the server is in its unconfigured,
uninitialized state. If it is connected to an uninitialized system, the Setup CD software
activates the Server Setup Wizard upon completion of the client setup.
Server Setup Wizard
When the user has completed the Server Setup Wizard, the system is flagged as
initialized, and subsequently the Server Setup Wizard no longer appears.
NOTE: This process will take place when creating an account using either the
Magnia SG20 Setup CD, or using the Administrative Web interface.
NOTE: Do not run the Client Setup CD. This activates the Server Setup Wizard, and
the system will no longer be flagged as uninitialized.

Customization Network configurations 12
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. If you do not, unintended preset networking
configurations could be 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. You can reset this option
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
might become part of your final customized image (an ease-of-use feature of the Magnia
SG20 UI). However, this can result in the end user viewing your account (the password
will be masked) if they configure modem access.
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 to their factory defaults if required.
You can even change these settings to your own preferred setting for shipment.
NOTE: 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.

Customization Custom image backup 13
Custom image backup
When implementing the custom image, it is easy to make a mistake, requiring you to
restore the system to a factory-original state, or recover it from an earlier version of your
custom image. The easiest and best way to create an earlier version of your custom
image 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 takes a complete snapshot of the entire disk and places 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, switch the primary and secondary disks and boot
from the snapshot backup. Do not forget to re-snapshot the drive.
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.
NOTE: 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.

Customization Software upgrades support 14
Software upgrades support
The standard retail version of the Magnia SG20 is supported by a Software Upgrades
site that allows end users to view, download and apply new features and fixes. This site
services customers using the standard Toshiba preinstall image only.
Because Toshiba does not control the changes or configuration of your preinstall image,
each system integrator has its own Software Upgrades site. Toshiba might occasionally
inform you of a software upgrade available on the standard site that you can make
available to end users with your custom image. It is your decision whether Toshiba
should deploy the upgrade to your customers.
To provide an Upgrade Site specific to your preinstall images, Toshiba edits a file on your
image to point to the custom site before releasing the image to the factory. If you wish to
retest your image after this change, or if you do not want Toshiba to make this change,
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 very little infrastructure
for the support of the Magnia SG20 system. User private data and the public share, as
well as user posted Intranet information are stored here. The /home directory contains
the following subdirectories:
Partition Description Size
/ Root (system) partition 1 GB
/var Scratch file partition, email, log files
and other temporary data
1.2 GB
/home User data Expands to fill the
remaining amount of disk.
Swap Partition Swap area for memory pages 120 MB
Directory Description
/home/backups This directory is a temporary location for data backup
processing.
/home/docs This directory contains documents posted for viewing using the
Magnia SG20 preinstalled intranet.
/home/ftp This directory contains the FTP applications subdirectories,
such as “incoming” and “public”.

Customization General system architecture 15
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 in the following figure:
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 template-based
configuration files, and invokes triggers to regenerate the system configuration files and
restart any services when 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.
❖Template-based configuration files contain the basic information about many of the
system’s actual configuration files. These templates are read by triggers, and are
used to regenerate the system configuration files when certain events occur.
/home/intranet This directory is a premapped location for a customized
intranet. You can reach it using the URL
http://myserver/intranet. You can easily create your own
intranet site by placing the Web pages here.
/home/public This directory is the open, public directory in which users can
share files.
/home/users This directory contains the individual private subdirectories for
each user with an account on the system.

Customization General system architecture 16
The file system reflects the following elements in its directory organization:
Directory Description
/sa2/templates This directory contains the configuration file templates
that are used to regenerate the system configuration
files.
/sa2/lang This directory contains the HTML and other files used to
generate the actual Magnia SG20 user interface are
contained in this directory. Because the Magnia SG20
can support multiple languages, this area of the system
is separated into various language directory trees. For
example, the “/sa2/lang/en” tree is used to support
English.
/sa2/triggers This directory contains the trigger scripts invoked to
perform system reconfiguration and other maintenance.
/sa2/firewall This directory contains definition files for special firewall
rules. By adding new directories and files here, you can
add your own optional firewall rules.
/sa2/conf This directory contains all the Magnia SG20 specific
configuration files. These configuration files are specific
to the Magnia SG20 implementation. These
configuration files do not replace the standard Linux
configuration files. The primary configuration file of
interest is “main.conf”, which is the central file in which
most configuration items from the user interface are
placed.
/sa2/lib This directory contains Perl and other modules used as
general routines to support the CGI code and other Perl
programs.
/sa2/web The Perl scripts, Java scripts, graphics and other Web-
based CGI code driving the Magnia SG20. Web sites
represented here are:
- System Administration (/sa2/web/admin)
- Preinstall Intranet (/sa2/web/intranet)
/sa2/firewall This directory contains subdirectories for each custom
firewall rule. Each subdirectory corresponds to a firewall
rule the user can enable or disable through the advanced
firewall settings option in the Web administration UI.
/sa2/log This directory contains logs specific to features
implemented in the Magnia SG20 user interface. The
logs in this directory do not replace the standard Linux
application logs typically contained in /var.
/sa2/bin This directory contains general utility scripts and
programs used by the Magnia SG20 to interface with the
Linux system and the system hardware.

Customization Customizing the firewall 17
Customizing the firewall
The Magnia SG20 contains firewall based on Linux IP Tables. 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. 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 passthrough, and Internet gaming. Adding custom firewall rules
in this area is the preferred method for customizing the Magnia SG20 firewall.
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.
1Create a new directory under /sa2/firewall, using a name relating to the new rule you
are adding. For example:
/sa2/firewall/vpnport500
/sa2/upgrades This directory contains information about the current
state of the system’s software upgrades. Because this
area is downloaded from, and communicates with, the
Toshiba Software Upgrades site, it is a good idea not to
modify it. If your preinstall image is sent to the Toshiba
factory, Toshiba changes a file in this directory to point to
a custom software upgrade Web site for your company.
CAUTION: Modifying the firewall rules is not recommended unless you are
experienced with IP Tables and firewall definitions. Adding inappropriate rules
added to the firewall can cause your system to become completely inaccessible,
require you to return the disk to the factory for re-imaging. Use care when
establishing new firewall rules.
NOTE: Take a disk snapshot before changing or adding custom firewall rules, so
that you can restore the system if needed.

Customization Customizing the firewall 18
2In 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 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 -%]
3Create a new file description in the directory, containing a short (less than one line)
description of the rule to be added. This description is displayed on the user
interface next to the check box. An example description is:
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 Dutch. If a language is invoked on the user interface, and there is no
corresponding language text in the description file, English is used as the default.
4Create 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
5Finally, create a new file called “type” in the directory, containing the word “client”,
"server” or “both”, that is used to describe to whom the firewall rule applies. An
example type file might be:
client
After these steps have been performed, a new selectable firewall rule is added to the
user interface.
A very easy way to get started with a new firewall rule is to use one of the existing firewall
rule directories. Copy the directory and its contents to a new directory name, and then
begin modifying the individual files to change the rule display name and the IP Tables
rule.

Customization Template-based configuration files 19
Template-based 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 (for example when a user is added or a configuration changed). When
a change has been made, a trigger is invoked, which regenerates the corresponding
system configuration file using the configuration file templates.
Because these template-based 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 does 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 in the following table:
The configuration file may be broken up into 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.
05system 15ftp 15postgress footer
10static 15mysql 20dynamic header

Customization Template-based configuration files 20
To place additional 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.