manual/util-linux/original/man1/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 .BI \-\-msgid " msgid"
 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 .\" this long line gets cut of in the output of "troff", and wraps
 230 .\" in "nroff"
 231 \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
 232 .\".fi
 233 .TP
 234 .BR \-S , " \-\-size " \fIsize
 235 Sets the maximum permitted message size to \fIsize\fR.  The default
 236 is 1KiB characters, which is the limit traditionally used and specified
 237 in RFC 3164.  With RFC 5424, this limit has become flexible.  A good assumption
 238 is that RFC 5424 receivers can at least process 4KiB messages.
 239
 240 Most receivers accept messages larger than 1KiB over any type of syslog
 241 protocol.  As such, the \fB\-\-size\fR option affects logger in
 242 all cases (not only when \fB\-\-rfc5424\fR was used).
 243
 244 Note: the message-size limit limits the overall message size, including
 245 the syslog header.  Header sizes vary depending on the selected options and
 246 the hostname length.  As a rule of thumb, headers are usually not longer than
 247 50 to 80 characters.  When selecting a maximum message size, it is important
 248 to ensure that the receiver supports the max size as well, otherwise messages
 249 may become truncated.  Again, as a rule of thumb two to four KiB message size
 250 should generally be OK, whereas anything larger should be verified to work.
 251
 252 .TP
 253 .BR \-\-socket\-errors [ =\fImode ]
 254 Print errors about Unix socket connections.  The \fImode\fR can be a value of
 255 \fBoff\fR, \fBon\fR, or \fBauto\fR.  When the mode is auto logger will detect
 256 if the init process is systemd, and if so assumption is made /dev/log can be
 257 used early at boot.  Other init systems lack of /dev/log will not cause errors
 258 that is identical with messaging using
 259 .BR openlog (3)
 260 system call.  The
 261 .BR logger (1)
 262 before version 2.26 used openlog, and hence was unable to detected loss of
 263 messages sent to Unix sockets.
 264 .IP
 265 The default mode is \fBauto\fR.  When errors are not enabled lost messages are
 266 not communicated and will result to successful exit status of
 267 .BR logger (1)
 268 invocation.
 269 .TP
 270 .BR \-T , " \-\-tcp"
 271 Use stream (TCP) only.  By default the connection is tried to the
 272 .I syslog-conn
 273 port defined in /etc/services, which is often
 274 .IR 601 .
 275 .sp
 276 See also \fB\-\-server\fR and \fB\-\-socket\fR to specify where to connect.
 277 .TP
 278 .BR \-t , " \-\-tag " \fItag
 279 Mark every line to be logged with the specified
 280 .IR tag .
 281 The default tag is the name of the user logged in on the terminal (or a user
 282 name based on effective user ID).
 283 .TP
 284 .BR \-u , " \-\-socket " \fIsocket
 285 Write to the specified
 286 .I socket
 287 instead of to the system log socket.
 288 .TP
 289 .B \-\-
 290 End the argument list.  This allows the \fImessage\fR
 291 to start with a hyphen (\-).
 292 .TP
 293 .BR \-V , " \-\-version"
 294 Display version information and exit.
 295 .TP
 296 .BR \-h , " \-\-help"
 297 Display help text and exit.
 298 .SH EXIT STATUS
 299 The
 300 .B logger
 301 utility exits 0 on success, and >0 if an error occurs.
 302 .SH FACILITIES AND LEVELS
 303 Valid facility names are:
 304 .IP
 305 .nr WI \n(.lu-\n(.iu-\w'\fBauthpriv\fR'u-3n
 306 .TS
 307 tab(:);
 308 l lw(\n(WIu).
 309 \fBauth
 310 \fBauthpriv\fR:for security information of a sensitive nature
 311 \fBcron
 312 \fBdaemon
 313 \fBftp
 314 \fBkern\fR:T{
 315 cannot be generated from userspace process, automatically converted to \fBuser
 316 T}
 317 \fBlpr
 318 \fBmail
 319 \fBnews
 320 \fBsyslog
 321 \fBuser
 322 \fBuucp
 323 \fBlocal0
 324   to:
 325 \fBlocal7
 326 \fBsecurity\fR:deprecated synonym for \fBauth
 327 .TE
 328 .PP
 329 Valid level names are:
 330 .IP
 331 .TS
 332 tab(:);
 333 l l.
 334 \fBemerg
 335 \fBalert
 336 \fBcrit
 337 \fBerr
 338 \fBwarning
 339 \fBnotice
 340 \fBinfo
 341 \fBdebug
 342 \fBpanic\fR:deprecated synonym for \fBemerg
 343 \fBerror\fR:deprecated synonym for \fBerr
 344 \fBwarn\fR:deprecated synonym for \fBwarning
 345 .TE
 346 .PP
 347 For the priority order and intended purposes of these facilities and levels, see
 348 .BR syslog (3).
 349 .SH CONFORMING TO
 350 The
 351 .B logger
 352 command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
 353 .SH EXAMPLES
 354 .B logger System rebooted
 355 .br
 356 .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc
 357 .br
 358 .B logger \-n loghost.example.com System rebooted
 359 .SH AUTHORS
 360 The
 361 .B logger
 362 command
 363 was originally written by University of California in 1983-1993 and later
 364 rewritten by
 365 .MT kzak@redhat.com
 366 Karel Zak
 367 .ME ,
 368 .MT rgerhards@adiscon.com
 369 Rainer Gerhards
 370 .ME
 371 and
 372 .MT kerolasa@iki.fi
 373 Sami Kerola
 374 .ME .
 375 .SH SEE ALSO
 376 .BR journalctl (1),
 377 .BR syslog (3),
 378 .BR systemd.journal-fields (7)
 379 .SH AVAILABILITY
 380 The logger command is part of the util-linux package and is available from
 381 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 382 Linux Kernel Archive
 383 .UE .