misc-utils/logger.1

   1 .\" Copyright (c) 1983, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)logger.1    8.1 (Berkeley) 6/6/93
  33 .\"
  34 .TH LOGGER "1" "November 2015" "util-linux" "User Commands"
  35 .SH NAME
  36 logger \- enter messages into the system log
  37 .SH SYNOPSIS
  38 .B logger
  39 [options]
  40 .RI [ message ]
  41 .SH DESCRIPTION
  42 .B logger
  43 makes entries in the system log.
  44 .sp
  45 When the optional \fImessage\fR argument is present, it is written
  46 to the log.  If it is not present, and the \fB\-f\fR option is not
  47 given either, then standard input is logged.
  48 .SH OPTIONS
  49 .TP
  50 .BR \-d , " \-\-udp"
  51 Use datagrams (UDP) only.  By default the connection is tried to the
  52 syslog port defined in /etc/services, which is often 514 .
  53 .TP
  54 .BR \-e , " \-\-skip-empty"
  55 Ignore empty lines when processing files.  An empty line
  56 is defined to be a line without any characters.  Thus a line consisting
  57 only of whitespace is NOT considered empty.
  58 Note that when the \fB\-\-prio\-prefix\fR option is specified, the priority
  59 is not part of the line.  Thus an empty line in this mode is a line that does
  60 not have any characters after the priority prefix (e.g. \fB<13>\fR).
  61 .TP
  62 .BR \-f , " \-\-file " \fIfile
  63 Log the contents of the specified \fIfile\fR.
  64 This option cannot be combined with a command-line message.
  65 .TP
  66 .B \-i
  67 Log the PID of the logger process with each line.
  68 .TP
  69 .BR "\-\-id" [ =\fIid ]
  70 Log the PID of the logger process with each line.  When the optional
  71 argument \fIid\fR is specified, then it is used instead of the logger
  72 command's PID.  The use of \fB\-\-id=$$\fR
  73 (PPID) is recommended in scripts that send several messages.
  74
  75 Note that the system logging infrastructure (for example \fBsystemd\fR when
  76 listening on /dev/log) may follow local socket credentials to overwrite the
  77 PID specified in the message.
  78 .BR logger (1)
  79 is able to set those socket credentials to the given \fIid\fR, but only if you
  80 have root permissions and a process with the specified PID exists, otherwise
  81 the socket credentials are not modified and the problem is silently ignored.
  82 .TP
  83 .BR \-\-journald [ =\fIfile ]
  84 Write a systemd journal entry.  The entry is read from the given \fIfile\fR,
  85 when specified, otherwise from standard input.
  86 Each line must begin with a field that is accepted by journald; see
  87 .BR systemd.journal-fields (7)
  88 for details.  The use of a MESSAGE_ID field is generally a good idea, as it
  89 makes finding entries easy.  Examples:
  90 .IP
  91 .nf
  92 \fB    logger \-\-journald <<end
  93 \fB    MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309
  94 \fB    MESSAGE=The dogs bark, but the caravan goes on.
  95 \fB    DOGS=bark
  96 \fB    CARAVAN=goes on
  97 \fB    end
  98 .IP
  99 \fB    logger \-\-journald=entry.txt
 100 .fi
 101 .IP
 102 Notice that
 103 .B \-\-journald
 104 will ignore values of other options, such as priority.  If priority is
 105 needed it must be within input, and use PRIORITY field.  The simple
 106 execution of
 107 .B journalctl
 108 will display MESSAGE field.  Use
 109 .B journalctl \-\-output json-pretty
 110 to see rest of the fields.
 111 .TP
 112 .BR \-\-msgid " \fImsgid
 113 Sets the RFC5424 MSGID field.  Note that the space character is not permitted
 114 inside of \fImsgid\fR.  This option is only used if \fB\-\-rfc5424\fR is
 115 specified as well; otherwise, it is silently ignored.
 116 .TP
 117 .BR \-n , " \-\-server " \fIserver
 118 Write to the specified remote syslog \fIserver\fR
 119 instead of to the system log socket.  Unless
 120 \fB\-\-udp\fR or \fB\-\-tcp\fR
 121 is specified, \fBlogger\fR will first try to use UDP,
 122 but if this fails a TCP connection is attempted.
 123 .TP
 124 .B \-\-no\-act
 125 Causes everything to be done except for writing the log message to the system
 126 log, and removing the connection or the journal.  This option can be used
 127 together with \fB\-\-stderr\fR for testing purposes.
 128 .TP
 129 .B \-\-octet\-count
 130 Use the RFC 6587 octet counting framing method for sending messages.
 131 When this option is not used, the default is no framing on UDP, and
 132 RFC6587 non-transparent framing (also known as octet stuffing) on TCP.
 133 .TP
 134 .BR \-P , " \-\-port " \fIport
 135 Use the specified \fIport\fR.  When this option is not specified, the
 136 port defaults to syslog for udp and to syslog-conn for tcp connections.
 137 .TP
 138 .BR \-p , " \-\-priority " \fIpriority
 139 Enter the message into the log with the specified \fIpriority\fR.
 140 The priority may be specified numerically or as a
 141 .IR facility . level
 142 pair.
 143 For example, \fB\-p local3.info\fR
 144 logs the message as informational in the local3 facility.
 145 The default is \fBuser.notice\fR.
 146 .TP
 147 .B \-\-prio\-prefix
 148 Look for a syslog prefix on every line read from standard input.
 149 This prefix is a decimal number within angle brackets that encodes both
 150 the facility and the level.  The number is constructed by multiplying the
 151 facility by 8 and then adding the level.  For example, \fBlocal0.info\fR,
 152 meaning facility=16 and level=6, becomes \fB<134>\fR.
 153 .sp
 154 If the prefix contains no facility, the facility defaults to what is
 155 specified by the \fB\-p\fR option.  Similarly, if no prefix is provided,
 156 the line is logged using the \fIpriority\fR given with \fB\-p\fR.
 157 .sp
 158 This option doesn't affect a command-line message.
 159 .TP
 160 .B \-\-rfc3164
 161 Use the RFC 3164 BSD syslog protocol to submit messages to a remote server.
 162 .TP
 163 .BR \-\-rfc5424 [ =\fIwithout ]
 164 Use the RFC 5424 syslog protocol to submit messages to a remote server.
 165 The optional \fIwithout\fR argument can be a comma-separated list of
 166 the following values: \fBnotq\fR, \fBnotime\fR, \fBnohost\fR.
 167
 168 The \fBnotq\fR value suppresses the time-quality structured data
 169 from the submitted message.  The time-quality information shows whether
 170 the local clock was synchronized plus the maximum number of microseconds
 171 the timestamp might be off.  The time quality is also automatically
 172 suppressed when \fB\-\-sd\-id timeQuality\fR is specified.
 173
 174 The \fBnotime\fR value (which implies \fBnotq\fR)
 175 suppresses the complete sender timestamp that is in
 176 ISO-8601 format, including microseconds and timezone.
 177
 178 The \fBnohost\fR value suppresses
 179 .BR gethostname (2)
 180 information from the message header.
 181 .IP
 182 The RFC 5424 protocol has been the default for
 183 .B logger
 184 since version 2.26.
 185 .TP
 186 .BR \-s , " \-\-stderr"
 187 Output the message to standard error as well as to the system log.
 188 .TP
 189 .BR "\-\-sd\-id \fIname" [ @\fIdigits ]
 190 Specifies a structured data element ID for an RFC 5424 message header.  The
 191 option has to be used before \fB\-\-sd\-param\fR to introduce a new element.
 192 The number of structured data elements is unlimited.  The ID (\fIname\fR plus
 193 possibly \fB@\fIdigits\fR) is case-sensitive and uniquely identifies the type
 194 and purpose of the element.  The same ID must not exist more than once in
 195 a message.  The \fB@\fIdigits\fR part is required for user-defined
 196 non-standardized IDs.
 197
 198 \fBlogger\fR currently generates the \fBtimeQuality\fR standardized element
 199 only.  RFC 5424 also describes the elements \fBorigin\fR (with parameters
 200 ip, enterpriseId, software and swVersion) and \fBmeta\fR (with parameters
 201 sequenceId, sysUpTime and language).
 202 These element IDs may be specified without the \fB@\fIdigits\fR suffix.
 203
 204 .TP
 205 .BR "\-\-sd\-param " \fIname ="\fIvalue\fB"
 206 Specifies a structured data element parameter, a name and value pair.
 207 The option has to be used after \fB\-\-sd\-id\fR and may be specified more
 208 than once for the same element.  Note that the quotation marks around
 209 \fIvalue\fR are required and must be escaped on the command line.
 210 .IP
 211 .nf
 212 \fB    logger \-\-rfc5424 \-\-sd-id zoo@123               \\
 213 \fB                     \-\-sd-param tiger=\\"hungry\\"   \\
 214 \fB                     \-\-sd-param zebra=\\"running\\"  \\
 215 \fB                     \-\-sd-id manager@123           \\
 216 \fB                     \-\-sd-param onMeeting=\\"yes\\"  \\
 217 \fB                     "this is message"
 218 .fi
 219 .IP
 220 produces:
 221 .IP
 222 .nf
 223 \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
 224 .fi
 225 .IP
 226 .TP
 227 .BR \-\-size " \fIsize
 228 Sets the maximum permitted message size to \fIsize\fR.  The default
 229 is 1KiB characters, which is the limit traditionally used and specified
 230 in RFC 3164.  With RFC 5424, this limit has become flexible.  A good assumption
 231 is that RFC 5424 receivers can at least process 4KiB messages.
 232
 233 Most receivers accept messages larger than 1KiB over any type of syslog
 234 protocol.  As such, the \fB\-\-size\fR option affects logger in
 235 all cases (not only when \fB\-\-rfc5424\fR was used).
 236
 237 Note: the message-size limit limits the overall message size, including
 238 the syslog header.  Header sizes vary depending on the selected options and
 239 the hostname length.  As a rule of thumb, headers are usually not longer than
 240 50 to 80 characters.  When selecting a maximum message size, it is important
 241 to ensure that the receiver supports the max size as well, otherwise messages
 242 may become truncated.  Again, as a rule of thumb two to four KiB message size
 243 should generally be OK, whereas anything larger should be verified to work.
 244
 245 .TP
 246 .BR \-\-socket\-errors [ =\fImode ]
 247 Print errors about Unix socket connections.  The \fImode\fR can be a value of
 248 \fBoff\fR, \fBon\fR, or \fBauto\fR.  When the mode is auto logger will detect
 249 if the init process is systemd, and if so assumption is made /dev/log can be
 250 used early at boot.  Other init systems lack of /dev/log will not cause errors
 251 that is identical with messaging using
 252 .BR openlog (3)
 253 system call.  The
 254 .BR logger (1)
 255 before version 2.26 used openlog, and hence was unable to detected loss of
 256 messages sent to Unix sockets.
 257 .IP
 258 The default mode is \fBauto\fR.  When errors are not enabled lost messages are
 259 not communicated and will result to successful return value of
 260 .BR logger (1)
 261 invocation.
 262 .TP
 263 .BR \-T , " \-\-tcp"
 264 Use stream (TCP) only.  By default the connection is tried to the
 265 .I syslog-conn
 266 port defined in /etc/services, which is often
 267 .IR 601 .
 268 .TP
 269 .BR \-t , " \-\-tag " \fItag
 270 Mark every line to be logged with the specified
 271 .IR tag .
 272 The default tag is the name of the user logged in on the terminal (or a user
 273 name based on effective user ID).
 274 .TP
 275 .BR \-u , " \-\-socket " \fIsocket
 276 Write to the specified
 277 .I socket
 278 instead of to the system log socket.
 279 .TP
 280 .B \-\-
 281 End the argument list.  This allows the \fImessage\fR
 282 to start with a hyphen (\-).
 283 .TP
 284 .BR \-V , " \-\-version"
 285 Display version information and exit.
 286 .TP
 287 .BR \-h , " \-\-help"
 288 Display help text and exit.
 289 .SH RETURN VALUE
 290 The
 291 .B logger
 292 utility exits 0 on success, and >0 if an error occurs.
 293 .SH FACILITIES AND LEVELS
 294 Valid facility names are:
 295 .IP
 296 .TS
 297 tab(:);
 298 left l l.
 299 \fBauth
 300 \fBauthpriv\fR:for security information of a sensitive nature
 301 \fBcron
 302 \fBdaemon
 303 \fBftp
 304 \fBkern\fR:cannot be generated from userspace process, automatically converted to \fBuser
 305 \fBlpr
 306 \fBmail
 307 \fBnews
 308 \fBsyslog
 309 \fBuser
 310 \fBuucp
 311 \fBlocal0
 312   to:
 313 \fBlocal7
 314 \fBsecurity\fR:deprecated synonym for \fBauth
 315 .TE
 316 .PP
 317 Valid level names are:
 318 .IP
 319 .TS
 320 tab(:);
 321 left l l.
 322 \fBemerg
 323 \fBalert
 324 \fBcrit
 325 \fBerr
 326 \fBwarning
 327 \fBnotice
 328 \fBinfo
 329 \fBdebug
 330 \fBpanic\fR:deprecated synonym for \fBemerg
 331 \fBerror\fR:deprecated synonym for \fBerr
 332 \fBwarn\fR:deprecated synonym for \fBwarning
 333 .TE
 334 .PP
 335 For the priority order and intended purposes of these facilities and levels, see
 336 .BR syslog (3).
 337 .SH EXAMPLES
 338 .B logger System rebooted
 339 .br
 340 .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc
 341 .br
 342 .B logger \-n loghost.example.com System rebooted
 343 .SH SEE ALSO
 344 .BR journalctl (1),
 345 .BR syslog (3),
 346 .BR systemd.journal-fields (7)
 347 .SH STANDARDS
 348 The
 349 .B logger
 350 command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
 351 .SH AVAILABILITY
 352 The logger command is part of the util-linux package and is available from
 353 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 354 Linux Kernel Archive
 355 .UE .