⟦426abde7b⟧

TextFile

Part 5:  Configuration files.

	In previous parts of this document, a number of configuration
	files were discussed: the config file, director, router and
	transport files, and method files.  In this part we go into
	more detail on how these files can be setup.


Section 5.1:  Conventions.

	There are a number of conventions that are followed in all or
	several of the 5 types of configuration files.  In particular
	the director, router and transport files are identical in
	form, varying only in the names of attributes which apply to
	file entries.


Section 5.1.1:  Delimiting file entries.

	A common routine is used to read in single entries from all of
	these files.  In addition to delimiting entries in a common
	fashion, this routine also folds continuation lines.

	Delimiting of file entries is quite simple: an entry ends at
	the end of file, or before a line that contains a character
	other than whitespace or a sharp (`#') in the first column.
	In addition, the first entry in a file begins on the first
	line which does not have a sharp as its first non-whitespace
	character.

	Lines which end in `\' will cause line continuation.  As well,
	any whitespace at the beginning of the continuation line will
	be ignored.  Thus, if you need whitespace at the place where
	you wish to break a line, the whitespace will need to precede
	the `\' character.

	As an example, consider the following simple config file:

	    # a configuration file for smail

	    # this file was brought to you by the makers of smail
	    # the mailer that makes you feel good about sending
	    # mail.
	    smail = /usr/lib/smail/smail

	    # we have several hostnames:
	    hostnames = kremvax.uucp:\
	    		kremvax.kgb.comm:\
			kremvax.ussr.comm

	This file contains two entries:

	    smail = /usr/lib/smail/smail

	    # we have several hostnames:

	and

	    hostnames = kremvax.uucp:kremvax.kgb.comm:kremvax.ussr.comm

	NOTE:  since comments are not stripped when reading the file,
	       except when they are at the beginning of a file, a `\'
	       character at the end of a comment will also be
	       continued on the next line, except at the beginning of
	       a file.


Section 5.1.2:  Comments within entries.

	Comments are supported within all configuration files as the
	sharp character (`#') up to the end of a line.  `#' does not
	begin a comment within a string value (defined below) or when
	preceded by a backslash in a regular attribute value.

Section 5.1.2:  Names, values and strings.

	In the config file, plus the director router and transport
	files, there are three common types of tokens: attribute and
	entry names, regular attribute values and string attribute
	values.  In addition to these there are also operators, such
	as `,' and `=', but we are not concerned about those in this
	section.

	An attribute or entry name is limited to characters from the
	set of letters, numbers and underscore (`_').  Names can begin
	or end or contain any character from this set.

	A regular attribute value can contain characters from the set
	of letters, numbers and one of the characters below:

		! @ $ % ^ & * - _ + ~ / ? | < > : [ ] { } . ' `

	In addition, any other character can be included by preceding
	it with a \ character (except newline).  Note that above set
	does not contain any of:

		# , " ( ) ;

	or ASCII control characters.

	Any collection of characters can be used for a value by using
	a C-style string constant in double quotes (`"').  The
	standard C \-escape sequences are handled appropriately, and
	as well \e is ASCII ESC, \g is ASCII BEL and \x or \X followed
	by up to three hexadecimal digits form a hexadecimal character
	literal.

	Often numeric values will be required.  These can be specified
	as C-style integer constants, such as 0777, 0xffe or 1234 and
	can optionally be followed by `k' or `K' to multiply the
	number by a factor of 1024 (2^10), or by `m' or `M' to
	multiply the number by a factor of 1048576 (2^20).  Numbers
	such as 12M3K are NOT valid.  Decimal points are not valid.
	It IS okay to put a number in double quotes, such as "100K".

	When a list is required, each element of the list is separated
	by a single colon (`:').  Colons cannot be included in the value
	of a list element (at the present time).


Section 5.2:  Expanded values.

	Many attribute values will be expanded before being used.
	When this is done, certain substrings, beginning with $, will
	be replaced by the value of a smail variable.  The names of
	expansion variables are either a single character, or are
	multiple characters from the set of letters, digits and
	underscore (`_').  A variable name can also be enclosed
	between { and }, to isolate the variable name from the
	surrounding text.

	In addition to variables, a number of meta-expansions can be
	used.  These expansions are always of the form:

		${meta_name:name}

	where `meta_name' defines some operation to perform on the
	value of the variable `name'.  Multiple meta-expansions can be
	specified, such as in:

		${lc:strip:user}

	This strips quotes from the value of the variable `user' and
	then converts characters to lower case.

	When a string to be expanded begins with the character `~', a
	home directory is substituted.  If only `~' is given, or `~/'
	is given, then the home directory associated with an address
	is substituted.  If the form `~username' is given, where
	`username' is the name of a user on the local host, that
	user's home directory is substituted.

	The complete set of variable names depends upon context, but
	the following are always available:

		bat     a string defining a bat which identifies where  your
		        smail sources originated.
	
		compile_date or ld_date
		        the date when the current smail binary was compiled.
	
		compile_num or ld_num
		        a decimal number giving the number  of  times  smail
		        has  been  compiled since the creation of the source
		        file ldinfo.c.
	
		ctime   the date and time,  in  the  form  returned  by  the
		        ctime(3) function.
	
		date    The date and time in ARPAnet format.
	
		grade   The priority  character  for  the  current  message.
		        See the grades attribute in the config file for more
		        information on this value.
	
		message_id or id
		        the message ID for the current message.
	
		patch_number or patch
		        the patch number for the  smail  sources,  from  the
		        source file patchnumber.

		patch_date
			the date that the  most recently  applied patch  was
			created.

		pid or $
		        the current process ID.
	
		primary_name or primary
		        the canonical name for the local host.
	
		release_date or release
		        the release date of the smail sources.
	
		sender  sender or from the address of the sender of  a  mes-
		        sage.
	
		uucp_name
		        the UUCP-network name for the local host.
	
		version a short version string for smail.
	
		version_string
		        a verbose version string for
	
		visible_name or name
		        the local host  name  used  in  outgoing  addresses.
		        smail.
	
	In addition, the following variables are defined if they are
	available in the current context:
	
		HOME or home
		        the home directory of  a  user  associated  with  an
		        address.
	
		host    the remote host  string  associated  with  a  remote
		        address.
	
		user or addr
		        a user name or remaining address  string  associated
		        with an address.
	
	These variables may exist if such data is available:
	
		inet_name
		        the internet address for the local host, in  decimal
		        bytes   separated   by   a   dots.    For   example:
		        ``192.2.12.3.''
	
		hex_inet_name
		        the internet address in hexadecimal.   For  example:
		        ``c0020c03.''
	
	The following meta-expansions also exist:
	
		lc      convert to lower case.
	
		parent  interpret the value within the context of the parent
		        local  address that produced the associated address.
		        This is useful when the local address that  produced
		        an address is desired.  Expansion fails if no parent
		        exists.
	
		quote   enclose the value in quotes, if it would not  other-
		        wise be a valid local-form address, within the rules
		        of RFC822.  Uses backslash escapes  as  appropriate.
		        (This  is  not  available  in  the  Alpha release of
		        smail).
	
		strip   Remove backslashes and double quotes from  a  value.
		        If  a  double-quote  is preceded by a backslash, the
		        backslash is removed, but the double quote  is  not.
		        Sequences of whitespace characters and dots are con-
		        verted to exactly one dot character.
	
		top     interpret the value within the context of the origi-
		        nal  address,  supplied to the mailer, that produced
		        the associated address.
	
		uc      convert to upper case.
	
	The following are sample expansions:

		/usr/spool/mail/${lc:user}

	    will become (assuming a next_addr of `Tron):

		/usr/spool/mail/tron

	    whereas:

	    	"Received: by $primary_name ($version_string)
			id <$message_id@primary_name>;
			$date"

	    will become something such as:

	    	Received: by name.uucp (smail /\--/\ 3.0.2 03-dec-87)
			id <m0c87zK-007zXpC@namei.uucp>;
			Tue,  8 Dec 87 19:45 PST

	    and:

	    	$host!rmail (${strip:addr})

	    with an $addr value of `Ronald S. Karr' and a $host of `amdahl'
	    will become:

	    	amdahl!rmail (Ronald.S.Karr)

	If a value does not exist, such as $HOME being used when no
	associated home directory is known, or when a string begins
	with "~username" and the username is not known, or when
	$host is used for a local address, the expansion fails.


Section 5.3:  Attributes.

	The config, director, router and transport files define the
	values for attributes.  These values are defined using one of
	the forms:

		variable_name = string or number

		variable_name	or   +variable_name

		-variable_name

	where the first form gives a value to an attribute that takes
	a non-boolean value, the second form gives a positive value to
	a boolean attribute, and the last form gives a negative value
	to a boolean attribute.  Additionally, the last form can
	assign a NULL value to a string variable.  This is useful, for
	example, to stop the use of a transport file by assigning a
	NULL value to the `transport_file' attribute.

	It is an error to use a form that does not match the type of
	value expected for an attribute.


Section 5.4:  The config file.

	Each entry in the config file specifies a value for a global
	attribute in smail.  The complete set of setable global
	attributes is given in Section 9.3.

	The config file overrides compiled in options.  See
	Section 10.1 for info on compiled in flags.


Section 5.5:  The director, router and transport files.

	Each entry in one of these files defines a specific director,
	router or transport.  The format of each entry is:

		name:  generic_attribute, generic_attribute ... ;
		       driver_attribute, driver_attribute ...

	The `name' above defines a name by which the the entry can be
	identified.  For director and router file entries, these names
	are only used in debugging output or in locating configuration
	file errors.  For the transport file entries, these names may
	be referred to by method files, router entries or from some
	directors.

	The list of possible `generic_attribute' names is a function
	of the configuration file it is in.  The possible generic
	attribute names are defined in Sections 6.1, 7.2 and 8.1.
	The list of possible `driver_attribute' names is a function of
	the specific driver associated with the entry, as specified by
	the generic `driver' attribute.  The possible driver attribute
	names are defined in parts 6, 7 and 8, in the sections that
	discuss each individual driver.

	Attribute value assignments are separated by commas, with the
	generic attributes being separated from the driver-specific
	attributes by a semicolon.  The generic attributes always come
	first.  An entry IS allowed to end in a comma or semicolon.


Section 5.6:  Method files.

	Method files have a very simple structure.  Each entry
	contains a host name and the name of a transport.  The two are
	separated by whitespace.  At the present time, double quotes
	cannot be used, as there are no possible conflicts between
	delimiters, comments and legal host names or transport names.
\f
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦426abde7b⟧ TextFile

Derivation

TextFile
