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

FreeBSD Manual Pages


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

     proxsmtpd -- an SMTP server for performing	filtering

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

     proxsmtpd is an SMTP filter that allows you to perform arbitrary filter-
     ing on email. It accepts SMTP connections and forwards the	SMTP commands
     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.

     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.

     The filter	script is specified using the FilterCommand option. By default
     the email is piped	through	the script on standard input.  Standard	output
     is	read for the filtered email. Standard error is also read for error

     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 vari-
     able. 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

     Various environment variables will	be present when	your script is run.
     You may need to escape them properly before use in	your favorite script-
     ing language. Failure to do this could lead to a REMOTE COMPROMISE	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	speci-
		 fied 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 command and
		 (b) the SMTP server (receiving	server)	must accept that XFOR-
		 WARD command without error.

		 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 command
		 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.

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

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

     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.

     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	traf-
     fic 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 go-
     ing 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 in-
     side a queue, which usually throttles the amount of email going through,
     this setting may need to be higher	than usual.

     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 tempo-
     rary files	to. In order to	be secure, it should not be a world writeable
     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).


     Stef Walter <>

proxsmtp			 May 12, 2021			      proxsmtp


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

home | help