NAME
  smtp-gated.conf - The smtp-gated configuration file.
DESCRIPTION
  This file defines configuration to be used by daemon.

  Options are placed one per line, and consists of option name, followed
  by number or spaces or tabs, and option value. Empty lines, and lines
  starting with # or ; (hash or semicolon) are ignored.

  Tags in square brackets, show additional information for each variable. See
  EXPLANATION later in this manual.

  This manual describes configuration for 1.4.14-rc1.
  For previous releases, use manuals included in source archive.

MAIN OPTIONS
  proxy_name STRING	Name that appears on communicates generated by daemon.
	(usually errors, or session blocking).
  bind_address IP [RESTART]	Defines IP the daemon listes on.
  port PORT [RESTART]		Defines listening TCP port.
  source_addr IP	Defines IP which appears as source on MTA servers.
  pidfile FILE [RESTART]	Defines .pid file path.
  dumpfile FILE		Defined file which will contains status. Status is
	dumped on receiving signal USR1.
  chroot_path PATH [RESTART] If this setting is defined, daemon chroot()'s to this
	path after forking. This allows to raise security.
  set_user USER	[RESTART]	
  set_group GROUP [RESTART]	Daemon changes it UID/GID to the one defined for username
	and groupname. This setting does not allow to specify UID/GID as
	numbers yet. Do NOT run proxy as root, as this will break locking.
  priority INT [RESTART]	Daemon changes it's priority when it's defined. 0
	means "no change". Values as in setpriority(2).
  connect_queue INT	Defines listen(2) backlog.
  buffer_size UINT	Defines buffer size (in bytes) to track SMTP sessions.
	Should be above 1500.
  pipeline_size UINT	Queue size for SMTP PIPELINING extension.
  mode nat|fixed|remote [ONE,RESTART]	Set operating mode, choose one of "nat", "fixed",
	"remote".
NAT MODE
  In this mode, all connections are forwarded to original MTA. Netfilter or ipfw
  connection tracking is used to lookup destination IP. Probably this is what
  you want. This mode was formerly enabled by "use_netfilter" option.
FIXED MODE
  In this mode, all connections are forwarded to one, defined MTA. This
  may be used to filter SMTP traffic just before ISP SMTP server. Use it, if
  you want to protect your SMTP server from outside world.

  fixed_server IP	IP of MTA to connect to.
  fixed_server_port PORT	Port to connect to.
REMOTE IDENT MODE
  In this mode, daemon is running on dedicated server. For each incoming
  connection lookup is performed on source IP, to discover destination IP.
  This requires patched ident daemon (not public yet), and therefore is
  useless for most users.
  lookup_port PORT	Port to lookup ident and destination IP.
LOCKING
  When virus/SPAM is found, user's IP or IP+ident can be blocked for certain
  time. After that time, lock is removed, and user is allowed to use SMTP
  again. Lockfile has name same as IP, or IP "-" IDENT if ident is used.

  Administrator can prevent locking some IP (IP+ident), by creating
  corresponding lock file with owner other than daemon runs on. This lock file
  is not automatically deleted. Contents is ignored, so it can be description,
  or sth else.
  lock_on virus|spam|maxhost|maxident|never [MULTI]	Set events locking
	occurs for. See max_per_host, max_per_ident.
  lock_duration	INT [s]	Time the lock persists. 0 disables locking, -1 means
	lock forever (or: until manually unlocked).
  lock_path PATH	Directory for lock files.
  lock_perm OCTAL	Lock files permissions as for open(2). Octal value
	must be preceded by zero.
ACTION SCRIPT
  Action script is called when virus or spam is found. If locking is used,
action_script is called only when lock is created (once until unblocked).
  action_script FILE	Defines path to script called when virus/spam is
	found.

  All parameters are passed via environment variables:
  PROXY_NAME	proxy name as defined in proxy_name in config file [>=1.4.12-rc7]
  FOUND		contains word "VIRUS" or "SPAM", "MAX_HOST", "MAX_IDENT".
  VIRUS_NAME	virus name if virus found.
  SPAM_SCORE	spam score if spam found.
  SOURCE_IP	source IP.
  SOURCE_PORT	source port.
  TARGET_IP	target (SMTP server) IP.
  TARGET_PORT	target (SMTP server) port.
  LOCAL_IP	local (proxy) IP as redirected.
  LOCAL_PORT	local (proxy) port as redirected.
  IDENT		source ident [REMOTE].
  IDENT_COUNT	connections count from particular host+ident [REMOTE].
  MAIL_FROM	SMTP "MAIL FROM" line, stripped.
  RCPTS_COUNT	total number of mail recipients in session (not transaction).
  SIZE		message size [bytes].
  TRANSACTION	transaction number, starting from 1.
  SPOOL_NAME	spool file name.
  LOCK_FILE	lock file name.
  TIME		time of connection start, human readable text.
  UNIXTIME	time of connection start, unix timestamp.
