White Papers

The Safe-Internet-Email system (SIE), also known as VirScan, uses CyberSoft's VFind anti-virus software to scan all incoming and outgoing email for viruses, suspicious file attachments, and spam. Clean mail is queued for delivery, and infected or suspicious mail is quarantined. Virus notifications are optionally sent to domain administrators, message senders, and/or message recipients.

The manager of an SIE system can create custom VDLs (using CyberSoft's Virus Definition Language) to specify additional patterns to be blocked, as well as specifying exception patterns which allow exceptions to the normal blocking rules. A flexible web-based console is provided to manage the queues, and a real-time queue monitor provides a summary of current activity.

The customization and run-time tuning options of SIE are extensive, and the system operation can be optimized to provide maximum throughput for any specific system configuration, number of processors, and size/volume distribution of email. Multiple VFind processing queues (typically 5 queues) are utilized, which is ideal for multi-processor systems, and also works very well on a single processor system with OS-managed load sharing. Limits on the maximum message size for each queue are optimized to help smaller messages get processed faster. Analysis of run-times from SIE log files are used to fine-tune SIE parameters to optimize system performance for the specific system environment.

1.1. Queue Overview

In the SIE system, two sendmail daemons are run. One listens on the SMTP port and stores incoming messages in queue in; the other one scans queue out to deliver messages.

Figure 1: VirScan queue example with N=5 feeds and default message size limits.

$\begin{figure}\centerline{\epsfysize 2.47in \epsfxsize 4.0in \epsfbox{v1.eps}} \end{figure}$

A feed process scans the in queue and distributes messages among five feed queues, feed1 ... feed5, depending on the message size and queue load. Each feed queue except for feed5 has a limit on message size; for example, messages over 50KB in size will only be placed in queues feed4 and feed5. The feed queue loads are measured by the total number of message bytes in the queue, and the feed process places messages in the least-loaded queue which can accept the message size. This helps smaller messages to get processed faster.

Five work processes are run, one for each feed queue. Each work process scans messages for viruses, bad file name extensions in attachments, and spam. Bad messages are moved to the virus, ext, or spam quarantine queues. Clean messages are moved to the out queue. If an error occurs while processing a message, the message is moved to the error queue.

1.2. Web-Based Queue Management Example

The VirScan/SIE web-based queue management interface provides access to all of the current and archived queues. Managers first authenticate using a UserID and Password, and each manager can selectively be assigned read-only or read-write privileges for each domain hosted on the mail server.

An example login page illustrates the selection of domains to view on CyberSoft's server. After selecting domains to view, the queue listing then allows selection of current or past archived queues. An example virus queue listing shows the options available for each message in the queue, and a help page explains the options.

1.3. Real-Time Queue Monitoring Example

The VirScan/SIE real-time monitoring tool provides a view of work queue activity in a small xterm window. The monitor displays an X for each message in each queue, and shows the total number of bytes in each queue. Summary statistics are listed at the bottom of the window. As messages enter and leave the queues, the display is updated in real-time. The following image shows a screen snapshot where four different mail servers were being monitored in separate xterm windows:

2. Configuration and Management

One-time VirScan/SIE configuration values are set in virscaninitvars, and ongoing "real-time" configuration values (not requiring a shutdown/restart) are set in virscanshellvars.

Configuration files for the web interface are virscan_web.users, virscanwebvars, and the login index.html page.

For configuration of virus detection notifications see notify.cf and the files in the notify/ subdirectory.

Stopping and restarting VirScan should only be performed using the rc2.d scripts which use stop files to allow the feed and work processes to cleanly shut down.

The feed and work scripts perform the following cycle:
1. Process a batch of messages.
The work scripts acquire a lock file before running vfind, and release the lock after scanning the messages.
2. If stop file is present, exit.
3. Sleep, then go to step 1.

VDL updates require work queue locking/unlocking during installation of the VDLs. VFind VDL updates should only be installed using updatevdl.sh. Local VDL updates should only be performed using the vdl Makefile.

qtool.pl can be used to manually move message files between queues when necessary.

3. Installation Directories and Files

The main installation directories are /opt/vstk/ for the VFind Security Toolkit (documented separately), /opt/virscan/ for VirScan/SIE programs, and /var/sendmail/ for mail queues and configuration files. The installation also includes several system startup scripts and root crontab entries, and versions of sendmail, perl, and apache.

3.1. /opt/virscan/bin/

This directory contains programs which may be run by users and/or system administrators.

Ctime

Converts time_t values to date/time strings. Useful for viewing the times at which feed queues will be ready to process more messages.

Usage: Ctime [-s] [file...]

The times will be sorted in increasing order unless the -s option is specified.

Sample run:

% pwd
/var/sendmail/virscan/locks
% ls
free.mqueue_feed1 free.mqueue_feed2 free.mqueue_feed3 free.mqueue_feed4 free.mqueue_feed5
% cat *
1022104584.890
1022104583.809
1022104570.119
1022104590.470
1022104591.319
% Ctime *
free.mqueue_feed2: Wed May 22 17:56:24 2002
free.mqueue_feed1: Wed May 22 17:56:25 2002
free.mqueue_feed4: Wed May 22 17:56:30 2002
free.mqueue_feed5: Wed May 22 17:56:31 2002
free.mqueue_feed3: Wed May 22 17:57:05 2002
%

Lock

Multi-threaded multi-queue locking, used by updatevdl.sh and vdlinst.sh.

The default directory for the locks is /var/sendmail/virscan/locks which can be overridden using the Lock -d command-line option.

Stop

Multi-threaded multi-queue stop program, used by the rc.virscan scripts to perform a clean shutdown of feed and/or work processes.

Time

Displays time, or time difference, with millisecond resolution. Used by the feed and work processes to calculate run-time and sleep-time.

Time is displayed in seconds since 00:00 Universal Coordinated Time, January 1, 1970. If a time command-line argument is specified, the difference in seconds between the current time and that argument is displayed.

Sample runs:

% Time
1022160463.904
% set t=`Time`; sleep 3; Time $t
3.014
% Time | Ctime
stdin: Thu May 23 09:29:24 2002
%

Unlock

Multi-queue unlocking. See Lock.

mailq

Displays mail queue file names and sizes, similar to sendmail -bp -O QueueSortOrder=time -oQ<qdir>, but with succinct output. Used by the feed and work processes.

Usage: mailq -oQ<qdir>

ptail

Multi-threaded parallel tail program, useful for simultaneously viewing all of the feed and work log files. The default log file directory is /var/sendmail/virscan/logs.

Usage: ptail [-d logsdir] name...

Sample run:

% ptail mqueue_in mqueue_feed1 mqueue_feed2 mqueue_feed3 mqueue_feed4 mqueue_feed5
mqueue_in:
mqueue_in: Thu May 23 10:18:03 EDT 2002: Started pass 20020523100634.19121.23.
mqueue_in: g4NEHl121396 1764 -> q1
mqueue_feed2:
mqueue_feed2: Thu May 23 10:18:03 EDT 2002: Started pass 20020523043705.21102.347.
mqueue_feed2: Thu May 23 10:18:03 EDT 2002: Finished pass.
mqueue_feed2: Thu May 23 10:18:03 EDT 2002: Sleeping: 55
mqueue_in: Thu May 23 10:18:04 EDT 2002: Finished pass.
mqueue_in: Thu May 23 10:18:04 EDT 2002: Sleeping: 29
mqueue_feed1:
mqueue_feed1: Thu May 23 10:18:10 EDT 2002: Started pass 20020523043700.21037.349.
mqueue_feed1: virscan-work: acquired lock /var/sendmail/virscan/locks/lock.mqueue_feed1
mqueue_feed4:
mqueue_feed4: Thu May 23 10:18:17 EDT 2002: Started pass 20020523043716.21179.347.
mqueue_feed4: Thu May 23 10:18:17 EDT 2002: Finished pass.
mqueue_feed4: Thu May 23 10:18:18 EDT 2002: Sleeping: 55
mqueue_feed1: virscan-work: released lock /var/sendmail/virscan/locks/lock.mqueue_feed1
mqueue_feed1: Clean, moving: g4NEHl121396
mqueue_feed1: Stats: vir:0 ext:0 spam:0 vir-ex:0 ext-ex:0 spam-ex:0 clean:1 msgs:1 bytes:2675 vf:15.32 vs:17.195 lock:0.085
mqueue_feed1: Thu May 23 10:18:28 EDT 2002: Finished pass.
mqueue_feed1: Thu May 23 10:18:28 EDT 2002: Sleeping: 38
mqueue_in:
mqueue_in: Thu May 23 10:18:33 EDT 2002: Started pass 20020523100634.19121.24.
mqueue_in: g4NEI7121458 106 -> q2
mqueue_feed3:
mqueue_feed3: Thu May 23 10:18:34 EDT 2002: Started pass 20020523043711.21145.348.
mqueue_feed3: Thu May 23 10:18:34 EDT 2002: Finished pass.
mqueue_feed3: Thu May 23 10:18:34 EDT 2002: Sleeping: 55
mqueue_in: Thu May 23 10:18:34 EDT 2002: Finished pass.
mqueue_in: Thu May 23 10:18:34 EDT 2002: Sleeping: 29
...

stats

Displays summary statistics for each work queue.

Sample run:

% stats

mqueue_feed1:

total max avg

files 471 6 1.15725

bytes 2.62706e+07 33517 6454.69

vf 6609.7 30.68 16.24

vs 9921.16 102.982 24.3763

...

mqueue_feed5:

total max avg

files 26 1 1

bytes 2.93909e+07 6.30194e+06 1.13042e+06

vf 14960.6 3574.71 575.406

vs 17847.2 4569.51 686.432

Stats: vir:76 ext:3 spam:180 vir-ex:167 ext-ex:31 spam-ex:36 clean:1301 msgs:1794 bytes:51870415 vf:46820.7 vs:62851.6 lock:198.998
%

vf represents vfind CPU-time, and vs is the worker script overall run-time.

3.2. /opt/virscan/external/

bin/bzip2
bin/chroot+setuidgid
bin/cpio
bin/unrar
bin/unstuff
src/Makefile
src/README
src/chroot+setuidgid.c
src/cpio.patch
src/uad-helper.chroot
src/uad-helper.chroot+setuidgid
src/uad-helper.su
src/unrar.patch

These files are for use with the uad -e option which enables an external expander for unknown archive types. A configured copy of uad-helper.chroot+setuidgid is in /opt/virscan/sbin/uad-helper which enables UAD expansion of bzip2, cpio, rar, and stuffit archives. To use uad-helper, add the following option to the uad command line in /var/sendmail/virscan/virscanshellvars: -e /opt/virscan/sbin/uad-helper

3.3. /opt/virscan/rc2.d/

This directory contains scripts which are generally only run at boot time.

rc.sendmail

This script is run at boot-time via the /etc/rc2.d/S88sendmail symbolic link to start the VirScan/SIE sendmail daemons. It can also be run manually to stop and restart sendmail, i.e.

sh /opt/virscan/rc2.d/rc.sendmail stop

sh /opt/virscan/rc2.d/rc.sendmail start

rc.virscan

This script is run at boot-time via the /etc/rc2.d/S88virscan symbolic link to start the VirScan/SIE feed and work processes. It can also be run manually to stop and restart VirScan, i.e.

sh /opt/virscan/rc2.d/rc.virscan stop

sh /opt/virscan/rc2.d/rc.virscan start

This is where a maximum file size limit (default 50 MB, i.e. 102400 512-byte blocks) is set to prevent a denial of service attack involving compressed multi-gigabyte /dev/zero mail attachments:

ulimit -f 102400

You can change or eliminate that limit as desired, then stop/restart VirScan for your changes to take effect.

rc.virscan-feed

This script is run at boot-time via the rc.virscan script to start the VirScan/SIE feed process. It can also be run manually to stop and restart the feed process, i.e.

sh /opt/virscan/rc2.d/rc.virscan-feed stop

sh /opt/virscan/rc2.d/rc.virscan-feed start

rc.virscan-work

This script is run at boot-time via the rc.virscan script to start the VirScan/SIE work processes. It can also be run manually to stop and restart the work processes, i.e.

sh /opt/virscan/rc2.d/rc.virscan-work stop

sh /opt/virscan/rc2.d/rc.virscan-work start

3.4. /opt/virscan/sbin/

This directory contains programs which are used by the VirScan/SIE system internally and/or are generally only run by system administrators.

amq
mq
feedq
inq
outq
spamq
virq

These scripts are all hard links to the same script and are used to view the contents of the mail queues. When invoked as amq all of the in, feed, virus, ext, and spam queues are shown. When invoked as mq only the in and feed queues are shown. When invoked as the other names, only the feed, in, out, spam, or virus queues are shown, respectively.

msgcat

This script concatenates sendmail qf and df files into one output of the same form used internally by VirScan. This is useful for manually scanning a queued message using UAD and vfind.

Usage: msgcat msgid [mqueue]

The default queue used is the sendmail outgoing queue if the mqueue argument is not specified.

msgscan

This script invokes msgcat and pipes the output into UAD and vfind to manually scan a queued message.

notify.sh

This script is used internally by results.sh to send virus detection notifications.

qtool.pl

This script is used internally by virscan-feed and virscan-work to move message files between queues. It locks the files the same way that sendmail does to prevent problems. You can also use this script to manually move message files between queues.

results.sh

This script is used by virscan-work to process the results of a queue pass.

rotate

This script is invoked by cron daily or weekly to collect statistics and rotate/archive the VirScan logs and quarantine queues.

uad-helper

A configured copy of uad-helper.chroot+setuidgid which enables uad expansion of bzip2, cpio, rar, and stuffit archives. To use uad-helper, add the following option to the uad command line in /var/sendmail/virscan/virscanshellvars: -e /opt/virscan/sbin/uad-helper

updatevdl.sh

This script uses wget to download vfind VDL updates, and it performs VirScan work queue locking/unlocking during installation of the VDLs.

vdlinst.sh

This script is invoked by the Makefile in /var/sendmail/virscan/vdl/ to test and install local VDL files.

virscan-feed

The main feed process which distributes message files among the work queues.

virscan-work

The main work process for scanning messages. A separate instance of this process is run for each work queue.

3.5. /opt/virscan/src/

These subdirectories contain the C source code for various utility programs:

Lock/
Stop/
Time/
mailq/
mon/
ptail/
solve/

In the mon/ directory you can run mon.sh to invoke the real-time queue monitor.

In the solve directory you can run solve.sh to analyze VirScan log files and solve for linear-least-square-error parameter values to use in /var/sendmail/virscan/virscanshellvars to tune system performance.

3.6. /var/sendmail/

archive/

Archived VirScan logs and quarantine queues.

mqueue/

The outgoing mail queue.

mqueue_delete/

Archive queue for messages deleted using the web interface.

mqueue_error/

Queue for messages not processed due to some serious error condition.

mqueue_ext/

Quarantine queue for messages containing attachments with suspicious file name extensions.

mqueue_feed1/
mqueue_feed2/
mqueue_feed3/
mqueue_feed4/
mqueue_feed5/

The worker feed queues.

mqueue_good/

Optional queue to temporarily store copies of clean messages which have been released for delivery.

mqueue_in/

The incoming mail queue.

mqueue_release/

Archive queue for messages released for delivery using the web interface.

mqueue_spam/

Quarantine queue for messages containing spam.

mqueue_virus/

Quarantine queue for messages containing viruses.

virscan/

Subdirectory for virscan processing and configuration files.

3.7. /var/sendmail/virscan/

This directory contains configuration files and subdirectories for logs, stats, web files, etc.

locks/

Subdirectory for lock files, stop files, and work queue free-time files.

logs/

Subdirectory for log files.

msg_error/
msg_ext/
msg_spam/
msg_virus/

Subdirectories for message processing results files.

notify/

Subdirectory for virus detection notification header files.

notify.cf

Configuration file for virus detection notifications. Documentation for notification features should be added here, but in the meantime check the comments in notify.sh.

pids/

Subdirectory for the process ids of feed and work processes, used by the /opt/virscan/rc2.d/ start/stop scripts.

results/

Subdirectory for temporary work process results and notify files.

stats/

Archive of work queue statistics.

summary/

Subdirectory for HTML summary statistics.

vdl/

Subdirectory for local VDL files. The Makefile in this directory controls construction and installation of the run-time VDL files run-spam.vdl, run-virus.vdl, and run-exceptions.vdl, from the corresponding source files spam.vdl, virus.vdl, and exceptions.vdl. vdlinst.sh is used to perform VirScan work queue locking/unlocking during installation of the VDLs.

virscan_web.users

Configuration file of domains and user access privileges for web-based queue administration.

Sample file:

# domain userid/access,... - default is rw

#

all rick,mark,anany,frodo/r,khenry

bcdv.org purple/r,bcdv

frodo frodo/rw

all Alice/r

virscaninitvars

This configuration file sets certain one-time initialization values and is sourced by various other Bourne shell scripts including the queue feed and work processes. Values configured in this file include the sender and recipient addresses for notifications of error conditions.

virscanshellvars

This configuration file is sourced by the feed and work processes before each queue run, and is also sourced by various other scripts. Values configured in this file include:

feed_loop_delay

Time in seconds for virscan-feed to sleep between passes.

sizes

The message size limits for each queue.

loop_delay

Time in seconds for virscan-work to sleep between passes.

maxpass

Maximum seconds per pass, used by virscan-work.

t00, t0, ts

Scan speed parameters. t00 = fixed overhead seconds, t0 = seconds/message, ts = seconds/byte. Optimal values for these parameters can be determined using solve.sh.

VSTK_HOME

VSTK installation directory, usually /opt/vstk

vdl_dir

Directory for local VDLs, usually /var/sendmail/virscan/vdl

spam_vdl, ex_vdl, virus_vdl

Local VDL files for spam, exceptions, and viruses.

vfind_vopts5

vfind options for work queue q5. q5 is reserved for very large messages which are not scanned for spam by default.

Number of queues for feed sorting. With NQ=4 (the default), only very large messages will be placed in q5. With NQ=5, any size message can be placed in q5.

UADP0

uad -p0 or -p option. Normally UAD does not provide output files for archives which have been expanded into component files. The -p option will cause UAD to also provide the archive files, whereas the -p0 option will cause UAD to provide only the top-level input archive files. With UADP0="-p" (the default) the original qf and df message files are scanned before decoding/extracting components, in addition to scanning components before and after decoding/extracting.

exts

File name extensions to block.

good_queue

Queue directory to save clean messages. If set to a non-empty string, then copies of clean messages (which have been released for delivery) will be saved.

virscanwebOLDlist

List of archive directories. Updated by rotate and used by the web interface.

virscanwebvars

Configuration file for the web interface. Values configured in this file include:

check_server_port

If set to a non-empty string, then the web interface will only respond to connections on the specified port, for example set check_server_port="443" to allow only SSL connections.

cgi

cgi wrapper href prefix, usually set as cgi="<a href=\"/cgi-bin/virscan?", depending on the location of the web interface programs.

index1

href for menu links, usually set as index1="<a href=\"/virscan/index1.html\">menu</a>" depending on the location of the web document files.

help

help href, usually set as help="<a href=\"/virscan/help.html\" target=\"_blank\">help</a>" depending on the location of the web document files.

LOG

Web interface log file, usually set as LOG="/var/sendmail/virscan/web-logs/virscan.log"

web/

Subdirectory for web server scripts, configuration, and data files. See below for details.

web-logs/

Subdirectory for web interface log files.

work/

Subdirectory for feed, work, and uad temporary files.

3.8. /var/sendmail/virscan/web/

This subdirectory contains web server scripts, configuration, and data files.

src/wrapper/

C source code for the setuid-root wrapper which is installed as cgi-bin/virscan.

cgi-bin/

The web server CGI script directory.

echo

Script to echo all script arguments, environment variables, and stdin data, for testing the web environment.

login

Script to process a login request and create/set a web cookie (VirScan_Domains) containing the requested domains to view. This script then sends a redirect to the main VirScan index page.

logout/

Subdirectory containing a script (index.cgi) and .htpasswd file used to logout and reset the browser cached password.

virscan

A setuid-root wrapper which cleans the environment, safely setting only environment vars HOME, PATH, SHELL, REMOTE_USER, REMOTE_ADDR, SERVER_PORT, and HTTP_COOKIE, and then exec's virscan.sh.

virscan.sh

The main VirScan web script. Configuration is set in virscanwebvars and access restrictions are set in virscan_web.users.

htdocs/

The web server document root directory.

empty.html

Placeholder for the bottom frame which contains the text "Choose a link from above".

help.html

Help page which explains the options available when using the web interface.

index.html

Login page which allows selection of domains to view.

index0.html

Frameset page which sets index1.html in the top frame and empty.html in the bottom frame.

index1.html

Main index page listing the queues available for viewing. This page is regenerated by mkindex1.sh whenever rotate is run by cron.

index1.head, index1.tail, mkindex1.sh

mkindex1.sh concatenates index1.head, archive directories extracted from virscanwebOLDlist, and index1.tail to create index1.html.

stats

Symbolic link to /var/sendmail/virscan/summary/

conf/

Subdirectory for web server configuration files.

private/

Subdirectory containing the .htpasswd file used for authenticated web logins.

logs/

Subdirectory for web server logs.

4. System Packages

Sendmail is required and may be installed in /opt/sendmail-8.11.5/.

perl is required and may be installed in /opt/perl-5.005.02/.

The Apache web server is required for the web interface and may be installed in /opt/apache_1.3.22+ssl_1.45/.

wget is required by updatevdl.sh and may be installed in /opt/bin/.

5. System Files

Some additions and modifications to system files are required.

/etc/local/mail/

Subdirectory for locally modified sendmail configuration files.

/etc/local/rc2.d/

Subdirectory for local boot scripts.

/etc/mail/sendmail.cf

Symbolic link to /etc/local/mail/sendmail.cf

/etc/rc2.d/S88sendmail

Symbolic link to /opt/virscan/rc2.d/rc.sendmail

/etc/rc2.d/S88virscan

Symbolic link to /opt/virscan/rc2.d/rc.virsca

/etc/rc2.d/S98httpd

Symbolic link to /etc/local/rc2.d/S98httpd

/usr/lib/sendmail

Symbolic link to /opt/sendmail-8.11.5/lib/sendmail

root crontab entries

A crontab entry is required to periodically run the rotate script. If copies of clean messages are saved, then a crontab entry is required to periodically remove old clean messages.

Sample root crontab entries:

# weekly rotation of virscan files
10 5 * * 0 /opt/virscan/sbin/rotate
# daily cleanup of mqueue_good
10 4 * * * /usr/bin/find /var/sendmail/mqueue_good -type f -ctime +3 -exec rm {} \;

Permission is granted to any individual or institution to use, copy, or redistribute this document so long as it is not sold for profit, and provided that it is reproduced whole and this copyright notice is retained.

VirScan/SIE is patent pending by CyberSoft, Inc.

View more CyberSoft White Papers

Home | About Us | Demo | About SIE | Support

Welcome to SafeInternetEmail

Newest Viruses Detected

Testimonials

News