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

FreeBSD Manual Pages

  
 
  

home | help 
proxsmtpd(8)		    System Manager's Manual		  proxsmtpd(8)

NAME
       proxsmtpd -- an SMTP server for performing filtering

SYNOPSIS
       proxsmtpd [-d level] [-f	configfile] [-p	pidfile]
       proxsmtpd -v

DESCRIPTION
       proxsmtpd  is  an SMTP filter that allows you to	perform	arbitrary fil-
       tering on email.	It accepts SMTP	connections and	forwards the SMTP com-
       mands and responses to another SMTP server.

       The DATA	email body is intercepted and scanned before forwarding. Email
       can be altered, bounced,	or silently dropped.

       proxsmtpd aims to be lightweight	and simple rather than have  a	myriad
       of  options.  The  options  it  does have are configured	by editing the
       proxsmtpd.conf(5) file. See the man page	for proxsmtpd.conf(5) for more
       info on the default location of the configuration file.

OPTIONS
       The options are as follows.

       -d	   Don't detach	from the console and run as a daemon. In addi-
		   tion	the level argument specifies what level	of error  mes-
		   sages to display. 0 being the least,	4 the most.

       -f	   configfile	specifies   an	 alternate  location  for  the
		   proxsmtpd configuration  file.  See	proxsmtpd.conf(5)  for
		   more	 details on where the configuration file is located by
		   default.

       -p	   pidfile specifies a location	for the	a process id  file  to
		   be  written	to.  This  file	 contains  the	process	 id of
		   proxsmtpd and can be	used to	stop the daemon.

       -v	   Prints the proxsmtp version number and exits.

FILTER SCRIPTS
       The filter script is specified using the	FilterCommand option.  By  de-
       fault  the  email is piped through the script on	standard input.	 Stan-
       dard output is read for the filtered email. Standard error is also read
       for error messages.

       If the FilterType option	is set to 'file', your filter will operate  on
       a  file	rather	than processing	standard in and	standard out. The file
       name will be passed to your filter command using	the EMAIL  environment
       variable.  Your script can change the file as needed. Standard error is
       still processed as outlined below.

       If the filter command returns a successful exit code (ie: 0), then  the
       filtered	 email is sent to the destination mail server as usual.	When a
       error exit code (ie: anything but 0) a failure message is sent back  to
       the sending server. In this case	the email is not sent.

       You  can	customize the error message sent back. The last	line of	output
       printed to standard error will be used in this case. If you  specify  a
       full  SMTP  error  code	then it	will be	used (ie: '550 Bad Email'). If
       it's just a text	message	then a 550 SMTP	error code will	be used.

       You can silently	drop messages by using an error	 message  with	a  250
       SMTP  code.   This  gives  the  illusion	to the sending server that the
       email was accepted.

       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  COMPRO-
       MISE of your machine.

       CLIENT	   The network address of the SMTP client connected.

       EMAIL	   When	the FilterType option is set to	'file',	this specifies
		   the file that the email was saved to.

       RECIPIENTS  The	email  addresses  of  the  email recipients. These are
		   specified one per line, in standard address format.

       REMOTE	   If proxsmtpd	is being used to  filter  email	 between  SMTP
		   servers,  then  this	 is  the  IP  address  of the original
		   client. In order for	this information to be present (a) the
		   SMTP	client (sending	server)	must an	send an	XFORWARD  com-
		   mand	and (b)	the SMTP server	(receiving server) must	accept
		   that	XFORWARD command without error.

       REMOTE_HELO
		   If  proxsmtpd  is  being  used to filter email between SMTP
		   servers, then this is the HELO/EHLO banner of the  original
		   client. In order for	this information to be present (a) the
		   SMTP	 client	(sending server) must an send an XFORWARD com-
		   mand	and (b)	the SMTP server	(receiving server) must	accept
		   that	XFORWARD command without error.

       SENDER	   The email address for the sender of the email.

       SERVER	   The network address of the SMTP server we're	connected to.

       TMPDIR	   The path to the temp	directory in use. This is the same  as
		   the TempDirectory option.

LOGGING
       proxsmtpd logs to syslogd by default under the 'mail' facility. You can
       also output logs	to the console using the -d option.

LOOPBACK FEATURE
       In  some	 cases it's advantageous to consolidate	the filtering for sev-
       eral mail servers on one	machine.  proxsmtpd allows this	by providing a
       loopback	feature	to connect back	to the	IP  that  an  SMTP  connection
       comes in	from.

       To  use this feature specify only a port	number (no IP address) for the
       OutAddress setting in the configuration file. This will cause proxsmtpd
       to pass the email back to the said port on the incoming IP address.

       Make sure the MaxConnections setting is set high	enough to  handle  the
       mail from all the servers without refusing connections.

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.  proxsmtpd has	support	for  transparent  proxying  of
       SMTP  traffic  by  enabling  the	TransparentProxy setting. This type of
       setup  usually  involves	 firewall  rules  which	 redirect  traffic  to
       proxsmtpd  and the setup	varies from OS to OS. The SMTP traffic will be
       forwarded to it's original destination after being scanned.

       Note that some features (such as	SSL/TLS) will not  be  available  when
       going through the transparent proxy.

       Make  sure  that	the MaxConnections setting is set high enough for your
       transparent proxying. Because proxsmtpd 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.

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.

       Care  should be taken with the directory	that proxsmtpd writes its tem-
       porary files to.	In order to be secure, it should not be	a world	write-
       able location. Specify the directory using the TempDirectory setting.

       Make sure you understand	the issues  involved  with  escaping  external
       data. The environment variables such as SENDER or RECIPIENTS need to be
       treated with care.

       If  running  proxsmtpd on a publicly accessible IP address or without a
       firewall	please be sure to understand all the possible security issues.
       This is especially true if the loopback feature is used (see above).

SEE ALSO
       proxsmtpd.conf(5)

AUTHOR
       Stef Walter <stef@memberwebs.com>

proxsmtp			September, 2004			  proxsmtpd(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=proxsmtpd&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>

home | help