Information about mksd v1.15

English language version 2003.10.09 (year.month.day)
Please send any comments and corrections to mkslinux@mks.com.pl
=================================

mksd may be used to run one or more mks32 processes in background,
so you may use your multi-processor machine more efectivly.
So it may work as server and thus avoids init time costs
during scan of files. Access to server is granted by additional programs
supplied and client library available with source.
mksd may server some clients at once,
even if only one mks32 process is running.

Contents:

1. How to run mksd
2. Security
3. Number of processes of mks
4. Diagnostic and maintaining
5. How to use mksd and supplied programs
6. Remote mksd server
7. Integration with amavis
8. Integration with procmail
9. Integration with exiscan
10. Integration with qmail
11. Integration with samba
12. Use of mksd server - techical info
13. Some internet links
14. List of files
15. Contact addresses


1. How to run mksd
------------------

For fast start you may read script 'inne/startmksd'

Program mksd requires directory `/var/run/mksd' 
You have to create it before first execution
and give it access rights, 
for example rwx--x---.
Only the client which has proper rights to search the directory
may use server. Owner of mksd must have full access rights (rwx).

Command line has following syntax:

mksd [-u <user>] [-g <group>[,...]] [-x] [scan|cure] [<number of mks32 processes>]

All arguments are optional. Providing of user and group make sense
only when mksd is run from root account.
By default mksd starts only one mks32 process 
in scan mode, without change of access rights.
Scan mode is potentialy faster than cure mode (cure),
because scanning may be stopped after first virus found,
and because cure of file takes more time, especialy when
it is inside nested archive.
Work mode may be changed later for every scanned file,
and it is not binded to default mode options.

If you use options "-u" or "-g", you must remember 
to set proper rights for `mks32' and `mks_vir.cfg' , they may be different
from rights used when user root runs mks32. The same note apply to 
directory `/var/run/mksd'.

Option "-x" changes behavior of daemon in situation 
when all mks32 processes die and no one will succesfully restart.
Mksd by deafult in such situation sends alert to syslog and waits
for human to resolve problem. Restart of child mks32 processes
is started by sending SIGHUP signal to mksd.
If option "-x" was used, mksd exits to system.

After run, mksd tries to look for mks32 in PATH and its local directory.
You must set search PATH so it reflects your local configuration.
For example you may star mksd in this way:

PATH=/usr/local/bin mksd -u amavis -g amavis,mail,antivir scan 4

If start of mksd fails, you should check syslog log 
On some systems you should turn on syslog, see chapter "Diagnostic".
If it was mks32 error,
then you should check  if mks32 can be run from terminal.
If mks32 runs from terminal, 
probably cause are bad access rights for user (see above),
missing configuration file `/etc/mks_vir.cfg'
or bad path to anti-virus databases for mks32 in configuration file.
mks_vir.cfg should contain:

# comment
--mks-vir-dat-path=/your/path/to/mks/databases/
--mem-limit=64M
# You have to add trailing '/' to path.

Working directory for mksd and for mks32 processes
is `/var/run/mksd',
so path to databeses should be given from root `/' or
as starting from /var/run/mksd
Similary, if in `/etc' directory there is no configuration file `mks_vir.cfg',
it should be placed in /var/run/mksd
You should give proper rights for executeables and configuration file,
and they can be different from rights used during executing of mks32
from terminal.

Programs mks32 and mksd are distributed in two versions, 
linked staticaly and dynamicaly. If dynamic linked version do not run,
because there are missing libraries, you may replace dynamic versions
by static ones (for example: mv -f mks32.static mks32 ; mv -f mksd.static mksd).
Do not try to use libraries with different version, 
you may get unpredictable results. You may instead search for libraries
which are compatible with binaries compiled in other version of your operating system.


