Adding upstream version 2.36.1.upstream/2.36.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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 .