]>
Commit | Line | Data |
---|---|---|
6dbe3af9 KZ |
1 | .\" Copyright (c) 1983, 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)logger.1 8.1 (Berkeley) 6/6/93 | |
33 | .\" | |
05e68ce7 | 34 | .TH LOGGER "1" "November 2015" "util-linux" "User Commands" |
c047c42d | 35 | .SH NAME |
a54b8e24 | 36 | logger \- enter messages into the system log |
c047c42d SK |
37 | .SH SYNOPSIS |
38 | .B logger | |
f49ccec2 BS |
39 | [options] |
40 | .RI [ message ] | |
c047c42d SK |
41 | .SH DESCRIPTION |
42 | .B logger | |
1c936504 | 43 | makes entries in the system log. |
a54b8e24 BS |
44 | .sp |
45 | When the optional \fImessage\fR argument is present, it is written | |
46 | to the log. If it is not present, and the \fB\-f\fR option is not | |
47 | given either, then standard input is logged. | |
c047c42d SK |
48 | .SH OPTIONS |
49 | .TP | |
a54b8e24 BS |
50 | .BR \-d , " \-\-udp" |
51 | Use datagrams (UDP) only. By default the connection is tried to the | |
52 | syslog port defined in /etc/services, which is often 514 . | |
bd0029f6 KZ |
53 | .sp |
54 | See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect. | |
f8bc8ce4 | 55 | .TP |
ae6846b8 | 56 | .BR \-e , " \-\-skip-empty" |
05e68ce7 BS |
57 | Ignore empty lines when processing files. An empty line |
58 | is defined to be a line without any characters. Thus a line consisting | |
ae6846b8 | 59 | only of whitespace is NOT considered empty. |
05e68ce7 BS |
60 | Note that when the \fB\-\-prio\-prefix\fR option is specified, the priority |
61 | is not part of the line. Thus an empty line in this mode is a line that does | |
eb024893 | 62 | not have any characters after the priority prefix (e.g., \fB<13>\fR). |
ae6846b8 | 63 | .TP |
a54b8e24 BS |
64 | .BR \-f , " \-\-file " \fIfile |
65 | Log the contents of the specified \fIfile\fR. | |
66 | This option cannot be combined with a command-line message. | |
f8bc8ce4 | 67 | .TP |
3f51c10b SK |
68 | .B \-i |
69 | Log the PID of the logger process with each line. | |
70 | .TP | |
71 | .BR "\-\-id" [ =\fIid ] | |
a54b8e24 BS |
72 | Log the PID of the logger process with each line. When the optional |
73 | argument \fIid\fR is specified, then it is used instead of the logger | |
74 | command's PID. The use of \fB\-\-id=$$\fR | |
59c6ac0b | 75 | (PPID) is recommended in scripts that send several messages. |
27a9eb53 | 76 | |
05e68ce7 BS |
77 | Note that the system logging infrastructure (for example \fBsystemd\fR when |
78 | listening on /dev/log) may follow local socket credentials to overwrite the | |
79 | PID specified in the message. | |
5593132a | 80 | .BR logger (1) |
05e68ce7 BS |
81 | is able to set those socket credentials to the given \fIid\fR, but only if you |
82 | have root permissions and a process with the specified PID exists, otherwise | |
27a9eb53 | 83 | the socket credentials are not modified and the problem is silently ignored. |
f8bc8ce4 | 84 | .TP |
a54b8e24 BS |
85 | .BR \-\-journald [ =\fIfile ] |
86 | Write a systemd journal entry. The entry is read from the given \fIfile\fR, | |
87 | when specified, otherwise from standard input. | |
88 | Each line must begin with a field that is accepted by journald; see | |
89 | .BR systemd.journal-fields (7) | |
90 | for details. The use of a MESSAGE_ID field is generally a good idea, as it | |
91 | makes finding entries easy. Examples: | |
92 | .IP | |
93 | .nf | |
99045219 | 94 | \fB logger \-\-journald <<end |
b632f55c MS |
95 | \fB MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309 |
96 | \fB MESSAGE=The dogs bark, but the caravan goes on. | |
97 | \fB DOGS=bark | |
98 | \fB CARAVAN=goes on | |
99 | \fB end | |
100 | .IP | |
99045219 | 101 | \fB logger \-\-journald=entry.txt |
a54b8e24 BS |
102 | .fi |
103 | .IP | |
104 | Notice that | |
105 | .B \-\-journald | |
106 | will ignore values of other options, such as priority. If priority is | |
107 | needed it must be within input, and use PRIORITY field. The simple | |
108 | execution of | |
109 | .B journalctl | |
110 | will display MESSAGE field. Use | |
99045219 | 111 | .B journalctl \-\-output json-pretty |
a54b8e24 | 112 | to see rest of the fields. |
1c4a2600 KZ |
113 | .sp |
114 | To include newlines in MESSAGE, specify MESSAGE several times. This is | |
115 | handled as a special case, other fields will be stored as an array in | |
116 | the journal if they appear multiple times. | |
55f5bc66 | 117 | .TP |
05e68ce7 BS |
118 | .BR \-\-msgid " \fImsgid |
119 | Sets the RFC5424 MSGID field. Note that the space character is not permitted | |
120 | inside of \fImsgid\fR. This option is only used if \fB\-\-rfc5424\fR is | |
121 | specified as well; otherwise, it is silently ignored. | |
a54b8e24 BS |
122 | .TP |
123 | .BR \-n , " \-\-server " \fIserver | |
124 | Write to the specified remote syslog \fIserver\fR | |
a4356173 | 125 | instead of to the system log socket. Unless |
a54b8e24 | 126 | \fB\-\-udp\fR or \fB\-\-tcp\fR |
e3a4ee43 | 127 | is specified, \fBlogger\fR will first try to use UDP, |
d35df4db | 128 | but if this fails a TCP connection is attempted. |
68265d07 | 129 | .TP |
0bb7e904 | 130 | .B \-\-no\-act |
da6bb5f8 BS |
131 | Causes everything to be done except for writing the log message to the system |
132 | log, and removing the connection or the journal. This option can be used | |
133 | together with \fB\-\-stderr\fR for testing purposes. | |
134 | .TP | |
135 | .B \-\-octet\-count | |
136 | Use the RFC 6587 octet counting framing method for sending messages. | |
137 | When this option is not used, the default is no framing on UDP, and | |
138 | RFC6587 non-transparent framing (also known as octet stuffing) on TCP. | |
139 | .TP | |
a54b8e24 BS |
140 | .BR \-P , " \-\-port " \fIport |
141 | Use the specified \fIport\fR. When this option is not specified, the | |
142 | port defaults to syslog for udp and to syslog-conn for tcp connections. | |
c047c42d | 143 | .TP |
a54b8e24 BS |
144 | .BR \-p , " \-\-priority " \fIpriority |
145 | Enter the message into the log with the specified \fIpriority\fR. | |
c047c42d | 146 | The priority may be specified numerically or as a |
a54b8e24 | 147 | .IR facility . level |
6dbe3af9 | 148 | pair. |
a54b8e24 | 149 | For example, \fB\-p local3.info\fR |
c047c42d | 150 | logs the message as informational in the local3 facility. |
a54b8e24 | 151 | The default is \fBuser.notice\fR. |
c047c42d | 152 | .TP |
b06c1ca6 | 153 | .B \-\-prio\-prefix |
e3a4ee43 | 154 | Look for a syslog prefix on every line read from standard input. |
a54b8e24 BS |
155 | This prefix is a decimal number within angle brackets that encodes both |
156 | the facility and the level. The number is constructed by multiplying the | |
157 | facility by 8 and then adding the level. For example, \fBlocal0.info\fR, | |
158 | meaning facility=16 and level=6, becomes \fB<134>\fR. | |
159 | .sp | |
98920f80 | 160 | If the prefix contains no facility, the facility defaults to what is |
e3a4ee43 | 161 | specified by the \fB\-p\fR option. Similarly, if no prefix is provided, |
a54b8e24 BS |
162 | the line is logged using the \fIpriority\fR given with \fB\-p\fR. |
163 | .sp | |
98920f80 | 164 | This option doesn't affect a command-line message. |
d9b38f6b | 165 | .TP |
a54b8e24 BS |
166 | .B \-\-rfc3164 |
167 | Use the RFC 3164 BSD syslog protocol to submit messages to a remote server. | |
168 | .TP | |
169 | .BR \-\-rfc5424 [ =\fIwithout ] | |
170 | Use the RFC 5424 syslog protocol to submit messages to a remote server. | |
171 | The optional \fIwithout\fR argument can be a comma-separated list of | |
172 | the following values: \fBnotq\fR, \fBnotime\fR, \fBnohost\fR. | |
4299ed1c | 173 | |
a54b8e24 | 174 | The \fBnotq\fR value suppresses the time-quality structured data |
4299ed1c | 175 | from the submitted message. The time-quality information shows whether |
981997dd | 176 | the local clock was synchronized plus the maximum number of microseconds |
05e68ce7 BS |
177 | the timestamp might be off. The time quality is also automatically |
178 | suppressed when \fB\-\-sd\-id timeQuality\fR is specified. | |
4299ed1c | 179 | |
05e68ce7 BS |
180 | The \fBnotime\fR value (which implies \fBnotq\fR) |
181 | suppresses the complete sender timestamp that is in | |
a54b8e24 | 182 | ISO-8601 format, including microseconds and timezone. |
4299ed1c | 183 | |
a54b8e24 BS |
184 | The \fBnohost\fR value suppresses |
185 | .BR gethostname (2) | |
186 | information from the message header. | |
d9b38f6b | 187 | .IP |
981997dd | 188 | The RFC 5424 protocol has been the default for |
d9b38f6b SK |
189 | .B logger |
190 | since version 2.26. | |
98920f80 | 191 | .TP |
da6bb5f8 BS |
192 | .BR \-s , " \-\-stderr" |
193 | Output the message to standard error as well as to the system log. | |
194 | .TP | |
05e68ce7 BS |
195 | .BR "\-\-sd\-id \fIname" [ @\fIdigits ] |
196 | Specifies a structured data element ID for an RFC 5424 message header. The | |
197 | option has to be used before \fB\-\-sd\-param\fR to introduce a new element. | |
198 | The number of structured data elements is unlimited. The ID (\fIname\fR plus | |
199 | possibly \fB@\fIdigits\fR) is case-sensitive and uniquely identifies the type | |
200 | and purpose of the element. The same ID must not exist more than once in | |
201 | a message. The \fB@\fIdigits\fR part is required for user-defined | |
202 | non-standardized IDs. | |
4299ed1c | 203 | |
05e68ce7 BS |
204 | \fBlogger\fR currently generates the \fBtimeQuality\fR standardized element |
205 | only. RFC 5424 also describes the elements \fBorigin\fR (with parameters | |
206 | ip, enterpriseId, software and swVersion) and \fBmeta\fR (with parameters | |
207 | sequenceId, sysUpTime and language). | |
208 | These element IDs may be specified without the \fB@\fIdigits\fR suffix. | |
4299ed1c KZ |
209 | |
210 | .TP | |
05e68ce7 | 211 | .BR "\-\-sd\-param " \fIname ="\fIvalue\fB" |
d35df4db | 212 | Specifies a structured data element parameter, a name and value pair. |
05e68ce7 BS |
213 | The option has to be used after \fB\-\-sd\-id\fR and may be specified more |
214 | than once for the same element. Note that the quotation marks around | |
215 | \fIvalue\fR are required and must be escaped on the command line. | |
4299ed1c KZ |
216 | .IP |
217 | .nf | |
99045219 KZ |
218 | \fB logger \-\-rfc5424 \-\-sd-id zoo@123 \\ |
219 | \fB \-\-sd-param tiger=\\"hungry\\" \\ | |
220 | \fB \-\-sd-param zebra=\\"running\\" \\ | |
221 | \fB \-\-sd-id manager@123 \\ | |
222 | \fB \-\-sd-param onMeeting=\\"yes\\" \\ | |
4299ed1c KZ |
223 | \fB "this is message" |
224 | .fi | |
225 | .IP | |
226 | produces: | |
227 | .IP | |
228 | .nf | |
229 | \fB <13>1 2015-10-01T14:07:59.168662+02:00 ws kzak - - [timeQuality tzKnown="1" isSynced="1" syncAccuracy="218616"][zoo@123 tiger="hungry" zebra="running"][manager@123 onMeeting="yes"] this is message | |
230 | .fi | |
231 | .IP | |
232 | .TP | |
1f658393 | 233 | .BR \-S , " -\-size " \fIsize |
da6bb5f8 BS |
234 | Sets the maximum permitted message size to \fIsize\fR. The default |
235 | is 1KiB characters, which is the limit traditionally used and specified | |
236 | in RFC 3164. With RFC 5424, this limit has become flexible. A good assumption | |
237 | is that RFC 5424 receivers can at least process 4KiB messages. | |
238 | ||
239 | Most receivers accept messages larger than 1KiB over any type of syslog | |
240 | protocol. As such, the \fB\-\-size\fR option affects logger in | |
241 | all cases (not only when \fB\-\-rfc5424\fR was used). | |
242 | ||
243 | Note: the message-size limit limits the overall message size, including | |
244 | the syslog header. Header sizes vary depending on the selected options and | |
245 | the hostname length. As a rule of thumb, headers are usually not longer than | |
246 | 50 to 80 characters. When selecting a maximum message size, it is important | |
247 | to ensure that the receiver supports the max size as well, otherwise messages | |
248 | may become truncated. Again, as a rule of thumb two to four KiB message size | |
249 | should generally be OK, whereas anything larger should be verified to work. | |
250 | ||
f8bc8ce4 | 251 | .TP |
d77dc29e SK |
252 | .BR \-\-socket\-errors [ =\fImode ] |
253 | Print errors about Unix socket connections. The \fImode\fR can be a value of | |
254 | \fBoff\fR, \fBon\fR, or \fBauto\fR. When the mode is auto logger will detect | |
255 | if the init process is systemd, and if so assumption is made /dev/log can be | |
256 | used early at boot. Other init systems lack of /dev/log will not cause errors | |
257 | that is identical with messaging using | |
258 | .BR openlog (3) | |
259 | system call. The | |
260 | .BR logger (1) | |
d35df4db | 261 | before version 2.26 used openlog, and hence was unable to detected loss of |
d77dc29e SK |
262 | messages sent to Unix sockets. |
263 | .IP | |
264 | The default mode is \fBauto\fR. When errors are not enabled lost messages are | |
265 | not communicated and will result to successful return value of | |
266 | .BR logger (1) | |
267 | invocation. | |
268 | .TP | |
da6bb5f8 BS |
269 | .BR \-T , " \-\-tcp" |
270 | Use stream (TCP) only. By default the connection is tried to the | |
271 | .I syslog-conn | |
272 | port defined in /etc/services, which is often | |
273 | .IR 601 . | |
bd0029f6 KZ |
274 | .sp |
275 | See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect. | |
da6bb5f8 BS |
276 | .TP |
277 | .BR \-t , " \-\-tag " \fItag | |
278 | Mark every line to be logged with the specified | |
279 | .IR tag . | |
28b6c76f KZ |
280 | The default tag is the name of the user logged in on the terminal (or a user |
281 | name based on effective user ID). | |
da6bb5f8 BS |
282 | .TP |
283 | .BR \-u , " \-\-socket " \fIsocket | |
284 | Write to the specified | |
285 | .I socket | |
286 | instead of to the system log socket. | |
287 | .TP | |
a54b8e24 BS |
288 | .B \-\- |
289 | End the argument list. This allows the \fImessage\fR | |
290 | to start with a hyphen (\-). | |
4b670c01 | 291 | .TP |
a54b8e24 | 292 | .BR \-V , " \-\-version" |
db3f9026 | 293 | Display version information and exit. |
c047c42d | 294 | .TP |
a54b8e24 BS |
295 | .BR \-h , " \-\-help" |
296 | Display help text and exit. | |
4c3ac8fe | 297 | .SH RETURN VALUE |
6dbe3af9 | 298 | The |
c047c42d | 299 | .B logger |
6dbe3af9 | 300 | utility exits 0 on success, and >0 if an error occurs. |
4c3ac8fe | 301 | .SH FACILITIES AND LEVELS |
c047c42d | 302 | Valid facility names are: |
4c3ac8fe | 303 | .IP |
62aa3f0e | 304 | .nr WI \n(.lu-\n(.iu-\w'\fBauthpriv\fR'u-3n |
4c3ac8fe SK |
305 | .TS |
306 | tab(:); | |
62aa3f0e | 307 | l lw(\n(WIu). |
a54b8e24 BS |
308 | \fBauth |
309 | \fBauthpriv\fR:for security information of a sensitive nature | |
310 | \fBcron | |
311 | \fBdaemon | |
312 | \fBftp | |
62aa3f0e BIG |
313 | \fBkern\fR:T{ |
314 | cannot be generated from userspace process, automatically converted to \fBuser | |
315 | T} | |
a54b8e24 BS |
316 | \fBlpr |
317 | \fBmail | |
318 | \fBnews | |
319 | \fBsyslog | |
320 | \fBuser | |
321 | \fBuucp | |
322 | \fBlocal0 | |
4c3ac8fe | 323 | to: |
a54b8e24 BS |
324 | \fBlocal7 |
325 | \fBsecurity\fR:deprecated synonym for \fBauth | |
4c3ac8fe | 326 | .TE |
c047c42d | 327 | .PP |
db3f9026 | 328 | Valid level names are: |
4c3ac8fe SK |
329 | .IP |
330 | .TS | |
331 | tab(:); | |
934a6fa8 | 332 | l l. |
a54b8e24 BS |
333 | \fBemerg |
334 | \fBalert | |
335 | \fBcrit | |
336 | \fBerr | |
337 | \fBwarning | |
338 | \fBnotice | |
339 | \fBinfo | |
340 | \fBdebug | |
341 | \fBpanic\fR:deprecated synonym for \fBemerg | |
342 | \fBerror\fR:deprecated synonym for \fBerr | |
343 | \fBwarn\fR:deprecated synonym for \fBwarning | |
4c3ac8fe SK |
344 | .TE |
345 | .PP | |
346 | For the priority order and intended purposes of these facilities and levels, see | |
c047c42d SK |
347 | .BR syslog (3). |
348 | .SH EXAMPLES | |
a54b8e24 | 349 | .B logger System rebooted |
c047c42d | 350 | .br |
a54b8e24 | 351 | .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc |
c047c42d | 352 | .br |
a54b8e24 | 353 | .B logger \-n loghost.example.com System rebooted |
c047c42d | 354 | .SH SEE ALSO |
4b670c01 | 355 | .BR journalctl (1), |
f053ff1e | 356 | .BR syslog (3), |
4b670c01 | 357 | .BR systemd.journal-fields (7) |
c047c42d | 358 | .SH STANDARDS |
6dbe3af9 | 359 | The |
c047c42d SK |
360 | .B logger |
361 | command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible. | |
8fd512e9 KZ |
362 | .SH AUTHORS |
363 | The | |
364 | .B logger | |
365 | command | |
366 | was originally written by University of California in 1983-1993 and later | |
367 | rewritten by | |
368 | .MT kzak@redhat.com | |
369 | Karel Zak | |
370 | .ME , | |
371 | .MT rgerhards@adiscon.com | |
372 | Rainer Gerhards | |
373 | .ME | |
374 | and | |
375 | .MT kerolasa@iki.fi | |
376 | Sami Kerola | |
377 | .ME . | |
c047c42d | 378 | .SH AVAILABILITY |
601d12fb | 379 | The logger command is part of the util-linux package and is available from |
d673b74e | 380 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
c047c42d SK |
381 | Linux Kernel Archive |
382 | .UE . |