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

FreeBSD Manual Pages

  
 
  

home | help
multilog(8)		    System Manager's Manual		   multilog(8)

NAME
       multilog	 -  reads  a sequence of lines from stdin and appends selected
       lines to	any number of logs.

SYNOPSIS
       multilog	script

DESCRIPTION
       script consists of any number of	arguments. Each	argument specifies one
       action.	The  actions  are carried out in order for each	line of	input.
       Note that actions may contain shell  metacharacters  that  need	to  be
       quoted when multilog is run from	a shell.

       multilog	 exits 0 when it sees the end of stdin.	If stdin has a partial
       final line then multilog	inserts	a final	newline.

       multilog	writes a message to stderr and exits 111, without reading  any
       input, if it runs out of	memory or if another multilog process is writ-
       ing to one of the same automatically rotated logs.

       If multilog has trouble writing to disk after it	starts reading	input,
       it  writes a message to stderr, pauses, and tries again,	without	losing
       any data. Note that this	may block any program feeding input to	multi-
       log.

       If multilog receives a TERM signal, it will read	and process data until
       the next	newline, and then exit,	leaving	stdin at  the  first  byte  of
       data it has not processed.

SELECTING LINES
       Each line is initially selected.	The following actions change this:

       -pattern
	      deselects	the line if pattern matches the	line.

       +pattern
	      selects the line if pattern matches the line.

       F      changes the pattern match	mode to	use fnmatch for	all subsequent
	      patterns.

       S      changes the pattern match	mode back to use simple	patterns  (the
	      default).

   SIMPLE PATTERNS
       pattern	is  a string of	stars and non-stars. It	matches	any concatena-
       tion of strings matched by all the stars	and non-stars in the same  or-
       der.  A	non-star  matches  itself.  A  star  before the	end of pattern
       matches any string that does not	include	the next character in pattern.
       A star at the end of pattern matches any	string.

       For example, the	action

	 +hello

       selects hello. It does not select hello world.

       The action

	 -named[*]: Cleaned cache *

       deselects named[135]: Cleaned cache of 3121 RRs.	The first star matches
       any string that does not	include	a right	bracket.

       The action

	 -*

       deselects every line.

       To save memory, multilog	actually checks	pattern	against	only the first
       1000 characters of each line.

   FNMATCH PATTERNS
       When fnmatch mode is selected, multilog uses the	system's fnmatch func-
       tion to match pattern.  This mode is less  efficient  than  the	simple
       patterns, but more flexable in the types	of patterns it allows.

       In particular,

       ?      (not between brackets) matches any single	character,

       *      (not  between  brackets) matches any string, including the empty
	      string,

       [...]  matches a	single character, and

       \?, \*, and \[
	      match ?, *, [ exactly, respectively.

       The expression [...]  matches any  single  character  enclosed  by  the
       brackets.  If the first character within	the brackets is	!, the expres-
       sion matches any	character except those enclosed	by the brackets.   Two
       characters within the brackets separated	by - denote a range.  [A-F] is
       equivalent to [ABCDEF].	The characters ?, *, and [ lose	their  special
       meaning within the brackets.

       See the fnmatch(3) or glob(7) man pages for more	details.

ALERTS
       The action

       e      prints (the first	200 bytes of) each selected line to stderr.

STATUS FILES
       The action

       =file  replaces	the  contents  of  file	with (the first	1000 bytes of)
	      each selected line, padded with newlines to 1001 bytes. There is
	      no protection of file against power outages.

	      For example, the sequence	of actions

		   -*
		   +STAT*
		   =log/status

	      maintains	 log/status as a copy of the most recent line starting
	      with STAT.

TIMESTAMPING
       The action

       t      inserts an @, a precise timestamp, and a space in	front of  each
	      line, using the same format as tai64n(8).

       T      inserts  an  accustamp-style  timestamp  and a space in front of
	      each line, formatted as S.M where	S is  the  number  of  seconds
	      since  the  UNIX epoch (midnight January 1 1970-01-01 UTC) and M
	      is the number of microseconds.

       These are required to be	the first action.

       Patterns	apply to the line after	the timestamp is inserted.  For	 exam-
       ple, if

	 multilog t '-*' '+* fatal: *' ./main

       reads the line

	 fatal:	out of memory

       then it will log	a line such as

	 @400000003b4a39c23294b13c fatal: out of memory

       with the	first *	matching the timestamp.

       You  can	 use tai64nlocal(8) to convert these timestamps	to human-read-
       able form.

AUTOMATICALLY ROTATED LOGS
       If dir starts with a dot	or slash then the action

       dir    appends each selected line to a log named	dir.  If dir does  not
	      exist, multilog creates it.

       Do  not attempt to write	to one log from	two simultaneous multilog pro-
       cesses, or two actions in one process.

       The log format is as follows.  dir is a directory containing some  num-
       ber  of	old  log  files, a log file named current, and other files for
       multilog	to keep	track of its actions. Each old log file	has a name be-
       ginning	with  @,  continuing with a precise timestamp showing when the
       file was	finished, and ending with one of the following codes:

       .s     This file	is completely processed	and safely  written  to	 disk.
	      This code	may be changed as described below.

       .u     This  file  was being created at the moment of an	outage.	It may
	      have been	truncated and has not been processed.

       Beware that NFS,	async filesystems,  and	 softupdates  filesystems  may
       discard files that were not safely written to disk before an outage.

       While  multilog	is running, current has	mode 644. If multilog sees the
       end of stdin, it	writes current safely to disk, and sets	 the  mode  of
       current	to  744. When it restarts, it sets the mode of current back to
       644 and continues writing new lines.

       When multilog decides that current is big  enough,  it  writes  current
       safely to disk, sets the	mode of	current	to 744,	and renames current as
       an old log file.

       ssize  sets the maximum file size for subsequent	dir actions.  multilog
	      will  decide  that  current  is  big  enough if current has size
	      bytes.  (multilog	will also decide that current is big enough if
	      it sees a	newline	within 2000 bytes of the maximum file size; it
	      tries to finish log files	at line	boundaries.)  size must	be be-
	      tween  4096  and	2147483647.  The  default maximum file size is
	      99999.

	      In versions 0.75 and above: If multilog receives an ALRM signal,
	      it immediately decides that current is big enough, if current is
	      nonempty.

       nnum   sets the number of log files for subsequent dir  actions.	 After
	      renaming current,	if multilog sees num or	more old log files, it
	      removes the old log file with the	smallest timestamp.  num  must
	      be at least 2. The default number	of log files is	10.

       !processor
	      sets a processor for subsequent dir actions.  multilog will feed
	      current through processor	and save the output as an old log file
	      instead  of  current.   multilog	will also save any output that
	      processor	writes to descriptor 5,	and make that output  readable
	      on descriptor 4 when it runs processor on	the next log file. For
	      reliability, processor must exit nonzero if it has  any  trouble
	      creating	its output; multilog will then run it again. Note that
	      running processor	may block any program feeding input to	multi-
	      log.

       wcode  Changes  the "safely written" code from .s as described above to
	      .code for	subsequent dir actions.	 This is useful	when  using  a
	      processor	 that compresses or otherwise translates the completed
	      log file into a different	file format.

SEE ALSO
       fnmatch(3), glob(7), supervise(8), svc(8), svok(8), svstat(8),  svscan-
       boot(8),	   svscan(8),	 readproctitle(8),   fghack(8),	  pgrphack(8),
       tai64n(8), tai64nlocal(8), setuidgid(8),	envuidgid(8), envdir(8), soft-
       limit(8), setlock(8)

								   multilog(8)

NAME | SYNOPSIS | DESCRIPTION | SELECTING LINES | ALERTS | STATUS FILES | TIMESTAMPING | AUTOMATICALLY ROTATED LOGS | SEE ALSO

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

home | help