[View README.rtf] 


PPPMonitor.app (version 1.16)
by Martin D. Flynn (mflynn@best.com)

This is an application I wrote to facilitate my connection to my Internet provider.  If you find it useful, please let me know.

PPPMonitor provides a simple interface for managing your PPP connection (eg. using ppp-2.2).  This is accomplished by executing and monitoring the PPP script files that you normally use to bring up, or take down, your PPP connection.  The following features are available on the monitor panel:
	- Simple Connect/Disconnect.
	- Auto-reconnect option (if connection fails).
	- Will load PPP LKS (loadable kernel server) if necessary (special configuration required).
	- Periodic execution of a specified command.
	- A miniature shelf to hold your network application.
	- Scroll view to monitor the contents of the PPP log file.
	- Display 'connect-time'.

Possible features in future releases:
	- Ability to select between several 'connect' shell scripts.
	- Drag/Drop of apps onto the mini-shelf.
	- Allow 'Disconnect' when the connection was established outside of PPPMonitor.

This is the first public release of PPPMonitor, so you will likely find conditions under which I have not tested the application.  The PPPMonitor application is provided with source code and comes with no warranty of any kind, and the user assumes all responsibility for its use.  But please let me know if you find areas that need improvement or need fixing.  Some features still being considered: multiple connect shell script selection, drag/drop of apps to mini-shelf.

v1.15 fixes a problem that could cause v1.14 to 'hang' in some situation when clicking '(stop)' before the 'Connect' has had a chance to complete.

v1.16 fixes a potential problem that could cause the connect time clock to stop (the connection was uneffected).  Also, the documentation was changed to show the proper arguments to the ping command (see below for proper arguments).

Building and Configuring PPPMonitor to work on your system:
It is assumed that you already have working PPP connect/disconnect command scripts. PPPMonitor simply makes it easier to work with and monitor your PPP connection.

PPPMonitor.app is provided as source, so you may need to compile the application before using it.  The first time you run PPPMonitor on your system, the Preference panel will be displayed. The following options which may be set through the Preference panel should provide all of the customization necessary to work with the PPP setup on your system.

Command: (eg. "/usr/local/bin/pppup")
This specifies the command script to execute when "Connect" is selected.  This script will typically contain the '/usr/local/bin/pppd' command and arguments.  It is important to make sure that the '-detach' argument has been specified specified to prevent pppd from being backgrounded.  (Note: "-detach" really means "don't detach").  An example of the 'pppup' script is available in 'PPPMonitor/bin' directory.
Sound: (eg. "Bullfrog")
This specifies the sound to play when connection has been established.  Omit this option to disable the connection sound.
Show Connect Time on Application Icon: 
This specifies whether the connect should also be displayed on the Application icon.

Command: (eg. "/usr/local/bin/pppdown")
This specifies the command script to execute when "Disconnect" is selected.  This script typically contains code to kill the pppd process.  An example of the 'pppdown' script is available in 'PPPMonitor/bin' directory.
Sound: (eg. "Glass")
This specifies the Set sound to play when connection has been broken.  Omit this user default to disable the disconnection sound.

Tail PPP Log File
Command: (eg. "/usr/ucb/tail -1f /usr/adm/ppp2.2.debug")
This specifies the command to tail the PPP log file present in the '/usr/adm' directory (the "tail" command is used here, but you may wish to provide your own log file filtering command). This command produces the output present in the scrolling text view.  You may need to change the name of the log file to match the one used on your system.  (Alternatively, you may also specify just the fully qualified log file path. The file must be specified as residing in the directory  "/usr/adm/".  ie. "/usr/adm/ppp2.2.debug")

Periodic Command
Command: (eg. "/etc/ping remote.host.com 64 5")
Interval: (eg. "180")
These specify the command to execute periodically to ping the PPP server.  My Internet provider drops the line if it appears quiet for more that 5 minutes.  This command seems to work for me (The above example pings the remote host 5 times only with a 64 byte packet size).  'Interval' specifies the _rough_ time interval in seconds.  The minimum specified interval is 60 seconds.  If the interval user default is not specified, the default interval is 180 seconds. Omit this option to disable this feature.  (Note: the output from the command will not be printed.) 

MiniShelf Apps/Commands
This specifies the list of applications or commands to display on the mini-shelf of the PPPMonitor  window (Sorry, no drag'n'drop yet.).  Each application/command should appear on a separate line and should not contain any semi-colons.
Commands (non-applications) may be specified with the following syntax:  
	(optional_title)<commandPath> <arguments>
	(Telnet)/usr/ucb/telnet somehost.com
The optional title should be between 1 to 10 characters.  If the title is omitted, then the command name will be substituted.  The title will be displayed on the button in the mini-shelf.  When a command button is selected (double-clicked) on the mini-shelf, a terminal shell window will be opened and the specified command with it's arguments will be entered.

Load PPP LKS Command
Command: (eg. "/usr/local/bin/LoadPPPDriver")
If you do not already load the PPP driver at boot time, this command can be used to load it automatically the first time you trying connecting to your PPP server.  The source file "LoadPPPDriver.c" has been included for this purpose.  This source file must be compiled and set to run as suid 'root' (how to do this is described in the source file itself), then placed in the directory "/usr/local/bin" (or some other 'root' protected directory).  Read the source file "LoadPPPDriver.c" for more information.

Running PPPMonitor:
Once everything is properly configured, just click "Connect" and your connection script will be executed.  The "Connect" title will then change to "(stop)" while waiting for the conenction to be established.  Once the PPP connection has been established it changes to "Disconnect". (Right now there is no way to 'Disconnect' connection made outside of PPPMonitor.)

If you wish PPPMonitor to re-attempt failed connections, then select "Auto-reconnect" ("Auto-reconnect" can be selected any time before or during the initial connection, and will be de-selected when "Disconnect" is manually pressed).  If the connection should fail for any reason, the PPP Control Panel is made-key and ordered-front, then the connect script will be re-executed. 

Any log information sent to your ppp log file may be viewed in the log scroll view.  If you do not wish to view the log information, you may resize the window so that only the mini-shelf and message bar are visible.  The log information is still being written to the scroll-view and may be seen at anytime by resizing the window to make it visible again.

If you have a color monitor and would like the mini-shelf tiles to look just like the Workspace 'Dock', then enter the following user default variable definitions at a command prompt (then re-start PPPMonitor.app):
	% dwrite PPPMonitor MiniShelfTile Yes
	% dwrite PPPMonitor MiniShelfDots Yes

These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.