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.

If you are going to build the code yourself (rather than use the pre-compiled binaries) you will need a compiler and make environment:

• For OSX development:
  Go to the Apple Developers Center and login (if you are not a registered developer you can become one for free). Once you are inside, download and install the latest XCODE. This will give you everything you need to compile the server side code.
• 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).

The Server Side Ultra Monitor software is available as source code and, for some platforms, as a pre-compiled binary. If a pre-compiled binary is not available for your platform, use the source code and build your own by following the instructions on this page.

Once you have downloaded either the source code or the pre-compiled binaries, double click the file to open it. No matter what you downloaded, each will be a directory. The directory contents are identical with the exception that the pre-compiled binary directories have the binary executable in them as well as the source.

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

gunzip ultramonitor.tar.gz
tar -xvf ultramonitor.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.
• In the case of a precompiled binary: um - The precompiled binary (simply named 'um').

NOTE: If you are using our pre-compiled binaries, you can skip this step and continue with the next step, testing.

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

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.

Once you have either downloaded a pre-compiled binary or 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

Ultra Monitor Test Mode
-----------------------

    Version: V1
 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 must match the Ultra Monitor iPhone application version number in order for it to be recognized.
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. 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

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

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.

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.

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.

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).

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, UDID restriction is turned off... all iPhone users are allowed.
• By default, BLOCK restriction is turned off... all iPhone 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

/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:

Command	Syntax / Description
BLOCK	BLOCK udid The BLOCK command lets you specify iPhone UDID (Unique Device ID's) to block from using Ultra Monitor. This is opposite of the UDID command (see below). Each iPhone UDID you wish to block needs its own BLOCK command with the UDID after it. For example: BLOCK a8b34179afb721833015579acbf524199ac2f3cb BLOCK 95827ac82bfa215e42accf15322f8523f2c5b1af The above example will block two iPhones based on the iPhones UDID.
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 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 UDID message Where mm-dd-yyyy is the date of the access, hh:mm:ss is the time of the access, UDID is the UDID of the accessing iPhone 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. 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 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 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 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 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=
UDID	UDID udid The UDID command lets you specify iPhone UDID (Unique Device ID's) to allow using Ultra Monitor. This is opposite of the BLOCK command (see above). If no UDID command is encountered in the configuration file, all iPhones are allowed except for any that are blocked using the BLOCK command. If, on the other hand, UDID commands exist in the configuration file, then ALL iPhones are blocked from using the program EXCEPT those that have matching UDID numbers. Each iPhone UDID you wish to allow needs its own UDID command with the udid after it. For example: UDID a8b34179afb721833015579acbf524199ac2f3cb UDID 95827ac82bfa215e42accf15322f8523f2c5b1af The above example will allow two iPhones with matching UDID's. All other iPhones will be automatically blocked.
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

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 UDID command in the configuration file to restrict which iPhones can access the server Ultra Monitor program. This does not guarantee security (because if someone knows someone elses UDID, they can write their own program to make it look like a fake iPhone access) - however, it will stop most unauthorized iPhone users from accessing your information. The UDID command is better to use than the BLOCK command because if UDID is being used, and the iPhone is not on the UDID list, it is automatically blocked.
• 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). 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 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 access using the HTTPS (secure) method. This will encrypt ALL the information including the users UDID 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 application lets you specify the cgi-bin name (it defaults to 'um' in the iPhone 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 UDID configuration option to restrict iPhone access.

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