Informacje o programie mksd v1.13
=================================

Program mksd suy do uruchamiania w tle jednego lub kilku procesw mks32.
Pozwala to na prac mks-a w trybie serwera, z pominiciem inicjowania
programu przy kadym sprawdzaniu pliku(-w). Dostp do serwera zapewniaj
programy uytkowe i biblioteka kliencka dostpna w rdach. Serwer moe
obsugiwa kilku klientw naraz.

Zawarto dokumentu:

1. Uruchamianie
2. Bezpieczestwo
3. Liczba procesw mks
4. Diagnostyka i konserwacja
5. Korzystanie z serwera przy uyciu zaczonych programw
6. Integracja z amavisem
7. Integracja z procmailem
8. Integracja z exiscanem
9. Integracja z samb
10. Korzystanie z serwera - opis techniczny
11. Strony internetowe zwizane z mksd
12. Wykaz plikw
13. Adresy kontaktowe


1. Uruchamianie
---------------

Program potrzebuje do pracy katalogu `/var/run/mksd'. Naley go uprzednio
utworzy i nada odpowiednie prawa dostpu, np. rwx--x---. Z serwera
mog korzysta tylko ci klienci, ktrzy maj uprawnienia do przeszukiwania
tego katalogu.

Linia wywoania ma posta:

mksd [-u <uytkownik>] [-g <grupa>[,...]] [scan|cure] [<liczba_procesw_mks>]

Wszystkie argumenty s opcjonalne. Wybr uytkownika i grup ma sens tylko
w przypadku, gdy program w momencie uruchomienia ma prawa roota. Domylnie
uruchmiany jest jeden proces mks w trybie skanowania, bez zmiany zastanych
uprawnie. Tryb skanowania jest potencjalnie szybszy od trybu leczenia (cure),
gdy sprawdzanie pliku moe zatrzyma si po pierwszym znalezionym wirusie.
Ponadto leczenie pliku zajmuje okrelony czas, szczeglnie w przypadku plikw
zagniedonych w archiwach. Tryb pracy moe by pniej ustalany dla kadego
pliku z osobna, niezalenie od trybu domylnego.

Po uruchomieniu mksd prbuje znale w ciece wyszukiwania i w swoim katalogu
program mks32. ciek naley ustawi zgodnie z lokaln konfiguracj. Przykad
linii wywoania:

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

Jeli uruchomienie demona nie powiedzie si, a w logach systemowych pojawi si
komunikat o bdzie uruchomienia mks32, naley sprawdzi, czy mks32 daje si
uruchomi z konsoli. Jeli tak jest, przyczyn jest najprawdopodobniej brak
pliku konfiguracyjnego w katalogu `/etc' lub cieka wzgldna do baz danych
podana w tym pliku. Katalogiem roboczym procesu mksd i uruchomionych przez
niego procesow mks32 jest `/var/run/mksd', zatem cieka do baz powinna by
bezwzgldna lub podana wzgldem tego katalogu. Podobnie, jeli w `/etc' nie
ma pliku konfiguracyjnego, powinien si on znale w `/var/run/mksd'. Naley
pamita o nadaniu plikom wykonywalnemu i konfiguracyjnemu stosownych praw
dostpu, ktre mog si rni od praw dostpu uywanych podczas uruchamiania
mks32 z konsoli roota.

W przypadku nagego zakoczenia pracy demona (po otrzymaniu sygnau SIGKILL
lub w wyniku awarii systemu) pozostaje na dysku plik `/var/run/mksd/mksd.pid'.
Uruchomienie demona nie powiedzie si, dopki ten plik istnieje. Jeli mksd
jest uruchamiany automatycznie podczas startu systemu, mona lini wywoania
poprzedzi instrukcj:

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

W systemach, ktrych skrypty startowe kasuj zawarto katalogu `/var/run',
naley zastpi powysz instrukcj poleceniami tworzenia katalogu
`/var/run/mksd' i nadawania mu wymaganych praw dostpu.


2. Bezpieczestwo
-----------------

Program najlepiej uruchamia na prawach uytkownika, ktry jest wacicielem
katalogu `/var/run/mksd' - moe to by root lub ten uytkownik, na ktrego
prawach dziaa program kliencki. Uytkownik ten musi mie prawa do czytania,
pisania i przeszukiwania katalogu `/var/run/mksd'. Mona te uruchomi mksd
na prawach fikcyjnego uytkownika utworzonego specjalnie w tym celu i wybranej
grupy (np. mail) lub kilku grup - pod warunkiem, e wszystkie skanowane pliki
bd miay ustawione odpowiednie uprawnienia dla czonkw tych grup.

Program jest przeznaczony do wykorzystywania przez administratora systemu
i zaufanych uytkownikw. Aby zapobiec atakom typu "denial-of-service" i
sprawdzaniu cudzych plikw przez zwykych uytkownikw, naley stosownie
ograniczy uprawnienia do przeszukiwania katalogu `/var/run/mksd'.


3. Liczba procesw mks
----------------------

Uruchomienie kilku (maks. 32) procesw mks moe w wielu przypadkach poprawi
wydajno i/lub czas odpowiedzi serwera:

* na komputerach wieloprocesorowych mona uruchomi tyle procesw, ile
  jest procesorw

* nadmiarowy proces moe poprawi szybko sprawdzania naraz wielu plikw,
  ktrych zawarto jest nieobecna w pamici buforowej (ze wzgldu na moliow
  zrwnoleglenia operacji dyskowych i oblicze)

* nadmiarowy proces pozwala unikn zmonopolizowania serwera przez klienta,
  ktry zleci czasochonn operacj (np. sprawdzanie duego archiwum zip);
  jest to istotne np. przy korzystaniu z moduu samba-vscan czy te przy
  sprawdzaniu poczty z procmaila, natomiast nie ma wikszego znaczenia, gdy
  mks otrzymuje ju rozpakowane zaczniki np. od amavisa

Pojedynczy klient moe korzysta z wielu procesw mks naraz, np. poprzez
uycie zaczonego programu mksscan lub mkschkin. Rozdzielaniem zada na
procesy zajmuje si mksd.


4. Diagnostyka i konserwacja
----------------------------

W sytuacjach specjalnych mksd zapisuje poprzez sysloga informacje typu
LOG_DAEMON na poziomach LOG_INFO, LOG_WARNING i LOG_ERR.

W czasie dziaania procesu mksd jego PID mona odczyta w postaci tekstowej
z pliku `/var/run/mksd/mksd.pid'.

Po otrzymaniu sygnau SIGHUP mksd uruchamia procesy potomne od nowa.
Stare procesy zostan zastpione nowymi po zakoczeniu ich inicjalizacji.
Serwer nie przerywa dziaania podczas uruchamiania nowych procesw.
W ten sposb mona aktualizowa wersj mks-a lub bazy danych.
Aby nagra now wersj mks-a w miejsce starej, trzeba najpierw skasowa
lub przemianowa stary plik mks32.

Po stwierdzeniu awarii ktrego z procesw mks demon podejmuje prb
odtworzenia tego procesu. Jeli taka sytuacja bdzie miaa miejsce, warto
uruchomi wszystkie procesy mks od nowa, wykorzystujc SIGHUP (pozwoli to
zaoszczdzi kilka MB pamici). Warto rwnie wysa raport o awarii
(najlepiej wraz z plikiem, ktry awari spowodowa) do Kamila Koniecznego
<kkoniec@mks.com.pl>. Dziki temu bdzie mona sprawniej wyszukiwa i usuwa
bdy w mks32.

Sygna SIGTERM powoduje, e serwer przestaje przyjmowa poczenia i po
zamkniciu ostatniego z nich koczy dziaanie. Ponowne wysanie tego
sygnau powoduje bezwarunkowe zakoczenie pracy. Takie samo dziaanie
ma pojedynczy sygna SIGINT.

	      
5. Korzystanie z serwera przy uyciu zaczonych programw
----------------------------------------------------------

