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

FreeBSD Manual Pages

  
 
  

home | help
NEWSYSLOG.CONF(5)	      File Formats Manual	     NEWSYSLOG.CONF(5)

NAME
       newsyslog.conf -- newsyslog(8) configuration file

DESCRIPTION
       The  newsyslog.conf file	is used	to set log file	rotation configuration
       for the newsyslog(8) utility.  Configuration may	 designate  that  logs
       are  rotated  based  on	size, last rotation time, or time of day.  The
       newsyslog.conf file can also be used to designate secure	permissions to
       log files at rotation time.  During initialization, newsyslog(8)	 reads
       a  configuration	file, normally /etc/newsyslog.conf, to determine which
       logs may	potentially be rotated	and  archived.	 Each  line  has  five
       mandatory  fields  and four optional fields, separated with whitespace.
       Blank lines or lines beginning with `#' are ignored.  If	`#' is	placed
       in  the	middle of the line, the	`#' character and the rest of the line
       after it	is ignored.  To	prevent	special	meaning, the `#' character may
       be escaped with `\'; in this case preceding `\' is removed and  `#'  is
       treated as an ordinary character.  The fields of	the configuration file
       are as follows:

       logfile_name
	       Name  of	the system log file to be archived, or one of the lit-
	       eral strings "<default>", or "<include>".  The special  default
	       entry  will  only be used if a log file name is given as	a com-
	       mand line argument to newsyslog(8), and if that log  file  name
	       is  not	matched	 by  any other line in the configuration file.
	       The include entry is used to include other configuration	 files
	       and supports globbing.

       owner:group
	       This  optional  field  specifies	 the  owner  and group for the
	       archive file.  The `:' is essential regardless if the owner  or
	       group  field  is	left blank or contains a value.	 The field may
	       be numeric, or a	 name  which  is  present  in  /etc/passwd  or
	       /etc/group.

       mode    Specify the file	mode of	the log	file and archives.  Valid mode
	       bits  are  0666.	  (That	is, read and write permissions for the
	       rotated log may be specified for	the owner, group, and others.)
	       All other mode bits are ignored.

       count   Specify the maximum number of archive files  which  may	exist.
	       This does not consider the current log file.

       size    When  the  size	of the log file	reaches	size in	kilobytes, the
	       log file	will be	trimmed	as described  above.   If  this	 field
	       contains	 an  asterisk  (`*'), the log file will	not be trimmed
	       based on	size.

       when    The when	field may consist of an	interval, a specific time,  or
	       both.   If the when field contains an asterisk (`*'), log rota-
	       tion will solely	depend on the  contents	 of  the  size	field.
	       Otherwise,  the	when field consists of an optional interval in
	       hours, usually followed by an `@'-sign and a time in restricted
	       ISO 8601	format.	 Additionally, the format  may	also  be  con-
	       structed	 with a	`$' sign along with a rotation time specifica-
	       tion of once a day, once	a week,	or once	a month.

	       Time based trimming happens only	if newsyslog(8)	is run	within
	       one  hour  of the specified time.  If an	interval is specified,
	       the log file will be trimmed if that  many  hours  have	passed
	       since  the last rotation.  When both a time and an interval are
	       specified then both conditions must be satisfied	for the	 rota-
	       tion to take place.

	       There  is  no  provision	 for  the specification	of a timezone.
	       There is	little point in	specifying an explicit minutes or sec-
	       onds component in the current implementation,  since  the  only
	       comparison is "within the hour".

	       ISO 8601	restricted time	format:

	       The  lead-in character for a restricted ISO 8601	time is	an `@'
	       sign.  The particular format of the time	in restricted ISO 8601
	       is: [[[[[cc]yy]mm]dd][T[hh[mm[ss]]]]].	Optional  date	fields
	       default	to  the	appropriate component of the current date; op-
	       tional time fields default to midnight; hence if	today is Janu-
	       ary 22, 1999, the following date	specifications are all equiva-
	       lent:

		     `19990122T000000'
		     `990122T000000'
		     `0122T000000'
		     `22T000000'
		     `T000000'
		     `T0000'
		     `T00'
		     `22T'
		     `T'
		     `'

	       Day, week, and month time format:

	       The lead-in character for day, week, and	month specification is
	       a `$' sign.  The	particular format  of  day,  week,  and	 month
	       specification  is:  [Dhh],  [Ww[Dhh]],  and [Mdd[Dhh]], respec-
	       tively.	Optional time fields default to	midnight.  The	ranges
	       for day and hour	specifications are:

		     hh	     hours, range 0..23
		     w	     day of week, range	0..6, 0	= Sunday
		     dd	     day  of month, range 1..31, or one	of the letters
			     `L' or `l'	to specify the last day	of the month.

	       Some examples:

		     $D0     rotate every night	at midnight (same as @T00)
		     $D23    rotate every day at 23:00 (same as	@T23)
		     $W0D23  rotate every week on Sunday at 23:00
		     $W5D16  rotate every week on Friday at 16:00
		     $M1D0   rotate at the first day of	every  month  at  mid-
			     night  (i.e.,  the	 start	of  the	 day;  same as
			     @01T00)
		     $M5D6   rotate on every fifth day of month	at 6:00	 (same
			     as	@05T06)

       flags   This  optional  field is	made up	of one or more characters that
	       specify any special processing to be done  for  the  log	 files
	       matched by this line.  The following are	valid flags:

	       B       indicates  that	the  log file is a binary file,	or has
		       some special format.  Usually newsyslog(8)  inserts  an
		       ASCII  message  into  a log file	during rotation.  This
		       message is used to indicate when, and sometimes why the
		       log file	was rotated.  If B is specified, then that in-
		       formational message will	not be inserted	into  the  log
		       file.

	       C       indicates  that	the  log  file should be created if it
		       does not	already	exist, and if the -C option  was  also
		       specified on the	command	line.

	       D       indicates  that	newsyslog(8)  should set the UF_NODUMP
		       flag when creating a new	 version  of  this  log	 file.
		       This option would affect	how the	dump(8)	command	treats
		       the log file when making	a file system backup.

	       E       indicates  that the log file should not be rotated when
		       its size	is zero.  The E	flag is	mostly useful in  con-
		       junction	 with  B flag to prevent newsyslog(8) from in-
		       serting an informational	ASCII  message	into  the  new
		       file.

	       G       indicates  that	the  specified logfile_name is a shell
		       pattern,	and that newsyslog(8) should archive all file-
		       names matching that pattern using the other options  on
		       this  line.   See  glob(3)  for	details	 on syntax and
		       matching	rules.

	       J       indicates that newsyslog(8) should attempt to save disk
		       space  by  compressing  the  rotated  log  file	 using
		       bzip2(1).

	       N       indicates  that	there  is no process which needs to be
		       signaled	when this log file is rotated.

	       p       indicates that the zero-th rotated file should  not  be
		       compressed.

	       R       if  this	 flag  is  set the newsyslog(8)	will run shell
		       command defined in path_to_pid_cmd_file after  rotation
		       instead of trying to send signal	to a process id	stored
		       in the file.

	       T       if  this	flag is	set the	informational rotation message
		       written to the log file will be in the format specified
		       by RFC5424.  Normally, the rotation message is  written
		       in the traditional (RFC3164) syslog format.

	       U       indicates     that     the     file     specified    by
		       path_to_pid_cmd_file will contain the ID	for a  process
		       group  instead of a process.  This option also requires
		       that the	first line in that file	be a negative value to
		       distinguish it from a process ID.

	       X       indicates that newsyslog(8) should attempt to save disk
		       space by	compressing the	rotated	log file using xz(1).

	       Y       indicates that newsyslog(8) should attempt to save disk
		       space  by  compressing  the  rotated  log  file	 using
		       zstd(1).

	       Z       indicates that newsyslog(8) should attempt to save disk
		       space   by  compressing	the  rotated  log  file	 using
		       gzip(1).

	       -       a minus sign will not cause any special processing, but
		       it can be used as a placeholder to create a flags field
		       when you	need to	specify	any of the following fields.

       path_to_pid_cmd_file
	       This optional field specifies the file name containing  a  dae-
	       mon's  process  ID  or to find a	group process ID if the	U flag
	       was specified.  If this field is	present, a signal is  sent  to
	       the  process  ID	 contained in this file.  If this field	is not
	       present and the N flag has not been specified,  then  a	SIGHUP
	       signal will be sent to syslogd(8) or to the process id found in
	       the  file  specified  by	 newsyslog(8)'s	-S switch.  This field
	       must start with `/' in order to be recognized  properly.	  When
	       used with the R flag, the file is treated as a path to a	binary
	       to  be  executed	 by the	newsyslog(8) after rotation instead of
	       sending the signal out.

       signal  This optional field specifies the signal	that will be  sent  to
	       the  daemon process (or to all processes	in a process group, if
	       the U flag was specified).  If this field is not	present,  then
	       a  SIGHUP  signal  will	be sent.  Signal names must start with
	       "SIG" and be the	signal name,  e.g.,  SIGUSR1.	Alternatively,
	       signal can be the signal	number,	e.g., 30 for SIGUSR1.

EXAMPLES
       The following is	an example of the "<include>" entry:
	     <include> /etc/newsyslog-local.conf

SEE ALSO
       bzip2(1),  gzip(1),  xz(1), zstd(1), syslog(3), chown(8), newsyslog(8),
       syslogd(8)

       C. Lonvick, The BSD syslog Protocol, RFC3164.

       R. Gerhards, The	Syslog Protocol, RFC5424.

HISTORY
       This manual page	first appeared in FreeBSD 4.10.

FreeBSD	13.2		       February	26, 2021	     NEWSYSLOG.CONF(5)

NAME | DESCRIPTION | EXAMPLES | SEE ALSO | HISTORY

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

home | help