More warnings about the virus action functionality

1 files changed, 44 insertions, 0 deletions

diff --git a/doc/clamsmtpd.8 b/doc/clamsmtpd.8
index b25f082..526f4ae 100644
--- a/doc/clamsmtpd.8
+++ b/doc/clamsmtpd.8
@@ -137,6 +137,44 @@ setting is set high enough for your transparent proxying. Because
 .Nm 
 is not being used as a filter inside a queue, which usually throttles the amount
 of email going through, this setting may need to be higher than usual. 
+.Sh VIRUS ACTIONS
+Using the 
+.Ar VirusAction
+option you can run a script or program whenever a virus is found. This may 
+be handy in certain circumstances but it has several drawbacks. For one, the 
+performance of the virus filtering will take a hit, perhaps DOS'ing your 
+machine under heavy load. Secondly as with running any program there are 
+security implications to be considered. 
+.Pp
+.Please consider the above carefully before implementing a virus action. 
+.Pp
+The script is run without its output being logged, or return value being 
+checked. Because of this you should test it thoroughly. Make sure it runs
+without problems under the user that 
+.Xr clamsmtpd 8
+is being run as. 
+.Pp
+Various environment variables will be present when your script is run. You 
+may need to escape them properly before use in your favorite scripting 
+language. Failure to do this could lead to a REMOTE COMPROMISE of your 
+machine.
+.Bl -tag -width Fl
+.It Ar EMAIL
+When the
+.Ar Quarantine
+option is enabled, this specifies the file that the virus was saved to.
+.It Ar RECIPIENTS
+The email addresses of the email recipients. These are specified one per 
+line, in standard address format. 
+.It Ar SENDER
+The email address for the sender of the email. 
+.It Ar TMP
+The path to the temp directory in use. This is the same as the 
+.Ar TempDirectory
+option. 
+.It Ar VIRUS
+The name of the virus found.
+.El
 .Sh SECURITY
 There's no reason to run this daemon as root. It is meant as a filter and should
 listen on a high TCP port. It's probably a good idea to run it using the same 
@@ -152,6 +190,12 @@ writeable location. Specify the directory using the
 .Ar TempDirectory
 setting.
 .Pp
+When using the 
+.Ar VirusAction
+option make sure you understand the security issues involved. Unescaped 
+environment variables can lead to execution of arbitrary shell commands 
+on your machine.
+.Pp
 If running 
 .Nm
 on a publicly accessible IP address or without a firewall please be sure to