* mksscan   - sprawdza pliki i/lub katalogi, ktrych nazwy podano jako
              argumenty wywoania; dopuszczalne s zarwno cieki wzgldne,
              jak i bezwzgldne; zwraca kod bdu 0, jeli nie znaleziono
              wirusa i nie byo bdw, od 1 do 7, jeli stwierdzono pewn
              liczb wirusw i nie byo bdw oraz inny kod w przypadku
              bdu (kody bdw s opisane w dokumentacji do mks-a);
              wyniki pojawiaj si na stdout, take w razie bdw (program
              nie pisze nic na stderr); narzdzie to jest przydatne do
              integracji mksd z amavisem lub podobnym skanerem poczty oraz
              do sprawdzania plikw z linii polece

* mksfiltr  - kopiuje stdin do pliku tymczasowego, uruchamia sprawdzanie lub
              leczenie tego pliku, po czym przepisuje tre pliku na stdout,
              a lini statusu na stderr (lub do wybranego pliku, jeli uyto
              opcji "-l"); kody bdw s takie same, jak dla mksscan, ale
              mona to zmieni opcj "-0" (zob. opis poniej);
              program uruchomiony z opcjami "-m -c" stanowi narzdzie do
              filtrowania poczty elektronicznej (mona go np. wywoywa z
              procmaila); domylnym katalogiem plikw tymczasowych jest /tmp,
              ale mona to zmieni, ustawiajc zmienn rodowiskow TMPDIR;
              prawa dostpu  do pliku tymczasowego zale od opcji "-g" i "-w"
              (opis poniej)

* mkschkin  - przepisuje stdin na wejcie serwera, a wyjcie serwera na stdout,
              przy czym cieki wzgldne s zamieniane na bezwzgldne;
              kolejno plikw na wejciu i wyjciu moe si rni, jeli
              zosta uruchomiony wicej ni jeden proces mks

Opis starszych narzdzi mona znale w pliku `inne/README'.

Programy mksscan, mksfiltr i mkschkin przyjmuj nastpujce argumenty:

"-s" - skanowanie
"-c" - leczenie
"-m" - oznacza skanowanie/leczenie poczty elektronicznej
       (w liniach statusu nazwy plikw bd zastpione przez
       Message-ID i inne informacje z nagwka listu)
"-q" - pomijanie na wyjciu linii zaczynajcych si od "OK"

Dodatkowe argumenty dla mksscan:

"-Q" - jak "-q", ale po wypisaniu pierwszej linii skanowanie jest przerywane
"-v" - wypisanie linii "OK ALL", jeli wyjcie byo puste
       (mona czy z opcjami "-q" i "-Q")
"-n <ile>" - specyfikuje maksymaln liczb procesw mks uywanych
       jednoczenie (domylnie 1)
"--" - znacznik koca opcji

Dodatkowe argumenty dla mksfiltr:

"-g" - plik tymczasowy zamiast domylnych praw dostpu rw------- bdzie mia
       prawa rw-rw---- (przydatne, gdy demon dziaa na prawach fikcyjnego
       uytkownika i wybranej grupy)
"-w" - jak powyej, ale prawa bd rwne rw-rw-rw-; ma to sens tylko
       w przypadku, gdy uytkownicy nie maj dostpu do shella
"-0" - program bdzie zwraca kod bdu 0 niezalenie od linii statusu
       raportowanej przez mks; kod niezerowy (128) pojawi si tylko w przypadku
       bdw wykonania; pozwala to ustawia w procmailrc flag 'w', co moe
       zapobiec zaobserwowanym problemom z niekasowaniem plikw blokady przez
       procmaila
"-b" - program bdzie zachowywa si jak czarna dziura, tj. nic nie pojawi si
       na stdout (ale nadal moe by linia statusu na stderr)
"-l <logfile>" - przekierowanie stderr do pliku `logfile', otwieranego w trybie
       doczania (zastpuje to fraz "2>>logfile", ktra uyta w procmailrc
       powoduje niepotrzebne wywoanie shella)


6. Integracja z amavisem
------------------------

