]>
Commit | Line | Data |
---|---|---|
295b3979 | 1 | //po4a: entry man manual |
6c64d12d MB |
2 | //// |
3 | Copyright (c) 1983, 1990, 1993 | |
4 | The Regents of the University of California. All rights reserved. | |
5 | ||
6 | Redistribution and use in source and binary forms, with or without | |
7 | modification, are permitted provided that the following conditions | |
8 | are met: | |
9 | 1. Redistributions of source code must retain the above copyright | |
10 | notice, this list of conditions and the following disclaimer. | |
11 | 2. Redistributions in binary form must reproduce the above copyright | |
12 | notice, this list of conditions and the following disclaimer in the | |
13 | documentation and/or other materials provided with the distribution. | |
14 | 3. All advertising materials mentioning features or use of this software | |
15 | must display the following acknowledgement: | |
16 | This product includes software developed by the University of | |
17 | California, Berkeley and its contributors. | |
18 | 4. Neither the name of the University nor the names of its contributors | |
19 | may be used to endorse or promote products derived from this software | |
20 | without specific prior written permission. | |
21 | ||
22 | THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | SUCH DAMAGE. | |
33 | ||
34 | @(#)logger.1 8.1 (Berkeley) 6/6/93 | |
35 | //// | |
36 | = logger(1) | |
37 | :doctype: manpage | |
38 | :man manual: User Commands | |
39 | :man source: util-linux {release-version} | |
40 | :page-layout: base | |
41 | :command: logger | |
42 | ||
43 | == NAME | |
44 | ||
45 | logger - enter messages into the system log | |
46 | ||
47 | == SYNOPSIS | |
48 | ||
49 | *logger* [options] _message_ | |
50 | ||
51 | == DESCRIPTION | |
52 | ||
53 | *logger* makes entries in the system log. | |
54 | ||
55 | When the optional _message_ argument is present, it is written to the log. If it is not present, and the *-f* option is not given either, then standard input is logged. | |
56 | ||
57 | == OPTIONS | |
58 | ||
59 | *-d*, *--udp*:: | |
2c646c80 MB |
60 | Use datagrams (UDP) only. By default the connection is tried to the syslog port defined in _/etc/services_, which is often 514. |
61 | + | |
62 | See also *--server* and *--socket* to specify where to connect. | |
6c64d12d MB |
63 | |
64 | *-e*, *--skip-empty*:: | |
2c646c80 | 65 | Ignore empty lines when processing files. An empty line is defined to be a line without any characters. Thus a line consisting only of whitespace is NOT considered empty. Note that when the *--prio-prefix* option is specified, the priority is not part of the line. Thus an empty line in this mode is a line that does not have any characters after the priority prefix (e.g., *<13>*). |
6c64d12d MB |
66 | |
67 | *-f*, *--file* _file_:: | |
2c646c80 | 68 | Log the contents of the specified _file_. This option cannot be combined with a command-line message. |
6c64d12d MB |
69 | |
70 | *-i*:: | |
360946bb | 71 | Log the PID of the *logger* process with each line. |
6c64d12d MB |
72 | |
73 | *--id*[**=**__id__]:: | |
360946bb | 74 | Log the PID of the *logger* process with each line. When the optional argument _id_ is specified, then it is used instead of the *logger* command's PID. The use of *--id=$$* (PPID) is recommended in scripts that send several messages. |
2c646c80 MB |
75 | + |
76 | Note that the system logging infrastructure (for example *systemd* when listening on _/dev/log_) may follow local socket credentials to overwrite the PID specified in the message. *logger*(1) is able to set those socket credentials to the given _id_, but only if you have root permissions and a process with the specified PID exists, otherwise the socket credentials are not modified and the problem is silently ignored. | |
6c64d12d MB |
77 | |
78 | *--journald*[**=**__file__]:: | |
bd67ca44 | 79 | Write a *systemd* journal entry. The entry is read from the given _file_, when specified, otherwise from standard input. Each line must begin with a field that is accepted by *journald*; see *systemd.journal-fields*(7) for details. The use of a MESSAGE_ID field is generally a good idea, as it makes finding entries easy. Examples: |
a8e071fa | 80 | + |
6c64d12d MB |
81 | ____ |
82 | logger --journald <<end | |
83 | MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309 | |
84 | MESSAGE=The dogs bark, but the caravan goes on. | |
85 | DOGS=bark | |
86 | CARAVAN=goes on | |
87 | end | |
88 | ||
89 | logger --journald=entry.txt | |
90 | ____ | |
a8e071fa | 91 | + |
2c646c80 MB |
92 | Notice that *--journald* will ignore values of other options, such as priority. If priority is needed it must be within input, and use PRIORITY field. The simple execution of *journalctl*(1) will display MESSAGE field. Use *journalctl --output json-pretty* to see rest of the fields. |
93 | + | |
6c64d12d MB |
94 | To include newlines in MESSAGE, specify MESSAGE several times. This is handled as a special case, other fields will be stored as an array in the journal if they appear multiple times. |
95 | ||
96 | *--msgid* _msgid_:: | |
2c646c80 | 97 | Sets the link:https://tools.ietf.org/html/rfc5424[RFC 5424] MSGID field. Note that the space character is not permitted inside of _msgid_. This option is only used if *--rfc5424* is specified as well; otherwise, it is silently ignored. |
6c64d12d MB |
98 | |
99 | *-n*, *--server* _server_:: | |
2c646c80 | 100 | Write to the specified remote syslog _server_ instead of to the system log socket. Unless *--udp* or *--tcp* is specified, *logger* will first try to use UDP, but if this fails a TCP connection is attempted. |
6c64d12d MB |
101 | |
102 | *--no-act*:: | |
bd67ca44 | 103 | Causes everything to be done except for writing the log message to the system log, and removing the connection to the journal. This option can be used together with *--stderr* for testing purposes. |
6c64d12d MB |
104 | |
105 | *--octet-count*:: | |
2c646c80 | 106 | Use the link:https://tools.ietf.org/html/rfc6587[RFC 6587] octet counting framing method for sending messages. When this option is not used, the default is no framing on UDP, and RFC6587 non-transparent framing (also known as octet stuffing) on TCP. |
6c64d12d MB |
107 | |
108 | *-P*, *--port* _port_:: | |
bd67ca44 | 109 | Use the specified _port_. When this option is not specified, the port defaults to *syslog* for udp and to *syslog-conn* for tcp connections. |
6c64d12d MB |
110 | |
111 | *-p*, *--priority* _priority_:: | |
2c646c80 | 112 | Enter the message into the log with the specified _priority_. The priority may be specified numerically or as a _facility_._level_ pair. For example, *-p local3.info* logs the message as informational in the local3 facility. The default is *user.notice*. |
6c64d12d MB |
113 | |
114 | *--prio-prefix*:: | |
2c646c80 MB |
115 | Look for a syslog prefix on every line read from standard input. This prefix is a decimal number within angle brackets that encodes both the facility and the level. The number is constructed by multiplying the facility by 8 and then adding the level. For example, *local0.info*, meaning facility=16 and level=6, becomes *<134>*. |
116 | + | |
117 | If the prefix contains no facility, the facility defaults to what is specified by the *-p* option. Similarly, if no prefix is provided, the line is logged using the _priority_ given with *-p*. | |
118 | + | |
119 | This option doesn't affect a command-line message. | |
6c64d12d MB |
120 | |
121 | *--rfc3164*:: | |
2c646c80 | 122 | Use the link:https://tools.ietf.org/html/rfc3164[RFC 3164] BSD syslog protocol to submit messages to a remote server. |
6c64d12d MB |
123 | |
124 | *--rfc5424*[**=**__without__]:: | |
2c646c80 MB |
125 | Use the link:https://tools.ietf.org/html/rfc5424[RFC 5424] syslog protocol to submit messages to a remote server. The optional _without_ argument can be a comma-separated list of the following values: *notq*, *notime*, *nohost*. |
126 | + | |
127 | The *notq* value suppresses the time-quality structured data from the submitted message. The time-quality information shows whether the local clock was synchronized plus the maximum number of microseconds the timestamp might be off. The time quality is also automatically suppressed when *--sd-id timeQuality* is specified. | |
128 | + | |
129 | The *notime* value (which implies *notq*) suppresses the complete sender timestamp that is in ISO-8601 format, including microseconds and timezone. | |
130 | + | |
131 | The *nohost* value suppresses *gethostname*(2) information from the message header. | |
132 | + | |
133 | The RFC 5424 protocol has been the default for *logger* since version 2.26. | |
6c64d12d MB |
134 | |
135 | *-s*, *--stderr*:: | |
2c646c80 | 136 | Output the message to standard error as well as to the system log. |
6c64d12d MB |
137 | |
138 | *--sd-id* _name_[**@**__digits__]:: | |
2c646c80 MB |
139 | Specifies a structured data element ID for an RFC 5424 message header. The option has to be used before *--sd-param* to introduce a new element. The number of structured data elements is unlimited. The ID (_name_ plus possibly **@**__digits__) is case-sensitive and uniquely identifies the type and purpose of the element. The same ID must not exist more than once in a message. The **@**__digits__ part is required for user-defined non-standardized IDs. |
140 | + | |
bd67ca44 | 141 | *logger* currently generates the *timeQuality* standardized element only. RFC 5424 also describes the elements *origin* (with parameters *ip*, *enterpriseId*, *software* and *swVersion*) and *meta* (with parameters *sequenceId*, *sysUpTime* and *language*). These element IDs may be specified without the **@**__digits__ suffix. |
6c64d12d MB |
142 | |
143 | *--sd-param* _name_=_value_:: | |
360946bb MB |
144 | Specifies a structured data element parameter, a name and value pair. The option has to be used after *--sd-id* and may be specified more than once for the same element. Note that the quotation marks around _value_ are required and must be escaped on the command line. |
145 | + | |
6c64d12d | 146 | .... |
e08e3d58 | 147 | logger --rfc5424 --sd-id zoo@123 \ |
6c64d12d MB |
148 | --sd-param tiger="hungry" \ |
149 | --sd-param zebra="running" \ | |
e08e3d58 CH |
150 | --sd-id manager@123 \ |
151 | --sd-param onMeeting="yes" \ | |
6c64d12d MB |
152 | "this is message" |
153 | .... | |
360946bb MB |
154 | produces: |
155 | + | |
6c64d12d MB |
156 | *<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* |
157 | ||
158 | *-S*, *--size* _size_:: | |
2c646c80 MB |
159 | Sets the maximum permitted message size to _size_. The default is 1KiB characters, which is the limit traditionally used and specified in RFC 3164. With RFC 5424, this limit has become flexible. A good assumption is that RFC 5424 receivers can at least process 4KiB messages. |
160 | + | |
360946bb | 161 | Most receivers accept messages larger than 1KiB over any type of syslog protocol. As such, the *--size* option affects *logger* in all cases (not only when *--rfc5424* was used). |
2c646c80 MB |
162 | + |
163 | Note: the message-size limit limits the overall message size, including the syslog header. Header sizes vary depending on the selected options and the hostname length. As a rule of thumb, headers are usually not longer than 50 to 80 characters. When selecting a maximum message size, it is important to ensure that the receiver supports the max size as well, otherwise messages may become truncated. Again, as a rule of thumb two to four KiB message size should generally be OK, whereas anything larger should be verified to work. | |
6c64d12d MB |
164 | |
165 | *--socket-errors*[**=**__mode__]:: | |
bd67ca44 | 166 | Print errors about Unix socket connections. The _mode_ can be a value of *off*, *on*, or *auto*. When the mode is *auto*, then *logger* will detect if the init process is *systemd*(1), and if so assumption is made _/dev/log_ can be used early at boot. Other init systems lack of _/dev/log_ will not cause errors that is identical with messaging using *openlog*(3) system call. The *logger*(1) before version 2.26 used *openlog*(3), and hence was unable to detected loss of messages sent to Unix sockets. |
2c646c80 MB |
167 | + |
168 | The default mode is *auto*. When errors are not enabled lost messages are not communicated and will result to successful exit status of *logger*(1) invocation. | |
6c64d12d MB |
169 | |
170 | *-T*, *--tcp*:: | |
2c646c80 MB |
171 | Use stream (TCP) only. By default the connection is tried to the _syslog-conn_ port defined in _/etc/services_, which is often _601_. |
172 | + | |
173 | See also *--server* and *--socket* to specify where to connect. | |
6c64d12d MB |
174 | |
175 | *-t*, *--tag* _tag_:: | |
2c646c80 | 176 | Mark every line to be logged with the specified _tag_. The default tag is the name of the user logged in on the terminal (or a user name based on effective user ID). |
6c64d12d MB |
177 | |
178 | *-u*, *--socket* _socket_:: | |
2c646c80 | 179 | Write to the specified _socket_ instead of to the system log socket. |
6c64d12d MB |
180 | |
181 | *--*:: | |
2c646c80 | 182 | End the argument list. This allows the _message_ to start with a hyphen (-). |
6c64d12d | 183 | |
2b2d3172 | 184 | include::man-common/help-version.adoc[] |
6c64d12d MB |
185 | |
186 | == EXIT STATUS | |
187 | ||
188 | The *logger* utility exits 0 on success, and >0 if an error occurs. | |
189 | ||
190 | == FACILITIES AND LEVELS | |
191 | ||
192 | Valid facility names are: | |
193 | ||
194 | *auth* + | |
195 | *authpriv* for security information of a sensitive nature + | |
196 | *cron* + | |
197 | ||
198 | *daemon* + | |
199 | *ftp* + | |
200 | *kern* cannot be generated from userspace process, automatically converted to *user* + | |
201 | ||
202 | *lpr* + | |
e08e3d58 | 203 | *mail* + |
6c64d12d MB |
204 | *news* + |
205 | *syslog* + | |
206 | *user* + | |
207 | *uucp* + | |
208 | *local0* + | |
209 | to + | |
e08e3d58 | 210 | *local7* + |
6c64d12d MB |
211 | *security* deprecated synonym for *auth* |
212 | ||
213 | Valid level names are: | |
214 | ||
215 | *emerg* + | |
216 | *alert* + | |
217 | *crit* + | |
218 | *err* + | |
219 | *warning* + | |
220 | *notice* + | |
221 | *info* + | |
222 | *debug* + | |
223 | *panic* deprecated synonym for *emerg* + | |
224 | *error* deprecated synonym for *err* + | |
225 | *warn* deprecated synonym for *warning* + | |
226 | ||
227 | For the priority order and intended purposes of these facilities and levels, see *syslog*(3). | |
228 | ||
229 | == CONFORMING TO | |
230 | ||
231 | The *logger* command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible. | |
232 | ||
233 | == EXAMPLES | |
a8e071fa KZ |
234 | ____ |
235 | logger System rebooted | |
236 | ||
237 | logger -p local0.notice -t HOSTIDM -f /dev/idmc | |
6c64d12d | 238 | |
a8e071fa KZ |
239 | logger -n loghost.example.com System rebooted |
240 | ____ | |
6c64d12d MB |
241 | |
242 | == AUTHORS | |
243 | ||
244 | The *logger* command was originally written by University of California in 1983-1993 and later rewritten by mailto:kzak@redhat.com[Karel Zak], mailto:rgerhards@adiscon.com[Rainer Gerhards], and mailto:kerolasa@iki.fi[Sami Kerola]. | |
245 | ||
246 | == SEE ALSO | |
247 | ||
248 | *journalctl*(1), | |
249 | *syslog*(3), | |
250 | *systemd.journal-fields*(7) | |
251 | ||
625e9c61 | 252 | include::man-common/bugreports.adoc[] |
6c64d12d | 253 | |
625e9c61 | 254 | include::man-common/footer.adoc[] |
6c64d12d MB |
255 | |
256 | ifdef::translation[] | |
625e9c61 | 257 | include::man-common/translation.adoc[] |
6c64d12d | 258 | endif::[] |