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

NAME
     newsyslog -- maintain system log files to manageable sizes

SYNOPSIS
     newsyslog [-Fnrv] [-f config_file] [-a directory] [file ...]

DESCRIPTION
     The  newsyslog  utility should be scheduled to run periodically by cron(8).
     When it is executed it archives log files if necessary.  If a log	file  is
     determined  to  require  archiving,  newsyslog rearranges the files so that
     "logfile"	is  empty,  "logfile.0"  has  the  last  period's  logs  in  it,
     "logfile.1"  has  the  next to last period's logs in it, and so on, up to a
     user-specified number of archived logs.  Optionally the archived  logs  can
     be compressed to save space.

     A log can be archived for three reasons:

	   1.	It is larger than the configured size (in kilobytes).

	   2.	A configured number of hours have elapsed since the log was last
		archived.

	   3.	This is the specific configured hour for rotation of the log.

     The  granularity  of newsyslog is dependent on how often it is scheduled to
     run by cron(8).  Since the program is quite fast, it may  be  scheduled  to
     run every hour without any ill effects, and mode three (above) assumes that
     this is so.

     When  starting  up,  newsyslog  reads  in a configuration file to determine
     which logs may potentially be archived.   By  default,  this  configuration
     file  is  /etc/newsyslog.conf.   Each line of the file contains information
     about a particular log file that should be handled by newsyslog.  Each line
     has five mandatory fields and four optional fields, with  whitespace  sepa-
     rating  each field.  Blank lines or lines beginning with ``#'' are ignored.
     If ``#'' is placed in the middle of the line, ``#'' character and the  rest
     of the line after it is ignored.  To prevent special meaning, the ``#'' may
     be  escaped  with	``\'', in this case preceding ``\'' is removed and ``#''
     treated as ordinary character.  The fields of the configuration file are as
     follows:

     logfile_name
	     Name of the system log file to be archived.

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

     mode    Specify the mode of the log file and archives.

     count   Specify the number of archive files to be kept besides the log file
	     itself.

     size    When  the	size  of the log file reaches size in kilobytes, the log
	     file will be trimmed as described above.  If this field is replaced
	     by an asterisk (`*'), then the size of the log file  is  not  taken
	     into account when determining when to trim the log file.

     when    The  when	field  can  consist  of an interval, a specific time, or
	     both.  If the when field is an asterisk (`*') log rotation will de-
	     pend only on the contents of the size field.  Otherwise,  the  when
	     field  consists  of  an optional interval in hours, optionally fol-
	     lowed by an `@'-sign and a time in a restricted ISO 8601 format  or
	     by  an  `$'-sign and a time specification for logfile rotation at a
	     fixed time once per day, per week or per month.

	     If a time is specified, the  log  file  will  only  be  trimmed  if
	     newsyslog	is run within one hour of the specified time.  If an in-
	     terval 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, both conditions must be satisfied for the
	     rotation to take place.

	     There is no provision for specification of a  timezone.   There  is
	     little point in specifying an explicit minutes or seconds 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  de-
	     fault  to	the  appropriate component of the current date; optional
	     time fields default to midnight; hence  if  today	is  January  22,
	     1999, the following date specifications are all equivalent:

		   `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  specifica-
	     tion  is:	[Dhh],	[Ww[Dhh]] and [Mdd[Dhh]] respectively.	Optional
	     time fields default to midnight.  The ranges for day and hour spec-
	     ifications are:

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

	     Some examples:

		   $D0	   rotate every night at midnight
		   $D23    rotate every day at 23:00 hr
		   $W0D23  rotate every week on Sunday at 23:00 hr
		   $W5D16  rotate every week on Friday at 16:00 hr
		   $MLD0   rotate at the last day of every month at midnight
		   $M5D6   rotate on every 5th day of month at 6:00 hr

     flags   This optional field specifies if the archive should have  any  spe-
	     cial  processing  done  to the archived log files.  The Z flag will
	     make the archive files compress to save  space  by  using	gzip(1).
	     The  J  flag  will make the archive files compress to save space by
	     using bzip2(1).  The B flag means that the file is a  binary  file,
	     and  so  the  ASCII message which newsyslog inserts to indicate the
	     fact that the logs have been turned over should  not  be  included.
	     The - flag means nothing, but can be used as a placeholder when the
	     path_to_pid_file  field  is  specified.   The G flag means that the
	     specified logfile_name is a  shell  pattern,  which  instructs  the
	     newsyslog	to archive all filenames matching this pattern using the
	     same options.  See glob(3)  for  details  on  syntax  and	matching
	     rules.   The  W  flag  in conjunction with the Z flag or the J flag
	     means that newsyslog should wait for previously started compression
	     jobs to complete before starting a new one for this entry.  When it
	     is used along with the G flag, in the case  when  several	logfiles
	     match the pattern and should be compressed, the newsyslog will com-
	     press  logs  one  by one, ensuring that only one compression job is
	     running at a time.

     path_to_pid_file
	     This optional field specifies the file name to  read  to  find  the
	     daemon  process  id.   If this field is present, a signal_number is
	     sent the process id contained in this file.  This field must  start
	     with "/" in order to be recognized properly.

     signal_number
	     This optional field specifies the signal number will be sent to the
	     daemon process.  By default a SIGHUP will be sent.

OPTIONS
     The following options can be used with newsyslog:

     -f config_file
	     Instruct	  newsyslog    to    use    config_file    instead    of
	     /etc/newsyslog.conf for its configuration file.

     -a directory
	     Specify a directory into which archived log files will be	written.
	     If a relative path is given, it is appended to the path of each log
	     file and the resulting path is used as the directory into which the
	     archived  log  for  that  log file will be written.  If an absolute
	     path is given,  all  archived  logs  are  written	into  the  given
	     directory.   If any component of the path directory does not exist,
	     it will be created when newsyslog is run.

     -v      Place newsyslog in verbose mode.  In this mode it	will  print  out
	     each  log	and its reasons for either trimming that log or skipping
	     it.

     -n      Cause newsyslog not to trim the logs, but	to  print  out	what  it
	     would do if this option were not specified.

     -r      Remove  the restriction that newsyslog must be running as root.  Of
	     course, newsyslog will not be able to send a  HUP	signal	to  sys-
	     logd(8) so this option should only be used in debugging.

     -F      Force  newsyslog to trim the logs, even if the trim conditions have
	     not been met.  This option is useful for diagnosing system problems
	     by providing you with fresh logs that contain only the problems.

     If additional command line arguments are given, newsyslog will only examine
     log files that match those arguments; otherwise, it will examine all  files
     listed in the configuration file.

FILES
     /etc/newsyslog.conf      newsyslog configuration file

BUGS
     Doesn't yet automatically read the logs to find security breaches.

AUTHORS
     Theodore Ts'o, MIT Project Athena

     Copyright 1987, Massachusetts Institute of Technology

COMPATIBILITY
     Previous  versions  of the newsyslog utility used the dot (``.'') character
     to distinguish the group name.  Beginning with FreeBSD 3.3, this  has  been
     changed  to a colon (``:'') character so that user and group names may con-
     tain the dot character.  The dot (``.'') character is  still  accepted  for
     backwards compatibility.

SEE ALSO
     gzip(1), syslog(3), chown(8), syslogd(8)

FreeBSD 4.8			  April 4, 2000 		    NEWSYSLOG(8)
home | help