|
Introduction
By default IMSpector will read the file
/etc/imspector/imspector.conf but this can be changed at
runtime with the -c /path/to/imspector.conf switch.
IMSpector will always fork into the background when started, unless it is
running in debug mode with the -d switch.
General options
port=16667
This option sets the listening port, and is the port that a redirect rule
should point outgoing connetion requests too. 16667 is the default
port, for historical reasons (IMSpector started out as an IRC-only
proxy).
plugin_dir=/usr/lib/imspector
Sets the directory that IMSpector will look in for its various
plugins. /usr/lib/imspector is the default.
user=imspector
group=imspector
If set, IMSpector will setuid and setgid to this named user and group. By
default, IMSpector will continue running as whatever user it was started by,
including root (which is not recommended).
pidfilename=/var/run/imspector.pid
Sets the PID filename. The PID file is created before optionally dropping
privs.
Enabling protocols
As well as creating the required redirection firewall rules, IMSpector
also needs to be told to handle each protocol you wish it to process:
icq_protocol=on
irc_protocol=on
msn_protocol=on
yahoo_protocol=on
gg_protocol=on
Typing events
By default, IMSpector will not log "typing events", because they are not
usually interesting. None the less, it is possible to log them if you
desire:
log_typing_events=on
IRC, being line based, does not have the concept of typing events and
thus IMSpector cannot log them.
IRC and group chats
IRC is alittle "special". With its channels, it suports group chatting. IMSpector copes
with this in the following way.
The local ID is always the nickname of the person making the IRC connection. The
remote ID will be a channel for channel messages, and the other persons nick for
private messages. When a remote user says a message on a channel, the event data is
prefixed with their nick and a colon followed be the message said.
MSN and Yahoo group chats are logged in a simular way; in both cases a
remote party is created "on demand" to hold the group. ICQ/AIM support
within IMSpector currently does not support group chats.
File log format
Logs are filed under a path like this:
{protocol}/{local id}/{remote id}/{year}-{month}-{day}
A prefix to this path is stored in the config file:
file_logging_dir=/var/log/imspector
This directory must be owned by whoever the imspector program will run as.
{protocol} is the name of a supported protocol (currently MSN or ICQ-AIM), {local id} is the
local identity who sent or received a message (ie the person "behind" the machine running
IMSpector, {remote id} is the person "in front" of the IMSpector machine, and the last item
is obviously the date of the chat.
The local and remote IDs are different depending on the protocol. For MSN it is the persons
registered passport email addresss, for AIM and ICQ it is just a simple string (ICQ is now
the same as AIM but has a numeric user ID).
An actual log file will look something like this:
192.168.0.4:62013,1160853400,0,1,0,yep
192.168.0.4:62013,1160853401,0,1,0,:~)
192.168.0.4:62013,1160853407,1,1,0,smoothie should be in the other rack
Columns are:
- IP address:Port of the client machine.
- UNIX timestamp.
- Outgoing. 1 for an outgoing event, 0 for an incoming event.
- Type of event. Currently supported are:
- 1 - Message.
- 2 - File transfer. Some protocols only.
- 3 - Typing event. User is typing a message. Some protocols only.
- 4 - Webcam event. User requested a webcam session. Yahoo only presently.
- Filtered. 0 means the message was not filtered (blocked), 1 means it
was. Does not relate to content manipulation, but rather ACLs and other
filter plugins.
- The event data, which for messages happens to be what ever was said. For
file transfers, the name and length is logged here. Both the typing events
and webcam events do not use this field. Note that the un-manipulated text
is logged, ie. before it has been censored for bad words, if the option is
enabled. If the message includes embedded new-lines, they are backslashed
as \n. Note that, depending on the client software and protocol, the
message may contain embedded HTML or other formatting elements.
MySQL logging
MySQL support is not built unless you invoke the make mysqlloggingplugin.so
target. Of course, the client side C MySQL library is required to build this
plugin. It adds the following options to the config file:
- mysql_server - The hostname of the DB server.
- mysql_database - The database name in the server.
- mysql_username and mysql_password - Login details for the DB.
The table in the database should be called "messages". The following SQL can be
used to be create it:
CREATE TABLE `messages` (
`id` int(11) NOT NULL auto_increment,
`timestamp` int(11) NOT NULL default '0',
`clientaddress` text NOT NULL,
`protocolname` text NOT NULL,
`outgoing` int(11) NOT NULL default '0',
`type` int(11) NOT NULL default '0',
`localid` text NOT NULL,
`remoteid` text NOT NULL,
`filtered` int(11) NOT NULL default '0',
`eventdata` blob NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1;
If this table does not exist, and the DB user is capable of doing so, this
table will automatically be created when IMSpector starts.
Note that only MySQL version 4 and 5 has been tested. Prepared statements
are used for efficiency reasons and I believe that these will not work on
version 3. Testing on this is welcome, as I am neither an MySQL or SQL
bod. Then again, MySQL 3 is probably considered ancient.
The plugin supports some level of resiliance against server disconnects
and other errors; if the server is remote and the connection between
IMSpector and the DB server is broken, IMSpector will queue the events and
periodically attempt a reconnection. When the connection is reestablished,
the queued events will be logged at the database in one hit.
PostgreSQL logging
PostgreSQL support is not built unless you invoke the make
postgresqlloggingplugin.so target. Of course, the clientside C
PostgreSQL libary is needed to build this plugin. It adds the following
options to the config file:
- pgsql_connect - Connection paramaters.
The connection parameters are varied and it depends on the details of
your client library and so on, but an example would be:
pgsql_connect=host=localhost dbname=imspector user=dbuser password=Password
The table in the database should be called "messages". The following SQL can be
used to be create it:
CREATE TABLE messages (
id serial primary key,
"timestamp" timestamp with time zone default now(),
clientaddress varchar,
protocolname varchar,
outgoing int default 0,
type int default 0,
localid varchar,
remoteid varchar,
filtered int default 0,
eventdata text )
If this table does not exist, and the DB user is capable of doing so, this
table will automatically be created when IMSpector starts.
The PostgreSQL plugin supports the same form of disconnected operation as
the MySQL plugin.
SQLite logging
SQLite support is not built unless you invoke the make sqliteloggingplugin.so
target. It adds the following options to the config file:
- sqlite_file - The filename of the DB.
Once again, a "messages" table is required:
CREATE TABLE messages (
id integer PRIMARY KEY AUTOINCREMENT,
timestamp integer NOT NULL,
clientaddress text NOT NULL,
protocolname text NOT NULL,
outgoing integer NOT NULL,
type integer NOT NULL,
localid text NOT NULL,
remoteid text NOT NULL,
filtered integer NOT NULL,
eventdata blob NOT NULL
);
This table is automatically created if it dosn't already exist.
Content manipulation
IMSpector is able to remove offensive words from all IM messages. Three config
options are used:
- badwords_filename - Should be pointed at a file of naughty words, one per line.
- badwords_replace_character - Should be a single character. Bad words will be
replaced with the character. Default is an asterisk.
- badwords_block_count - If a message contains more then this many bad
words then the message will be completely blocked, not just replaced.
This filter is by no means uncircumventable, but the supplied list of
naughty words is enough to filter most strong swear words. The filter is
not enabled by default.
File-backed filtering
In addition to content replacement, IMSpector is able to completely block
messages and other events from reaching the recipient. This is useful for,
say, limiting people to certain contacts, or from blocking a listed group of
people. There are two implementations for this type of blocking: file based,
and database (SQlite) based. In both cases, the mechanism used is a kind of
ACL.
In the file based filter, there are two lists: a blacklist and a whitelist.
Inside these lists is a series of local IDs, tied to a list of remote
IDs.
For example:
local@local.com: remote1@remote1.com remote2@remote2.com
1234: 5678 8765
If this list was used as a whitelist, for example, then 1234 could talk to
5678 and 87654, but none else. Likewise for the local@local.com user.
To enable ACL support, include the following options in the configuration
file:
whitelist_filename=/path/to/file
blacklist_filename=/path/to/file
Of course, the file must be readable by the user IMSpector runs as.
Whitelists are processed first, so if a match is made on the whitelist
then the blacklist is not examined. By default, if no match occures after
all list processing then the request is allowed, but this behavior can be
overridden:
block_unlisted=on
Database-backed filter
The DB-backed filter is not built by default. To build it, run
make dbfilterplugin.so. SQLite client libraries are needed to
build this plugin. It adds the following options to the config file:
- db_filter_filename - The filename of the DB.
The table in this database will be called "lists", and will be
automatically created if needed:
CREATE_TABLE "CREATE TABLE IF NOT EXISTS lists (
id integer PRIMARY KEY AUTOINCREMENT,
localid text,
remoteid text,
action integer NOT NULL,
type integer NOT NULL,
timestamp integer NOT NULL );
localid and remoteid may be NULL, which means when a search is done for
an entry, it will match any value.
"action" can be one of the following values:
- 1 - ACCEPT - allow the message to pass.
- 2 - BLOCK - reject the message.
- 3 - AWL - matching outgoing messages will have the localid and remote
id automatically inserted as ACCEPT rules, so replies can pass.
"type" can be one of the following values:
- 1 - MANUAL - the type value to use for manually added rules.
- 2 - AUTO - AWL entries will be given ths type.
The timestamp is set when an entry is created by the AWL rules and is
useful if one wished to, say, remove all entries over a month old.
The matching logic is as follows:
- First look for matches with action=ACCEPT, allowing the messages if we
find any
- If a message is outgoing, then look for action=AWL. If we find a match,
then allow this message to pass, and automatically create a rule with action=ACCEPT and type=AUTO.
- Look for a match with action=REJECT, blocking the message if we find
any.
- Finally, allow the message.
Note that the ordering of rules within the table is not relevent; only
the fact that a match was found somewhere in the table is important.
Example: to enable AWL for all local users except the user
example@company.com - which is to always be allowed, create three rows:
- localid=example@company.com, remoteid=NULL, action=ACCEPT,
type=MANUAL
- localid=NULL, remoteid=NULL, action=AWL, type=MANUAL
- localid=NULL, remoteid=NULL, action=BLOCK, type=MANUAL
Note 1: because of the way SQLite works, you can freely modify the table
from outside of IMSpetor, while it is still running, without any
problems.
Note 2: What would happen if this filter was combined with the file-based
ACL filter is unclear.
Other blocking
Also two additional, global, options are available that are applied
regardless of the outcome of ACL processing:
block_files=on
This option will block all file-transfers on all protocols that IMSpector is
watching and understand file-transfers..
block_webcams=on
This option will block all webcam sessions. Currently IMSpector can only
spot webcam sessions on Yahoo.
|