SPOOLING
  spool_path PATH	Directory for temporary message files.
  spool_perm OCTAL	Temporary files permissions as for open(2). Octal
	value must be preceded by zero.
  spool_leave_on error|spam|virus|never [MULTI]		Set events, spool file is left for.
	If set to "never", spool is always deleted.
TIMEOUTS
  All timeouts are specified in seconds.
  timeout_direct UINT	Timeout for direct proxy session. This type of session
	is used on TLS connections.
  timeout_lookup UINT [REMOTE]	Timeout for lookup.
  timeout_scanner UINT	Timeout for antivirus scanner engine.
  timeout_spam UINT	Timeout for antispam scanner engine.
  timeout_session UINT	Timeout for fake session (when virus/SPAM is blocked).
  timeout_idle UINT	Timeout for idle sessions. Prevents stale connections.
  timeout_connect UINT	Timeout for connecting to remote MTA.
AUTHENTICATION
  Proxy can limit access to MTA, according to SMTP AUTH support and state.
  For now, there is no way to whitelist host or MTA.

  auth_require no|loose|mandatory [ONE]	Set authorization requirements:
	no		do not require any authorization, pass all messages.
	loose		require authorization if MTA advertises support for it. If authorization is not advertised, mail is passed. If authorization is advertised, mail is passed only if client has authorized successfully.
	mandatory	require authorization for all connections. It MTA does not support authorization, no mail is passed.

  Authentication state is logged in "CLOSE by=... auth=N", where N is bitwise OR for following values:
	1		MTA supports auth (advertised in EHLO response)
	2		user authenticated successfuly
	4		user authentication failed (rejected by MTA)

LIMITS
  All sizes are specified in bytes.
  Loadavg limits can be disabled by specyfing zero, but this is not
  recommended.
  max_connections UINT [RESTART]	Total maximum connections.
  max_per_host UINT	Maximum connections per source IP.
  max_per_ident UINT [REMOTE]	maximum connections per IP+ident.
  max_load FLOAT	Reject connections if load is above this setting.
  scan_max_size UINT	av-scan messages with size up to this limit.
  spam_max_size	INT	SPAM-scan messages with size up to this limit. Should
spam scanning be turned off, set it to 0 (default).
  spam_block BOOL	Block SPAM-s (like viruses) instead of just logging.
Remember to set spam_max_size (see CAVEATS).
  spam_max_load FLOAT	Don't SPAM-scan messages if load above this setting.
  spam_threshold FLOAT	Treat message as SPAM if it's score is equal/greater
	than this value.
MISCELLANOUS
  ignore_errors	BOOL	Continue when possible even if error occured (i.e.
	virus scanner failure).
LOGGING
  Daemon logs messages via syslog, facility daemon.
  log_helo BOOL		Logs HELO/EHLO issued by client.
  log_mail_from	accepted|rejected|base64|off [MULTI]	Client MAIL FROM logging
options:
		off		[do not log]
		accepted	log if address is accepted by MTA
		rejected	log if address is rejected by MTA
		base64		log as base64 encoded md5 hash of e-mail
  log_rcpt_to [MULTI]	Client RCPT TO logging mask. (see log_mail_from).
  email_length UINT	MAIL FROM/RCPT TO email length limit (before optional md5 encoding).
  log_level debug|info|notice|warning|err|alert|emerg|crit [ONE,RESTART]	Defined log level, as used by syslog(3):
	crit	Emergency messages (highest priority)
	emerg	Critical, requires intervention
	alert	Critical messages
	err	Errors
	warning	Warnings
	notice	Normal, but significiant messages
	info	Informational messages
	debug	Debugging messages (lowest priority)
  log_facility user|mail|daemon|auth|news|authpriv|local0|local1|local2|local3|local4|local5|local6|local7 [ONE,RESTART]	Defined log facility, as used by syslog(3).
MANGLING
  nat_header		Header injected into message stream header (sent to
	MTA); default is "X-NAT-Received" [>=1.4.12-rc5]
  nat_header_type none|simple|full [ONE]	Turns on/off injecting X-NAT-Received headers to messages. [>=1.4.12-rc5]
	none	[no header]
	full	full header
	simple	simple header (source IP only; useful in fixed mode)
  spool_header		Header injected into message spool header (not sent to MTA, visible in AV-scanner and AS-scanner), default is "X-Proxy-Spool-Info" [>=1.4.12-rc5]
  abuse	STRING		Sets "abuse" info in full X-NAT-Received header.
SCANNERS
  scanner_path FILE	not used.
  antivirus_type off|clamd [ONE]	Choose antivirus to use. "off" means
	no scanning.
  antivirus_path SOCKET		Path for clamd socket.
  antispam_type off|spamassassin [ONE]	Choose antispam to use. "off" means no
	scanning.
  antispam_path SOCKET	Path for spamd socket.
MESSAGES
  All messages sent to user are customisable.

  locale		Changes locale of system errors from strerror(3). See
	setlocale(3). Does not change messages generated by daemon itself.
