There are several options when it comes to placing IMSpector within your network.

IMSpector is normally run on the routing machine in the network. This would typically be the Linux box shoved in the corner doing NATing onto an Internet connection. This machine would normally be performing NAT for the network, but does not have too. IMSpector should in theory run on a machine that is doing bridging. Basically it wll run anywhere that a webproxy could be used to do transparent proxying. Please note that the clients themselves do not have to be routed directly through the IMSpector host; they might alternativly be HTTP proxying through a webproxy such as Squid, situated behind the NATing machine running IMSpector.

Under Linux at least, it can also be ran on a machine which is running a webproxy such as Squid, which IM clients are connecting through. This mechanism also works for other proxies, such as SOCKS. This could be used, for example, to host a central IM logging service for use by a client anywhere on the Internet.

Finally, using IMSpector's built-in HTTP proxy, you can configure your client to HTTP proxy through IMSpector directly. This does not require any iptable redirects, and would work nicely if the IM client and IMSpector were running on the same host.

System requirements are minimal, although with a large number of local users IMSpector will fork many copies of itself (a typical MSN connection can consist of a dozen or more concurrent connections).

Download the code, and untar. Currently there is no configure script, so you must configure the Makefile by hand (if needed) and run make. There are no dependancies beyond a working C++ compiler, unless you are planning to use a SQL logging plugin. Please note that GCC prior to v3 is known not to work due to its incomplete STL implementation. In the event that you wish to build the SQL logging plugins, you will also need the client libraries. Please note that v3 of MySQL will probably not work with the MySQL plugin. The SQLite plugin requires the sqlite3 client libraries and headers to be installed.

The Makefile, trivial that it is, contains one variable, PREFIX that you can set to the target dir of the install. The default is /usr, which is probably okay for most people.

By default, IMSpector will link against openssl and assume that the headers and libraries are under /usr. If you have an openssl install in a non-standard location, or you do not requre SSL support, please modify the Makefile accordingly.

Note that if you chagne the PREFIX value (say to /usr/local) you will need to adjust the plugin_dir config option to tell IMSpector where to look for plugins.

To build IMSpector under BSD, follow the instructions in the Makefile.

make
sudo make install

If you require SSL support (ie. monitoring of SSL IM sessions) then you will require a CA certificate. The Makefile includes commands for making a simple CA certificate that is valid for 1 year:

sudo make install-ca-cert

IMSpector is capable of setuid-ing to a non root user (indeed it has no requirement to run as root, or even be started as the root user), but the install target does not currently attempt to make a special user. Thus the default config will run as the whatever use started the program. This kind of "tidying up" is on the TODO.

This will install the files as follows, assuming a PREFIX of /usr:

    * /usr/sbin/imspector - the imspector binary.
    * /usr/lib/libimspector.so - a shared library that the main program and plugins share.
    * /usr/lib/imspector/*protocolplugin.so - the protocol plugins.
    * /usr/lib/imspector/*loggingplugin.so - the logging plugins.
    * /usr/lib/imspector/*filterplugin.so - the filtering and content-manipulation plugins.
    * /usr/etc/imspector/imspector.conf - an example config file, good enough for quick playing.
    * /usr/etc/imspector/badwords.txt - an example list of swear words to block.
    * /usr/etc/imspector/acl.txt - an example of a trivial and useless ACL.
    * /usr/etc/imsepctor/servercert.pem - optional server ssl certificate.
    * /usr/etc/imspector/serverkey.pem - optional server ssl key.
    * /usr/etc/imsepctor/cacert.pem - optional ca ssl certificate.
    * /usr/etc/imspector/cakey.pem - optional ca ssl key.

Note that the plugins are loaded at runtime and can use config file entries. The plugins loaded will be logged to syslog.

After compiling and installing IMSpector, the following iptables rules are required to transparently proxy the various IM ports. This is required if you are using transparent proxying. You can of course choose which protocols you wish to proxy into IMSpector:

    * MSN: iptables -t nat -A PREROUTING -p tcp --destination-port 1863 -j REDIRECT --to-ports 16667
    * Jabber: iptables -t nat -A PREROUTING -p tcp --destination-port 5222 -j REDIRECT --to-ports 16667
    * Jabber over SSL: iptables -t nat -A PREROUTING -p tcp --destination-port 5223 -j REDIRECT --to-ports 16667
    * ICQ/AIM: iptables -t nat -A PREROUTING -p tcp --destination-port 5190 -j REDIRECT --to-ports 16667
    * Yahoo: iptables -t nat -A PREROUTING -p tcp --destination-port 5050 -j REDIRECT --to-ports 16667
    * IRC: iptables -t nat -A PREROUTING -p tcp --destination-port 6667 -j REDIRECT --to-ports 16667
    * Gadu-Gadu: iptables -t nat -A PREROUTING -p tcp --destination-port 8074 -j REDIRECT --to-ports 16667

If you are also running a webproxy, like Squid, or a SOCKS proxy, on the same machine which is operating as your network gateway, you can also redirect the outgoing Squid traffic into IMSpector:

    * MSN: iptables -t nat -A OUTPUT -p tcp --destination-port 1863 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667
    * Jabber: iptables -t nat -A OUTPUT -p tcp --destination-port 5222 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667
    * Jabber over SSL: iptables -t nat -A OUTPUT -p tcp --destination-port 5223 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667
    * ICQ/AIM: iptables -t nat -A OUTPUT -p tcp --destination-port 5190 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667
    * Yahoo: iptables -t nat -A OUTPUT -p tcp --destination-port 5050 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667
    * IRC: iptables -t nat -A OUTPUT -p tcp --destination-port 6667 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667
    * Gadu-Gadu: iptables -t nat -A OUTPUT -p tcp --destination-port 8074 -m owner --uid-owner 100 -j REDIRECT --to-ports 16667

Here, 100 is the User ID which the webproxy or SOCKS proxy is running as; replace it as appropriate to your system. This is needed to stop a cyclic loop whereby IMSpector's outgoing packets to the IM servers are themselves fed into IMSpector.

These commands will obviously have to be run in your startup script.

For an inital test, run the program in debug mode:

imspector -d

Login to MSN and you should see some debug output. Finally, send someone a message and it should be logged both on the console and into a logfile within the logging directory. Rerun the program without the -d switch to force it into the background.

Also included in the code archive (contrib directory) is a CGI, imspector.cgi. This CGI is a log viewer of IMSpector logs, written in perl. It has no dependancies other then a working perl installation and should be installed under a webserver's cgi-bin directory. Before deployment, the script should be edited and the configuration variables (set at the top of the file) changed to match your installation. If you are feeling adventerous, the script can also be customised and the colours changed etc. Please note that this viewer can only view text file logs, and is not able to view logs stored in a database.