**cyr_virusscan**
*****************

Scan for viruses using configured virus scanner or manage infected
messages using search criteria.


Synopsis
========

   **cyr_virusscan** [ **-C** *config-file* ] [ **-s** *imap-search-string* ] [ **-r** [ **-n**] ] [**-v**] [ *mboxpattern1* ... ]


Description
===========

**cyr_virusscan** can be used to invoke an external virus scanner
(currently only ClamAV is supported) to scan specified IMAP mailboxes.
If no mboxpattern is given, **cyr_virusscan** works on all mailboxes.

Alternately, with the **-s** option, the IMAP SEARCH string will be
used as a specification of messages which are *assumed* to be
infected, and will be treated as such.  The virus scanner is not
invoked. Useful for removing messages without a distinct signature,
such as Phish.

A table of infected messages will be output.

To remove infected messages, use the **-r** flag. Infected messages
will be expunged from the user's mailbox.

With the notify flag, **-n**, notifications will be appended to the
inbox of the mailbox owner, containing message digest information for
the affected mail. This flag only works in combination with **-r**.
The notification message can by customised by template, for details
see Notifications below.

**cyr_virusscan** can be configured to run periodically by cron(8) via
crontab(5) or your preferred method (i.e. /etc/cron.hourly), or by
master(8) via the EVENTS{} section in cyrus.conf(5).

**cyr_virusscan** reads its configuration options out of the
imapd.conf(5) file unless specified otherwise by **-C**.

Note that Cyrus does not ship with any virus scanners: you need to
install one separately to make use of it with Cyrus.


Options
=======

-C config-file

   Use the specified configuration file *config-file* rather than the
   default imapd.conf(5).

-n, --notify

   Notify mailbox owner of deleted messages via email.  This flag is
   only operable in combination with **-r**.

-r, --remove-infected

   Remove infected messages.

-s imap-search-string, --search=imap-search-string

   Rather than scanning for viruses, messages matching the search
   criteria will be treated as infected.

-v, --verbose

   Produce more verbose output


Notifications
=============

When the **-n** flag is provided, notifications are sent to mailbox
owners when infected messages are removed.  One notification is sent
per owner, containing a digest of each message that was deleted from
any of their mailboxes.

The default notification subject is "Automatically deleted mail",
which can be overridden by setting "virusscan_notification_subject" in
imapd.conf(5) to a UTF-8 value.

Each infected message will be described according to the following
template:

   The following message was deleted from mailbox '%MAILBOX%'
   because it was infected with virus '%VIRUS%'

       Message-ID: %MSG_ID%
       Date: %MSG_DATE%
       From: %MSG_FROM%
       Subject: %MSG_SUBJECT%
       IMAP UID: %MSG_UID%

To use a custom template, create a UTF-8 file containing your desired
text and using the same %-delimited substitutions as above, and set
the "virusscan_notification_template" option in imapd.conf(5) to its
path.

The notification message will be properly MIME-encoded at delivery. Do
not pre-encode the template file or the subject!

When **cyr_virusscan** starts up, if notifications have been requested
(with the **-n** flag), a basic sanity check of the template will be
performed prior to initialising the antivirus engine.  If it appears
that the resultant notifications would be undeliverable for some
reason, **cyr_virusscan** will exit immediately with an error, rather
than risk deleting messages without notifying.


Examples
========

   **cyr_virusscan**

   Scan all mailboxes, printing report on the screen.  Do not remove
   infected messages.

   **cyr_virusscan** -r -n user/bovik

   Scan mailbox *user/bovik*, removing infected messages and append
   notifications to Bovik's inbox.

   **cyr_virusscan** -r -n -s 'SUBJECT "Fedex"' user/bovik

   Search mailbox user/bovik for messages which have Fedex in the
   subject line, removing them all, and appending notifications to
   Bovik's inbox.


History
=======

Virus scan support was first introduced in Cyrus version 3.0.


Files
=====

/etc/imapd.conf


See Also
========

imapd.conf(5), master(8), ClamAV