After sudden crash of mksd (if SIGKILL was sent or if there was failure
in mksd or mks32 or system) there left file `/var/run/mksd/mksd.pid'.

Executing of mksd will fail as long as  this file exist.
If mksd is run after system boot-up,
then you may provide following line in rc.d files
before starting mksd:

rm -f /var/run/mksd/mksd.pid

If system at booting time deletes directory `/var/run',
you have to replace this line with creation of directory
`/var/run/mksd' and then grant it proper access rights,
proper user and group.

You may also use script `inne/startmksd', which should run on all platforms.

2. Security
-----------------

The best way to execute program is to do it with user rights 
who is the owner of directory `/var/run/mksd' - 
it can be root or user which run client program.
This user needs rights for `/var/run/mksd' : access, write, execute.
It is possible to run mksd with fake user created for this special
purpose and selected group (for example mail) or a few groups,
but you must check if all scanned files will have proper rights sets
for some of these groups.

Program is desined to use by admins and system operators.
To offer resist to "denial-of-service" attacts when ordinary users
starts checking files of other users or system,
the right to search directory `/var/run/mksd' should be restricted.


3. Number of processes of mks
-----------------------------

If you execute some processes (max 32) of mks32 may in some cases 
increase performance and shorten response time of server:

* on multi-processor machines you can run the same number of processes
  as is number of processors

* one more process can give more speed when scanning multiply files,
  which contents is temporaly out of buffered memory
  (the system may continue work while waiting for disk access)

* one more process can let the system work if one of client 
  is hard working (for example is scanning one big zip archive)
  It may be required by samba-vscan or for check e-mails by procmail,
  and it can not be required when mks is scanning attachments
  already unpacked by amavis.
  

One client may use many processors at the same time,
for example by useing attached programs mksscan or mkschkin.
mksd distributes work to do between mks32.


4. Diagnostic and maintaining
-----------------------------

In special cases mksd writes info to syslog, facility LOG_DAEMON
with priorities LOG_INFO, LOG_WARNING , LOG_ERR and LOG_ALERT.
On some platforms this messages will be directed to /dev/null,
so it is worth checking file /etc/syslog.conf
If they miss, you may add line:

daemon.*  /var/log/daemons

and restart syslog.

At work of mksd you may read its PID in text form from file
`/var/run/mksd/mksd.pid'.

Atfer receiving SIGHUP signal mksd executes two new child processes.
Old processes will be replaced by new ones after end of initialization.
Server do not stop working during start of new processes.
This way you may make mks32 update or anti-virus databases update.
If you plan to replace old mks version, you must first delete or rename old mks32.
For automatic database update you may use script `inne/mksupdate'.
You should check if scripts conforms to your needs, update it if needed,
then add to crontab following:

mksupdate get uselog


After mulfanction of some of mks32 processes daemon try to recreate this process.
If this happen, it may be good to restart all processes with SIGHUP signal
(it saves some memory). It may be useful if you send bug report
(with some file which casue problem) to Kamil Konieczny  <mkslinux@mks.com.pl>
It helps us to find and remove bugs.

Signal SIGTERM makes server stop receving connections 
and after closeing last process it ends work.
Sending SIGTERM signal again ends mksd work immidiatly.
The same behavior is after SIGINT signal.

	      
5. How to use mksd and supplied programs
----------------------------------------------------------

* mksscan   -   it cheks files and directories, which are given in arguments
		you may give relative and global paths ;
		it returns exit code 0 if there was no virus and was no errors
		numbers from 1 to 7 if there where viruses and no errors,
		and other numbers if there where errors.
		Numbers from 1 to 7 may be bitwise OR with error codes,
		int this case there where viruses and errors (see mks32 doc).
		Results will be printed on stdout, also in case of errors
		(program do not write to stderr).
		This tool is useful with amavis (amavisd) or similar e-mail scanner
		and for checking files from command line.


* mksfiltr  -   It copies stdin to temporary file, starts scan or cure of it,
		then writes it to stdout, and writes status info to stderr
		(or to file given with '-l' otion).
		Error codes are the same as mksscan,
		but you can change it with '-0' option (see description below).
		Program started with options "-m -c" may be used as pipe
		for e-mail (for example with procmail).
		In this caes default temporary file is located in /tmp,
		you can change it with environment variable TMPDIR;
		access rights are the same as given by "-g" and "-w"
		(see decription below)

* mkschkin  -   writes file paths from stdin to server, 
		server output writes to stdout,
		relative paths are changed to root based,
		files on output may be written in different order if there is
		more than one mks process.


Description of older tools you find in file  `inne/README'.

