ULTRA MONITOR
SERVER SETUP GUIDE
  • Works with OSXTM, linux, and unix servers
  • Can run as a CGI under your current webserver
  • Can run as its own stand-alone server
  • Stand-alone server supports efficient concurrency
  • TEST and DEBUG mode built-in
  • Works with or without configuration
  • Full source code with in-line documentation
Table of Contents

  • Requirements
  • Downloads
  • Compiling
  • Testing
  • Install as CGI
  • Install as Server
  • Configuration
  • Security
  • PROBLEMS

  • REQUIREMENTS

    The server-side software for ULTRA MONITOR should work with most any installation of OSX, linux, and unix. This includes the following platforms:

    • OSX Snow Leopard, Leopard, Tiger
    • Debian
    • Solaris (sparc)
    • SUSE
    • Ubuntu

    If your particular platform is not listed above, go ahead and try it anyways - there is a good chance that one of the make methods will work - and we can assist as well.

    Note that if you do make changes to the Makefile or code to make it compile on a platform we do not list, please let us know the changes so we can incorporate it into the public code base.

    To build the code yourself you will need a compiler and make environment:

    • For OSX development:
      Go to the OSX App Store and download and install the free XCODE development system. Once you have installed the XCODE development system, run it and follow these steps:

      1. In XCODE open the XCODE pulldown and select Preferences
      2. In the Preferences window, click on the Downloads tab
      3. In the Downloads window, click on the Components tab
      4. In the line that reads Command Line Tools click the Install button. Wait for the tools to download and install.
    • For linux/unix development:
      We prefer the gcc compiler, though you can easily modify the Makefile to use another compiler. gcc is available for free from the Free Software Foundation. You will also need a standard make program (gcc includes one).

     


    DOWNLOADS

    The Server Side Ultra Monitor software is available as source code.

    ULTRA MONITOR
    Source Code Download

    Latest Version
    Version 1 Updated
    For Ultra Monitor App Version 2.0

    All Platforms (click to download):

    Once you have downloaded the source code double click the file to open it. The file will expand to a directory. The directory contains all the source and Makefiles you need.

    If you are extracting the archive from a unix/linux command line (as opposed to double-clicking), use the following commands:

      gunzip ultramonitor_2.0.tar.gz
      tar -xvf ultramonitor_2.0.tar

    Once extracted, the ultramonitor directory will contain:

    • um.c - This is the server-side ultramonitor source code.
    • Makefile - This is the makefile that compiles the source code.
    • README - A README file that contains instructions.
    • um.conf - An example configuration file.
     

    COMPILING

    Assuming you have XCODE (for OSX) installed or the proper GCC environment (for linux/unix) you are ready to compile the Ultra Monitor source.

    To compile, follow these steps:

    1. Open a terminal window (shell)
    2. Navigate using cd into the ultramonitor directory.
      For example, if you are on OSX and you extracted the directory on your desktop, open up the Finder and click on the Utilities folder and then scroll down to Terminal and double click it. Once Terminal has opened, type the following command:
        cd Desktop/ultramonitor
    3. Type:
        make
      And you should see this:
        To compile Ultra Monitor use one of the following 'make' syntax:
        make osx     - For any OSX (Mac) computer
        make solaris - For any older Solaris (Sun) computer
        make linux   - For most flavors of Linux (suse, debian, ubuntu, etc)
      Select the proper syntax from the list and type it in. For example, if you are a Linux (say ubuntu) server, type in:
        make linux
      You should see this:
        gcc -O -Wall -c um.c
        gcc -o um um.o -lrt -lnsl
        strip um
        rm um.o
    4. After a successful make, there should be a file named um

      If the make failed, try one of the other syntax. If all fail and you can not figure out why, contact us with the error you are receiving.

     

    TESTING

    It is very important to test Ultra Monitor on your server prior to purchasing the iPhone/iPad Ultra Monitor application.

    This section will show you how to test and verify that Ultra Monitor will work properly on your server.

    NOTE that no configuration files are needed for this step.

    Once you have successfully compiled your own copy from our source code, you are ready to test the program to make sure it works as it should.

    The ultramonitor directory should contain a binary file named um. To test the program, type this:

      ./um test
    If the program is working properly, you should see something that looks like this:

      Ultra Monitor Test Mode
      -----------------------
      
          Version: V1 (UPDATED)
       Time-Stamp: 1258568970
              CPU: 0.05% (yellow=1.50%, red=3.00%)
        Partition: root 21.93% used (alert=-1.00)
          Process: 33 http (min=-1 max=-1)
          Process: 2 mail (min=-1 max=-1)
          Process: 0 cgi (min=-1 max=-1)
             User: george x1
             User: judy x2
             User: robert x1
      
         Response: UMV1,1258568970,0.05:1.50:3.00,root:21.93:-1.00,http:33:-1:-1;
                   mail:2:-1:-1;cgi:0:-1:-1,george:1;judy:2;robert:1
      
      

    Something that looks simlar to the above indicates a successful test. Here are what the fields mean and what you should look for:

    Version:This is the current Version Number of the server side code. This is matched against an internal server-side version ID in the Ultra Monitor device application. Currently the Ultra Monitor App Version 2.0 uses Server-side code Version 1.0 UPDATED.
    Time-Stamp:This is the unix time_t timestamp (number of seconds since January 1, 1970). It should be a very large number.
    CPU:This is the current CPU load of your system. The number reported here should match the CPU load as shown by the unix 'w' or 'top' commands. This number is the first of the three load numbers reported by 'w' and 'top'. The 'yellow' and 'red' percents will be 1.50 and 3.00 if you are not using a custom configuration file (these are the default warning and alarm limits).
    Partition:Without a configuration file, the default setup is to show your root partition size (amount used). The (alert=-1.00) is the default alert level and a negative value turns partition alerts off.
    Process:Without a configuration file, the default setup is to look for 'http', 'mail', and 'cgi' processes and show the count. You should see all three of these lines (ignore the min and max values, they will be -1 with no configuration file). If you suspect that processes are not being counted properly, see the next section on DEBUGGING.
    User:Without a configuration file, the default setup is to show all users that are currently logged in. You should see one line per logged in user with the user name, and then a 'x' followed by a number. The number indicates the number of times that user is logged in. If you do not see users being counted properly, see the next section on DEBUGGING.
    Response:This is the final string that is formatted for delivery to the iPhone/iPad. This string should incorporate all the info shown in the test lines into one long line.

    DEBUGGING A PROBLEM

    If the output of your test did not look similar to the above, most likely the problematic areas are the PROCESSES and the USER information. These two fields require Ultra Monitor to use unix commands to examine the processes and the users in the system.

    The command Ultra Monitor uses to find processes is: ps -Ao comm=

    The command Ultra Monitor uses to find users is: who -u

    You can run Ultra Monitor in both TEST and DEBUG mode - this provides more information and will show you the entire output of the PS and WHO commands. Use this to identify if the command is incorrect:

      ./um test debug
    You should see output similar to this:
      PS Command: ps -Ao comm=
      sched
      /etc/init
      pageout
      fsflush
      /usr/lib/saf/sac
      login
      /usr/lib/sysevent/syseventd
      /usr/lib/sysevent/syseventconfd
      /root/web/apache/bin/httpd
      /usr/lib/utmpd
      /usr/lib/inet/xntpd
      /usr/sbin/syslogd
      /usr/sbin/cron
      /usr/lib/saf/ttymon
      /usr/local/sbin/sshd
      /root/web/apache/bin/httpd
      /root/web/apache/bin/httpd
      /usr/sbin/in.named
      login
      /root/web/apache/bin/httpd
      /root/web/apache/bin/httpd
      /usr/lib/sendmail
      
      WHO Command: who -u
      george pts/1   Nov 17 06:43 17:47  13846
      judy   pts/3   Nov 17 06:42  0:42  13834
      robert pts/4   Nov 15 15:13  5:28   9623
      judy   pts/5   Nov 18 11:08   .    14533
      
    The above will be followed by the TEST output (so you will need to scroll above the test output to see the above information).

    Note that the first thing shown is the result of the PS (processes). The PS command is displayed on the top line, followed by what it saw. Then the WHO (users) command will be displayed, followed by what it saw.

    The output will vary, depending on your platform, processes, and users... HOWEVER, the important thing is to look at the beginning of each line. The very first thing that should appear on the lines of processes, is the name of the process (it might have the path in it as well).

    The very first thing that should appear on the lines of users, is the name of the user (other stuff might follow, we ignore that).

    If either of the above do not look right, consult your unix MAN page for the "ps" and "who" command to see what options will produce the process/user name as the first item on the line. You can then modify the configuration file for Ultra Monitor to specify the proper commands to use.

     


    INSTALLING AS A CGI

    If the server you are monitoring already is running a web server (such as Apache, etc) you can integrate Ultra Monitor into the web server as a cgi-bin program.

    This has the following advantages:

    • Quickly integrates into your existing web server environment
    • Works with your existing HTTPS (secure) and HTTP (non-secure) protocols

    It also has the following disadvantages:

    • Because CGI invocation can be concurrent from different users, the more people you have monitoring your servers, the more concurrent requests for cpu, partitions, processes, and users are done. In general, this is not a big deal unless you have many people monitoring and very fast monitoring intervals.
    To install the um binary executable as a cgi-bin, simply copy the um binary executable into your web servers cgi-bin directory and make sure permissions of the executable are set so that your webserver can access it.

     


    INSTALLING AS A STAND-ALONE SERVER

    If the server you intend to monitor does not currently run its own webserver (e.g., Apache, etc) you can install Ultra Monitor as a stand-alone server.

    This has the following advantages:

    • No 3rd-party webserver is needed
    • Allows you to assign any port number for the server
    • Smart concurrency means that a large number of monitoring users do not cause simultaneous reading of cpu, partitions, disk, and users. When running Ultra Monitor in server mode, Ultra Monitor will only poll system resources on demand AND ONLY IF the previous poll was more than 10 seconds ago (otherwise the previous poll information is returned to the caller).

    It also has the following disadvantages:

    • Stand-alone server mode does not support HTTPS secure protocol.
    • Smart concurrency limits accurate data updates to no faster than once every 10 seconds.
    To install Ultra Monitor as a background process, specify the word server followed immediately by a colon and then the port number (server:port) on the command line and launch it into the background.

    For example, if you want the stand-alone server to listen for connections on port # 1234, you would launch it like this:

      ./um server:1234 &

    Notice the final '&' at the end of the line which causes the server to launch into the background. Replace 1234 with whatever open port you wish to use. Make sure the port is open in all firewalls through which you wish to access the port. If Ultra Monitor can not bind to the port, it will announce that at startup and will then exit (if this happens, either Ultra Monitor is already running on the specified port, or some other program is using the specified port).

     


    CONFIGURATION

    Ultra Monitor does not require a configuration file in order to work. Without a configuration file, Ultra Monitor uses the following defaults:

      Ultra Monitor configuration defaults

      • CPU monitoring defaults to ON and the Yellow (warning) cpu limit is set to 1.50% and the Red (alarm) cpu limit is set to 3.00%
      • Disk partition monitoring defaults to the root (/) partition. No alarm limit is specified.
      • User monitoring defaults to ALL LOGGED IN USERS.
      • By default the software looks for 'cgi', 'mail', and 'http' in the process list. No minimum or maximum limits are set.
      • By default, ALLOW restriction is turned off... all iPhone/iPad users are allowed.
      • By default, BLOCK restriction is turned off... all iPhone/iPad users are allowed.
      • By default, the PS command is ps -Ao comm=
      • By default, the WHO command is who -u
      • By default, the LOG command is turned off
    To supply your own configuration file, the configuration file MUST be named um.conf and MUST be in the subdirectory /usr/local/um (you will need to create this directory if this is a new installation):

    /usr/local/um/um.conf

    In the configuration file, blank lines, and any line starting with a pound sign (#) are ignored (use lines that start with # as comments).

    The following (alphabetical) table gives the syntax and complete description for all the Ultra Monitor configuration file commands:

    CommandSyntax / Description
    ALLOW ALLOW identity_string

    The ALLOW command lets you specify one or more Identity strings to restrict users using Ultra Monitor. This is opposite of the BLOCK command (see below).

    If no ALLOW command is encountered in the configuration file, all iPhones/iPads are allowed except for any that are blocked using the BLOCK command.

    If, on the other hand, one or more ALLOW commands exist in the configuration file, then ALL iPhones/iPads are blocked from using the program EXCEPT those that have matching identity_strings.

    Each iPhone/iPad you wish to allow needs its own ALLOW command with the identity_string for that device after it. For example:

      ALLOW DavesiPhone
      ALLOW TheNewSalesManagersiPad
      

    The above example will allow any iPhone/iPad with matching identity_strings. All other iPhones/iPads will be automatically blocked.

    The identity_string must contain only numbers and letters. It can not start with the word test or debug. There is a maximum of 40 characters for any identity_string.

    To set the identity_string on the users iPhone/iPad, run the Ultra Monitor application on the users device. In the app tap the SETTINGS button and then tap the Identity field. Enter the same identity_string and tap the DONE button.

    IMPORTANT NOTE

    In the previous version of the iPhone app (1.1) the identity_string was the iPhones UDID string and was automatically sent. This is now discouraged practice and we have replaced this concept with the identity_string concept.

    In the previous Server-Side code, the ALLOW command was called UDID. It worked identically to ALLOW but only allowed UDID strings. The updated version (1.0 UPDATED) of the Server-Side code replaces the UDID command with the ALLOW command but keeps the UDID command for backward compatibility (it now works like ALLOW).

    If you upgraded your iPhone/iPad application to 2.0 prior to upgrading the Server-Side code, and you were using either UDID or BLOCK, you will have experienced truncated data errors on your device. A temporary fix (prior to updating the Server-Side code) is to enter your devices UDID value into the Identity field in your devices Ultra Monitor application (SETTINGS pane).

    Note that Identity Strings are limited to 40 characters maximum.

    BLOCK BLOCK identity_string

    NOTE... the BLOCK command is no longer necessary and is only supported for backward compatibility. Using the ALLOW command will automatically block anyone not on the ALLOW list. If you use the BLOCK command as well, it will work to block anyone with a matching identity_string but is really not necessary.

    The BLOCK command lets you specify iPhone/iPad Identity Strings to block from using Ultra Monitor. This is opposite of the ALLOW command (see above). Each iPhone/iPad you wish to block needs its own BLOCK command with the identity_string after it. For example:

      BLOCK TheOldSalesGuy
      BLOCK TheAnnoyingGeekInAccounting
      
    The above example will block two iPhones/iPads based on the iPhones/iPads identity_string.

    Note that this is only useful when also using the ALLOW command. BLOCK lets you block users that used to have access to your system and may still have the identity_string setup in their devices. You could also just remove them from the ALLOW list (as long as you have other devices in the ALLOW list).

    IMPORTANT NOTE

    In the previous version of the iPhone app (1.1) the identity_string was the iPhones UDID string and was automatically sent. This is now discouraged practice and we have replaced this concept with the identity_string concept.

    In the previous Server-Side code, the ALLOW command was called UDID. It worked identically to ALLOW but only allowed UDID strings. The updated version (1.0 UPDATED) of the Server-Side code replaces the UDID command with the ALLOW command but keeps the UDID command for backward compatibility (it now works like ALLOW).

    If you upgraded your iPhone/iPad application to 2.0 prior to upgrading the Server-Side code, and you were using either UDID or BLOCK, you will have experienced truncated data errors on your device. A temporary fix (prior to updating the Server-Side code) is to enter your devices UDID value into the Identity field in your devices Ultra Monitor application (SETTINGS pane).

    Note that Identity Strings are limited to 40 characters maximum.

    CPU CPU on|off [yellow_limit [red_limit]]

    The CPU command lets you specify whether or not CPU load is to be monitored, and if so, whether or not yellow and red limits are specified. Use ON to turn CPU monitoring on (default) and OFF to turn CPU monitoring off. You can also specify a YELLOW LIMIT (this is a warning) and a RED LIMIT (this is an alarm) for the CPU percentages. If no limits are found, no limits are set.

      CPU on 2.0 5.0
    The above example will turn CPU monitoring ON and will place a yellow limit (warning) of 2.0% load and a red limit (alarm) of 5.0% load.
    DISK DISK name partition [used]

    The DISK command lets you specify which partitions should be monitored for disk used space. If no DISK command is specified, partition monitoring is diabled. To monitor partitions, specify a DISK command for each partition you wish to monitor. The name parameter should be a short name you wish to refer to this partition by (this will be displayed on the iPhone/iPad as the partition name). The partition parameter should be the actual name the partition is mounted on. The used parameter is optional. If not specified, no limits are placed on the partition. If used is specified, it should be a number that indicates the percentage of disk full at which an alarm is issued.

      DISK root / 80
      DISK user /usr
      
    The above two examples show two partitions being monitored. The first line is monitoring the '/' partition and is calling it 'root'. A limit of 80% used is placed on the partition (alarms will sound if the partition fills up to, or beyond, 80%).

    The second example is monitoring the /usr partition and has given it a name of 'user'. No limit is placed on this partition (no alarms will be sounded if it fills up).

    LOG LOG /path/filename

    If no LOG command is found in the configuration, no logging is performed.

    To use the LOG command, make /path/filename the path and filename of the log file you wish created and written to.

    When logging is in effect, all accesses to the program are logged as:

      mm-dd-yyyy hh:mm:ss identity_string message

    Where mm-dd-yyyy is the date of the access, hh:mm:ss is the time of the access, identity_string is the identity_string of the accessing iPhone/iPad and message shows the disposition (such as BLOCKED or OK or NOT ON ALLOW LIST, etc).

    Use this command sparingly! It can create large log files quickly if there is lots of access to the program.

    The primary purpose of this command is to be able to find out an abusive user who needs to be blocked or to find a new user who needs to be added to the ALLOW list. If you are not doing those two things, do not use the LOG command!

      LOG /tmp/um.log
    You can see that the above example LOG command will log access to a file in /tmp/um.log
    PROCESS PROCESS name pattern [minimum maximum]

    If no PROCESS commands are found in the configuration file, no processes are monitored. Otherwise, a PROCESS command should exist for each process you want monitored in the system.

    The name is a short name you want to assign this process, and is what is displayed to the user on the iPhone/iPad.

    The pattern is some sequence of characters (no spaces) that when found in a PS listing, will match this process. For example, if looking for sendmail processes, you might set this parameter to just mail. Any process with mail in the name (or path) will count as one of these processes.

    If minimum and maximum are not specified, no minimum or maximum number of these processes are required and no alarms will be issued. Otherwise, both minimum and maximum must be specified. The minimum value is the least number of these processes that should be running. If less than minimum are found running, an alarm is issued. The maximum value is the most number of these processes that should be running. If more than maximum are found running, an alarm is issued.

      PROCESS mail sendmail 1 15
      PROCESS cgi  cgi-bin  0 10
      PROCESS www  http     5 35
      PROCESS ssh  ssh 
      
    The above four examples show montoring of four processes. The first line will count all processes with sendmail in the process listing. The iPhone/iPad display will show this named as mail. An alarm will sound if less than 1 or more than 15 instances are running.

    The second line will count all processes with cgi-bin in the process listing. The iPhone/iPad display will show this named as cgi. An alarm will sound if more than 10 are found running at the same time.

    The third line will count all processes with http in the process listing. (Note that this will count http AND https). The iPhone/iPad display will show this named as www. An alarm will sound if less than 5 or more than 35 of these are running.

    The fourth line will count all processes with ssh in the process listing. The iPhone/iPad display will show this named as ssh. No limits are set and no alarms will be sounded.

    PS PS ps_command

    This command allows you to override the default PS command the program uses to find processes. ps_command should be the entire command line including the command.

    If no PS command is found in the configuration file, the following default PS command is used:

      PS ps -Ao comm=
    You can see that the above (default) PS command sets the ps command to ps -Ao comm=
    USER USER name name name...

    The USER command lets you specify which users you want to monitor for logged in status. If no USER command exists in the configuration file then user monitoring is turned off.

    You can list as many user names as you want to on each USER line. Simply separate them by spaces. You can also use multiple USER lines, each with as many user names as you want.

    You can also specify that all users should be monitored by using the asterisk (*) wildcard charactaer. You should only do this if your server does not have many users that log in.

      USER judy george robert

    The above example will only monitor users named: judy, george, and robert.

      USER *

    The above example will monitor all logged-in users.

    WHO WHO who_command

    This command allows you to override the default WHO command the program uses to find users. who_command should be the entire command line including the command.

    If no WHO command is found in the configuration file, the following default WHO command is used:

      WHO who -u
    You can see that the above (default) WHO command sets the who command to who -u

     


    SECURITY

    Generally, the server side Ultra Monitor software does not provide much information that can be used by people to break into a server. About the most dangerous thing that is transmitted is the list of logged in users (which you can disable).

    However, depending on how you run Ultra Monitor (as a CGI-BIN or as a stand-alone server), there are some steps you can take to make the environment even more secure:

      General Security Tips
      • Always create a configuration file (/usr/local/um/um.conf) and set the permissions such that only the program can read it.
      • Always use the ALLOW command in the configuration file to restrict which iPhones/iPads can access the server Ultra Monitor program. This does not guarantee security (because if someone knows someone elses identity_string, they can use it on their own device to fake access) - however, it will stop most unauthorized iPhone/iPad users from accessing your information. The BLOCK command is only useful if ALLOW is also being used (since ALLOW automatically blocks anyone not on the allow list).
      • Rename the 'name' used to show users both partitions and processes. For example, if you are monitoring for sendmail processes, name it 'mail' not 'sendmail' (this is the name shown the user on the iPhone/iPad). Likewise for non-standard partitions, give them a name that is not identical to the actual mount point.
      CGI-BIN Security Tips
        When running Ultra Monitor as a cgi-bin under an existing webserver, here are additional steps you can take to secure the environment:

      • The iPhone/iPad application lets you specify HTTPS or HTTP access. If you have a secure socket layer (SSL) setup with a valid certificate on your web server, you should consider only allowing iPhone/iPad access using the HTTPS (secure) method. This will encrypt ALL the information including any users identity_string number as well as the response from the server. This is the tightest security you can achieve.
      • Rename the cgi-bin 'um' to another name when you install it into your cgi-bin directory. The iPhone/iPad application lets you specify the cgi-bin name (it defaults to 'um' in the iPhone/iPad app, but you can change it). By making it something other than 'um' people will not automatically be able to guess the name of the program.
      Stand-Alone Security Tips
        When running Ultra Monitor as a stand-alone server, it is not currently possible to run it under SSL (secure socket layer), nor does changing the name of the program do anything useful. Instead, try these tips:

      • Run the program on a non-standard port.
      • Use the ALLOW configuration option to restrict iPhone/iPad access.

     


    PROBLEMS

    To see a list of frequently asked questions and troubleshooting tips, click here.

     

    home page | user manual | server setup | support | contact | download

    © 2012 David Cook.
    Apple®, the Apple logo, iPod, iPad, iPhone, and iTunes are trademarks of Apple Inc., registered in the U.S. and other countries.