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

FreeBSD Manual Pages

  
 
  

home | help
DIREVENT.CONF(5)	    Direvent User Reference	      DIREVENT.CONF(5)

NAME
       direvent.conf - configuration file for direvent(8).

DESCRIPTION
       The configuration file consists of statements and comments.

       There  are three	classes	of lexical tokens: keywords, values, and sepa-
       rators. Blanks, tabs, newlines and comments, collectively called	 white
       space  are  ignored except as they serve	to separate tokens. Some white
       space is	required to separate otherwise adjacent	keywords and values.

COMMENTS
       Comments	may appear anywhere where white	space may appear in  the  con-
       figuration  file.   There  are  two  kinds of comments: single-line and
       multi-line comments.  Single-line comments start	with # or // and  con-
       tinue to	the end	of the line:

	   # This is a comment
	   // This too is a comment

       Multi-line or C-style comments start with the two characters /* (slash,
       star) and continue until	the first occurrence of	*/ (star, slash).

       Multi-line comments cannot be nested.   However,	 single-line  comments
       may well	appear within multi-line ones.

   Pragmatic Comments
       Pragmatic  comments  are	similar	to the usual single-line comments, ex-
       cept that they cause some changes  in  the  way	the  configuration  is
       parsed.	 Pragmatic  comments begin with	a # sign and end with the next
       physical	newline	character.

       #include	<FILE>
       #include	FILE
	      Include the contents of the file FILE.  If FILE is  an  absolute
	      file name, the named file	is included.  An error message will be
	      issued if	it does	not exist.

	      If FILE contains wildcard	characters (*, [, ], or	?), it is  in-
	      terpreted	 as  a	shell  globbing	pattern	and all	files matching
	      that pattern are included,  in  lexicographical  order.	If  no
	      matching	files  are  found,  the	 directive is replaced with an
	      empty line.

	      Otherwise, the form with angle brackets searches for file	in the
	      include  search  path,  while the	second one looks for it	in the
	      current working directory	first, and, if not found there,	in the
	      include search path.  If the file	is not found, an error message
	      will be issued.

	      The order	of directories is as follows.  First,  direvent	 scans
	      any  directories	given  with  -I	 options, in the same order as
	      given on the command line, and then the directories in the stan-
	      dard include search path.	 The latter is defined at compile time
	      and can be inspected in the output of the	--help option.

       #include_once <FILE>
       #include_once FILE
	      Same as #include,	except that, if	the FILE (or any of the	 files
	      it  expands  to)	has  already been included, it will not	be in-
	      cluded again.

       #line num
       #line num "FILE"
	      This line	causes the parser to believe, for  purposes  of	 error
	      diagnostics,  that  the  line  number of the next	source line is
	      given by num and the current input file is named by FILE.	If the
	      latter is	absent,	the remembered file name does not change.

       # num "FILE"
	      This  is	a  special form	of the #line statement,	understood for
	      compatibility with the C preprocessor.

