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

FreeBSD Manual Pages


home | help
masqmail.conf(5)		 File Formats		      masqmail.conf(5)

       masqmail.conf - masqmail	configuration file

       This  man  page	describes the syntax of	the main configuration file of
       masqmail.  Its usual location is	/etc/masqmail/masqmail.conf

       The configuration consists of lines of the form

	       val = expression

       Where val is a variable name and	expression  a  string,	which  can  be
       quoted  with double quotes `"'.	If the expression is on	multiple lines
       or contains characters other than letters,  digits  or  the  characters
       `.',  `-',  `_',	 `/',  ';',  '@', ':', it must be quoted.  You can use
       quotes inside quotes by escaping	them with a backslash.

       Each val	has a type, which can be boolean, numeric, string or list.   A
       boolean	variable  can  be  set with one	of the values `on', `yes', and
       `true' or `off',	`no' and `false'.  List	items are separated with semi-
       colons `;'.  The	spaces around the equal	sign `=' are optional.

       All  lists, except and	permanent_routes, accept abso-
       lute pathnames (leading slash `/') as entries, too.  They can be	inter-
       mixed  with  normal  entries.   The contents of these files will	be in-
       cluded at this position in the list.  This makes	including large	 lists
       more convenient.	 Within	these files, each line is one entry; the semi-
       colon is	no separator.

       Blank lines and lines starting with a hash `#' are ignored.

       run_as_user = boolean

	      If this is set, masqmail runs with the user id of	the  user  who
	      invoked it and never changes it.	This is	for debugging purposes
	      only.  If	the user is not	root, masqmail will  not  be  able  to
	      listen  on  a  port < 1024 and will not be able to deliver local
	      mail to others than the user.

       use_syslog = boolean

	      If this is set, masqmail uses syslogd for	logging.  It uses  fa-
	      cility MAIL.  You	still have to set log_dir for debug files.

       debug_level = n

	      Set the debug level.  Valid values are 0 to 6 and	9.  Be careful
	      if you set this as high as 5 or higher, the logs may  very  soon
	      fill  your  hard	drive.	Level 9	enables	printing of debug mes-
	      sages to stderr during reading of	the config  file.   The	 debug
	      file  comes  available for the first time	after this step.  Thus
	      nothing but stderr is available.	Level 9	is almost never	inter-

       log_dir = file

	      The directory where logs are stored, if syslog is	not used.  De-
	      bug files	are always stored in this directory  if	 debugging  is
	      enabled.	file must be an	absolute path.

	      Default: /var/log/masqmail

       mail_dir	= file

	      The    directory	 where	 local	 mail	is   stored,   usually
	      /var/spool/mail or /var/mail.  file must be an absolute path.

	      Default: /var/mail

       spool_dir = file

	      The directory where masqmail stores its spool  files  (and  lock
	      files  if	 run_as_user).	 Masqmail needs	read and write permis-
	      sions for	this directory.	 file must be an absolute path.

	      Default: /var/spool/masqmail

       lock_dir	= file

	      The directory where masqmail stores its  lock  files.   Masqmail
	      needs  read  and	write permissions for this directory.  The de-
	      fault is /var/lock/masqmail for normal operation.	 file must  be
	      an  absolute  path.   The	directory is created on	startup	if yet

	      If run_as_user then lock files are stored	in the	spool_dir  di-
	      rectly and the lock_dir setting is ignored.

       host_name = string

	      This  is used in different places: Masqmail identifies itself in
	      the greeting banner on incoming connections and in the HELO/EHLO
	      command  for  outgoing connections with this name, it is used in
	      the Received: header and to qualify  the	sender	of  a  locally
	      originating message.

	      If  the string begins with a slash `/', it it assumed that it is
	      a	filename, and the first	line of	this file will be used.	  Usu-
	      ally  this  will	be `/etc/mailname' to make masqmail conform to
	      Debian policies.

	      It is not	used to	find whether an	address	 is  local.   Use  lo-
	      cal_hosts	for that.

	      Default: none; host_name MUST be set in the config file

       local_hosts = list

	      A	semicolon `;' separated	list of	hostnames which	are considered
	      local.   Can  contain  glob  patterns,  like  `*'  or
	      `mail?.*'.   Normally	 you  should set it to "local-
	      host;foo;" if your host has the fully	qualified  do-
	      main name	`'.

	      Default: localhost ; <value of host_name cut at the first	dot> ;
	      <value of	host_name>

	      Example:	localhost;foo;	(if   you   have   set
	      host_name	to

       local_addresses = list

	      A	 semicolon  `;'	 separated  list  of fully qualified email-ad-
	      dresses which are	considered local although  their  domain  name
	      part  is	not in the list	of local_hosts.	 This list can be seen
	      as an addition to	local_hosts.

	      Further more only	the local part of the addresses	 will  be  re-
	      garded, seeing it	as a local user.


	       local_hosts = "localhost;myhost"
	       local_addresses = "bob@somewhere;alice@foo"

	      This  means  mail	 to  person1@yourdomain	will effectively go to
	      person1@localhost, if not	redirected by an alias.

       not_local_addresses = list

	      A	semicolon `;' separated	 list  of  fully  qualified  email-ad-
	      dresses  which  are  considered  not local although their	domain
	      name part	is in the list of local_hosts.	This list can be  seen
	      as a substraction	to local_hosts.

	      This  is the opposite of the previous case.  The majority	of ad-
	      dresses of a specific domain are local.  But some	users are not.
	      With this	option you can easily exclude these users.


	       local_hosts = "localhost;myhost;"
	       not_local_addresses = ""

       listen_addresses	= list

	      A	 semicolon  `;'	 separated list	of interfaces on which connec-
	      tions will be accepted.  An interface ist	defined	by a hostname,
	      optionally  followed  by	a colon	`:' and	a number for the port.
	      If this is left out, port	25 will	be used.

	      You can set this to "localhost:25;foo:25"	if  your  hostname  is

	      Note  that the names are resolved	to IP addresses.  If your host
	      has different names which	resolve	to the same IP,	use  only  one
	      of them, otherwise you will get an error message.

	      Default: localhost:25 (i.e. only local processes can connect)

       do_save_envelope_to = boolean

	      If  this is set to true, a possibly existing Envelope-to:	header
	      in an incoming mail which	is received via	either	pop3  or  smtp
	      will be saved as an X-Orig-Envelope-to: header.

	      This  is	useful	if  you	 retrieve mail from a pop3 server with
	      fetchmail, and the server	supports Envelope-to: headers, and you
	      want to make use of those	with a mail filtering tool, e.g. proc-
	      mail.  It	cannot be  preserved  because  masqmail	 sets  such  a
	      header by	itself.

	      Default is false.

       do_relay	= boolean

	      If this is set to	false, mail with a return path that is not lo-
	      cal and a	destination that is also not local  will  not  be  ac-
	      cepted via smtp and a 550	reply will be given.  Default is true.

	      Note that	this will not protect you from spammers	using open re-
	      lays, but	from users unable to set their address in  their  mail

       do_queue	= boolean

	      If  this	is  set, masqmail will not try to deliver mail immedi-
	      ately when accepted.  Instead it will always queue  it.	(Note:
	      Masqmail will always automatically queue mail if necessary, i.e.
	      if it cannot deliver because no suitable route was available for

	      Same  as	calling	 masqmail  with	 the -odq option.  Usually you
	      should leave this	option unset.

	      Default: false

       permanent_routes	= list

	      Set this to the filename (or a semicolon-separated list of file-
	      names)  of  the route configuration for always available connec-
	      tions.  Main purpose is to define	a mail server  with  mail_host
	      in  your local network, or if masqmail should send mail directly
	      to the target host.  If you have only a  single  host,  you  can
	      leave it unset.

	      A	 setting `local_nets = "*"' in versions	<= 0.3.3 is in
	      newer versions configured	as:  `permanent_routes	=  "/etc/masq-
	      mail/homenet.route"' and the route file `homenet.route' contain-

	       allowed_recipients = "*@*"
	       connect_error_fail = true
	       resolve_list = byname

	      This is just as it had been with local_net_route,	with  the  ex-
	      ception  that the	filtering for appropriate addresses is only in
	      the route	file and not with local_nets. = list

	      Replace name with	a name to identify the connection.   Set  this
	      to  a  filename (or a semicolon-separated	list of	filenames) for
	      the route	configuration for that connection.

	      Routes of	this kind cannot be  expected  to  be  online  always.
	      Masqmail will query which	of the routes are online.

	      You  can use the name to call masqmail with the -qo option every
	      time a connection	to your	ISP is set up, in order	to send	queued
	      mail through this	route.

	      Example: Your ISP	has the	name FastNet.  Then you	write the fol-
	      lowing line in the main configuration:

	       query_routes.FastNet = "/etc/masqmail/fastnet.route"

	      /etc/masqmail/fastnet.route is the route configuration file, see
	      masqmail.route(5).   As  soon  as	a link to FastNet has been set
	      up, you call `masqmail -qo FastNet'.  Masqmail  will  then  read
	      the specified file and send the mails.

	      See online_query.

       alias_file = file

	      Set  this	 to  the  location of your alias file.	If not set, no
	      aliasing will be done.

	      Default: <not set> (i.e. no aliasing is done)

       globalias_file =	file

	      Set this to the location of a  glob-pattern  alias  file.	  This
	      kind  of	aliasing  matches glob patterns	against	full email ad-
	      dresses, not strings against local parts like in	normal	alias-
	      ing.   You can use this to handle	catch-all maildrops (``*@exam-'') and to	split between virtual hosts on	a  single  ma-
	      chine (e.g. ``'' and ``'').

	      Glob  aliasing is	done before normal aliasing.  If you have both
	      kinds, glob and normal aliasing, then the	results	 of  the  glob
	      aliasing	may  be	expanded further by the	normal aliasing	mecha-

	      Default: <not set> (i.e. no glob aliasing	is done)

       caseless_matching = boolean

	      If this is set, aliasing and the	matching  for  local_addresses
	      and not_local_addresses will be done caseless.

	      Note:  Be	 sure to change	this option only if the	queue is empty
	      as correct processing of queued messages is not guaranteed  oth-

	      Default: false

       pipe_fromline = boolean

	      If  this	is  set,  a  from line will be prepended to the	output
	      stream whenever a	pipe command is	called after an	 alias	expan-
	      sion.  Default is	false.

       pipe_fromhack = boolean

	      If  this	is  set,  each line beginning with `From ' is replaced
	      with `>From ' whenever a pipe command is called after  an	 alias
	      expansion.  You probably want this if you	have set pipe_fromline
	      above.  Default is false.

       mbox_default = string

	      The default local	delivery method.  Can be mbox or mda.  You can
	      override this for	each user by using the mbox_users or mda_users
	      (see below).

	      Default: mbox.

       mbox_users = list

	      A	list of	users which  wish  delivery  to	 an  mbox  style  mail

       mda_users = list

	      A	 list  of users	which wish local delivery to an	mda.  You have
	      to set mda (see below) as	well.

       mda = expand string

	      If you want local	delivery to be transferred to an mda (Mail De-
	      livery  Agent), set this to a command.  The argument will	be ex-
	      panded on	delivery time, you can use variables beginning with  a
	      dolloar  sign  `$',  optionally enclosed in curly	braces.	 Vari-
	      ables you	can use	are:

	       uid    the unique message id.  (This is not necessarily identi-
		      cal  with	 the  Message  ID  as given in the Message ID:

		      the host the mail	was received from

	       ident  the user id of the sender	if the	message	 was  received

		      the local	part of	the return path	(sender).

		      the domain part of the return path (sender).

		      the complete return path (sender).

		      the local	part of	the recipient.

		      the domain part of the recipient.

	       rcpt   the complete recipient address.


	       mda="/usr/bin/procmail -Y -d ${rcpt_local}"

	      For  the	mda, as	for pipe commands, a few environment variables
	      will be set as well.  See	masqmail(8).  To use environment vari-
	      ables  for the mda, the dollar sign `$' has to be	escaped	with a
	      backslash, otherwise they	will be	tried to be expanded with  the
	      internal variables.

       mda_fromline = boolean

	      If  this	is  set,  a  from line will be prepended to the	output
	      stream whenever a	message	is delivered to	an  mda.   Default  is

       mda_fromhack = boolean

	      If  this	is  set,  each line beginning with `From ' is replaced
	      with `>From ' whenever a message is delivered to	an  mda.   You
	      probably	want this if you have set mda_fromline above.  Default
	      is false.

       online_query = command line

	      Defines the method masqmail uses to detect whether there	exists
	      an online	connection currently.

	      Masqmail	executes the command given and reads from its standard
	      output.  The command should just print a route name, as  defined
	      with,	to  standard  output and return	a zero
	      status code.  Masqmail assumes it	is offline if the  script  re-
	      turns  with  a non-zero status.  Leading and trailing whitespace
	      is removed from the output.

	      Simple example:

	       test -e /var/tmp/masqmail-route || exit 1
	       cat /var/tmp/masqmail-route
	       exit 0

	      No matter	how masqmail detects the online	status,	only  messages
	      that  are	 accepted  at  online time will	be delivered using the
	      connection.  The mail spool still	needs to be  emptied  manually

	      command  line  must start	with an	absolute path to an executable
	      program.	It can contain optional	arguments.

	      To simulate the old online_method=file, use:

	       /bin/cat	/path/to/file

	      To be always online with connection `foo', use:

	       /bin/echo foo

	      To query a masqdialer server (i.e. asking	it whether  a  connec-
	      tion exists and what its name is)	use:

	       /usr/bin/mservdetect localhost 224

       errmsg_file = file

	      Set  this	 to a template which will be used to generate delivery
	      failure reports.	Variable parts within the template begin  with
	      a	 dollar	 sign  and are identical to those which	can be used as
	      arguments	for the	mda command, see mda above.  Additional	infor-
	      mation  can  be  included	 with  @failed_rcpts, @msg_headers and
	      @msg_body, these must be at the beginning	of a line and will  be
	      replaced	with  the  list	 of the	failed recipients, the message
	      headers and the message body of the failed message.

	      Default is /usr/share/masqmail/tpl/failmsg.tpl.

       warnmsg_file = file

	      Set this to a template which will	be used	to  generate  delivery
	      warning  reports.	  It uses the same mechanisms for variables as
	      errmsg_file, see above.

	      Default is /usr/share/masqmail/tpl/warnmsg.tpl.

       warn_intervals =	list

	      Set this to a list of time intervals, at which delivery warnings
	      (starting	 with the receiving time of the	message) shall be gen-

	      A	warning	will only be generated just after an  attempt  to  de-
	      liver  the  mail	and  if	that attempt failed temporarily.  So a
	      warning may be generated after a longer time, if	there  was  no
	      attempt before.

	      Default is "1h;4h;8h;1d;2d;3d"

       max_defer_time =	time

	      This  is	the  maximum  time, in which a temporarily failed mail
	      will be kept in the spool.  When this time is exceeded, it  will
	      be  handled  as  a  delivery  failure,  and  the message will be

	      The excedence of this time will only be noticed if  the  message
	      was  actually  tried to be delivered.  If, for example, the mes-
	      sage can only be delivered when online, but you  have  not  been
	      online for that time, no bounce will be generated.

	      Default is 4d (4 days)

       log_user	= name

	      Replace name with	a valid	local or remote	mail address.

	      If  this	option	is set,	then a copy of every mail, that	passes
	      through the masqmail system will also be sent to the given  mail

	      For  example  you	can feed your mails into a program like	hyper-
	      mail for archiving purpose by placing an appropriate  pipe  com-
	      mand in masqmail.alias.

       max_msg_size = bytes

	      This  option sets	the maximum size in bytes masqmail will	accept
	      for delivery.  This value	is advertised to the  SMTP  client  by
	      the  `SIZE' message during SMTP session setup.  Clients pretend-
	      ing to send, or actually send, more than bytes will  get	a  552
	      error message.

	      A	zero value disables the	maximum	size limit.

	      Default is 0 (= unlimited).

       defer_all = boolean

	      If  set to true, masqmail	replies	with ``421 service temporarily
	      unavailable'' to any SMTP	request	and shuts the connection down.
	      Note: This option	is for debugging purposes only.

	      Default: false

       Masqmail	 was  written by Oliver	Kurth.	It is now maintained by	Markus
       Schnalke	<>.

       You  will  find	the  newest  version  of   masqmail   at   http://mar-	 There	is  also a mailing list, you will find
       information about it at masqmail's main site.

       Please report bugs to the mailing list.

       masqmail(8), masqmail.route(5)

masqmail-0.3.5			  2015-02-07		      masqmail.conf(5)


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

home | help