MESSAGES MAIN
  msg_virus_found	Virus found in message.
  msg_virus_locked	User locked, virus or SPAM found before.
  msg_spam_found	SPAM found in message.
  msg_unknown_virus	Virus name substituted, when it's unknown.
  msg_spool_problem	Spooling file name problem.
  msg_spool_open_fail	Spool creation failed.
  msg_pipeline_full	Pipeline queue full.
  msg_scanner_failed	Scanner has failed.

  msg_cannot_connect	Cannot connect to MTA.
  msg_connect_timeout	Connection to MTA timed out.
  msg_nomem		Out of memory
MESSAGES FAKE MTA SESSION
  msg_hello		Hello message.
  msg_sign_off		Signing off.
  msg_virus_no_more	Virus found, please end the session.
  msg_session_timeout	Session timed out.
  msg_proto_error	Protocol error.
  msg_transaction_failed	Fake MTA transaction failed.
  msg_unimpl_command	Unimplemented command (SMTP verb).
  msg_temp_unavail	Service temporarily unavailable.
MESSAGES LIMITS
  msg_max_reached	Total connections limit reached, try again later.
  msg_max_per_host	Connections limit for IP reached, try again later.
  msg_max_per_ident	Connections limit for IP+ident reached, try again
	later.
  msg_system_load	System load too high, try again later.
MESSAGES FOR REMOTE IDENT MODE
  msg_malformed_ip	Malformed IP received [REMOTE].
  msg_lookup_failed	Lookup failed.
  msg_lookup_timeout	Lookup timed out.
  msg_lookup_mismatch	Invalid lookup response format.
  msg_lookup_nomem	Lookup failed, not enough memory.

FAQ
  These are popular Questions and Answers:

  Q1: Antispam is not working! What is wrong?	You must change max_spam_size to something above 0 to turn on antispam scanning. It's set to 0 by default, and this means turning antispam off. Also, set antispam_type.
  Q2: Spammers don't get locked! What is wrong?		If you want to block spammers, set spam_block to 1, and see Question#1.
  Q3: I wanted to block some user by creating lockfile manually, but now his traffic is not even scanned!	Creating lockfile with owner other than proxy process runs with, will protect that host from being locked. The contents of file does not matter.
  Q4: My header is invalid after upgrading!	nat_header changed into nat_header_type since 1.4.12-rc5, so after upgrade header will not be injected unless you rename it in configuration file.
  Q5: I don't have idents in my logs or headers, why?	It simple -- ident is used in REMOTE IDENT mode, which is currently not available.
  Q6: I don't see X-NAT-Received header in mails, why?	Please remember, that mail sent with TLS is not scanned. Also, check nat_header_type directive in your config file, and nat_header (see MANGLING above).
  Q7: When X-Virus-Scan and/or X-Spam-Status headers will be supported?		The answer is: never. Reason is simple -- proxy is passing-thru email headers and body. Because headers are sent first, we can't predict spam-score or virus presence. The main assumption for this project was not to buffer mail before forwarding, so this option won't appear.
  Q8: I have many locks left, even if they should be gone long time ago!	Lock files are check (and eventually removed) for every incoming connection. They will exist after expiration, until next connection from its "owner".
  Q9: Host gets locked, lock file appears, but he can still send e-mails!  Please *do not* run proxy as root, and set set_user properly. If you do, remove all locks manually.

CHANGES
  1.4.14-rc1:	Changed many configuration options. Please review your previous configuration using:
	smtp-gated -t /path/to/smtp-gated.conf

REPORTING BUGS
  If you are willing to sent me a bug report, please check manuals first to
ensure you have configured properly. In report, please include:

  1. output of "smtp-gated -V"
  2. config file (as attachment if big)
  3. logs related to e-mails sent, with "debug" set to 7
  4. optional mail header (as sent from proxy).

EXPLANATION
  INT	Signed integer
  UINT	Unsigned number; can be specified as decimal, octal (beginning
	with 0), or hexadecimal (beginning with 0x or 0X)
  BOOL	Boolean (0, 1)
  FLOAT	Floating-point number
  IP	Valid IP address
  PORT	Valid IP port
  STRING	Arbitrary text string
  PATH	Valid directory name
  FILE	Valid file name
  SOCKET	UNIX socket or TCP socket. UNIX socket must begin with backslash ("/"), otherwise path is considered TCP socket and must be submitted in following form: ip:port (i.e. 127.0.0.1:1097)
  [ONE]		Only one value allowed.
  [MULTI]	Multiple values allowed, comma separated (do NOT insert any white space before comma).
  [RESTART]	This option needs full restart to take effect.
  [REMOTE]	This option affects REMOTE IDENT MODE only.
SEE ALSO
  smtp-gated(8)
HOMEPAGE
  http://smtp-proxy.klolik.org
AUTHOR
  Bartlomiej Korupczynski <smtp-proxy@klolik.org>