STATEMENTS
   Simple statement
       A simple	statement consists of a	keyword	and  value  separated  by  any
       amount  of whitespace.  Simple statement	is terminated with a semicolon
       (;).

       The following is	a simple statement:

	   pidfile /var/run/direvent.pid;

       See below for a list of valid simple statements.

       A value can be one of the following:

       number A	number is a sequence of	decimal	digits.

       boolean
	      A	boolean	value is one of	the following:	yes,  true,  t	or  1,
	      meaning true, and	no, false, nil,	0 meaning false.

       unquoted	string
	      An  unquoted  string may contain letters,	digits,	and any	of the
	      following	characters: _, -, ., /,	@, *, :.

       quoted string
	      A	quoted string is any sequence of characters enclosed  in  dou-
	      ble-quotes  (").	 A  backslash appearing	within a quoted	string
	      introduces an escape sequence, which is replaced with  a	single
	      character	according to the following rules:

		      Sequence	Expansion		ASCII
		      \\	\			134
		      \"	"			042
		      \a	audible	bell		007
		      \b	backspace		010
		      \f	form-feed		014
		      \n	new line		012
		      \r	charriage return	015
		      \t	horizontal tabulation	011
		      \v	vertical tabulation	013

	      In  addition,  the sequence \newline is removed from the string.
	      This allows to split long	strings	over several  physical	lines,
	      e.g.:

		  "a long string may be\
		   split over several lines"

	      If the character following a backslash is	not one	of those spec-
	      ified above, the backslash is ignored and	a warning is issued.

	      Two or more adjacent  quoted  strings  are  concatenated,	 which
	      gives  another  way  to split long strings over several lines to
	      improve readability.  The	following fragment produces  the  same
	      result as	the example above:

		  "a long string may be"
		  " split over several lines"

       Here-document
	      A	 here-document is a special construct that allows to introduce
	      strings of text containing embedded newlines.

	      The <<word construct instructs the parser	to read	all  the  fol-
	      lowing  lines up to the line containing only word, with possible
	      trailing blanks.	Any lines thus read are	concatenated  together
	      into a single string.  For example:

		  <<EOT
		  A multiline
		  string
		  EOT

	      The  body	 of  a	here-document is interpreted the same way as a
	      double-quoted string, unless word	is  preceded  by  a  backslash
	      (e.g.   <<\EOT)  or enclosed in double-quotes, in	which case the
	      text is read as is, without interpretation of escape sequences.

	      If word is prefixed with - (a dash), then	all leading tab	 char-
	      acters  are  stripped  from  input lines and the line containing
	      word.  Furthermore, - is followed	by a single space, all leading
	      whitespace  is  stripped from them.  This	allows to indent here-
	      documents	in a natural fashion.  For example:

		  <<- TEXT
		      The leading whitespace will be
		      ignored when reading these lines.
		  TEXT

	      It is important that the terminating delimiter be	the only token
	      on  its  line.   The only	exception to this rule is allowed if a
	      here-document appears as the last	element	of  a  statement.   In
	      this  case  a  semicolon can be placed on	the same line with its
	      terminating delimiter, as	in:

		   help-text <<-EOT
		       A sample	help text.
		   EOT;

       list   A	comma-separated	list of	values,	enclosed in parentheses.   The
	      following	 example  shows	 a  statement whose value is a list of
	      strings:

		  option (wait,	stderr);

	      In any context where a list is appropriate, a  single  value  is
	      allowed  without being a member of a list: it is equivalent to a
	      list with	a single member.  This means that, e.g.

		  option wait;

	      is equivalent to

		  option (wait);

   Block Statement
       A block statement introduces a logical group of	statements.   It  con-
       sists  of a keyword, followed by	an optional value, called a tag, and a
       sequence	of statements enclosed in curly	braces,	as shown in the	 exam-
       ple below:

	   watcher {
	       path /etc;
	       event create;
	   }

       The  closing  curly brace may be	followed by a semicolon, although this
       is not required.

MACRO EXPANSION
       Arguments of some statements undergo macro expansion before use.	  Dur-
       ing  the	 macro	expansion any occurrence of ${NAME} is replaced	by the
       value of	macro NAME.  Macro names follow	the usual convention: they be-
       gin  with  a  letter  and  contain letters digits and underscores.  The
       curly braces around the NAME are	optional.  They	are required  only  if
       the macro reference is followed by a character that is not to be	inter-
       preted as part of its name, as in ${command}string.

       The following macros are	defined:

       file   Name of the file covered by the event.

       genev_code
	      Generic (system-independent) event code.	It is a	bitwise	OR  of
	      the event	codes represented as a decimal number.

       genev_name
	      Generic  event name.  If several generic events are reported si-
	      multaneously, the	value of this variable	is  a  list  of	 event
	      names separated by space characters.  Each name corresponds to a
	      bit in genev_code.

       self_test_pid
	      The PID of the external command  started	with  the  --self-test
	      (-T)  option.   If direvent is started without this option, this
	      variable is not defined.

       sysev_code
	      System-dependent event code.  It is a bitwise OR	of  the	 event
	      codes represented	as a decimal number.

       sysev_name
	      System-dependent	event  name.   If several events are reported,
	      the value	of this	variable is a list of event names separated by
	      space characters.	 Each name corresponds to a bit	in sysev_code.
	      See the section SYSTEM DEPENDENCIES in direvent(8), for  a  list
	      of system-dependent event	names.

GENERAL	SETTINGS
       user NAME;
	      Sets  the	 user  to  run as.  NAME must be a name	of an existing
	      user.

       foreground BOOL;
	      Run in foreground.

       pidfile FILE;
	      Upon successful startup store the	PID of the daemon  process  in
	      FILE.

       debug NUMBER;
	      Set  debug  level.   Valid  NUMBER  values are 0 (no debug) to 3
	      (maximum verbosity).

LOGGING
       While connected to the terminal direvent	outputs	 its  diagnostics  and
       debugging messages to the standard error.  After	disconnecting from the
       controlling terminal it closes the first	three file descriptors and di-
       rects  all  its output to the syslog.  When running in foreground mode,
       its messages are	sent both to the standard error	and to the syslog.

       The following configuration statement controls the syslog output:

	 syslog	{
	     facility STRING;
	     tag STRING;
	     print-priority BOOL;
	 }

       The statements are:

       facility	STRING;
	      Set syslog facility.  STRING is one of the following: user, dae-
	      mon,  auth or authpriv, mail, cron, local0 through local7	(case-
	      insensitive), or a facility number.

       tag STRING;
	      Tag syslog messages with	STRING.	  Normally  the	 messages  are
	      tagged with the program name.

       print-priority BOOL;
	      Prefix each message with its priority.

       An example syslog statement:

	   syslog {
	       facility	local0;
	       print-priority yes;
	   }

WATCHER
       The watcher statement configures	a single event watcher.	 A watcher can
       control several events in multiple pathnames.  Any  number  of  watcher
       statements  is  allowed	in  the	 configuration	file, each one of them
       declaring a separate watcher.

	 watcher {
	     path PATHNAME [recursive [NUMBER]];
	     file STRING-LIST;
	     event STRING-LIST;
	     command STRING;
	     user NAME;
	     timeout NUMBER;
	     option STRING-LIST;
	     environ ENV-SPEC;
	 }

       The statements within a watcher block are:

       path PATHNAME [recursive	[NUMBER]];
	      Defines a	pathname to watch.  PATHNAME must be the  name	of  an
	      existing	directory  in the file system.	The watcher will watch
	      events occurring for all files within that  directory.   If  the
	      optional	recursive  clause is specified,	this directory will be
	      watched recursively, i.e.	 when any subdirectory is  created  in
	      it,  direvent  will set up a watcher for files in	this subdirec-
	      tory.  This new watcher will be an  exact	 copy  of  the	parent
	      watcher,	excepting  for the pathnames.  The optional NUMBER pa-
	      rameter defines a	cut-off	nesting	level for recursive  watching.
	      If  supplied, the	recursive behaviour will apply only to the di-
	      rectories	that are nested	below that level.

	      Any number of path statements can	appear in a watcher block.  At
	      least one	path must be defined.

       file STRING-LIST;
	      Selects  which  files are	eligible for monitoring.  The argument
	      is a list	of globbing patterns  (in  the	sense  of  fnmatch(3))
	      and/or extended regular expressions ( regex(7)) one of which the
	      file name	must match in order for	the  watcher  to  act  on  it.
	      Regular expressions must be surrounded by	a pair of slashes, op-
	      tionally followed	by the following flags:

	      b	     Use basic regular expressions.

	      i	     Enable case-insensitive matching.

		     A pattern or regular expression prefixed with  !  matches
		     file names	that don't match the pattern without !.

       event STRING-LIST;
	      Configures the filesystem	events to watch	for in the directories
	      declared by the path statements.	The  argument  is  a  list  of
	      event names.  Both generic and system-dependent event namess are
	      allowed.	Multiple event statements accumulate.  A missing event
	      statements means watch all events.  For example:

		  event	(open,delete);

       command STRING;
	      Defines a	command	to execute on event.  STRING is	a command line
	      just as you would	type it	in sh(1).  It may contain macro	 vari-
	      ables, which will	be expanded prior to execution.	 For example:

		  command "/bin/prog -event $genev_name	-file $file";

	      See  the	section	 HANDLER ENVIRONMENT in	direvent(8), for a de-
	      tailed discussion	of how the command is executed.

       user STRING;
	      Run command as this user.

       timeout NUMBER;
	      Terminate	the command if it runs	longer	than  NUMBER  seconds.
	      The default is 5 seconds.

       option STRING-LIST;
	      A	 list  of  additional  options.	 The following options are de-
	      fined:

		       shell  Invoke the handler command as /bin/sh  -c	 "com-
			      mand".

		       wait   Wait  for	 the  program to terminate before han-
			      dling next event from the	event queue.  Normally
			      the program runs asynchronously.

		       stdout Capture  the  standard output of the command and
			      redirect it to the syslog	with the LOG_INFO pri-
			      ority.

		       stderr Capture  the  standard  error of the command and
			      redirect it to the syslog	with the LOG_ERR  pri-
			      ority.

       environ ENV-SPEC;
	      Modify command environment.  By default the command inherits the
	      environment of direvent augmented	with the following variables:

		 DIREVENT_SYSEV_CODE
			The system-dependent event code	(see the ${sysev_code}
			variable).

		 DIREVENT_SYSEV_NAME
			The  system-dependent  event  name  or	names (see the
			${sysev_name} variable).

		 DIREVENT_GENEV_CODE
			The generic event code (see  the  ${genev_code}	 vari-
			able).

		 DIREVENT_GENEV_NAME
			The generic event name or names	(see the ${genev_name}
			variable).

		 DIREVENT_FILE
			The name of the	affected file relative to the  current
			working	directory (see the ${file} variable).

	      The  environ statement allows for	trimming the environment.  Its
	      argument is a list of one	or more	of the	folloeing  environment
	      modification directives:

		 - (a single dash)
			Clear  the inherited environment, but retain the vari-
			ables added  by	 direvent.   The  removed  environment
			variables  can	be  selectively	restored by the	direc-
			tives that follow.  This must be the  first  directive
			in the list.

		 -- (double-dash)
			Clear  the entire environment, including the variables
			added by direvent.  This must be the  first  directive
			in the list.

		 -NAME	Unset the variable NAME.

		 -NAME=VAL
			Unset  the environment variable	NAME only if its value
			is VAL.

		 NAME	Restore	the environment	variable NAME.	This directive
			is  useful after - or -- to retain some	variables from
			the environment.

		 NAME=VALUE
			Define environment variable NAME to the	VALUE.	 VALUE
			can  contain  macro  variables,	which will be expanded
			prior to the assignment.

		 NAME+=VALUE
			Retain the variable NAME and append VALUE to  its  ex-
			isting	value.	 If no such variable is	present	in the
			environment, it	 will  be  created  and	 assigned  the
			VALUE.	 If VALUE begins with a	punctuation character,
			this character is removed from it before  the  assign-
			ment.	This  is  convenient  for using	this construct
			with environment variables like	PATH, e.g.:

			    PATH+=:/sbin

			In this	example, if PATH exists, :/sbin	 will  be  ap-
			pended	to  it.	 Otherwise, it will be created and as-
			signed the value /sbin.

			The VALUE can contain macro variables, which  will  be
			expanded prior to the assignment.

		 NAME=+VALUE
			Retain	the variable NAME and prepend VALUE to its ex-
			isting value.  If no such variable is present  in  the
			environment,  it  will	be  created  and  assigned the
			VALUE.	In this	case, if VALUE ends with a punctuation
			character,  this character will	be removed from	it be-
			fore the assignment.

			The VALUE can contain macro variables, which  will  be
			expanded prior to the assignment.

SEE ALSO
       direvent(8).

COPYRIGHT
       Copyright (C) 2012, 2013	Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li-
       censes/gpl.html>
       This is free software: you are free  to	change	and  redistribute  it.
       There is	NO WARRANTY, to	the extent permitted by	law.

DIREVENT			 June 20, 2016		      DIREVENT.CONF(5)

NAME | DESCRIPTION | COMMENTS | STATEMENTS | MACRO EXPANSION | GENERAL SETTINGS | LOGGING | WATCHER | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=direvent.conf&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help