| newsyslog.conf.5 (55bf17e95898e4714ae7bfe5afbf7cd88201a7a9) | newsyslog.conf.5 (9cdb6ee1641e84242a1640055e0072ad693e1a7d) |
|---|---|
| 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 June 03, 2004 | 24.Dd June 3, 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 configuration of the newsyslog utility | 29.Nd 30.Xr newsyslog 8 31configuration file |
| 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. | 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. |
| 48Each line has five mandatory fields and four optional fields | 50Each line has five mandatory fields and four optional fields, |
| 49separated with whitespace. 50Blank lines or lines beginning with | 51separated with whitespace. 52Blank lines or lines beginning with |
| 51.Dq # | 53.Ql # |
| 52are ignored. 53If | 54are ignored. 55If |
| 54.Dq # | 56.Ql # |
| 55is placed in the middle of the line, the | 57is placed in the middle of the line, the |
| 56.Dq # | 58.Ql # |
| 57character and the rest of the line after it is ignored. 58To prevent special meaning, the | 59character and the rest of the line after it is ignored. 60To prevent special meaning, the |
| 59.Dq # | 61.Ql # |
| 60character may be escaped with | 62character may be escaped with |
| 61.Dq \e\e , | 63.Ql \e\e ; |
| 62in this case preceding | 64in this case preceding |
| 63.Dq \e\e | 65.Ql \e\e |
| 64is removed and | 66is removed and |
| 65.Dq # 66treated as ordinary character. | 67.Ql # 68is treated as an ordinary character. |
| 67The fields of the configuration file are as follows: | 69The fields of the configuration file are as follows: |
| 68.Pp | |
| 69.Bl -tag -width indent 70.It Ar logfile_name 71Name of the system log file to be archived, or the literal string | 70.Bl -tag -width indent 71.It Ar logfile_name 72Name of the system log file to be archived, or the literal string |
| 72.Dq Aq default . | 73.Dq Aq Li default . |
| 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 | 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 |
| 81.Dq \&: | 82.Ql \&: |
| 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 | 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 |
| 101.Pq Ql \&* , | 102.Pq Ql * , |
| 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 | 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 |
| 110.Pq Ql \&* | 111.Pq Ql * , |
| 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 | 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 |
| 123.So Li \&$ Sc Ns No -sign 124along with a rotation time specification of once 125a day, once a week or once a month. | 124.Ql $ 125sign along with a rotation time specification of once 126a day, once a week, or once a month. |
| 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 | 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 |
| 139.Sq within the hour . | 140.Dq within the hour . |
| 140.Pp | 141.Pp |
| 141.Sy ISO 8601 restricted time format: | 142.Sy ISO 8601 restricted time format : |
| 142.Pp 143The lead-in character for a restricted 144.Tn ISO 8601 145time is an | 143.Pp 144The lead-in character for a restricted 145.Tn ISO 8601 146time is an |
| 146.So Li \&@ Sc Ns No -sign . | 147.Ql @ 148sign. |
| 147The particular format of the time in restricted 148.Tn ISO 8601 149is: 150.Sm off 151.Oo | 149The particular format of the time in restricted 150.Tn ISO 8601 151is: 152.Sm off 153.Oo |
| 154.Op Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd |
|
| 152.Oo | 155.Oo |
| 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 | 156.Li T 157.Op Va hh Oo Va mm Oo Va ss Oc Oc Oc |
| 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 | 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 |
| 201.Sq Li \&T | 183.Sq Li T |
| 202.It 203.Sq Li \& 204.El 205.Pp 206.Sy Day, week, and month time format: 207.Pp | 184.It 185.Sq Li \& 186.El 187.Pp 188.Sy Day, week, and month time format: 189.Pp |
| 208The lead-in character for day, week, and month specification is an 209.So Li \&$ Sc Ns No -sign . | 190The lead-in character for day, week, and month specification is a 191.Ql $ 192sign. |
| 210The particular format of day, week, and month specification is: | 193The particular format of day, week, and month specification is: |
| 211.Op Va D\&hh , 212.Op Va W\&w Ns Op Va D\&hh | 194.Op Li D Ns Va hh , 195.Op Li W Ns Va w Ns Op Li D Ns Va hh , |
| 213and | 196and |
| 214.Op Va M\&dd Ns Op Va D\&hh | 197.Op Li M Ns Va dd Ns Op Li D Ns Va hh , |
| 215respectively. 216Optional time fields default to midnight. 217The ranges for day and hour specifications are: 218.Pp | 198respectively. 199Optional time fields default to midnight. 200The ranges for day and hour specifications are: 201.Pp |
| 219.Bl -tag -width Ds -compact -offset indent | 202.Bl -tag -width indent -offset indent -compact |
| 220.It Ar hh | 203.It Ar hh |
| 221hours, range 0 ... 23 | 204hours, range 0..23 |
| 222.It Ar w | 205.It Ar w |
| 223day of week, range 0 ... 6, 0 = Sunday | 206day of week, range 0..6, 0 = Sunday |
| 224.It Ar dd | 207.It Ar dd |
| 225day of month, range 1 ... 31, or one of the letters 226.Em L | 208day of month, range 1..31, or one of the letters 209.Ql L |
| 227or | 210or |
| 228.Em l | 211.Ql l |
| 229to specify the last day of the month. 230.El 231.Pp 232Some examples: 233.Pp | 212to specify the last day of the month. 213.El 214.Pp 215Some examples: 216.Pp |
| 234.Bl -tag -width Ds -compact -offset indent 235.It Ar $D0 | 217.Bl -tag -width indent -offset indent -compact 218.It Li $D0 |
| 236rotate every night at midnight 237(same as | 219rotate every night at midnight 220(same as |
| 238.Ar @T00 ) 239.It Ar $D23 240rotate every day at 23:00 hr | 221.Li @T00 ) 222.It Li $D23 223rotate every day at 23:00 |
| 241(same as | 224(same as |
| 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 | 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 |
| 248rotate at the first day of every month at midnight 249(i.e., the start of the day; same as | 231rotate at the first day of every month at midnight 232(i.e., the start of the day; same as |
| 250.Ar @01T00 ) 251.It Ar $M5D6 252rotate on every 5th day of month at 6:00 hr | 233.Li @01T00 ) 234.It Li $M5D6 235rotate on every 5th day of month at 6:00 |
| 253(same as | 236(same as |
| 254.Ar @05T06 ) | 237.Li @05T06 ) |
| 255.El | 238.El |
| 256.Pp | |
| 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 | 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 |
| 263.It Sy B | 245.It Cm B |
| 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 | 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 |
| 274.Sy B | 256.Cm B |
| 275is specified, then that informational message will not be 276inserted into the log file. | 257is specified, then that informational message will not be 258inserted into the log file. |
| 277.It Sy C | 259.It Cm C |
| 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. | 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. |
| 282.It Sy D | 264.It Cm D |
| 283indicates that 284.Xr newsyslog 8 | 265indicates that 266.Xr newsyslog 8 |
| 285should set the NODUMP flag when creating a new version of | 267should set the 268.Dv UF_NODUMP 269flag when creating a new version of |
| 286this log file. 287This option would effect how the 288.Xr dump 8 289command treats the log file when making a file system backup. | 270this log file. 271This option would effect how the 272.Xr dump 8 273command treats the log file when making a file system backup. |
| 290.It Sy G | 274.It Cm G |
| 291indicates that the specified 292.Ar logfile_name 293is a shell pattern, and that 294.Xr newsyslog 8 295should archive all filenames matching that pattern using the 296other options on this line. 297See 298.Xr glob 3 299for details on syntax and matching rules. | 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. |
| 300.It Sy J | 284.It Cm J |
| 301indicates that 302.Xr newsyslog 8 303should attempt to save disk space by compressing the rotated 304log file using 305.Xr bzip2 1 . | 285indicates that 286.Xr newsyslog 8 287should attempt to save disk space by compressing the rotated 288log file using 289.Xr bzip2 1 . |
| 306.It Sy N | 290.It Cm N |
| 307indicates that there is no process which needs to be signaled 308when this log file is rotated. | 291indicates that there is no process which needs to be signaled 292when this log file is rotated. |
| 309.It Sy U | 293.It Cm U |
| 310indicates that the file specified by 311.Ar path_to_pid_file | 294indicates that the file specified by 295.Ar path_to_pid_file |
| 312will contain the id for a process group instead of a process. | 296will contain the ID for a process group instead of a process. |
| 313This option also requires that the first line in that file | 297This option also requires that the first line in that file |
| 314be a negative value to distinguish it from a process id. 315.It Sy W | 298be a negative value to distinguish it from a process ID. 299.It Cm W |
| 316if used with the | 300if used with the |
| 317.Sy Z | 301.Cm Z |
| 318or | 302or |
| 319.Sy J | 303.Cm J |
| 320flag, this indicates that 321.Xr newsyslog 8 322should wait for previously started compression jobs to complete before 323starting a new one for this entry. 324If this is used with the | 304flag, this indicates that 305.Xr newsyslog 8 306should wait for previously started compression jobs to complete before 307starting a new one for this entry. 308If this is used with the |
| 325.Sy G | 309.Cm G |
| 326flag and if multiple log files match the given pattern, then 327.Xr newsyslog 8 328will compress those logs one by one. 329This ensures that only one compression job is running at a time. | 310flag and if multiple log files match the given pattern, then 311.Xr newsyslog 8 312will compress those logs one by one. 313This ensures that only one compression job is running at a time. |
| 330.It Sy Z | 314.It Cm Z |
| 331indicates that 332.Xr newsyslog 8 333should attempt to save disk space by compressing the rotated 334log file using 335.Xr gzip 1 . | 315indicates that 316.Xr newsyslog 8 317should attempt to save disk space by compressing the rotated 318log file using 319.Xr gzip 1 . |
| 336.It Sy - | 320.It Fl |
| 337a minus sign will not cause any special processing, but it 338can be used as a placeholder to create a 339.Ar flags 340field when you need to specify any of the following fields. 341.El 342.It Ar path_to_pid_file 343This optional field specifies the file name containing a daemon's | 321a minus sign will not cause any special processing, but it 322can be used as a placeholder to create a 323.Ar flags 324field when you need to specify any of the following fields. 325.El 326.It Ar path_to_pid_file 327This optional field specifies the file name containing a daemon's |
| 344process id or to find a group process id if the 345.Sy U | 328process ID or to find a group process ID if the 329.Cm U |
| 346flag was specified. 347If this field is present, a 348.Ar signal_number | 330flag was specified. 331If this field is present, a 332.Ar signal_number |
| 349is sent the process id contained in this file. | 333is sent the process ID contained in this file. |
| 350If this field is not present, then a 351.Dv SIGHUP 352signal will be sent to 353.Xr syslogd 8 , 354unless the | 334If this field is not present, then a 335.Dv SIGHUP 336signal will be sent to 337.Xr syslogd 8 , 338unless the |
| 355.Sy N | 339.Cm N |
| 356flag has been specified. 357This field must start with | 340flag has been specified. 341This field must start with |
| 358.Dq / | 342.Ql / |
| 359in order to be recognized properly. 360.It Ar signal_number 361This optional field specifies the signal number that will be sent 362to the daemon process (or to all processes in a process group, if the | 343in order to be recognized properly. 344.It Ar signal_number 345This optional field specifies the signal number that will be sent 346to the daemon process (or to all processes in a process group, if the |
| 363.Sy U | 347.Cm U |
| 364flag was specified). 365If this field is not present, then a 366.Dv SIGHUP 367signal will be sent. 368.El 369.Sh SEE ALSO 370.Xr bzip 1 , 371.Xr gzip 1 , 372.Xr syslog 3 , 373.Xr chown 8 , 374.Xr newsyslog 8 , 375.Xr syslog 8 376.Sh HISTORY 377This manual page first appeared in 378.Fx 4.10 . | 348flag was specified). 349If this field is not present, then a 350.Dv SIGHUP 351signal will be sent. 352.El 353.Sh SEE ALSO 354.Xr bzip 1 , 355.Xr gzip 1 , 356.Xr syslog 3 , 357.Xr chown 8 , 358.Xr newsyslog 8 , 359.Xr syslog 8 360.Sh HISTORY 361This manual page first appeared in 362.Fx 4.10 . |