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

FreeBSD Manual Pages

  
 
  

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

NAME
       slocal -	asynchronously filter and deliver new mail to nmh

SYNOPSIS

       /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]

DESCRIPTION
       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-
       processes 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-
       nored.

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

	    header    pattern	action	  result    string

       header:
	    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-
		      cipient

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

	    *	      this always matches

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

       action:
	    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.

	    destroy
		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
		succeeds.

	    mmdf
		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
			      message

		$(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 by	piping
		the message to the nmh program rcvstore.

       result:
	    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-
		ered.

	    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
       #
       # FIELD	 PATTERN   ACTION  RESULT  STRING
       #

       # 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
       failed.

       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.

FILES
       /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

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

DEFAULTS
       `-noverbose'
       `-nosuppressdup'
       `-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.

CONTEXT
       None

HISTORY
       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).

BUGS
       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.8+dev			  2022-03-13			     SLOCAL(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=slocal&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help