All programs mksscan, mksfiltr, mkschkin may be given arguments:

"-s" - scan
"-c" - cure
"-m" - means scan/cure e-mail
       (only _whole_ mail messages, not files extracted by amavis
	in status lines file name will be replaced with
	Message-ID and other information from e-mail header)
"-q" - do not output lines started with "OK" (report only errors and viruses)
"-t <timeout>" - sets maximum response time from mks32 (default 200 seconds)
	if time expires, in status line is printed error message;
	this option is implemented only in mksscan and mksfiltr

Additional mksscan parameters:

"-Q" - as "-q", but after write of first line stop scan
	you may see as result not virus name, but heuristic or suspiocious name
"-v" - write line "OK ALL", if output was empty
       (you may use it with "-q" and "-Q")
"-n <NUMBER>" - specify max number of mks processes used at the same time
	(default 1)
"--" - end of options

Additional mksfiltr parameters:

"-Q" -  it is like "-q", but result of scan may have heuristic name
	instead of virus name
"-g" -  temporary file instead of default access writes rw------- 
	will have rw-rw--- 
	It is useful when daemon works on non-real user and group;
	In BSD systems GID of temporary file is set to 
	EGID of mksfiltr process, in Linux it will have original group
	(in most cases identical with EGID)

"-w" -  as above, but rights will be equal rw-rw-rw-; it may be used
	if users will not have access to shell

"-0" -  program will return 0 code regardless of status returned by mks;
	non-zero code (128) will be given only in case of fatal error
	It allows setting 'w' flag in procmailrc,
	it may be used when you observe problem that 
	procmail lock files are not deleted.
	
"-b" -  program will be working as black hole, e.g. it will not write to stdout
	(but there may be output on stderr)

"-l <logfile>" - redirect stderr to file `logfile', opened in append mode
	(it replaces "2>>logfile", that used in procmailrc may invoke shell)

6. Remote mksd server
----------------------

In version 1.15 we add two new experimental options "-i" and "-r" for mksfiltr,
which allows for scan or cure files from mksd run on remote machine.
On local system (client) you need mksfiltr, 
on remote (server) inetd (xinetd), mksfiltr and mksd.
If there is no port of mks32 to your machine (for example UltraSparc5, Alpha)
we may try compile port of mksfiltr for this machine.

In version 1.15, client sends to server file without any options,
so options must be set on server. There is one exception with "-l" option,
which may be used on client.
Then you may or may not set option "-b" on both client and server.
If on server exist user "mks" and in /etc/services:

mksfiltr 997/tcp

then there are two possible modes of remote work:

A) e-mail filtering

/etc/inetd.conf on server:
mksfiltr stream tcp nowait mks /opt/mks/mksfiltr mksfiltr -i -m -c -0

Run on client:

cat email | mksfiltr -r serwer:997 -l log | ...

B) check files

/etc/inetd.conf on server:
mksfiltr stream tcp nowait mks /opt/mks/mksfiltr mksfiltr -i -s -b -0

Run on client:

mksfiltr -b -r serwer:997 < file

This is preliminary version of remote scan.
If there will be demand from our users,
we may make more improvements to this mode,
in this case please contact by e-mail with us.


7. Integration with amavis
--------------------------

See section "13. Some internet links", 
there are addresses of documentation 
supplied by users of mksd and amavis.
If some solution works with mkschk, 
you should build that program from sources
(see description in file `inne/README').

Current solution is useing mksscan, this will allow to avoid problems
with scanning of empty derectory.
Exact integration description depends on version of amavis,
for example in file `amavisd.conf' in distribution amavisd-new
there is:

  ['MkS_Vir daemon',
    'mksscan', '-s -q {}', [0], [1..7],
    qr/^... (\S+)/ ],

To avoid doble scan of files, you should comment out line with mks32 invoke.
Users of multi-processors machines may run mksd with to child processes
and add option "-n2" in above citation.
If you want to stop scan after first virus found,
replace "-q" option with "-Q".
Other example (for amavis and amavisd) you find in
`inne/amavis-mksscan'.


8. Integration with procmail
----------------------------

See file `inne/procmail-example' 


9. Integration with exiscan
---------------------------

Exim users with patch exiscan version 4.12-23 or above
or exiscan-acl version 4.20-10 have built-in support for mksd.
You should remember that mksd should work with root rights or
EXIM_USER or group EXIM_GROUP,
so it can access scanned directories and files.
Exiscan is accessible from
<http://duncanthrax.net/exiscan/>.

Instructions about anti-virus scanning are placed 
in file `exiscan-readme.txt' or `exiscan-acl-spec.txt', 
which is part of documentation of exim (exactly of exiscan)
Configuration options may be different in different versions of exim (or exiscan).
For exiscan-acl the simplest configuration looks like following:

- in first section add line:
    av_scanner = mksd

- if there is missing ACL for smtp_data, you need to add:
    acl_smtp_data = acl_check_data

- in section with ACL definitions you should place:
    acl_check_data:
      deny message = AV scanner mks_vir found malware ($malware_name)
           demime = *
	   malware = *
      accept

More detailed configuration description for exiscan-acl was done
by Adam Wojtkiewicz (see links below).

In old versions of exiscan, configuration options may be different,
as quick start you may try:

exiscan_condition = 1
exiscan_crypt_salt = mk
exiscan_demime_condition = 1
exiscan_av_condition = 1
exiscan_av_scanner = mksd


10. Integration with qmail
-------------------------

See section "12. Some internet links"
or follow below description, written by Radosaw Ejsmont (Thanks!):

We replace qmail-queue in such the way that our script will be scannig
for viruses and then deliver e-mail.
mksd works as root, mksscan is stared by sudo
(so that no simple user except root can start scan from / 
or disable exploiting our daemon by script kiddies )
Rights to execute mks_vir has only one user in system,
all others may (under some conditions - to check e-mails)
execute mks as that user.
Very few indirect rights for all users are indispensible,
because qmail-queue works as root - 
when it delivers e-mail for root or remote-users -
or as user which receives mail.
We want that that user may execute mks to scan his/her mail.

Datailed description is in file `inne/qmail-mksscan'.


11. Integration with samba
--------------------------

Saba-vscan is part of OpenAntivirus project
you may find it here:
<http://sourceforge.net/projects/openantivirus>

It allows scanning "on-access" files accessed on samba server.
From version 0.3.2 there is support for mksd.
Before building samba-vscan it is worth to build
library libmksd from current mksd distribution (file `inne/src.tar'),
becuase samba-vscan may have older version of libmksd.

It is also worth to start mksd with some number of processes
to make it work without delays.


12. Use of mksd server - techical info
-------------------------------------------

mksd server checks (scans or cures) files, 
which pathnames are given from clients.
Server gets from stdin lines containnig pathnames 
started from root directory '/'
ans ended with end-of-line char. 
Every file path may have one or more special chars at begin of line,
that modify server work:

'S' - scan
'C' - cure
'M' - file contains e-mail (so mks32 may decode it first before scan attachments)
' ' - separator (ignored)

On stdout server prints information (one line for every checked file),
this info starts with status word, space char, name of virus,
additional info,
which may be Message-ID if it's mail, or name of file.


"OK"  - no viruses, no errors
"CLN" - all viruses cleaned
"VIR" - there left viruse(s) in file(s)
"DEL" - file with virus was delteted (in case of archives or mail
        it means delted of part which contains virus)
"ERR" - error occured (eg. bad access rights to file)

In different versions of mks_vir status words may have different meaning,
("CLN" and "DEL" are not implemented now, there is "VIR" instead)
but be gurantee that "OK" remains its meaning.
All printed info are generated by mks32 program (not mksd)
so please consult mks32 documentation if needed.

