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 .\" Section on valid facility and level strings added by
  35 .\" and1000@debian.org, 26 Oct 1997.
  36 .TH LOGGER "1" "June 2014" "util-linux" "User Commands"
  37 .SH NAME
  38 logger \- a shell command interface to the syslog(3) system log module
  39 .SH SYNOPSIS
  40 .B logger
  41 [options]
  42 .RI [ message ]
  43 .SH DESCRIPTION
  44 .B logger
  45 makes entries in the system log.  It provides a shell command
  46 interface to the
  47 .BR syslog (3)
  48 system log module.
  49 .SH OPTIONS
  50 .TP
  51 \fB\-d\fR, \fB\-\-udp\fR
  52 Use datagram (UDP) only.  By default the connection is tried to the
  53 .I syslog
  54 port defined in /etc/services, which is often
  55 .IR 514 .
  56 .TP
  57 \fB\-h\fR, \fB\-\-help\fR
  58 Display help text and exit.
  59 .TP
  60 \fB\-i\fR, \fB\-\-id\fR[=\fBid\fR]
  61 Log the PID of the logger process with each line.  When optional
  62 argument
  63 .B id
  64 is specified then it is used instead of logger command PID.  Use of
  65 .B --id=$$
  66 (PPID) is recommended in scripts that send several messages.
  67 .TP
  68 \fB\-n\fR, \fB\-\-server\fR \fIserver\fR
  69 Write to the specified remote syslog
  70 .I server
  71 instead of to the builtin syslog routines.  Unless
  72 .B \-\-udp
  73 or
  74 .B \-\-tcp
  75 is specified, \fBlogger\fR will first try to use UDP,
  76 but if thist fails a TCP connection is attempted.
  77 .TP
  78 \fB\-P\fR, \fB\-\-port\fR \fIport\fR
  79 Use the specified
  80 .IR port .
  81 When
  82 .I port
  83 is not specified it defaults to
  84 .I syslog
  85 for udp and
  86 .I syslog-conn
  87 for tcp connections.
  88 .TP
  89 \fB\-f\fR, \fB\-\-file\fR \fIfile\fR
  90 Log the contents of the specified
  91 .IR file .
  92 This option cannot be combined with a command-line message.
  93 .TP
  94 \fB\-p\fR, \fB\-\-priority\fR \fIpriority\fR
  95 Enter the message into the log with the specified
  96 .IR priority  .
  97 The priority may be specified numerically or as a
  98 .I facility.level
  99 pair.
 100 For example,
 101 .B -p
 102 .I local3.info
 103 logs the message as informational in the local3 facility.
 104 The default is
 105 .IR user.notice .
 106 .TP
 107 \fB\-\-prio\-prefix\fR
 108 Look for a syslog prefix on every line read from standard input.
 109 This prefix is a number within angle brackets that contains both the facility
 110 and the level.  This decimal prefix is constructed by multiplying the
 111 facility by 8 and then adding the level.  Thus, for example, \fIlocal0.info\fR,
 112 facility=16 and level=6, becomes \fI<134>\fR.
 113
 114 If the prefix contains no facility, the facility defaults to what is
 115 specified by the \fB\-p\fR option.  Similarly, if no prefix is provided,
 116 the line is logged using the \fB\-p\fR \fIpriority\fR.
 117
 118 This option doesn't affect a command-line message.
 119
 120 .TP
 121 \fB\-\-rfc3164\fR
 122 Use RFC 3164 BSD syslog protocol to submit messages to remote server.
 123 .TP
 124 \fB\-\-rfc5424\fR [\fInotime\fR,\fInotq\fR,\fInohost\fR]
 125 Use RFC 5424 syslog protocol to submit messages to remote server.
 126 Optional argument
 127 .I notime
 128 will suppress submission of sender time stamp that is in ISO-8601 format,
 129 including microseconds and timezone.  When
 130 .I notime
 131 is specified the time quality structured data, that can be suppressed
 132 separately with
 133 .IR notq ,
 134 is excluded from output.  The time quality information tells if local
 135 clock was syncronized, and maximum number of microseconds the time stamp
 136 could be off.  Option argument
 137 .I nohost
 138 will suppress
 139 .IR gethostname (2)
 140 information from message header.
 141 .IP
 142 The rfc5424 protocol has been default for
 143 .B logger
 144 since version 2.26.
 145 .TP
 146 \fB\-s\fR, \fB\-\-stderr\fR
 147 Output the message to standard error as well as to the system log.
 148 .TP
 149 \fB\-T\fR, \fB\-\-tcp\fR
 150 Use stream (TCP) only.  By default the connection is tried to the
 151 .I syslog-conn
 152 port defined in /etc/services, which is often
 153 .IR 601 .
 154 .TP
 155 \fB\-t\fR, \fB\-\-tag\fR \fItag\fR
 156 Mark every line to be logged with the specified
 157 .IR tag .
 158 .TP
 159 \fB\-u\fR, \fB\-\-socket\fR \fIsocket\fR
 160 Write to the specified
 161 .I socket
 162 instead of to the builtin syslog routines.
 163 .TP
 164 \fB\-\-journald\fR [\fIfile\fR]
 165 Write systemd journal entry.  The entry is read from
 166 .I stdin
 167 or input
 168 .IR file .
 169 Each new line must begin with a field that is accepted by journald, see
 170 .IR systemd.journal-fields (7)
 171 for details.  Use of MESSAGE_ID field is generally good idea, as they
 172 make finding entries easy.
 173 .IP
 174 .nf
 175 $ printf "%s\\n%s\\n%s\\n" MESSAGE_ID=86184c3b1aa444f58ebe7b30fec1438b DOGS=bark "CARAVAN=goes on" | logger --journald
 176 $ logger --journald=entry.txt
 177 .fi
 178 .IP
 179 Notice that
 180 .B \-\-journald
 181 will ignore values of other options, such as priority.  If priority is
 182 needed it must be within input, and use PRIORITY field.  The simple
 183 execution of
 184 .B journalctl
 185 will display MESSAGE field.  Use
 186 .B journalctl --output json-pretty
 187 to see rest of the fields.
 188 .TP
 189 \fB\-V\fR, \fB\-\-version\fR
 190 Display version information and exit.
 191 .TP
 192 \fB\-\-\fR
 193 End the argument list.  This is to allow the
 194 .I message
 195 to start with a hyphen (\-).
 196 .TP
 197 .I message
 198 Write this \fImessage\fR to the log; if not specified, and the
 199 .B \-f
 200 flag is not provided, standard input is logged.
 201 .SH RETURN VALUE
 202 The
 203 .B logger
 204 utility exits 0 on success, and >0 if an error occurs.
 205 .SH FACILITIES AND LEVELS
 206 Valid facility names are:
 207 .IP
 208 .TS
 209 tab(:);
 210 left l l.
 211 \fIauth\fR
 212 \fIauthpriv\fR:for security information of a sensitive nature
 213 \fIcron\fR
 214 \fIdaemon\fR
 215 \fIftp\fR
 216 \fIkern\fR:cannot be generated from user process
 217 \fIlpr\fR
 218 \fImail\fR
 219 \fInews\fR
 220 \fIsyslog\fR
 221 \fIuser\fR
 222 \fIuucp\fR
 223 \fIlocal0\fR
 224   to:
 225 \fIlocal7\fR
 226 \fIsecurity\fR:deprecated synonym for \fIauth\fR
 227 .TE
 228 .PP
 229 Valid level names are:
 230 .IP
 231 .TS
 232 tab(:);
 233 left l l.
 234 \fIemerg\fR
 235 \fIalert\fR
 236 \fIcrit\fR
 237 \fIerr\fR
 238 \fIwarning\fR
 239 \fInotice\fR
 240 \fIinfo\fR
 241 \fIdebug\fR
 242 \fIpanic\fR:deprecated synonym for \fIemerg\fR
 243 \fIerror\fR:deprecated synonym for \fIerr\fR
 244 \fIwarn\fR:deprecated synonym for \fIwarning\fR
 245 .TE
 246 .PP
 247 For the priority order and intended purposes of these facilities and levels, see
 248 .BR syslog (3).
 249 .SH EXAMPLES
 250 logger System rebooted
 251 .br
 252 logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc
 253 .br
 254 logger \-n loghost.example.com System rebooted
 255 .SH SEE ALSO
 256 .BR syslog (3),
 257 .BR syslogd (8),
 258 .BR journalctl (1),
 259 .BR systemd.journal-fields (7)
 260 .SH STANDARDS
 261 The
 262 .B logger
 263 command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
 264 .SH AVAILABILITY
 265 The logger command is part of the util-linux package and is available from
 266 .UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 267 Linux Kernel Archive
 268 .UE .