| newsyslog.conf.5 (cb45b78eaea2baeb65284b81da6fc74dfcb41c78) | newsyslog.conf.5 (491abe5ac7deaaa290da0239f0351f993f79b2f4) |
|---|---|
| 1.\" This file was split from the newsyslog(8) manual page by Tom Rhodes 2.\" and includes modifications as appropriate. 3.\" The original header is included below: 4.\" 5.\" This file contains changes from the Open Software Foundation. 6.\" 7.\" from: @(#)newsyslog.8 8.\" $FreeBSD$ --- 7 unchanged lines hidden (view full) --- 16.\" this permission notice appear in supporting documentation, 17.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 18.\" used in advertising or publicity pertaining to distribution 19.\" of the software without specific, written prior permission. 20.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 21.\" the suitability of this software for any purpose. It is 22.\" provided "as is" without express or implied warranty. 23.\" | 1.\" This file was split from the newsyslog(8) manual page by Tom Rhodes 2.\" and includes modifications as appropriate. 3.\" The original header is included below: 4.\" 5.\" This file contains changes from the Open Software Foundation. 6.\" 7.\" from: @(#)newsyslog.8 8.\" $FreeBSD$ --- 7 unchanged lines hidden (view full) --- 16.\" this permission notice appear in supporting documentation, 17.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 18.\" used in advertising or publicity pertaining to distribution 19.\" of the software without specific, written prior permission. 20.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 21.\" the suitability of this software for any purpose. It is 22.\" provided "as is" without express or implied warranty. 23.\" |
| 24.Dd November 27, 2006 | 24.Dd March 10, 2004 |
| 25.Dt NEWSYSLOG.CONF 5 26.Os 27.Sh NAME 28.Nm newsyslog.conf | 25.Dt NEWSYSLOG.CONF 5 26.Os 27.Sh NAME 28.Nm newsyslog.conf |
| 29.Nd 30.Xr newsyslog 8 31configuration file | 29.Nd configuration of the newsyslog utility |
| 32.Sh DESCRIPTION 33The 34.Nm 35file is used to set log file rotation configuration for the 36.Xr newsyslog 8 37utility. 38Configuration may designate that logs are rotated based on 39size, last rotation time, or time of day. 40The 41.Nm 42file can also be used to designate secure permissions to log 43files at rotation time. 44During initialization, 45.Xr newsyslog 8 46reads a configuration file, 47normally 48.Pa /etc/newsyslog.conf , 49to determine which logs may potentially be rotated and archived. | 30.Sh DESCRIPTION 31The 32.Nm 33file is used to set log file rotation configuration for the 34.Xr newsyslog 8 35utility. 36Configuration may designate that logs are rotated based on 37size, last rotation time, or time of day. 38The 39.Nm 40file can also be used to designate secure permissions to log 41files at rotation time. 42During initialization, 43.Xr newsyslog 8 44reads a configuration file, 45normally 46.Pa /etc/newsyslog.conf , 47to determine which logs may potentially be rotated and archived. |
| 50Each line has five mandatory fields and four optional fields, | 48Each line has five mandatory fields and four optional fields |
| 51separated with whitespace. 52Blank lines or lines beginning with | 49separated with whitespace. 50Blank lines or lines beginning with |
| 53.Ql # | 51.Dq # |
| 54are ignored. 55If | 52are ignored. 53If |
| 56.Ql # | 54.Dq # |
| 57is placed in the middle of the line, the | 55is placed in the middle of the line, the |
| 58.Ql # | 56.Dq # |
| 59character and the rest of the line after it is ignored. 60To prevent special meaning, the | 57character and the rest of the line after it is ignored. 58To prevent special meaning, the |
| 61.Ql # | 59.Dq # |
| 62character may be escaped with | 60character may be escaped with |
| 63.Ql \e ; | 61.Dq \e\e , |
| 64in this case preceding | 62in this case preceding |
| 65.Ql \e | 63.Dq \e\e |
| 66is removed and | 64is removed and |
| 67.Ql # 68is treated as an ordinary character. | 65.Dq # 66treated as ordinary character. |
| 69The fields of the configuration file are as follows: | 67The fields of the configuration file are as follows: |
| 68.Pp |
|
| 70.Bl -tag -width indent 71.It Ar logfile_name 72Name of the system log file to be archived, or the literal string | 69.Bl -tag -width indent 70.It Ar logfile_name 71Name of the system log file to be archived, or the literal string |
| 73.Dq Aq Li default . | 72.Dq Aq default . |
| 74The special default entry will only be used if a log file 75name is given as a command line argument to 76.Xr newsyslog 8 , 77and if that log file name is not matched by any other 78line in the configuration file. 79.It Ar owner : Ns Ar group 80This optional field specifies the owner and group for the archive file. 81The | 73The special default entry will only be used if a log file 74name is given as a command line argument to 75.Xr newsyslog 8 , 76and if that log file name is not matched by any other 77line in the configuration file. 78.It Ar owner : Ns Ar group 79This optional field specifies the owner and group for the archive file. 80The |
| 82.Ql \&: | 81.Dq \&: |
| 83is essential regardless if the 84.Ar owner 85or 86.Ar group 87field is left blank or contains a value. 88The field may be numeric, or a name which is present in 89.Pa /etc/passwd 90or 91.Pa /etc/group . 92.It Ar mode 93Specify the file mode of the log file and archives. 94.It Ar count 95Specify the maximum number of archive files which may exist. 96This does not consider the current log file. 97.It Ar size 98When the size of the log file reaches 99.Ar size 100in kilobytes, the log file will be trimmed as described above. 101If this field contains an asterisk | 82is essential regardless if the 83.Ar owner 84or 85.Ar group 86field is left blank or contains a value. 87The field may be numeric, or a name which is present in 88.Pa /etc/passwd 89or 90.Pa /etc/group . 91.It Ar mode 92Specify the file mode of the log file and archives. 93.It Ar count 94Specify the maximum number of archive files which may exist. 95This does not consider the current log file. 96.It Ar size 97When the size of the log file reaches 98.Ar size 99in kilobytes, the log file will be trimmed as described above. 100If this field contains an asterisk |
| 102.Pq Ql * , | 101.Pq Ql \&* , |
| 103the log file will not be trimmed based on size. 104.It Ar when 105The 106.Ar when 107field may consist of an interval, a specific time, or both. 108If the 109.Ar when 110field contains an asterisk | 102the log file will not be trimmed based on size. 103.It Ar when 104The 105.Ar when 106field may consist of an interval, a specific time, or both. 107If the 108.Ar when 109field contains an asterisk |
| 111.Pq Ql * , | 110.Pq Ql \&* |
| 112log rotation will solely depend on the contents of the 113.Ar size 114field. 115Otherwise, the 116.Ar when 117field consists of an optional interval in hours, usually followed 118by an 119.So Li \&@ Sc Ns No -sign 120and a time in restricted 121.Tn ISO 8601 122format. 123Additionally, the format may also be constructed with a | 111log rotation will solely depend on the contents of the 112.Ar size 113field. 114Otherwise, the 115.Ar when 116field consists of an optional interval in hours, usually followed 117by an 118.So Li \&@ Sc Ns No -sign 119and a time in restricted 120.Tn ISO 8601 121format. 122Additionally, the format may also be constructed with a |
| 124.Ql $ 125sign along with a rotation time specification of once 126a day, once a week, or once a month. | 123.So Li \&$ Sc Ns No -sign 124along with a rotation time specification of once 125a day, once a week or once a month. |
| 127.Pp 128If a time is specified, the log file will only be trimmed if 129.Xr newsyslog 8 130is run within one hour of the specified time. 131If an interval is specified, the log file will be trimmed if that many 132hours have passed since the last rotation. 133When both a time and an interval are 134specified then both conditions must be satisfied for the rotation to 135take place. 136.Pp 137There is no provision for the specification of a timezone. 138There is little point in specifying an explicit minutes or 139seconds component in the current implementation, since the only comparison is | 126.Pp 127If a time is specified, the log file will only be trimmed if 128.Xr newsyslog 8 129is run within one hour of the specified time. 130If an interval is specified, the log file will be trimmed if that many 131hours have passed since the last rotation. 132When both a time and an interval are 133specified then both conditions must be satisfied for the rotation to 134take place. 135.Pp 136There is no provision for the specification of a timezone. 137There is little point in specifying an explicit minutes or 138seconds component in the current implementation, since the only comparison is |
| 140.Dq within the hour . | 139.Sq within the hour . |
| 141.Pp | 140.Pp |
| 142.Sy ISO 8601 restricted time format : | 141.Sy ISO 8601 restricted time format: |
| 143.Pp 144The lead-in character for a restricted 145.Tn ISO 8601 146time is an | 142.Pp 143The lead-in character for a restricted 144.Tn ISO 8601 145time is an |
| 147.Ql @ 148sign. | 146.So Li \&@ Sc Ns No -sign . |
| 149The particular format of the time in restricted 150.Tn ISO 8601 151is: 152.Sm off 153.Oo | 147The particular format of the time in restricted 148.Tn ISO 8601 149is: 150.Sm off 151.Oo |
| 154.Op Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd | |
| 155.Oo | 152.Oo |
| 156.Li T 157.Op Va hh Oo Va mm Oo Va ss Oc Oc Oc | 153.Oo 154.Oo 155.Oo 156.Va \&cc 157.Oc 158.Va \&yy 159.Oc 160.Va \&mm 161.Oc 162.Va \&dd 163.Oc 164.Oo 165.Li \&T 166.Oo 167.Va \&hh 168.Oo 169.Va \&mm 170.Oo 171.Va \&ss 172.Oc 173.Oc 174.Oc 175.Oc |
| 158.Oc . 159.Sm on 160Optional date fields default to the appropriate component of the 161current date; optional time fields default to midnight; hence if today 162is January 22, 1999, the following date specifications are all 163equivalent: 164.Pp 165.Bl -item -compact -offset indent --- 9 unchanged lines hidden (view full) --- 175.Sq Li T000000 176.It 177.Sq Li T0000 178.It 179.Sq Li T00 180.It 181.Sq Li 22T 182.It | 176.Oc . 177.Sm on 178Optional date fields default to the appropriate component of the 179current date; optional time fields default to midnight; hence if today 180is January 22, 1999, the following date specifications are all 181equivalent: 182.Pp 183.Bl -item -compact -offset indent --- 9 unchanged lines hidden (view full) --- 193.Sq Li T000000 194.It 195.Sq Li T0000 196.It 197.Sq Li T00 198.It 199.Sq Li 22T 200.It |
| 183.Sq Li T | 201.Sq Li \&T |
| 184.It 185.Sq Li \& 186.El 187.Pp 188.Sy Day, week, and month time format: 189.Pp | 202.It 203.Sq Li \& 204.El 205.Pp 206.Sy Day, week, and month time format: 207.Pp |
| 190The lead-in character for day, week, and month specification is a 191.Ql $ 192sign. | 208The lead-in character for day, week, and month specification is an 209.So Li \&$ Sc Ns No -sign . |
| 193The particular format of day, week, and month specification is: | 210The particular format of day, week, and month specification is: |
| 194.Op Li D Ns Va hh , 195.Op Li W Ns Va w Ns Op Li D Ns Va hh , | 211.Op Va D\&hh , 212.Op Va W\&w Ns Op Va D\&hh |
| 196and | 213and |
| 197.Op Li M Ns Va dd Ns Op Li D Ns Va hh , | 214.Op Va M\&dd Ns Op Va D\&hh |
| 198respectively. 199Optional time fields default to midnight. 200The ranges for day and hour specifications are: 201.Pp | 215respectively. 216Optional time fields default to midnight. 217The ranges for day and hour specifications are: 218.Pp |
| 202.Bl -tag -width indent -offset indent -compact | 219.Bl -tag -width Ds -compact -offset indent |
| 203.It Ar hh | 220.It Ar hh |
| 204hours, range 0..23 | 221hours, range 0 ... 23 |
| 205.It Ar w | 222.It Ar w |
| 206day of week, range 0..6, 0 = Sunday | 223day of week, range 0 ... 6, 0 = Sunday |
| 207.It Ar dd | 224.It Ar dd |
| 208day of month, range 1..31, or one of the letters 209.Ql L | 225day of month, range 1 ... 31, or one of the letters 226.Em L |
| 210or | 227or |
| 211.Ql l | 228.Em l |
| 212to specify the last day of the month. 213.El 214.Pp 215Some examples: 216.Pp | 229to specify the last day of the month. 230.El 231.Pp 232Some examples: 233.Pp |
| 217.Bl -tag -width indent -offset indent -compact 218.It Li $D0 | 234.Bl -tag -width Ds -compact -offset indent 235.It Ar $D0 |
| 219rotate every night at midnight 220(same as | 236rotate every night at midnight 237(same as |
| 221.Li @T00 ) 222.It Li $D23 223rotate every day at 23:00 | 238.Ar @T00 ) 239.It Ar $D23 240rotate every day at 23:00 hr |
| 224(same as | 241(same as |
| 225.Li @T23 ) 226.It Li $W0D23 227rotate every week on Sunday at 23:00 228.It Li $W5D16 229rotate every week on Friday at 16:00 230.It Li $M1D0 | 242.Ar @T23 ) 243.It Ar $W0D23 244rotate every week on Sunday at 23:00 hr 245.It Ar $W5D16 246rotate every week on Friday at 16:00 hr 247.It Ar $M1D0 |
| 231rotate at the first day of every month at midnight 232(i.e., the start of the day; same as | 248rotate at the first day of every month at midnight 249(i.e., the start of the day; same as |
| 233.Li @01T00 ) 234.It Li $M5D6 235rotate on every 5th day of month at 6:00 | 250.Ar @01T00 ) 251.It Ar $M5D6 252rotate on every 5th day of month at 6:00 hr |
| 236(same as | 253(same as |
| 237.Li @05T06 ) | 254.Ar @05T06 ) |
| 238.El | 255.El |
| 256.Pp |
|
| 239.It Ar flags 240This optional field is made up of one or more characters 241that specify any special processing to be done for the log 242files matched by this line. 243The following are valid flags: 244.Bl -tag -width indent | 257.It Ar flags 258This optional field is made up of one or more characters 259that specify any special processing to be done for the log 260files matched by this line. 261The following are valid flags: 262.Bl -tag -width indent |
| 245.It Cm B | 263.It Sy B |
| 246indicates that the log file is a binary file, or has some 247special format. 248Usually 249.Xr newsyslog 8 250inserts an 251.Tn ASCII 252message into a log file during rotation. 253This message is used to indicate 254when, and sometimes why the log file was rotated. 255If | 264indicates that the log file is a binary file, or has some 265special format. 266Usually 267.Xr newsyslog 8 268inserts an 269.Tn ASCII 270message into a log file during rotation. 271This message is used to indicate 272when, and sometimes why the log file was rotated. 273If |
| 256.Cm B | 274.Sy B |
| 257is specified, then that informational message will not be 258inserted into the log file. | 275is specified, then that informational message will not be 276inserted into the log file. |
| 259.It Cm C | 277.It Sy C |
| 260indicates that the log file should be created if it does not 261already exist, and if the 262.Fl C 263option was also specified on the command line. | 278indicates that the log file should be created if it does not 279already exist, and if the 280.Fl C 281option was also specified on the command line. |
| 264.It Cm D 265indicates that 266.Xr newsyslog 8 267should set the 268.Dv UF_NODUMP 269flag when creating a new version of 270this log file. 271This option would affect how the 272.Xr dump 8 273command treats the log file when making a file system backup. 274.It Cm G | 282.It Sy G |
| 275indicates that the specified 276.Ar logfile_name 277is a shell pattern, and that 278.Xr newsyslog 8 279should archive all filenames matching that pattern using the 280other options on this line. 281See 282.Xr glob 3 283for details on syntax and matching rules. | 283indicates that the specified 284.Ar logfile_name 285is a shell pattern, and that 286.Xr newsyslog 8 287should archive all filenames matching that pattern using the 288other options on this line. 289See 290.Xr glob 3 291for details on syntax and matching rules. |
| 284.It Cm J | 292.It Sy J |
| 285indicates that 286.Xr newsyslog 8 287should attempt to save disk space by compressing the rotated 288log file using 289.Xr bzip2 1 . | 293indicates that 294.Xr newsyslog 8 295should attempt to save disk space by compressing the rotated 296log file using 297.Xr bzip2 1 . |
| 290.It Cm N | 298.It Sy N |
| 291indicates that there is no process which needs to be signaled 292when this log file is rotated. | 299indicates that there is no process which needs to be signaled 300when this log file is rotated. |
| 293.It Cm U | 301.It Sy U |
| 294indicates that the file specified by 295.Ar path_to_pid_file | 302indicates that the file specified by 303.Ar path_to_pid_file |
| 296will contain the ID for a process group instead of a process. | 304will contain the id for a process group instead of a process. |
| 297This option also requires that the first line in that file | 305This option also requires that the first line in that file |
| 298be a negative value to distinguish it from a process ID. 299.It Cm Z | 306be a negative value to distinguish it from a process id. 307.It Sy W 308if used with the 309.Sy Z 310or 311.Sy J 312flag, this indicates that 313.Xr newsyslog 8 314should wait for previously started compression jobs to complete before 315starting a new one for this entry. 316If this is used with the 317.Sy G 318flag and if multiple log files match the given pattern, then 319.Xr newsyslog 8 320will compress those logs one by one. 321This ensures that only one compression job is running at a time. 322.It Sy Z |
| 300indicates that 301.Xr newsyslog 8 302should attempt to save disk space by compressing the rotated 303log file using 304.Xr gzip 1 . | 323indicates that 324.Xr newsyslog 8 325should attempt to save disk space by compressing the rotated 326log file using 327.Xr gzip 1 . |
| 305.It Fl | 328.It Sy - |
| 306a minus sign will not cause any special processing, but it 307can be used as a placeholder to create a 308.Ar flags 309field when you need to specify any of the following fields. 310.El 311.It Ar path_to_pid_file 312This optional field specifies the file name containing a daemon's | 329a minus sign will not cause any special processing, but it 330can be used as a placeholder to create a 331.Ar flags 332field when you need to specify any of the following fields. 333.El 334.It Ar path_to_pid_file 335This optional field specifies the file name containing a daemon's |
| 313process ID or to find a group process ID if the 314.Cm U | 336process id or to find a group process id if the 337.Sy U |
| 315flag was specified. 316If this field is present, a 317.Ar signal_number | 338flag was specified. 339If this field is present, a 340.Ar signal_number |
| 318is sent the process ID contained in this file. | 341is sent the process id contained in this file. |
| 319If this field is not present, then a 320.Dv SIGHUP 321signal will be sent to 322.Xr syslogd 8 , 323unless the | 342If this field is not present, then a 343.Dv SIGHUP 344signal will be sent to 345.Xr syslogd 8 , 346unless the |
| 324.Cm N | 347.Sy N |
| 325flag has been specified. 326This field must start with | 348flag has been specified. 349This field must start with |
| 327.Ql / | 350.Dq / |
| 328in order to be recognized properly. 329.It Ar signal_number 330This optional field specifies the signal number that will be sent 331to the daemon process (or to all processes in a process group, if the | 351in order to be recognized properly. 352.It Ar signal_number 353This optional field specifies the signal number that will be sent 354to the daemon process (or to all processes in a process group, if the |
| 332.Cm U | 355.Sy U |
| 333flag was specified). 334If this field is not present, then a 335.Dv SIGHUP 336signal will be sent. 337.El 338.Sh SEE ALSO | 356flag was specified). 357If this field is not present, then a 358.Dv SIGHUP 359signal will be sent. 360.El 361.Sh SEE ALSO |
| 339.Xr bzip2 1 , | 362.Xr bzip 1 , |
| 340.Xr gzip 1 , 341.Xr syslog 3 , 342.Xr chown 8 , 343.Xr newsyslog 8 , | 363.Xr gzip 1 , 364.Xr syslog 3 , 365.Xr chown 8 , 366.Xr newsyslog 8 , |
| 344.Xr syslogd 8 | 367.Xr syslog 8 |
| 345.Sh HISTORY 346This manual page first appeared in 347.Fx 4.10 . | 368.Sh HISTORY 369This manual page first appeared in 370.Fx 4.10 . |