diff options
Diffstat (limited to '')
| -rw-r--r-- | misc-utils/logger.1 | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/misc-utils/logger.1 b/misc-utils/logger.1 new file mode 100644 index 0000000..448311d --- /dev/null +++ b/misc-utils/logger.1 @@ -0,0 +1,383 @@ +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)logger.1 8.1 (Berkeley) 6/6/93 +.\" +.TH LOGGER "1" "November 2015" "util-linux" "User Commands" +.SH NAME +logger \- enter messages into the system log +.SH SYNOPSIS +.B logger +[options] +.RI [ message ] +.SH DESCRIPTION +.B logger +makes entries in the system log. +.sp +When the optional \fImessage\fR argument is present, it is written +to the log. If it is not present, and the \fB\-f\fR option is not +given either, then standard input is logged. +.SH OPTIONS +.TP +.BR \-d , " \-\-udp" +Use datagrams (UDP) only. By default the connection is tried to the +syslog port defined in /etc/services, which is often 514 . +.sp +See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect. +.TP +.BR \-e , " \-\-skip-empty" +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 \fB\-\-prio\-prefix\fR 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., \fB<13>\fR). +.TP +.BR \-f , " \-\-file " \fIfile +Log the contents of the specified \fIfile\fR. +This option cannot be combined with a command-line message. +.TP +.B \-i +Log the PID of the logger process with each line. +.TP +.BR "\-\-id" [ =\fIid ] +Log the PID of the logger process with each line. When the optional +argument \fIid\fR is specified, then it is used instead of the logger +command's PID. The use of \fB\-\-id=$$\fR +(PPID) is recommended in scripts that send several messages. + +Note that the system logging infrastructure (for example \fBsystemd\fR when +listening on /dev/log) may follow local socket credentials to overwrite the +PID specified in the message. +.BR logger (1) +is able to set those socket credentials to the given \fIid\fR, 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. +.TP +.BR \-\-journald [ =\fIfile ] +Write a systemd journal entry. The entry is read from the given \fIfile\fR, +when specified, otherwise from standard input. +Each line must begin with a field that is accepted by journald; see +.BR 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: +.IP +.nf +\fB logger \-\-journald <<end +\fB MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309 +\fB MESSAGE=The dogs bark, but the caravan goes on. +\fB DOGS=bark +\fB CARAVAN=goes on +\fB end +.IP +\fB logger \-\-journald=entry.txt +.fi +.IP +Notice that +.B \-\-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 +.B journalctl +will display MESSAGE field. Use +.B journalctl \-\-output json-pretty +to see rest of the fields. +.sp +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. +.TP +.BI \-\-msgid " msgid" +Sets the RFC5424 MSGID field. Note that the space character is not permitted +inside of \fImsgid\fR. This option is only used if \fB\-\-rfc5424\fR is +specified as well; otherwise, it is silently ignored. +.TP +.BR \-n , " \-\-server " \fIserver +Write to the specified remote syslog \fIserver\fR +instead of to the system log socket. Unless +\fB\-\-udp\fR or \fB\-\-tcp\fR +is specified, \fBlogger\fR will first try to use UDP, +but if this fails a TCP connection is attempted. +.TP +.B \-\-no\-act +Causes everything to be done except for writing the log message to the system +log, and removing the connection or the journal. This option can be used +together with \fB\-\-stderr\fR for testing purposes. +.TP +.B \-\-octet\-count +Use the 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. +.TP +.BR \-P , " \-\-port " \fIport +Use the specified \fIport\fR. When this option is not specified, the +port defaults to syslog for udp and to syslog-conn for tcp connections. +.TP +.BR \-p , " \-\-priority " \fIpriority +Enter the message into the log with the specified \fIpriority\fR. +The priority may be specified numerically or as a +.IR facility . level +pair. +For example, \fB\-p local3.info\fR +logs the message as informational in the local3 facility. +The default is \fBuser.notice\fR. +.TP +.B \-\-prio\-prefix +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, \fBlocal0.info\fR, +meaning facility=16 and level=6, becomes \fB<134>\fR. +.sp +If the prefix contains no facility, the facility defaults to what is +specified by the \fB\-p\fR option. Similarly, if no prefix is provided, +the line is logged using the \fIpriority\fR given with \fB\-p\fR. +.sp +This option doesn't affect a command-line message. +.TP +.B \-\-rfc3164 +Use the RFC 3164 BSD syslog protocol to submit messages to a remote server. +.TP +.BR \-\-rfc5424 [ =\fIwithout ] +Use the RFC 5424 syslog protocol to submit messages to a remote server. +The optional \fIwithout\fR argument can be a comma-separated list of +the following values: \fBnotq\fR, \fBnotime\fR, \fBnohost\fR. + +The \fBnotq\fR 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 \fB\-\-sd\-id timeQuality\fR is specified. + +The \fBnotime\fR value (which implies \fBnotq\fR) +suppresses the complete sender timestamp that is in +ISO-8601 format, including microseconds and timezone. + +The \fBnohost\fR value suppresses +.BR gethostname (2) +information from the message header. +.IP +The RFC 5424 protocol has been the default for +.B logger +since version 2.26. +.TP +.BR \-s , " \-\-stderr" +Output the message to standard error as well as to the system log. +.TP +.BR "\-\-sd\-id \fIname" [ @\fIdigits ] +Specifies a structured data element ID for an RFC 5424 message header. The +option has to be used before \fB\-\-sd\-param\fR to introduce a new element. +The number of structured data elements is unlimited. The ID (\fIname\fR plus +possibly \fB@\fIdigits\fR) 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 \fB@\fIdigits\fR part is required for user-defined +non-standardized IDs. + +\fBlogger\fR currently generates the \fBtimeQuality\fR standardized element +only. RFC 5424 also describes the elements \fBorigin\fR (with parameters +ip, enterpriseId, software and swVersion) and \fBmeta\fR (with parameters +sequenceId, sysUpTime and language). +These element IDs may be specified without the \fB@\fIdigits\fR suffix. + +.TP +.BR "\-\-sd\-param " \fIname ="\fIvalue\fB" +Specifies a structured data element parameter, a name and value pair. +The option has to be used after \fB\-\-sd\-id\fR and may be specified more +than once for the same element. Note that the quotation marks around +\fIvalue\fR are required and must be escaped on the command line. +.IP +.nf +\fB logger \-\-rfc5424 \-\-sd-id zoo@123 \\ +\fB \-\-sd-param tiger=\\"hungry\\" \\ +\fB \-\-sd-param zebra=\\"running\\" \\ +\fB \-\-sd-id manager@123 \\ +\fB \-\-sd-param onMeeting=\\"yes\\" \\ +\fB "this is message" +.fi +.IP +produces: +.IP +.\".nf +.\" this long line gets cut of in the output of "troff", and wraps +.\" in "nroff" +\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 +.\".fi +.TP +.BR \-S , " \-\-size " \fIsize +Sets the maximum permitted message size to \fIsize\fR. 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. + +Most receivers accept messages larger than 1KiB over any type of syslog +protocol. As such, the \fB\-\-size\fR option affects logger in +all cases (not only when \fB\-\-rfc5424\fR was used). + +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. + +.TP +.BR \-\-socket\-errors [ =\fImode ] +Print errors about Unix socket connections. The \fImode\fR can be a value of +\fBoff\fR, \fBon\fR, or \fBauto\fR. When the mode is auto logger will detect +if the init process is systemd, 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 +.BR openlog (3) +system call. The +.BR logger (1) +before version 2.26 used openlog, and hence was unable to detected loss of +messages sent to Unix sockets. +.IP +The default mode is \fBauto\fR. When errors are not enabled lost messages are +not communicated and will result to successful exit status of +.BR logger (1) +invocation. +.TP +.BR \-T , " \-\-tcp" +Use stream (TCP) only. By default the connection is tried to the +.I syslog-conn +port defined in /etc/services, which is often +.IR 601 . +.sp +See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect. +.TP +.BR \-t , " \-\-tag " \fItag +Mark every line to be logged with the specified +.IR tag . +The default tag is the name of the user logged in on the terminal (or a user +name based on effective user ID). +.TP +.BR \-u , " \-\-socket " \fIsocket +Write to the specified +.I socket +instead of to the system log socket. +.TP +.B \-\- +End the argument list. This allows the \fImessage\fR +to start with a hyphen (\-). +.TP +.BR \-V , " \-\-version" +Display version information and exit. +.TP +.BR \-h , " \-\-help" +Display help text and exit. +.SH EXIT STATUS +The +.B logger +utility exits 0 on success, and >0 if an error occurs. +.SH FACILITIES AND LEVELS +Valid facility names are: +.IP +.nr WI \n(.lu-\n(.iu-\w'\fBauthpriv\fR'u-3n +.TS +tab(:); +l lw(\n(WIu). +\fBauth +\fBauthpriv\fR:for security information of a sensitive nature +\fBcron +\fBdaemon +\fBftp +\fBkern\fR:T{ +cannot be generated from userspace process, automatically converted to \fBuser +T} +\fBlpr +\fBmail +\fBnews +\fBsyslog +\fBuser +\fBuucp +\fBlocal0 + to: +\fBlocal7 +\fBsecurity\fR:deprecated synonym for \fBauth +.TE +.PP +Valid level names are: +.IP +.TS +tab(:); +l l. +\fBemerg +\fBalert +\fBcrit +\fBerr +\fBwarning +\fBnotice +\fBinfo +\fBdebug +\fBpanic\fR:deprecated synonym for \fBemerg +\fBerror\fR:deprecated synonym for \fBerr +\fBwarn\fR:deprecated synonym for \fBwarning +.TE +.PP +For the priority order and intended purposes of these facilities and levels, see +.BR syslog (3). +.SH CONFORMING TO +The +.B logger +command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible. +.SH EXAMPLES +.B logger System rebooted +.br +.B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc +.br +.B logger \-n loghost.example.com System rebooted +.SH AUTHORS +The +.B logger +command +was originally written by University of California in 1983-1993 and later +rewritten by +.MT kzak@redhat.com +Karel Zak +.ME , +.MT rgerhards@adiscon.com +Rainer Gerhards +.ME +and +.MT kerolasa@iki.fi +Sami Kerola +.ME . +.SH SEE ALSO +.BR journalctl (1), +.BR syslog (3), +.BR systemd.journal-fields (7) +.SH AVAILABILITY +The logger command is part of the util-linux package and is available from +.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . |