| .\" 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 |
| .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 |
| \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 . |