# @(#)76 1.4 src/bos/usr/sbin/snappd/palm/README, snapp, bos720 3/15/01 18:04:27 # IBM_PROLOG_BEGIN_TAG # This is an automatically generated prolog. # # bos720 src/bos/usr/sbin/snappd/palm/README 1.4 # # Licensed Materials - Property of IBM # # COPYRIGHT International Business Machines Corp. 2000,2001 # All Rights Reserved # # US Government Users Restricted Rights - Use, duplication or # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. # # IBM_PROLOG_END_TAG THE SYSTEM NETWORKING, ANALYSIS AND PERFORMANCE PILOT (SNAPP) ============================================================= TABLE OF CONTENTS: ------------------ OVERVIEW ARCHITECTURE GETTING STARTED A. Installation B. Software Setup C. Hardware Setup D. Starting the SNAPP Application E. Using the SNAPP Application F. Exiting the SNAPP Application G. Problem Resolution H. Miscellaneous Notes EXTENDING SNAPP FUNCTIONALITY A. Example Script (SetDate.pl) B. Valid XML Tags C. Example Script (DoSetDate.pl) D. Incorporating New Functionality into SNAPP Application E. Summary of Steps OVERVIEW: -------- SNAPP enables basic RS/6000 network configuration from a handheld Personal Digital Assistant (PDA) via a serial line connection. The SNAPP application's primary purpose is to allow minimum IP address configuration on a newly pre-installed RS/6000, running AIX, that does not have a monitor or ASCII terminal and keyboard connected to it. It is assumed that once the AIX machine is on a network, access can be given to it through telnet, rlogin, or some other tcpip remote login command. This remote access may then be used to further configure the AIX system. Please note that the SNAPP application is not designed to replace a monitor or ASCII terminal. ARCHITECTURE: ------------ The SNAPP architecture is modeled after a simplified web architecture. Specifically, the SNAPP client runs on a handheld PDA and acts as a "browser" that knows how to send requests, receive responses, and display simple XML documents. The SNAPP server runs on the AIX system and is basically a "web server" that knows how to respond to requests from the client. Specifically, the SNAPP server will route the client's request to the appropriate perl script on the AIX system, which will perform the requested administrative function, and return the appropriate XML response page to the SNAPP client. GETTING STARTED: --------------- A. Installation ------------ The SNAPP application is contained in the bos.net.snapp fileset. This fileset is automatically installed on all pre-installed systems, running the AIX 4330-05 Recommended Maintenance Package. For existing AIX installations, you may install the bos.net.snapp fileset from the 10/2000 (or later) AIX Update CD. When the bos.net.snapp fileset is installed, all the necessary files for the SNAPP server are installed on the local machine. The SNAPP client binary must be installed on to a handheld PDA device that is compatible with Palm OS and has a Palm OS software level of V3.5.0 or above. You must copy the SNAPP client binary to a PC and install the SNAPP application as you would install any other handheld PDA application. Once the SNAPP client is installed, the SNAPP icon will appear as a light bulb with the word SNAPP beneath it. The SNAPP application consists of the following. Snapp.prc : The SNAPP client binary which runs on the handheld PDA. This binary may be obtained from the /usr/samples/snapp directory on the AIX system or from the AlphaWorks web site at the following URL. http://www.alphaWorks.ibm.com/tech/snapp *************************************************************** WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING *************************************************************** When transferring the Snapp.prc file from the web site or your AIX system, please make sure you use the BINARY mode to transfer the file to the system you will be using to download it to your handheld PDA. For example, when using ftp, specify "bin" or "binary" at the ftp prompt before transferring the file. If you use the ascii mode to transfer this file, you may get a Fatal Exception when you attempt to download the file to your handheld PDA. If this should occur, you can reset the handheld PDA as follows. 1. At the same time, press the "reset" button displayed in the Fatal Alert window and the up scroll button on the handheld PDA. Press both of these for a few seconds. When you let go, you should see your Preferences page. 2. Now, reload your handheld PDA with an uncorrupted version of the Snapp.prc file. *************************************************************** WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING *************************************************************** /usr/sbin/snappd : The SNAPP server which runs on the AIX system. This SNAPP server starts automatically, when the SNAPP client attempts to connect to the AIX system. The SNAPP server exits when the user exits the SNAPP client. /usr/sbin/snapp : The directory which contains the perl scripts used by the SNAPP server to perform administrative tasks on the AIX system. B. Software Setup -------------- On a new pre-installed system, no further software setup is required to use the SNAPP application. The tty0 on serial port 1 is already configured for use with the handheld PDA. For all other installations, further software setup is required to use the SNAPP application. The following steps describe the software setup needed. All of these changes are required to allow the SNAPP client to establish a connection with the SNAPP server. These steps are done automatically if the SNAPP application is used on a newly pre-installed system that does not have a console defined. - Configure the tty for the serial port you wish to use. Make sure, if the tty is not being used for the console, that login is enabled. Also add the "clocal" flag to the STTY attributes for LOGIN. - If the tty you configured in the previous step is not tty0, then edit the characteristics of user "snapp", so that the user recognizes the tty as a valid tty. C. Hardware Setup -------------- On a new pre-installed system, connect the handheld PDA to the RS/6000 by plugging the serial cable of the handheld PDA cradle into serial port 1 on the RS/6000. For all other installations, plug the serial cable of the handheld PDA cradle into the serial port you configured in the Software Setup section above. If the RS/6000 has an RJ-45 serial connection on the front of the system and you are using serial port 1, this port may be used with the appropriate RJ-45 to 9-pin connector cable supplied with your system. D. Starting the SNAPP Application ------------------------------ Once the serial cable of the handheld PDA cradle has been connected to the appropriate serial port, connect the handheld PDA to the cradle. Launch the SNAPP client by tapping on the SNAPP icon. Please note, when using the SNAPP application on a newly pre-installed machine that does not have a console defined, you must first complete the serial connection and power on the AIX system before launching the SNAPP client. The connection will take some time to complete, since the machine needs to boot first. E. Using the SNAPP Application --------------------------- Once you launch the SNAPP client, it will establish a connection with the SNAPP server on the AIX system. The SNAPP server will require that you provide the root password, if one exists, before you can use the SNAPP application to perform administrative tasks on the system. After you have successfully logged into the SNAPP server, you will see the Home page for the SNAPP application. This page and all other pages in the application contain three icons which are located in the upper right hand corner of the page. These three icons are "back", "home", and "reload", respectively. The "back" icon takes you back to the previously displayed page, the "home" icon takes you back to the Home page, and the "reload" icon causes the current page to be reloaded. The SNAPP Home page lists the available system administration tasks that may be performed. The following tasks are listed. Set/Reset Root Password Set Paging Space Network Setup Tap on the button pertaining to the task you wish to perform. Set/Reset Root Password If the AIX system does not have a password set for the root user (pre-installed systems will not have a root password), then this task will allow you to set the password. If the AIX system already has a root password, this task will allow you to change the password. Please note that due to the nature of the handheld PDA, the password will not be hidden when you enter it on the handheld PDA. Set Paging Space New pre-installed systems are configured with minimal paging space. In order to optimally run your applications on the system, it is recommended that you configure the paging space according to the amount of memory and disk space available on your system. This task may be used to increase the paging space available on your system. Recommended settings are provided for your convenience. Network Setup Network Configuration This task may be used to minimally configure a network interface on your system and test to see if it is setup correctly. You may use either minimum configuration, where you specify the exact IP addresses to use, or the Dynamic Host Configuration Protocol (DHCP) to configure a network interface on the AIX system. The minimum configuration task works like the Minimum Configuration selection in the SMIT administration tool on AIX. Minimum configuration should only be done on ONE interface in the system. Therefore, the SNAPP application's minimum configuration task should only be used to configure ONE interface on your system. Further interfaces may be configured, using a remote connection. The DHCP task allows you to configure a network interface to use the DHCP client. You will only be allowed to specify when you want the interface to be started and a hostname for the interface. With this task, you may configure more than one interface on your system. However, please note that for every interface configured, the dhcpcd daemon on the AIX system will be restarted. This means that all the interfaces will be brought down and required to request new IP addresses from their DHCP servers. This will cause applications using those interfaces to be disconnected from the network. The interface types which you may configure, using the SNAPP application, are the following. Standard Ethernet (en#) IEEE Ethernet (et#) Token Ring (tr#) A list of the interfaces available for configuration on your AIX system will be provided for you to choose from. Once you have selected an interface to configure, you will be able to enter either the specific configuration information or the DHCP information for that interface, depending on the method of configuration that you selected earlier. Network Status Once the interface has been configured, you may use this task to check the status of your network. This task consists of the Ping test. You may ping a hostname or an IP address to see if your network is setup correctly. If the interface you are trying to test was just recently configured to use the DHCP client, then your ping test may fail because the DHCP protocol has not had time to completely configure and bring up the interface. You may need to wait a few minutes for the network to become available. F. Exiting the SNAPP Application ----------------------------- If you tap the application icon on your handheld PDA, the SNAPP application will exit and you will be shown a listing of the applications currently installed on your device. G. Problem Resolution ------------------ The SNAPP server keeps a log file in /var/tmp/snapp.log. If the SNAPP server encounters a fatal error, it will log a message to this file and exit. If you are not using a new pre-installed system and the SNAPP client is unable to establish a connection with the SNAPP server, please review the software setup procedures outlined earlier in this document. H. Miscellaneous Notes ------------------ - Handheld PDA's do not provide a Carrier Detect signal to the serial port. Therefore, the tty settings for the serial port used to log into the system must be changed to include the "clocal" flag in the STTY attributes for LOGIN. This change is done automatically, when the SNAPP application is used for the first time on a new pre-installed system. This setting must be configured manually, if the system is not newly preinstalled. If you do not wish to have this flag set on the tty after the SNAPP application has been used, you will need to manually remove the flag from the tty settings. It will not be removed automatically by the application. Please note that once this setting is removed, the SNAPP client will no longer be able to connect to the SNAPP server. This tty setting should not interfere with the use of an ASCII terminal on the serial port. EXTENDING SNAPP FUNCTIONALITY ----------------------------- Additional system administration tasks may be added to the existing SNAPP product. This may be done through additional Perl/XML scripts. All the existing Perl/XML scripts that ship with the SNAPP product on the AIX system are installed in the /usr/sbin/snapp directory. Any additional scripts must be installed in this same location. The SNAPP server responds to a request to perform some task from the SNAPP client by running one of the scripts in /usr/sbin/snapp. Each script consists of some Perl code and some XML code. The Perl code usually performs some task in the AIX OS. The XML code determines how the results will be displayed on the handheld PDA. A. Example Script: SetDate.pl -------------------------- The following example script gets the current date of the local AIX operating system. The XML part of the script, will display this date and prompt the user to reset the date. Line numbers have been added for easy reference. However, these line numbers should not appear in your script. #----------------------------------------------------------------------- # Script: SetDate.pl #----------------------------------------------------------------------- # Line # Code #----------------------------------------------------------------------- 1 #!/usr/bin/perl 2 $ENV{'PATH'} = '/bin:/usr/bin:/usr/sbin'; 3 $currentDate = `/usr/bin/date`; 4 open(OUTFILE, ">/tmp/snapp.fres.tmp"); 5 print OUTFILE < 7 Reset the Date 8 150 9 12 10 5 11 40 12 13 15 14 10 15 16 15 17 5 18 19 35 20 15 21 55 22 23 150 24 5 25 15 26 27 15 28 35 29 30 20 31 135 32 50 33 34 65 35 36 37 EOXML 38 close(OUTFILE); 39 system("/usr/bin/cp /tmp/snapp.fres.tmp /tmp/snapp.fres"); #----------------------------------------------------------------------- # End of script SetDate.pl #----------------------------------------------------------------------- Lines 1 and 2 are required for your Perl script. If your script uses executables in directories other than the ones already defined in line 2, you must add the additional directories to the PATH definition. Lines 4-39 generate the information that the SNAPP server will send to the SNAPP client on the handheld PDA. All the XML code enclosed within (lines 6-36) will be transferred to the SNAPP Client which will display it on the handheld PDA. It will be displayed something like the following. Current Date: Mon Oct 16 12:33:02 CDT 2000 Set Date To: ___________ *Please set date using the format mmddHHMM[yy] ------ -------- | OK | |Cancel| ------ -------- Lines 4,5, and 37 are required to copy all the XML tags into a temporary file (/tmp/snapp.fres.tmp). Use of the /tmp/snapp.fres.tmp file is not required. However, the SNAPP server automatically cleans up this file, when it exits. So, if you use a different file, the SNAPP server will not know to remove it. Any information that is contained in the code between lines 5 and 27 will be placed in this temporary file and sent to the SNAPP client. Only valid XML tags and blank lines should be placed in this section of code. The XML section of the Perl/XML script (lines 6-36) include several interesting tags. The tags allow you to display text on the panel. The tags allow your script to obtain data from the user. The () tags create a button on the panel that, when selected, will cause the SNAPP client to request the SNAPP server to run the perl script associated with the button. In this example, the "OK" button is associated with a script called DoSetDate.pl. When this button is selected, the SNAPP client will request that the SNAPP server run the "DoSetDate.pl" script. The SNAPP client will send over the new, user entered, date as an argument for the script. Lines 38 and 39 are required to close the temporary file and copy it's contents to the official file to be transferred (/tmp/snapp.fres). The SNAPP server knows to look at the /tmp/snapp.fres file for information that needs to be sent to the SNAPP client. If you save your XML information to any other file, the SNAPP server will not know to send it. Finally, printing the XML information to a temporary file and then copying that file to the official transfer file may seem redundant. However, this eliminates a timing issue that can occur. The SNAPP server continuously looks to see if the /tmp/snapp.fres file exists. If it exists, the SNAPP server initiates the transfer of the file, regardless of whether or not the information in the file is complete. Once the SNAPP server, completes the transfer of the /tmp/snapp.fres information to the SNAPP client, the server removes the file. Therefore, if you directly print your XML information to the official file, you may end up sending only part of your information to the SNAPP client. This will cause your panel to be displayed incorrectly or not at all. B. Valid XML Tags -------------- The following tags are known to the SNAPP client and the SNAPP server. _Some_Number_Of_Tags_ Allows the SNAPP client to read a full page of XML information. All of the following XML tags MUST be included between these two tags for the SNAPP client to interpret them correctly. _title_name_ Sets the Title for the Page being displayed. This information will appear at the top of the panel. Creates a button which will activate a perl page when pressed. Creates a label with the specified text. _default_setting_ Creates a field where the user can enter data. The "_field_name_" can be any name that you want the field to be known by. The "_default_setting_" may be optionally added, so that the field is displayed to the user with a default value. If the "_default_setting_" is not defined, the field will be blank. The SNAPP client will use the FIELD tag to create an OBJECT tag to pass back to the SNAPP server. This OBJECT tag will be in the following format. The SNAPP server will take all the OBJECT tags received for a specific Perl/XML script and will extract the _field_name_ and the _user_entered_text_ . These are passed to the script as arguments in the following form. "_field_name_" "_user_entered_text_" ... _Number_Value_ Sets the Width of the Object _Number_Value_ Increases the 'W' value by _Number_Value_ _Number_Value_ Sets the Height of the Object _Number_Value_ Increases the 'H' value by _Number_Value_ _Number_Value_ Sets the position from the left side of the screen _Number_Value_ Increases the 'X' value by _Number_Value_ _Number_Value_ Sets the position from the top of the screen _Number_Value_ Increases the 'Y' value by _Number_Value_ Creates a Bar/Box for the user to enter input. Sets the attribute for Bar/Box to Hollow Bar. This creates a hollow box. Sets the attribute for Bar/Box to a Solid One. This creates a solid box. Creates a line. C. Example Script: (DoSetDate.pl) ------------------------------ In the SetDate.pl example explained above, when the user enters a new date and selects the "OK" button, the SNAPP client will request the SNAPP server to run the DoSetDate.pl script. The DoSetDate.pl script will set the new date on the AIX system. It will also send an XML page to the SNAPP client to display the new date that was set. Once the user finishes reviewing the results, they can press the "OK" button and be returned to the main menu. An example of this script is included below. In your script, you may want to add more error checking to verify that the user entered data is in the correct format before actually trying to reset the date on the system. #----------------------------------------------------------------------- # Script: DoSetDate.pl #----------------------------------------------------------------------- #!/usr/bin/perl $ENV{'PATH'} = '/bin:/usr/bin:/usr/sbin'; #----------------------------------------------------------------------- # main #----------------------------------------------------------------------- # Get the user entered data from the command line. Here, we have chosen # to create a hash table of the arguments, since the arguments are # given to the script in the form : # "field_name" "user_entered_value". # Now, we can access each entry, using the "field_name". %hshObjectTags=@ARGV; # Set the date $strNewDate = $hshObjectTags{"NewDate"}; $strNewDate =~ s/\n//g; $strNewDate =~ s/\s+//g; $strSetNewDate = system("/usr/bin/date $strNewDate"); $setnewDate = `/usr/bin/date`; # Output the results open(OUTFILE, ">/tmp/snapp.fres.tmp"); print OUTFILE < Reset the Date 150 12 5 45 15 15 50 135 50 EOXML close(OUTFILE); system("/usr/bin/cp /tmp/snapp.fres.tmp /tmp/snapp.fres"); #----------------------------------------------------------------------- # End of script DoSetDate.pl #----------------------------------------------------------------------- D. Incorporating New Functionality Into SNAPP Application ------------------------------------------------------ Once you have created your scripts to request information from the user and perform some task on the AIX system, the existing SNAPP menu needs to be modified to include a button for this new functionality. The menu serves as a link or launching pad to get to the new function. The main SNAPP menu resides in the Home.pl script. For example, add the following lines to the existing /usr/sbin/snapp/Home.pl to add the "Reset the Date" function. 25 So, the SNAPP menu will now include a button the user can select to set the date on the AIX system. When the user selects the button, the SNAPP client will inform the SNAPP server to run the "SetDate.pl" script. E. Summary of Steps ---------------- There are three steps that must be taken to add new functionality to the SNAPP product. Step 1. Create a script that will setup the request and prompt the user for any user data that will be needed to perform the task. Step 2. Create another script that will take the user entered data and perform the required task. Step 3. Add a BUTTON to the Home.pl that references the script created in Step 1. In our examples, two scripts were created to complete the task of setting the date. The first script (SetDate.pl) set up the request and prompted the user for the new date. The second script (DoSetDate.pl) used the user data to set the date on the AIX system and send back the result to the user. Finally, a BUTTON tag was added to the Home.pl script that referenced the SetDate.pl script.