W sekcji "Strony internetowe zwizane z mksd" mona znale adresy dokumentw,
w ktrych uytkownicy mksd dziel si swoimi sposobami na podpicie go do
amavisa. Jeli dane rozwizanie dziaa w oparciu o program mkschk, naley
skompilowa ten program ze rde (opis kompilacji zamieszczono w pliku
`inne/README').

Obecnie polecanym rozwizaniem jest uycie programu mksscan, co pozwala
unikn problemw ze skanowaniem pustego katalogu. Dokadny sposb integracji
zaley od uytej wersji amavisa, np. dla amavisd-new zadziaa poniszy wpis
umieszczony w ostatniej sekcji pliku `amavisd.conf':

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

Naley oczywicie zakomentowa wpis dla mks32. Posiadacze komputerw
dwuprocesorowych mog uruchomi mksd z dwoma procesami potomnymi i doda
opcj "-n2" w linii wywoania mksscan. Jeli skanowanie ma by przerywane
po znalezieniu pierwszego wirusa, powyszy wpis mona nieco uproci:

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

Inny przykad (dla programw amavis i amavisd) mona znale w pliku
`inne/amavis-mksscan'.


7. Integracja z procmailem
--------------------------

Plik `inne/procmail-example' moe stanowi punkt wyjcia do tworzenia
wasnych rozwiza.


8. Integracja z exiscanem
-------------------------

Uytkownicy programu exim z naoon at exiscan w wersji 4.12-23 lub
wyszej maj wbudowane wsparcie dla mksd. Naley pamita, e mksd musi
dziaa na prawach roota, uytkownika EXIM_USER lub grupy EXIM_GROUP,
aby mie dostp do skanowanych plikw. Exiscan jest dostpny pod adresem
<http://duncanthrax.net/exiscan/>.

Instrukcje dotyczce uaktywnienia skanowania antywirusowego znajduj si
w pliku `exiscan-readme.txt', wchodzcym w skad dokumentacji exima
(a dokadniej exiscana). Opcje konfiguracyjne mog by rne w rnych
wersjach, ale jako "szybki start" mona wyprbowa poniszy zestaw opcji:

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


9. Integracja z samb
---------------------

Modu samba-vscan, wchodzcy w skad projektu OpenAntivirus
<http://sourceforge.net/projects/openantivirus>, pozwala skanowa
"w locie" pliki zarzdzane przez serwer samby. Od wersji 0.3.2 wczono
wsparcie dla mksd. Przed waciw kompilacj warto skompilowa osobno
bibliotek libmksd z biecej dystrybucji mksd (plik `inne/src.tar'),
gdy samba-vscan moe by wyposaony w starsz wersj tej bliblioteki.
Aby cao dziaaa pynnie, warto uruchamia mksd z kilkoma procesami
potomnymi.


10. Korzystanie z serwera - opis techniczny
-------------------------------------------

Praca serwera polega na sprawdzaniu (i ew. leczeniu) plikw, ktrych nazwy
s dostarczane przez klientw. Serwer przyjmuje na wejciu cigi cieek
bezwzgldnych zakoczonych znakami koca linii. Kada cieka moe by
poprzedzona jednym lub kilkoma znakami okrelajcymi tryb pracy:

'S' - tryb skanowania
'C' - tryb leczenia
'M' - zawartoci pliku jest list elektroniczny
' ' - separator (bez znaczenia)

Na wyjciu zwracane s komunikaty (po jednej linii na kady sprawdzany plik),
zaczynajce si od sowa statusu, po ktrym nastpuje spacja i dodatkowe
informacje, w szczeglnoci nazwa pliku lub Message-ID listu, nazwa wirusa itp.
Sowo statusu moe mie posta:

"OK"  - brak wirusw, brak bdw
"CLN" - usunito wszystkie znalezione wirusy
"VIR" - w pliku pozosta(-y) wirus(-y)
"DEL" - skasowano plik z wirusem (w przypadku archiww i listw elektronicznych
        oznacza to skasowanie elementu archiwum lub zacznika listu)
"ERR" - podczas sprawdzania wystpi bd (np. brak dostpu do pliku)

W rnych wersjach mks_vir-a sowa statusu mog mie rne znaczenie
(w chwili pisania niniejszej instrukcji statusy "CLN" i "DEL" nie zostay
jeszcze zaimplementowane - zamiast nich pojawia si "VIR"), ale gwarantowane
jest zachowanie znaczenia statusu "OK". Wszystkie zwracane komunikaty
s generowane przez program mks32 (nie mksd), dlatego ich dokadnego
i aktualnego opisu naley szuka w dokumentacji do mks_vir-a.

Zapytania do serwera mona wysya przy uyciu opisanych powyej programw
lub bezporednio z wasnych aplikacji. Demonstruj to rda biblioteki
libmksd i programu mkschk, ktry korzysta z tej biblioteki. rda znajduj
si w pliku `inne/src.tar'. Mona je dowolnie modyfikowa i dostosowywa do
wasnych potrzeb. Aby mc korzysta z wielu procesw mks jednoczenie, program
kliencki musi "rozdzieli" strumienie wejcia i wyjcia. Powinien wwczas albo
zlicza zapytania i odpowiedzi, albo zasygnalizowa serwerowi koniec strumienia
wejciowego poprzez wywoanie funkcji

shutdown (fd, SHUT_WR)

i poczeka na zamknicie przez serwer poczenia. Mniej zalecan opcj
jest otwarcie naraz kilku pocze z serwerem.

Jeli pierwszym znakiem w strumieniu wejciowym jest '\n', to zamknicie
poczenia z serwerem funkcj shutdown() lub close() powoduje natychmiastowe
zerwanie poczenia, bez zapisania informacji o tym w logach systemowych.
Dziki temu mona przerywa skanowanie po znalezieniu pierwszego wirusa,
nawet jeli w buforach wejciowych demona znajduj si jeszcze nie przetworzone
cieki.

Serwer moe obsuy jednoczenie do 8 pocze (lub 2 razy tyle, ile wynosi
liczba procesw mks); po osigniciu tej liczby kolejni klienci musz czeka
na dostp do serwera.


11. Strony internetowe zwizane z mksd
--------------------------------------

W tej sekcji bd si pojawia adresy stron internetowych, na ktrych
uytkownicy mksd opisuj sposoby intergacji tego programu z innymi
elementami oprogramowania, w szczeglnoci z MTA. Jeli dane rozwizanie
dziaa w oparciu o program mkschk, naley skompilowa ten program ze rde
(opis kompilacji zamieszczono w pliku `inne/README').

http://www.nzs.pw.edu.pl/~bkorupcz/pub/prog/patches/
        m. in. opis integracji mksd z amavisem, podpicie demona amavisd
        do qmaila + skrypty administracyjne
                                                    [ Bartomiej Korupczyski ]

http://mks.s-gen.pl/
        opis integracji mksd z amavisem, kompilacja i konfiguracja amavisd,
        podpicie go do postfiksa + skrypt startujcy demony
                                                        [ Sergiusz Brzeziski ]

http://glinki.waw.pl/mks/qs.patch
        patch na qmail-scannera dodajcy wsparcie dla mksd i polskie
        komunikaty w ISO-8859-2
                                                               [ Marek Zbroch ]

http://vega.umcs.lublin.pl/sendmail/amavis_rh.html
        opis integracji mksd z amavisd-new podpitym do sendmaila + pakiety rpm
        z tymi programami (dla RedHata)
                                                              [ Mateusz Drach ]


12. Wykaz plikw
----------------

* README          - wiadomo
* CONOWEGO        - opis zmian wprowadzonych w biecej wersji
* LICENCJA        - warunki uytkowania pakietu mksd
* mksd,
  mksscan,
  mkschkin,
  mksfiltr        - opisane powyej binaria w wersjach zlinkowanych
                    dynamicznie
* mksd.static,
  mksscan.static,
  mkschkin.static,
  mksfiltr.static - opisane powyej binaria w wersjach zlinkowanych
                    statycznie
* inne            - starsze narzdzia i rne dodatki, opisane w pliku
                    `inne/README'


13. Adresy kontaktowe
---------------------

Projektem mks32 opiekuje si Kamil Konieczny <kkoniec@mks.com.pl>.
Projektem mksd opiekuje si Dariusz Grzegrski <darq@mks.com.pl>.
