356 lines
13 KiB
Groff
356 lines
13 KiB
Groff
.\" 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 .
|
|
.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.
|
|
.TP
|
|
.BR \-\-msgid " \fImsgid
|
|
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
|
|
.BR \-\-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
|
|
\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
|
|
.IP
|
|
.TP
|
|
.BR \-\-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 return value 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 .
|
|
.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 RETURN VALUE
|
|
The
|
|
.B logger
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
.SH FACILITIES AND LEVELS
|
|
Valid facility names are:
|
|
.IP
|
|
.TS
|
|
tab(:);
|
|
left l l.
|
|
\fBauth
|
|
\fBauthpriv\fR:for security information of a sensitive nature
|
|
\fBcron
|
|
\fBdaemon
|
|
\fBftp
|
|
\fBkern\fR:cannot be generated from userspace process, automatically converted to \fBuser
|
|
\fBlpr
|
|
\fBmail
|
|
\fBnews
|
|
\fBsyslog
|
|
\fBuser
|
|
\fBuucp
|
|
\fBlocal0
|
|
to:
|
|
\fBlocal7
|
|
\fBsecurity\fR:deprecated synonym for \fBauth
|
|
.TE
|
|
.PP
|
|
Valid level names are:
|
|
.IP
|
|
.TS
|
|
tab(:);
|
|
left 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 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 SEE ALSO
|
|
.BR journalctl (1),
|
|
.BR syslog (3),
|
|
.BR systemd.journal-fields (7)
|
|
.SH STANDARDS
|
|
The
|
|
.B logger
|
|
command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
|
|
.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 .
|