]>
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 . | |
f8bc8ce4 | 53 | .TP |
ae6846b8 | 54 | .BR \-e , " \-\-skip-empty" |
05e68ce7 BS |
55 | Ignore empty lines when processing files. An empty line |
56 | is defined to be a line without any characters. Thus a line consisting | |
ae6846b8 | 57 | only of whitespace is NOT considered empty. |
05e68ce7 BS |
58 | Note that when the \fB\-\-prio\-prefix\fR option is specified, the priority |
59 | is not part of the line. Thus an empty line in this mode is a line that does | |
60 | not have any characters after the priority prefix (e.g. \fB<13>\fR). | |
ae6846b8 | 61 | .TP |
a54b8e24 BS |
62 | .BR \-f , " \-\-file " \fIfile |
63 | Log the contents of the specified \fIfile\fR. | |
64 | This option cannot be combined with a command-line message. | |
f8bc8ce4 | 65 | .TP |
3f51c10b SK |
66 | .B \-i |
67 | Log the PID of the logger process with each line. | |
68 | .TP | |
69 | .BR "\-\-id" [ =\fIid ] | |
a54b8e24 BS |
70 | Log the PID of the logger process with each line. When the optional |
71 | argument \fIid\fR is specified, then it is used instead of the logger | |
72 | command's PID. The use of \fB\-\-id=$$\fR | |
59c6ac0b | 73 | (PPID) is recommended in scripts that send several messages. |
27a9eb53 | 74 | |
05e68ce7 BS |
75 | Note that the system logging infrastructure (for example \fBsystemd\fR when |
76 | listening on /dev/log) may follow local socket credentials to overwrite the | |
77 | PID specified in the message. | |
5593132a | 78 | .BR logger (1) |
05e68ce7 BS |
79 | is able to set those socket credentials to the given \fIid\fR, but only if you |
80 | have root permissions and a process with the specified PID exists, otherwise | |
27a9eb53 | 81 | the socket credentials are not modified and the problem is silently ignored. |
f8bc8ce4 | 82 | .TP |
a54b8e24 BS |
83 | .BR \-\-journald [ =\fIfile ] |
84 | Write a systemd journal entry. The entry is read from the given \fIfile\fR, | |
85 | when specified, otherwise from standard input. | |
86 | Each line must begin with a field that is accepted by journald; see | |
87 | .BR systemd.journal-fields (7) | |
88 | for details. The use of a MESSAGE_ID field is generally a good idea, as it | |
89 | makes finding entries easy. Examples: | |
90 | .IP | |
91 | .nf | |
99045219 | 92 | \fB logger \-\-journald <<end |
b632f55c MS |
93 | \fB MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309 |
94 | \fB MESSAGE=The dogs bark, but the caravan goes on. | |
95 | \fB DOGS=bark | |
96 | \fB CARAVAN=goes on | |
97 | \fB end | |
98 | .IP | |
99045219 | 99 | \fB logger \-\-journald=entry.txt |
a54b8e24 BS |
100 | .fi |
101 | .IP | |
102 | Notice that | |
103 | .B \-\-journald | |
104 | will ignore values of other options, such as priority. If priority is | |
105 | needed it must be within input, and use PRIORITY field. The simple | |
106 | execution of | |
107 | .B journalctl | |
108 | will display MESSAGE field. Use | |
99045219 | 109 | .B journalctl \-\-output json-pretty |
a54b8e24 | 110 | to see rest of the fields. |
55f5bc66 | 111 | .TP |
05e68ce7 BS |
112 | .BR \-\-msgid " \fImsgid |
113 | Sets the RFC5424 MSGID field. Note that the space character is not permitted | |
114 | inside of \fImsgid\fR. This option is only used if \fB\-\-rfc5424\fR is | |
115 | specified as well; otherwise, it is silently ignored. | |
a54b8e24 BS |
116 | .TP |
117 | .BR \-n , " \-\-server " \fIserver | |
118 | Write to the specified remote syslog \fIserver\fR | |
a4356173 | 119 | instead of to the system log socket. Unless |
a54b8e24 | 120 | \fB\-\-udp\fR or \fB\-\-tcp\fR |
e3a4ee43 | 121 | is specified, \fBlogger\fR will first try to use UDP, |
d35df4db | 122 | but if this fails a TCP connection is attempted. |
68265d07 | 123 | .TP |
0bb7e904 | 124 | .B \-\-no\-act |
da6bb5f8 BS |
125 | Causes everything to be done except for writing the log message to the system |
126 | log, and removing the connection or the journal. This option can be used | |
127 | together with \fB\-\-stderr\fR for testing purposes. | |
128 | .TP | |
129 | .B \-\-octet\-count | |
130 | Use the RFC 6587 octet counting framing method for sending messages. | |
131 | When this option is not used, the default is no framing on UDP, and | |
132 | RFC6587 non-transparent framing (also known as octet stuffing) on TCP. | |
133 | .TP | |
a54b8e24 BS |
134 | .BR \-P , " \-\-port " \fIport |
135 | Use the specified \fIport\fR. When this option is not specified, the | |
136 | port defaults to syslog for udp and to syslog-conn for tcp connections. | |
c047c42d | 137 | .TP |
a54b8e24 BS |
138 | .BR \-p , " \-\-priority " \fIpriority |
139 | Enter the message into the log with the specified \fIpriority\fR. | |
c047c42d | 140 | The priority may be specified numerically or as a |
a54b8e24 | 141 | .IR facility . level |
6dbe3af9 | 142 | pair. |
a54b8e24 | 143 | For example, \fB\-p local3.info\fR |
c047c42d | 144 | logs the message as informational in the local3 facility. |
a54b8e24 | 145 | The default is \fBuser.notice\fR. |
c047c42d | 146 | .TP |
b06c1ca6 | 147 | .B \-\-prio\-prefix |
e3a4ee43 | 148 | Look for a syslog prefix on every line read from standard input. |
a54b8e24 BS |
149 | This prefix is a decimal number within angle brackets that encodes both |
150 | the facility and the level. The number is constructed by multiplying the | |
151 | facility by 8 and then adding the level. For example, \fBlocal0.info\fR, | |
152 | meaning facility=16 and level=6, becomes \fB<134>\fR. | |
153 | .sp | |
98920f80 | 154 | If the prefix contains no facility, the facility defaults to what is |
e3a4ee43 | 155 | specified by the \fB\-p\fR option. Similarly, if no prefix is provided, |
a54b8e24 BS |
156 | the line is logged using the \fIpriority\fR given with \fB\-p\fR. |
157 | .sp | |
98920f80 | 158 | This option doesn't affect a command-line message. |
d9b38f6b | 159 | .TP |
a54b8e24 BS |
160 | .B \-\-rfc3164 |
161 | Use the RFC 3164 BSD syslog protocol to submit messages to a remote server. | |
162 | .TP | |
163 | .BR \-\-rfc5424 [ =\fIwithout ] | |
164 | Use the RFC 5424 syslog protocol to submit messages to a remote server. | |
165 | The optional \fIwithout\fR argument can be a comma-separated list of | |
166 | the following values: \fBnotq\fR, \fBnotime\fR, \fBnohost\fR. | |
4299ed1c | 167 | |
a54b8e24 | 168 | The \fBnotq\fR value suppresses the time-quality structured data |
4299ed1c | 169 | from the submitted message. The time-quality information shows whether |
981997dd | 170 | the local clock was synchronized plus the maximum number of microseconds |
05e68ce7 BS |
171 | the timestamp might be off. The time quality is also automatically |
172 | suppressed when \fB\-\-sd\-id timeQuality\fR is specified. | |
4299ed1c | 173 | |
05e68ce7 BS |
174 | The \fBnotime\fR value (which implies \fBnotq\fR) |
175 | suppresses the complete sender timestamp that is in | |
a54b8e24 | 176 | ISO-8601 format, including microseconds and timezone. |
4299ed1c | 177 | |
a54b8e24 BS |
178 | The \fBnohost\fR value suppresses |
179 | .BR gethostname (2) | |
180 | information from the message header. | |
d9b38f6b | 181 | .IP |
981997dd | 182 | The RFC 5424 protocol has been the default for |
d9b38f6b SK |
183 | .B logger |
184 | since version 2.26. | |
98920f80 | 185 | .TP |
da6bb5f8 BS |
186 | .BR \-s , " \-\-stderr" |
187 | Output the message to standard error as well as to the system log. | |
188 | .TP | |
05e68ce7 BS |
189 | .BR "\-\-sd\-id \fIname" [ @\fIdigits ] |
190 | Specifies a structured data element ID for an RFC 5424 message header. The | |
191 | option has to be used before \fB\-\-sd\-param\fR to introduce a new element. | |
192 | The number of structured data elements is unlimited. The ID (\fIname\fR plus | |
193 | possibly \fB@\fIdigits\fR) is case-sensitive and uniquely identifies the type | |
194 | and purpose of the element. The same ID must not exist more than once in | |
195 | a message. The \fB@\fIdigits\fR part is required for user-defined | |
196 | non-standardized IDs. | |
4299ed1c | 197 | |
05e68ce7 BS |
198 | \fBlogger\fR currently generates the \fBtimeQuality\fR standardized element |
199 | only. RFC 5424 also describes the elements \fBorigin\fR (with parameters | |
200 | ip, enterpriseId, software and swVersion) and \fBmeta\fR (with parameters | |
201 | sequenceId, sysUpTime and language). | |
202 | These element IDs may be specified without the \fB@\fIdigits\fR suffix. | |
4299ed1c KZ |
203 | |
204 | .TP | |
05e68ce7 | 205 | .BR "\-\-sd\-param " \fIname ="\fIvalue\fB" |
d35df4db | 206 | Specifies a structured data element parameter, a name and value pair. |
05e68ce7 BS |
207 | The option has to be used after \fB\-\-sd\-id\fR and may be specified more |
208 | than once for the same element. Note that the quotation marks around | |
209 | \fIvalue\fR are required and must be escaped on the command line. | |
4299ed1c KZ |
210 | .IP |
211 | .nf | |
99045219 KZ |
212 | \fB logger \-\-rfc5424 \-\-sd-id zoo@123 \\ |
213 | \fB \-\-sd-param tiger=\\"hungry\\" \\ | |
214 | \fB \-\-sd-param zebra=\\"running\\" \\ | |
215 | \fB \-\-sd-id manager@123 \\ | |
216 | \fB \-\-sd-param onMeeting=\\"yes\\" \\ | |
4299ed1c KZ |
217 | \fB "this is message" |
218 | .fi | |
219 | .IP | |
220 | produces: | |
221 | .IP | |
222 | .nf | |
223 | \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 | |
224 | .fi | |
225 | .IP | |
226 | .TP | |
1f658393 | 227 | .BR \-S , " -\-size " \fIsize |
da6bb5f8 BS |
228 | Sets the maximum permitted message size to \fIsize\fR. The default |
229 | is 1KiB characters, which is the limit traditionally used and specified | |
230 | in RFC 3164. With RFC 5424, this limit has become flexible. A good assumption | |
231 | is that RFC 5424 receivers can at least process 4KiB messages. | |
232 | ||
233 | Most receivers accept messages larger than 1KiB over any type of syslog | |
234 | protocol. As such, the \fB\-\-size\fR option affects logger in | |
235 | all cases (not only when \fB\-\-rfc5424\fR was used). | |
236 | ||
237 | Note: the message-size limit limits the overall message size, including | |
238 | the syslog header. Header sizes vary depending on the selected options and | |
239 | the hostname length. As a rule of thumb, headers are usually not longer than | |
240 | 50 to 80 characters. When selecting a maximum message size, it is important | |
241 | to ensure that the receiver supports the max size as well, otherwise messages | |
242 | may become truncated. Again, as a rule of thumb two to four KiB message size | |
243 | should generally be OK, whereas anything larger should be verified to work. | |
244 | ||
f8bc8ce4 | 245 | .TP |
d77dc29e SK |
246 | .BR \-\-socket\-errors [ =\fImode ] |
247 | Print errors about Unix socket connections. The \fImode\fR can be a value of | |
248 | \fBoff\fR, \fBon\fR, or \fBauto\fR. When the mode is auto logger will detect | |
249 | if the init process is systemd, and if so assumption is made /dev/log can be | |
250 | used early at boot. Other init systems lack of /dev/log will not cause errors | |
251 | that is identical with messaging using | |
252 | .BR openlog (3) | |
253 | system call. The | |
254 | .BR logger (1) | |
d35df4db | 255 | before version 2.26 used openlog, and hence was unable to detected loss of |
d77dc29e SK |
256 | messages sent to Unix sockets. |
257 | .IP | |
258 | The default mode is \fBauto\fR. When errors are not enabled lost messages are | |
259 | not communicated and will result to successful return value of | |
260 | .BR logger (1) | |
261 | invocation. | |
262 | .TP | |
da6bb5f8 BS |
263 | .BR \-T , " \-\-tcp" |
264 | Use stream (TCP) only. By default the connection is tried to the | |
265 | .I syslog-conn | |
266 | port defined in /etc/services, which is often | |
267 | .IR 601 . | |
268 | .TP | |
269 | .BR \-t , " \-\-tag " \fItag | |
270 | Mark every line to be logged with the specified | |
271 | .IR tag . | |
28b6c76f KZ |
272 | The default tag is the name of the user logged in on the terminal (or a user |
273 | name based on effective user ID). | |
da6bb5f8 BS |
274 | .TP |
275 | .BR \-u , " \-\-socket " \fIsocket | |
276 | Write to the specified | |
277 | .I socket | |
278 | instead of to the system log socket. | |
279 | .TP | |
a54b8e24 BS |
280 | .B \-\- |
281 | End the argument list. This allows the \fImessage\fR | |
282 | to start with a hyphen (\-). | |
4b670c01 | 283 | .TP |
a54b8e24 | 284 | .BR \-V , " \-\-version" |
db3f9026 | 285 | Display version information and exit. |
c047c42d | 286 | .TP |
a54b8e24 BS |
287 | .BR \-h , " \-\-help" |
288 | Display help text and exit. | |
4c3ac8fe | 289 | .SH RETURN VALUE |
6dbe3af9 | 290 | The |
c047c42d | 291 | .B logger |
6dbe3af9 | 292 | utility exits 0 on success, and >0 if an error occurs. |
4c3ac8fe | 293 | .SH FACILITIES AND LEVELS |
c047c42d | 294 | Valid facility names are: |
4c3ac8fe | 295 | .IP |
62aa3f0e | 296 | .nr WI \n(.lu-\n(.iu-\w'\fBauthpriv\fR'u-3n |
4c3ac8fe SK |
297 | .TS |
298 | tab(:); | |
62aa3f0e | 299 | l lw(\n(WIu). |
a54b8e24 BS |
300 | \fBauth |
301 | \fBauthpriv\fR:for security information of a sensitive nature | |
302 | \fBcron | |
303 | \fBdaemon | |
304 | \fBftp | |
62aa3f0e BIG |
305 | \fBkern\fR:T{ |
306 | cannot be generated from userspace process, automatically converted to \fBuser | |
307 | T} | |
a54b8e24 BS |
308 | \fBlpr |
309 | \fBmail | |
310 | \fBnews | |
311 | \fBsyslog | |
312 | \fBuser | |
313 | \fBuucp | |
314 | \fBlocal0 | |
4c3ac8fe | 315 | to: |
a54b8e24 BS |
316 | \fBlocal7 |
317 | \fBsecurity\fR:deprecated synonym for \fBauth | |
4c3ac8fe | 318 | .TE |
c047c42d | 319 | .PP |
db3f9026 | 320 | Valid level names are: |
4c3ac8fe SK |
321 | .IP |
322 | .TS | |
323 | tab(:); | |
934a6fa8 | 324 | l l. |
a54b8e24 BS |
325 | \fBemerg |
326 | \fBalert | |
327 | \fBcrit | |
328 | \fBerr | |
329 | \fBwarning | |
330 | \fBnotice | |
331 | \fBinfo | |
332 | \fBdebug | |
333 | \fBpanic\fR:deprecated synonym for \fBemerg | |
334 | \fBerror\fR:deprecated synonym for \fBerr | |
335 | \fBwarn\fR:deprecated synonym for \fBwarning | |
4c3ac8fe SK |
336 | .TE |
337 | .PP | |
338 | For the priority order and intended purposes of these facilities and levels, see | |
c047c42d SK |
339 | .BR syslog (3). |
340 | .SH EXAMPLES | |
a54b8e24 | 341 | .B logger System rebooted |
c047c42d | 342 | .br |
a54b8e24 | 343 | .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc |
c047c42d | 344 | .br |
a54b8e24 | 345 | .B logger \-n loghost.example.com System rebooted |
c047c42d | 346 | .SH SEE ALSO |
4b670c01 | 347 | .BR journalctl (1), |
f053ff1e | 348 | .BR syslog (3), |
4b670c01 | 349 | .BR systemd.journal-fields (7) |
c047c42d | 350 | .SH STANDARDS |
6dbe3af9 | 351 | The |
c047c42d SK |
352 | .B logger |
353 | command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible. | |
354 | .SH AVAILABILITY | |
601d12fb | 355 | The logger command is part of the util-linux package and is available from |
d673b74e | 356 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
c047c42d SK |
357 | Linux Kernel Archive |
358 | .UE . |