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 .sp
  54 See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect.
  55 .TP
  56 .BR \-e , " \-\-skip-empty"
  57 Ignore empty lines when processing files.  An empty line
  58 is defined to be a line without any characters.  Thus a line consisting
  59 only of whitespace is NOT considered empty.
  60 Note that when the \fB\-\-prio\-prefix\fR option is specified, the priority
  61 is not part of the line.  Thus an empty line in this mode is a line that does
  62 not have any characters after the priority prefix (e.g. \fB<13>\fR).
  63 .TP
  64 .BR \-f , " \-\-file " \fIfile
  65 Log the contents of the specified \fIfile\fR.
  66 This option cannot be combined with a command-line message.
  67 .TP
  68 .B \-i
  69 Log the PID of the logger process with each line.
  70 .TP
  71 .BR "\-\-id" [ =\fIid ]
  72 Log the PID of the logger process with each line.  When the optional
  73 argument \fIid\fR is specified, then it is used instead of the logger
  74 command's PID.  The use of \fB\-\-id=$$\fR
  75 (PPID) is recommended in scripts that send several messages.
  76
  77 Note that the system logging infrastructure (for example \fBsystemd\fR when
  78 listening on /dev/log) may follow local socket credentials to overwrite the
  79 PID specified in the message.
  80 .BR logger (1)
  81 is able to set those socket credentials to the given \fIid\fR, but only if you
  82 have root permissions and a process with the specified PID exists, otherwise
  83 the socket credentials are not modified and the problem is silently ignored.
  84 .TP
  85 .BR \-\-journald [ =\fIfile ]
  86 Write a systemd journal entry.  The entry is read from the given \fIfile\fR,
  87 when specified, otherwise from standard input.
  88 Each line must begin with a field that is accepted by journald; see
  89 .BR systemd.journal-fields (7)
  90 for details.  The use of a MESSAGE_ID field is generally a good idea, as it
  91 makes finding entries easy.  Examples:
  92 .IP
  93 .nf
  94 \fB    logger \-\-journald <<end
  95 \fB    MESSAGE_ID=67feb6ffbaf24c5cbec13c008dd72309
  96 \fB    MESSAGE=The dogs bark, but the caravan goes on.
  97 \fB    DOGS=bark
  98 \fB    CARAVAN=goes on
  99 \fB    end
 100 .IP
 101 \fB    logger \-\-journald=entry.txt
 102 .fi
 103 .IP
 104 Notice that
 105 .B \-\-journald
 106 will ignore values of other options, such as priority.  If priority is
 107 needed it must be within input, and use PRIORITY field.  The simple
 108 execution of
 109 .B journalctl
 110 will display MESSAGE field.  Use
 111 .B journalctl \-\-output json-pretty
 112 to see rest of the fields.
 113 .sp
 114 To include newlines in MESSAGE, specify MESSAGE several times.  This is
 115 handled as a special case, other fields will be stored as an array in
 116 the journal if they appear multiple times.
 117 .TP
 118 .BR \-\-msgid " \fImsgid
 119 Sets the RFC5424 MSGID field.  Note that the space character is not permitted
 120 inside of \fImsgid\fR.  This option is only used if \fB\-\-rfc5424\fR is
 121 specified as well; otherwise, it is silently ignored.
 122 .TP
 123 .BR \-n , " \-\-server " \fIserver
 124 Write to the specified remote syslog \fIserver\fR
 125 instead of to the system log socket.  Unless
 126 \fB\-\-udp\fR or \fB\-\-tcp\fR
 127 is specified, \fBlogger\fR will first try to use UDP,
 128 but if this fails a TCP connection is attempted.
 129 .TP
 130 .B \-\-no\-act
 131 Causes everything to be done except for writing the log message to the system
 132 log, and removing the connection or the journal.  This option can be used
 133 together with \fB\-\-stderr\fR for testing purposes.
 134 .TP
 135 .B \-\-octet\-count
 136 Use the RFC 6587 octet counting framing method for sending messages.
 137 When this option is not used, the default is no framing on UDP, and
 138 RFC6587 non-transparent framing (also known as octet stuffing) on TCP.
 139 .TP
 140 .BR \-P , " \-\-port " \fIport
 141 Use the specified \fIport\fR.  When this option is not specified, the
 142 port defaults to syslog for udp and to syslog-conn for tcp connections.
 143 .TP
 144 .BR \-p , " \-\-priority " \fIpriority
 145 Enter the message into the log with the specified \fIpriority\fR.
 146 The priority may be specified numerically or as a
 147 .IR facility . level
 148 pair.
 149 For example, \fB\-p local3.info\fR
 150 logs the message as informational in the local3 facility.
 151 The default is \fBuser.notice\fR.
 152 .TP
 153 .B \-\-prio\-prefix
 154 Look for a syslog prefix on every line read from standard input.
 155 This prefix is a decimal number within angle brackets that encodes both
 156 the facility and the level.  The number is constructed by multiplying the
 157 facility by 8 and then adding the level.  For example, \fBlocal0.info\fR,
 158 meaning facility=16 and level=6, becomes \fB<134>\fR.
 159 .sp
 160 If the prefix contains no facility, the facility defaults to what is
 161 specified by the \fB\-p\fR option.  Similarly, if no prefix is provided,
 162 the line is logged using the \fIpriority\fR given with \fB\-p\fR.
 163 .sp
 164 This option doesn't affect a command-line message.
 165 .TP
 166 .B \-\-rfc3164
 167 Use the RFC 3164 BSD syslog protocol to submit messages to a remote server.
 168 .TP
 169 .BR \-\-rfc5424 [ =\fIwithout ]
 170 Use the RFC 5424 syslog protocol to submit messages to a remote server.
 171 The optional \fIwithout\fR argument can be a comma-separated list of
 172 the following values: \fBnotq\fR, \fBnotime\fR, \fBnohost\fR.
 173
 174 The \fBnotq\fR value suppresses the time-quality structured data
 175 from the submitted message.  The time-quality information shows whether
 176 the local clock was synchronized plus the maximum number of microseconds
 177 the timestamp might be off.  The time quality is also automatically
 178 suppressed when \fB\-\-sd\-id timeQuality\fR is specified.
 179
 180 The \fBnotime\fR value (which implies \fBnotq\fR)
 181 suppresses the complete sender timestamp that is in
 182 ISO-8601 format, including microseconds and timezone.
 183
 184 The \fBnohost\fR value suppresses
 185 .BR gethostname (2)
 186 information from the message header.
 187 .IP
 188 The RFC 5424 protocol has been the default for
 189 .B logger
 190 since version 2.26.
 191 .TP
 192 .BR \-s , " \-\-stderr"
 193 Output the message to standard error as well as to the system log.
 194 .TP
 195 .BR "\-\-sd\-id \fIname" [ @\fIdigits ]
 196 Specifies a structured data element ID for an RFC 5424 message header.  The
 197 option has to be used before \fB\-\-sd\-param\fR to introduce a new element.
 198 The number of structured data elements is unlimited.  The ID (\fIname\fR plus
 199 possibly \fB@\fIdigits\fR) is case-sensitive and uniquely identifies the type
 200 and purpose of the element.  The same ID must not exist more than once in
 201 a message.  The \fB@\fIdigits\fR part is required for user-defined
 202 non-standardized IDs.
 203
 204 \fBlogger\fR currently generates the \fBtimeQuality\fR standardized element
 205 only.  RFC 5424 also describes the elements \fBorigin\fR (with parameters
 206 ip, enterpriseId, software and swVersion) and \fBmeta\fR (with parameters
 207 sequenceId, sysUpTime and language).
 208 These element IDs may be specified without the \fB@\fIdigits\fR suffix.
 209
 210 .TP
 211 .BR "\-\-sd\-param " \fIname ="\fIvalue\fB"
 212 Specifies a structured data element parameter, a name and value pair.
 213 The option has to be used after \fB\-\-sd\-id\fR and may be specified more
 214 than once for the same element.  Note that the quotation marks around
 215 \fIvalue\fR are required and must be escaped on the command line.
 216 .IP
 217 .nf
 218 \fB    logger \-\-rfc5424 \-\-sd-id zoo@123               \\
 219 \fB                     \-\-sd-param tiger=\\"hungry\\"   \\
 220 \fB                     \-\-sd-param zebra=\\"running\\"  \\
 221 \fB                     \-\-sd-id manager@123           \\
 222 \fB                     \-\-sd-param onMeeting=\\"yes\\"  \\
 223 \fB                     "this is message"
 224 .fi
 225 .IP
 226 produces:
 227 .IP
 228 .nf
 229 \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
 230 .fi
 231 .IP
 232 .TP
 233 .BR \-S , " -\-size " \fIsize
 234 Sets the maximum permitted message size to \fIsize\fR.  The default
 235 is 1KiB characters, which is the limit traditionally used and specified
 236 in RFC 3164.  With RFC 5424, this limit has become flexible.  A good assumption
 237 is that RFC 5424 receivers can at least process 4KiB messages.
 238
 239 Most receivers accept messages larger than 1KiB over any type of syslog
 240 protocol.  As such, the \fB\-\-size\fR option affects logger in
 241 all cases (not only when \fB\-\-rfc5424\fR was used).
 242
 243 Note: the message-size limit limits the overall message size, including
 244 the syslog header.  Header sizes vary depending on the selected options and
 245 the hostname length.  As a rule of thumb, headers are usually not longer than
 246 50 to 80 characters.  When selecting a maximum message size, it is important
 247 to ensure that the receiver supports the max size as well, otherwise messages
 248 may become truncated.  Again, as a rule of thumb two to four KiB message size
 249 should generally be OK, whereas anything larger should be verified to work.
 250
 251 .TP
 252 .BR \-\-socket\-errors [ =\fImode ]
 253 Print errors about Unix socket connections.  The \fImode\fR can be a value of
 254 \fBoff\fR, \fBon\fR, or \fBauto\fR.  When the mode is auto logger will detect
 255 if the init process is systemd, and if so assumption is made /dev/log can be
 256 used early at boot.  Other init systems lack of /dev/log will not cause errors
 257 that is identical with messaging using
 258 .BR openlog (3)
 259 system call.  The
 260 .BR logger (1)
 261 before version 2.26 used openlog, and hence was unable to detected loss of
 262 messages sent to Unix sockets.
 263 .IP
 264 The default mode is \fBauto\fR.  When errors are not enabled lost messages are
 265 not communicated and will result to successful return value of
 266 .BR logger (1)
 267 invocation.
 268 .TP
 269 .BR \-T , " \-\-tcp"
 270 Use stream (TCP) only.  By default the connection is tried to the
 271 .I syslog-conn
 272 port defined in /etc/services, which is often
 273 .IR 601 .
 274 .sp
 275 See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect.
 276 .TP
 277 .BR \-t , " \-\-tag " \fItag
 278 Mark every line to be logged with the specified
 279 .IR tag .
 280 The default tag is the name of the user logged in on the terminal (or a user
 281 name based on effective user ID).
 282 .TP
 283 .BR \-u , " \-\-socket " \fIsocket
 284 Write to the specified
 285 .I socket
 286 instead of to the system log socket.
 287 .TP
 288 .B \-\-
 289 End the argument list.  This allows the \fImessage\fR
 290 to start with a hyphen (\-).
 291 .TP
 292 .BR \-V , " \-\-version"
 293 Display version information and exit.
 294 .TP
 295 .BR \-h , " \-\-help"
 296 Display help text and exit.
 297 .SH RETURN VALUE
 298 The
 299 .B logger
 300 utility exits 0 on success, and >0 if an error occurs.
 301 .SH FACILITIES AND LEVELS
 302 Valid facility names are:
 303 .IP
 304 .nr WI \n(.lu-\n(.iu-\w'\fBauthpriv\fR'u-3n
 305 .TS
 306 tab(:);
 307 l lw(\n(WIu).
 308 \fBauth
 309 \fBauthpriv\fR:for security information of a sensitive nature
 310 \fBcron
 311 \fBdaemon
 312 \fBftp
 313 \fBkern\fR:T{
 314 cannot be generated from userspace process, automatically converted to \fBuser
 315 T}
 316 \fBlpr
 317 \fBmail
 318 \fBnews
 319 \fBsyslog
 320 \fBuser
 321 \fBuucp
 322 \fBlocal0
 323   to:
 324 \fBlocal7
 325 \fBsecurity\fR:deprecated synonym for \fBauth
 326 .TE
 327 .PP
 328 Valid level names are:
 329 .IP
 330 .TS
 331 tab(:);
 332 l l.
 333 \fBemerg
 334 \fBalert
 335 \fBcrit
 336 \fBerr
 337 \fBwarning
 338 \fBnotice
 339 \fBinfo
 340 \fBdebug
 341 \fBpanic\fR:deprecated synonym for \fBemerg
 342 \fBerror\fR:deprecated synonym for \fBerr
 343 \fBwarn\fR:deprecated synonym for \fBwarning
 344 .TE
 345 .PP
 346 For the priority order and intended purposes of these facilities and levels, see
 347 .BR syslog (3).
 348 .SH EXAMPLES
 349 .B logger System rebooted
 350 .br
 351 .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc
 352 .br
 353 .B logger \-n loghost.example.com System rebooted
 354 .SH SEE ALSO
 355 .BR journalctl (1),
 356 .BR syslog (3),
 357 .BR systemd.journal-fields (7)
 358 .SH STANDARDS
 359 The
 360 .B logger
 361 command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
 362 .SH AUTHORS
 363 The
 364 .B logger
 365 command
 366 was originally written by University of California in 1983-1993 and later
 367 rewritten by
 368 .MT kzak@redhat.com
 369 Karel Zak
 370 .ME ,
 371 .MT rgerhards@adiscon.com
 372 Rainer Gerhards
 373 .ME
 374 and
 375 .MT kerolasa@iki.fi
 376 Sami Kerola
 377 .ME .
 378 .SH AVAILABILITY
 379 The logger command is part of the util-linux package and is available from
 380 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 381 Linux Kernel Archive
 382 .UE .