You may send requests to server by use of programs 
described in above paragraphs,
or directly from your application.
There is demonstration in library source libmksd and source of mkschk,
which makes use of this library.
Sources are provided in `inne/src.tar'.
You are allowed to modify provided sources 
so you may adjust them to your needs.

If you want to use many mks processes at the same time,
client program must "split" input and output stream.
It should either counts requests and replays, 
or tell server about end of input stream by call function

shutdown (fd, SHUT_WR)

and then wait for close of connection by server.
It may be dangarous to make more than one connections with server.

If first char in input stream is '\n',
then closeing connection with server by shutdown() function
will cause immediatly breaking of connection without info in syslog .
This enables break of connection after first virus found,
even if there are not readed filenames in input stream.

Server may serve max 8 connections at any time 
(or 2 times number of mks processes),
after reaching this number rest of clients will be waiting
to be served by server.


13. Some internet links
--------------------------------------

Here we will place adresses of www pages with 
description of uses of mksd and mks32,  
for example descriptions of integration with other programs,
specialy (but not limited to) integration with MTA (Mail Transport Agent).
If some description works witj mkschk, you should compile this program
from sources (description of build is placed in `inne/README').

http://www.nzs.pw.edu.pl/~bkorupcz/pub/prog/patches/
	integration of mksd with amavis, 
	amavisd and qmail and administration scripts        
	and other useful info
                                                    [ Bartomiej Korupczyski ]

http://mks.s-gen.pl/
	integration of mksd with amavis, 
	compilation and configuration of amavisd,
	amavisd and postfix and script starting daemons
                                                        [ Sergiusz Brzeziski ]

http://glinki.waw.pl/mks/qs.patch
        patch for qmail-scanner which add mksd
	and polish language logs in ISO-8859-2
                                                               [ Marek Zbroch ]

http://vega.umcs.lublin.pl/sendmail/amavis_rh.html
	integration of mksd with amavisd-new and sendmail, 
	RPM packets with needed programs (for RedHat Linux)
                                                              [ Mateusz Drach ]


http://www.piorunek.pl/~dominik/#mkslinux
	RPM packets with mks32, mksd and anti-virus databases,
	script for automatically updateing databases
                                                       [ Dominik Mierzejewski ]

http://sourceforge.net/projects/openantivirus
	samba-vscan, part of OpenAntivirus project.


http://adomas.ng.pl/teksty/exim4-mks.html
       integration with exim4 + exiscan-acl + mksd (Debiana and other Linuxes)
                                                       [ Adam Wojtkiewicz ]

http://bodyn.fm.interia.pl/la/la.html
	description of useing amavisd-new filtering 
        (postfix + amavisd-new + mksd)
                                                       [ Bodyn ]


14. List of files
----------------

* README          - this file
* CONOWEGO        - changelog
* LICENCJA        - licence for mksd
* mksd,
  mksscan,
  mkschkin,
  mksfiltr        - files described above linked dinamicaly

* mksd.static,
  mksscan.static,
  mkschkin.static,
  mksfiltr.static - files described above linked staticly

* inne            - other , older tools and other files, for description see
                    `inne/README'


15. Contact addresses
---------------------

mks32 maintainer is Kamil Konieczny <kkoniec@mks.com.pl>
mksd  maintainer is Dariusz Grzegrski <darq@mks.com.pl>
General information about mks_vir for *nix  mkslinux@mks.com.pl

http://linux.mks.com.pl/index_en.html
	Page with english language information about mks for Linux.

http://linux.mks.com.pl/index.html
	Page with polish language information about mks for Linux.

http://forum.mks.com.pl/forum/
	User forum (registration needed to send, free read).

http://mkslinux.mks.com.pl/
	Anti-virus mks32 and daemon mksd for Linux, FreeBSD,
	NetBSD, OpenBSD and Solaris8 (all ia32 by now).
--------------------- end of readme for mksd ----------------------
