Documentation for TransparentProxy

3 files changed, 36 insertions, 3 deletions

diff --git a/doc/clamsmtpd.8 b/doc/clamsmtpd.8
index 2317b59..b25f082 100644
--- a/doc/clamsmtpd.8
+++ b/doc/clamsmtpd.8
@@ -114,6 +114,29 @@ Make sure the
 .Ar MaxConnections
 setting is set high enough to handle the mail from all the servers without refusing
 connections. 
+.Sh TRANSPARENT PROXY FEATURE
+A transparent proxy is a configuration on a gateway that routes certain types of 
+traffic through a proxy server without any changes on the client computers. 
+.Nm
+has support for transparent proxying of SMTP traffic by enabling the 
+.Ar TransparentProxy
+setting. This type of setup usually involves firewall rules which redirect traffic to 
+.Nm 
+and the setup varies from OS to OS. The SMTP traffic will be forwarded to it's 
+original destination after being scanned. 
+.Pp
+When doing transparent proxying for outgoing email it's probably a good idea to 
+turn on bounce notifications using the
+.Ar Bounce
+setting. Also note that some features (such as SSL/TLS) will not be available
+when going through the transparent proxy. 
+.Pp
+Make sure that the
+.Ar MaxConnections 
+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 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 
diff --git a/doc/clamsmtpd.conf b/doc/clamsmtpd.conf
index 18ff33a..b450091 100644
--- a/doc/clamsmtpd.conf
+++ b/doc/clamsmtpd.conf
@@ -6,12 +6,14 @@
 # - All the options are found below with their defaults commented out
 
 
-# The address to send scanned mail to. Required
+# The address to send scanned mail to.
+# This option is required unless TransparentProxy is enabled
 OutAddress: 10026
 
 
 
-# The maximum number of connection allowed at once
+# The maximum number of connection allowed at once.
+# Be sure that clamd can also handle this many connections
 #MaxConnections: 64
 
 # Amount of time (in seconds) to wait on network IO
@@ -35,4 +37,5 @@ OutAddress: 10026
 # Whether or not to keep virus files
 #Quarantine: off
 
-
+# Enable transparent proxy support
+#TransparentProxy: off
diff --git a/doc/clamsmtpd.conf.5 b/doc/clamsmtpd.conf.5
index 7d698af..c61a0fc 100644
--- a/doc/clamsmtpd.conf.5
+++ b/doc/clamsmtpd.conf.5
@@ -95,6 +95,8 @@ character or number):
 [ Default: off ] 
 .It Ar MaxConnections
 Specifies the maximum number of connections to accept at once. 
+.Xr clamd 8
+also needs to be setup to accept at least this number of connections. 
 [ Default: 64 ]
 .It Ar ScanHeader
 A header to add to scanned messages. Put an empty value to supress adding
@@ -116,6 +118,11 @@ and
 .It Ar TimeOut
 The number of seconds to wait while reading data from network connections.
 [ Default: 180 seconds ]
+.It Ar TransparentProxy
+This option enables transparent proxy support, which allows you to route all 
+SMTP traffic that's going through a gateway through clamsmtp which will then 
+send it on to its final destination. This setup usually involves firewall 
+rules which redirect traffic to clamsmtp, and the setup varies from OS to OS.
 .El
 .Sh ADDRESSES
 Addresses can be specified in multiple formats: