NAME

       cyr_virusscan - Cyrus IMAP documentation

       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  mailbox owner of deleted messages via email.  This flag is only operable in
              combination with -r.

       -r     Remove infected messages.

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

       -v     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

AUTHOR

       The Cyrus Team, Nic Bernstein (Onlight)

COPYRIGHT

       1993–2023, The Cyrus Team