Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
avcheck(1)		    General Commands Manual		    avcheck(1)

       avcheck - antivirus daemon client for mail system

       avcheck options -- recipient...

       avcheck	reads a	mail message from standard input, saves	it to a	tempo-
       rary file, and then asks	the running antivirus  daemon  to  check  this
       file  for  viruses.   If	no viruses are found, avcheck optionally rein-
       jects message back into mail system for further delivery.  If  the  an-
       tivirus	software claims	that message contains some virus-infected file
       or such,	avcheck	will call another program to handle this  message  and
       take  appropriate  actions.   In	case of	any error (except of incorrect
       usage/options), avcheck will exit with EX_TEMPFAIL exit code,  so  that
       further "delivery" attempt will be attempted again later, thus allowing
       to correct that error.

       Typically, avcheck is used as a part of mail  subsystem	to  scan  mail
       messages	before further delivery.

       The  "idea" behind this simple program is as follows: Mail messages are
       received	by a mail system, queued, and then passed to avcheck  for  in-
       spection.   If  a  message  passes the antivirus	check, then it will be
       routed using normal MTA mechanisms, either by  reinjecting  (requeuing)
       back  into  that	 same  mail subsystem (or other	a subsystem on another
       host etc), or by	continuing without reinjecting.	 Or, if	the  antivirus
       software	 detects  a  virus,  control  will be passed to	an administra-
       tor-defined handler that	will send virus-alert messages to  administra-
       tor,  sender  or	 recipients, places the	message	into quarantine	folder
       for further examination etc.

       Note that avcheck is not	a virusscanner,	but antivirus client: it can't
       work without a supported	antivirus daemon.  The antivirus daemon	should
       be able to handle MIME structure, attachtments,	archives  and  so  on,
       since avcheck itself doesn't contain any	code for these tasks.

       -f from (required)
	      specify envelope from (sender) address of	a mail message

       -s avtype[:avsocket] (required)
	      specifies	 antivirus  daemon  product to use and a path for it's
	      control socket.  Currently, only	antivirus  products  from  the
	      following	vendors	are supported:
	      avsocket	may  be	a pathname to Unix-domain socket, or host:port
	      for a TCP	connection.  In	latter case, host part may be  omitted
	      and  defaults to  avsocket may	be omitted, default is

       -d tmpdir (required)
	      specify a	temporary directory where the message will  be	stored
	      for  inspection  by  the	antivirus  daemon.   Do	 NOT use /tmp,
	      /var/tmp and other public-accessable directory here, but	create
	      one  especially  dedicated for mail antivirus scanning, and give
	      it appropriate, restrictive  permissions.	  If  tmpdir  contains
	      "/./"  component,	 e.g.  /var/avscan/./tmp, then avcheck assumes
	      that antivirus daemon is chrooted	in /var/avscan,	 and  filename
	      will  be	translated  accordingly	before being sent to antivirus

       -t timeout
	      set timeout in secounds to wait for answer  from	the  antivirus
	      daemon.	If  the	 answer	will not be available after this time,
	      avcheck will exit	with  EX_TEMPFAIL  error  code.	  By  default,
	      avcheck will not restrict	time it	waits for an answer.

       -n     do  not  reinject	 good message back into	mail subsystem (by de-
	      fault, avcheck will do so).

       -g okcode
	      exit with	okcode (default	0) when	no viruses found.  Useful with
	      conjunction with -n and an MTA which will	continue normal	deliv-
	      ery when AV inspector returns this exit code.

       -S sendmail
	      specifies	path to	sendmail-compatible program that will be  used
	      for  message  re-injection  (unless  -n option given).  May be a
	      pathname (starting with slash character),	or  host:port  to  use
	      (subset of) SMTP.	 Default is, i.e.  avcheck will
	      attempt to talk SMTP with	 localhost  using  the	standard  smtp

	      In  case	of SMTP	(host:port form), either host or port part may
	      be omitted  and  defaults	 to	and  25).   Note  that
	      avcheck's	 SMTP  implementation  does  not  permit multiline re-
	      sponses from SMTP	server,	and the	ESMTP  protocol	 is  not  sup-

	      When  given a path to local program, this	program	should be com-
	      patible with sendmail(1).	 In particular,	-f option  (specifying
	      envelope	from address) should be	supported, and this program is
	      expected to send a mail message given on	standard  input	 to  a
	      list of recipients specified in command line.  In	order to spec-
	      ify additional arguments for this	external  program  (for	 Send-
	      mail,  it	 may be	useful to specify -ppoto option, for example),
	      -S option	may be repeated	with all needed	arguments, or one  can
	      specify multiword	value for -S option.  For example, to specify
		/usr/sbin/sendmail -p AVSCAN
	      as a sendmail program, one may use either
		avcheck	-S "/usr/sbin/sendmail -p AVSCAN"
		avcheck	-S /usr/sbin/sendmail -S -p -S AVSCAN
		avcheck	-S /usr/sbin/sendmail -S "-p AVSCAN"
	      and so on.

	      When using Sendmail-compatible program, do not forget to specify
	      -i option	for it (use avcheck -S /usr/sbin/sendmail -S  -i),  to
	      stop sendmail from treating a line consisting of one dot charac-
	      ter (.) as end of	a message.

	      Note that	the flow path used for further delivery	 as  specified
	      by  this -S option should	not include avcheck again, or else the
	      mail will	loop.  The mail	system should assume  that  mails  in-
	      jected  by  this method are already safe from an antivirus point
	      of view.

       -h hdr Prepend the
		X-AV-Checked: <time> hdr
	      header line to every email message passed	virus check and	 rein-
	      jected  back  into the mail system (via the path specified by -S
	      option).	It is common to	use a local hostname as	 a  value  for
	      hdr.   Note  that	this option has	no effect when used with -c or
	      -n options or when avcheck encounters an infected	message.

       -i infected-program
	      specify  a  pathname  for	 an  external  program	(typically,  a
	      shell-like  script  will	be  used here) to handle infected mail
	      messages.	 Default  is  `infected'  in  the  same	 directory  as
	      avcheck  itself,	i.e. if	apcheck	called as /some/where/avcheck,
	      it will attempt to execute /some/where/infected  to  handle  in-
	      fected  mail.  This external program will	be called with 3 fixed
	      arguments: the full pathname where the infected message has been
	      stored  temporary	 (in  a	directory specified with -d option be-
	      low), it is up to	this handler to	delete this file; the  message
	      from  the	 antivirus  daemon  (may be multiline or empty if none
	      available), and the envelope from	(sender) address as  specified
	      with -f argument).  Next arguments will be recipient address(es)
	      as given to avcheck itself.

	      Environment variables for	this program will be set as follows:

	      PATH   will hold standard	"/bin:/usr/bin"	value.

		     will point	to a program with arguments sutable to	inject
		     a mail message into the mail subsystem that will not be a
		     subject for an antivirus check (as	specified with -S  op-
		     tion  for	avcheck).  In case when	argument for -S	option
		     specifies	 a   TCP   socket,    SENDMAIL	  will	  hold
		     "/path/to/avcheck -c -S host:port"	(see -c	option below).

	      This program/script should perform all the required work,	as lo-
	      cal administrator	decides.  Examples of such a shell script  are
	      provided in the avcheck distribution.

       -w waitfile
	      Instructs	 avcheck  not to attempt to contact with the antivirus
	      daemon and not to	perform	any actions but	 to  immediately  exit
	      with the EX_TEMPFAIL exit	code if	specified waitfile is present.
	      If it is not present, avcheck will operate as usual.   This  may
	      be  useful  to  safely restart antivirus daemon without worrying
	      about mails not being scanned etc	while the daemon starts	up and
	      initializes.   The idea behind this is to	create waitfile	before
	      reloading/restarting the daemon (e.g. when there is  a  need  to
	      reload  it's  antivirus  bases),	wait for some time so that all
	      current in-progress checking operations will complete, then  ac-
	      tually  reload/restart  a	daemon,	and after the reload completes
	      successefully to remove waitfile.	 All mails  that  need	to  be
	      checked  during  this time will be deferred by a mail system and
	      retried later.  Note that	avcheck	will always exit with EX_TEMP-
	      FAIL  in	case  of  any error (e.g. when connection to antivirus
	      daemon can't be established or a daemon returned some unexpected

       -c     This  is a special option	that turns on the special "mail	injec-
	      tion client" mode.  If this option is given, avcheck will	read a
	      mail  message from standard input	and inject it into mail	system
	      as specifier by -S option.  Only -f (from) option	 and  list  of
	      recipients  are  required;  all other options are	ignored.  Note
	      that avcheck will	not contact the	antivirus daemon in this mode,
	      it will only submit mail without checking	it for viruses.

	      This  mode of operation can be used inside the `infected'	script
	      to submit	message(s) (see	-S option).  When sendmail given in -S
	      option  specifies	a TCP socket, avcheck sets the $SENDMAIL envi-
	      ronment variable to be
		/path/to/avcheck -c -Ssendmail
	      where sendmail is	the argument given to -S option, so  that  the
	      script  can  submit mail using the same SMTP protocol as avcheck

       Many mail transfer agents exists, and every one needs it's own  section
       here.   For  now,  please read various README files in the avcheck dis-

       In order	to operate safely and securely,	the "antivirus	checking  sub-
       system"	should	be  configured	properly.   Most  important  parts are
       filesystem and process permissions.  Many antivirus software  available
       today  runs  as	root  user  by	default	-- this	is a very bad idea and
       clearly violates	the "principle of least	privilege".   This  simplifies
       access  to any user's file from the antivirus daemon (in	order to check
       a file for viruses, the daemon needs read permissions for  that	file),
       but  opens  a  great risk to crack a system (in case of bugs in the an-
       tivirus software, inaccurate settings and so on).  Unfortunately,  many
       antiviruses  today,  while  being good at their primary task (detecting
       viruses), are inaccurate	from security/stability	point of view.

       To use antivirus	in mail	system,	I recommend to set  up	two  user  ac-
       counts  on  a  system  that will	be dedicated for virusscanning of mail
       (and nothing else!).  One account (be it	avdaemon for example)  is  for
       antivirus  daemon, and another (avclient) is for	antivirus client (like
       avcheck).  Place	them both in one (again, dedicated for this  purposes)
       group  (named e.g. avgroup), and	set up a temporary directory owned and
       fully accessible	by avclient user, executable by	avgroup, and  not  ac-
       cessible	 by  anyone  else.   If	 the antivirus daemon uses Unix-domain
       socket for control connection (like AVP does or DrWeb may be configured
       to  do),	 then place it to a directory owned by avdaemon	and accessible
       by avgroup group	(for avclient user) only.

       This way:

       o      the mail system will not harm the	antivirus daemon, since	it has
	      no permissions to	do so;

       o      the  antivirus  daemon will not be able to access/crash mailsys-
	      tem, and message(s) stored in that temporary directory  will  be
	      safe as no one else will be able to read/modify them

       o      the  antivirus  daemon  will  not	be able	to modify them as well
	      (but can read them in order to check for viruses).

       Configure mail system in	such a way so that it will call	avcheck	as av-
       client user, grouop avgroup.

       For  extra care,	antivirus daemon may be	run chrooted (avcheck supports
       this, see -d option).

       To simplify running the antivirus daemon	chrooted and as	non-privileged
       user,  there  is	a program in the avcheck distribution, called uchroot.
       It is similar to	the standard unix chroot(1) utility, but has two addi-
       tional  options:	-u, to switch to given userid before running specified
       program,	and -d,	to chdir to non-root directory inside the chroot jail.

       This program written by Michael Tokarev <>,	with many con-
       tributions,   ideas   and  testing  by  Ralf  Hildebrandt  <Ralf_Hilde->.

       This program is a public	domain code.  Do with it anything you like.



Want to link to this manual page? Use this URL:

home | help