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

FreeBSD Manual Pages


home | help
SLOCAL(1)		    General Commands Manual		     SLOCAL(1)

       slocal -	asynchronously filter and deliver new mail to nmh

       /usr/local/libexec/nmh/slocal [-help] [-version]	[-addr address]	[-info
	    data] [-sender sender] [-user username] [-mailbox mbox] [-file
	    file] [-maildelivery deliveryfile] [-verbose | -noverbose] [-sup-
	    pressdup | -nosuppressdup] [-debug]

       slocal is a program designed to allow you to  have  your	 inbound  mail
       processed according to a	complex	set of selection criteria.  You	do not
       normally	invoke slocal yourself,	rather slocal is invoked on  your  be-
       half  by	 your  system's	Message	Transfer Agent (such as	sendmail) when
       the message arrives.

       The message selection criteria used by slocal is	specified in the  file
       ".maildelivery"	in  the	user's home directory.	You can	specify	an al-
       ternate file with the -maildelivery file	option.	 The  syntax  of  this
       file is specified below.

       The message delivery address and	message	sender are determined from the
       Message Transfer	Agent envelope information, if possible.  Under	 send-
       mail,  the sender will obtained from the	UUCP "From:" line, if present.
       The user	may override these values with the -addr and -sender switches.

       The message is normally read from the standard input.  The -file	switch
       sets  the  name	of the file from which the message should be read, in-
       stead of	reading	stdin.	This is	useful when debugging  a  ".maildeliv-
       ery" file.

       The  -user  switch tells	slocal the name	of the user for	whom it	is de-
       livering	mail.  It must exist on	the local system.  The -mailbox	switch
       tells slocal the	name of	the user's mail	drop file.

       slocal  is  able	 to detect and suppress	duplicate messages.  To	enable
       this, use the option -suppressdup.  slocal will keep  a	database  con-
       taining	the  Message-ID's of incoming messages,	in order to detect du-
       plicates.  Depending on your configuration, this	database  will	be  in
       either ndbm or Berkeley db format.

       The  -info switch may be	used to	pass an	arbitrary argument to sub-pro-
       cesses which slocal may invoke on your behalf.

       The -verbose switch causes slocal to give information on	 stdout	 about
       its progress.  The -debug switch	produces more verbose debugging	output
       on stderr.  These flags are useful when	creating  and  debugging  your
       ".maildelivery"	file,  as  they	allow you to see the decisions and ac-
       tions that slocal is taking, as well as check for syntax	errors in your
       ".maildelivery" file.

   Message Transfer Agents
       Most  modern  MTAs including sendmail, postfix and exim support a .for-
       ward file for directing incoming	mail.  You should include the line

		  "| /usr/local/libexec/nmh/slocal -user username"

       in your .forward	file in	your home directory.  This will	cause your MTA
       to invoke slocal	on your	behalf when a message arrives.

   The Maildelivery File
       The  ".maildelivery"  file controls how slocal filters and delivers in-
       coming mail.  Each line of this file consists of	five fields, separated
       by whitespace or	comma.	Since double-quotes are	honored, these charac-
       ters may	be included in a single	argument by enclosing the entire argu-
       ment  in	double-quotes.	A double-quote can be included by preceding it
       with a backslash.  Lines	beginning with `#' and	blank  lines  are  ig-

       The format of each line in the ".maildelivery" file is:

	    header    pattern	action	  result    string

	    The	 name  of a header field (such as To, Cc,  or From) that is to
	    be searched	for a pattern.	This is	any field in  the  headers  of
	    the	message	that might be present.

	    The	following special fields are also defined:

	    source    the out-of-band sender information

	    addr      the  address  that was used to cause delivery to the re-

	    default   this matches only	if the message hasn't  been  delivered

	    *	      this always matches

	    The	sequence of characters to match	in the specified header	field.
	    Matching is	case-insensitive, but does  not	 use  regular  expres-

	    The	 action	to take	to deliver the message.	 When a	message	is de-
	    livered, a "Delivery-Date: date" header is added  which  indicates
	    the	date and time that message was delivered.

		This action always succeeds.

	    file, mbox,	or _
		Append	the  message to	the file named by string.  The message
		is appended to the file	in mbox	(uucp) format.	 This  is  the
		format	used  by most other mail clients (such as mailx, elm).
		If the message can be appended to the file, then  this	action

		Identical  to  file,  but always appends the message using the
		MMDF mailbox format.

	    pipe or |
		Pipe the message as the	standard input to the command named by
		string,	 using	the  Bourne  shell sh to interpret the string.
		Prior to giving	the string to the shell, it is	expanded  with
		the following built-in variables:

		$(sender)     the out-of-band sender information

		$(address)    the  address  that was used to cause delivery to
			      the recipient

		$(size)	      the size of the message in bytes

		$(reply-to)   either the "Reply-To:" or	"From:"	field  of  the

		$(info)	      the out-of-band information specified

	    qpipe or ^
		Similar	 to  pipe,  but	 executes  the command directly, after
		built-in  variable  expansion,	without	 assistance  from  the
		shell.	This action can	be used	to avoid quoting special char-
		acters which your shell	might interpret.

	    folder or +
		Store the message in the nmh folder  named  by	string.	  Cur-
		rently	this  is handled by piping the message to the nmh pro-
		gram rcvstore, although	this may change	in the future.

	    Indicates how the action should be performed:

	    A	Perform	the action.  If	the action succeeds, then the  message
		is considered delivered.

	    R	Perform	 the action.  Regardless of the	outcome	of the action,
		the message is not considered delivered.

	    ?	Perform	the action only	if the message has not been delivered.
		If  the	action succeeds, then the message is considered	deliv-

	    N	Perform	the action only	if the message has not been  delivered
		and  the  previous action succeeded.  If this action succeeds,
		then the message is considered delivered.

	    The	delivery file is  always  read	completely,  so	 that  several
	    matches can	be made	and several actions can	be taken.

   Security of Delivery	Files
       In order	to prevent security problems, the ".maildelivery" file must be
       owned either by the user	or by root, and	must be	writable only  by  the
       owner.  If this is not the case,	the file is not	read.

       If the ".maildelivery" file cannot be found, or does not	perform	an ac-
       tion which delivers the message,	then slocal will check	for  a	global
       delivery	 file  at  /usr/local/etc/nmh/maildelivery.  This file is read
       according to the	same rules.  This file must be owned by	root and  must
       be writable only	by root.

       If a global delivery file cannot	be found or does not perform an	action
       which delivers the message, then	standard delivery to the  user's  mail
       drop is performed.

   Example Delivery File
       To summarize, here's an example delivery	file:

       # .maildelivery file for	nmh's slocal
       # Blank lines and lines beginning with a	'#' are	ignored

       # File mail with	foobar in the "To:" line into file foobar.log
       To	 foobar	   file	   A	   foobar.log

       # Pipe messages from coleman to the program message-archive
       From	 coleman   pipe	   A	   /bin/message-archive

       # Anything to the "nmh-workers" mailing list is put in
       # its own folder, if not	filed already
       To	 nmh-workers  folder ?	   nmh-workers

       # Anything with Unix in the subject is put into
       # the file unix-mail
       Subject	 unix	   file	   A	   unix-mail

       # I don't want to read mail from	Steve, so destroy it
       From	 steve	   destroy A	   -

       # Put anything not matched yet into mailbox
       default	 -	  file	  ?	  mailbox

       # always	run rcvtty
       *	 -	  pipe	  R	  /usr/local/libexec/nmh/rcvtty

   Sub-process environment
       When  a	process	is invoked, its	environment is:	the user/group-ids are
       set to recipient's ids; the working directory is	the  recipient's  home
       directory; the umask is 0077; the process has no	/dev/tty; the standard
       input is	set to the message; the	standard output	and diagnostic	output
       are  set	to /dev/null; all other	file-descriptors are closed; the envi-
       ronment variables $USER,	$HOME, $SHELL are set  appropriately,  and  no
       other environment variables exist.

       The  process  is	 given	a  certain  amount of time to execute.	If the
       process does not	exit within this limit,	the process will be terminated
       with  extreme  prejudice.  The amount of	time is	calculated as ((size /
       60) + 300) seconds, where size is the number of bytes  in  the  message
       (with 30	minutes	the maximum time allowed).

       The  exit status	of the process is consulted in determining the success
       of the action.  An exit status of zero means that the action succeeded.
       Any  other  exit	status (or abnormal termination) means that the	action

       In order	to avoid any time limitations, you might implement  a  process
       that  began  by	fork()-ing.   The  parent would	return the appropriate
       value immediately, and the child	could continue on, doing  whatever  it
       wanted  for  as	long as	it wanted.  This approach is somewhat risky if
       the parent is going to return an	exit status of zero.  If the parent is
       going  to return	a non-zero exit	status,	then this approach can lead to
       quicker delivery	into your mail drop.

       /usr/local/etc/nmh/mts.conf	    nmh	mts configuration file
       $HOME/.maildelivery		    The	file controlling local delivery
       /usr/local/etc/nmh/maildelivery	    Rather than	the standard file
       /var/mail/$USER			    The	default	mail drop

       rcvdist(1), rcvpack(1), rcvstore(1), rcvtty(1), mh-format(5)

       `-maildelivery' defaults	to $HOME/.maildelivery
       `-mailbox' defaults to /var/mail/$USER
       `-file' defaults	to stdin
       `-addr' defaults	to the current user
       `-user' defaults	to the current user

       -addr and -user will be set the the user	part of	the Local-Mailbox pro-
       file entry, if set.


       slocal  was  originally	designed  to  be  backward-compatible with the
       maildelivery facility provided by MMDF-II.  Thus,  the  ".maildelivery"
       file  syntax is somewhat	limited.  But slocal has been modified and ex-
       tended, so that is it no	longer compatible with MMDF-II.

       In addition to an exit status of	zero, the MMDF values RP_MOK (32)  and
       RP_OK  (9)  mean	 that the message has been fully delivered.  Any other
       non-zero	exit status, including abnormal	termination, is	interpreted as
       the MMDF	value RP_MECH (200), which means "use an alternate route" (de-
       liver the message to the	mail drop).

       Only two	return codes are meaningful, others should be.

       slocal was originally designed  to  be  backwards-compatible  with  the
       maildelivery functionality provided by MMDF-II.

nmh-1.7.1			  2016-05-02			     SLOCAL(1)


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

home | help