doc/man/lttng-relayd.8.txt

   1 lttng-relayd(8)
   2 ===============
   3
   4
   5 NAME
   6 ----
   7 lttng-relayd - LTTng 2 relay daemon
   8
   9
  10 SYNOPSIS
  11 --------
  12 [verse]
  13 *lttng-relayd* [option:--background | option:--daemonize]
  14              [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL']
  15              [option:--output='PATH'] [option:-v | option:-vv | option:-vvv]
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
  21 source software package used for correlated tracing of the Linux kernel,
  22 user applications, and user libraries.
  23
  24 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
  25 dynamically loaded libraries (for user application and library tracing).
  26
  27 The _LTTng relay daemon_ is responsible for receiving trace data from
  28 possibly remote LTTng session/consumer daemons and for writing it to
  29 the local file system. The relay daemon also accepts _LTTng live_
  30 connections from compatible viewers; this is the official approach to
  31 viewing LTTng events as they are emitted.
  32
  33 The relay daemon listens by default on all network interfaces to gather
  34 trace data, but only on localhost for LTTng live connections.
  35
  36 The relay daemon does not require any particular permissions, as long as
  37 it can write to the output directory and listen on the configured ports.
  38 If a user is within a secured network and/or has proper firewall
  39 settings, `lttng-relayd` can listen to LTTng live connections from _all_
  40 network interfaces by specifying
  41 +--live-port=tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
  42
  43 Once a trace has been streamed completely, the trace can be processed by
  44 any tool that can process an LTTng trace located on the local
  45 file system.
  46
  47
  48 [[output-directory]]
  49 Output directory
  50 ~~~~~~~~~~~~~~~~
  51 By default, the relay daemon writes the traces to:
  52
  53 [verse]
  54 $LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
  55
  56 with:
  57
  58 'HOSTNAME'::
  59     Remote hostname.
  60
  61 'SESSION'::
  62     Full session name.
  63
  64 'DOMAIN'::
  65     Tracing domain.
  66
  67 You can override the default output directory prefix
  68 (`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other
  69 parts depend on the remote configuration.
  70
  71
  72 [[url-format]]
  73 URL format
  74 ~~~~~~~~~~
  75 The option:--control-port, option:--data-port, and option:--live-port
  76 options specify URLs.
  77
  78 The format of those URLs is:
  79
  80 [verse]
  81 tcp://('HOST' | 'IPADDR'):__PORT__
  82
  83 with:
  84
  85 ('HOST' | 'IPADDR')::
  86     Binding hostname or IP address (IPv6 address *must* be enclosed in
  87     brackets (`[` and `]`); see
  88     https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
  89
  90 'PORT'::
  91     TCP port.
  92
  93
  94 OPTIONS
  95 -------
  96 Daemon
  97 ~~~~~~
  98 option:-b, option:--background::
  99     Start as Unix daemon, but keep file descriptors (console) open.
 100     Use the option:--daemonize option instead to close the file
 101     descriptors.
 102
 103 option:-d, option:--daemonize::
 104     Start as Unix daemon, and close file descriptors (console). Use the
 105     option:--background option instead to keep the file descriptors
 106     open.
 107
 108 option:-g 'GROUP', option:--group='GROUP'::
 109     Use 'GROUP' as Unix tracing group (default: `tracing`).
 110
 111 option:-o 'PATH', option:--output='PATH'::
 112     Set base directory of written trace data to 'PATH'.
 113 +
 114 See the <<output-directory,Output directory>> section above for more
 115 information.
 116
 117 option:-v, option:--verbose::
 118     Increase verbosity.
 119 +
 120 Three levels of verbosity are available, which are triggered by
 121 appending additional `v` letters to the option
 122 (that is, `-vv` and `-vvv`).
 123
 124
 125 Ports
 126 ~~~~~
 127 See the <<url-format,URL format>> section above for more information
 128 about the syntax of the following options' 'URL' argument.
 129
 130 option:-C 'URL', option:--control-port='URL'::
 131     Listen to control data on URL 'URL' (default:
 132     +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
 133
 134 option:-D 'URL', option:--data-port='URL'::
 135     Listen to trace data on URL 'URL' (default:
 136     +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
 137
 138 option:-L 'URL', option:--live-port='URL'::
 139     Listen to LTTng live connections on URL 'URL'
 140     (default:
 141     +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
 142
 143
 144 Program information
 145 ~~~~~~~~~~~~~~~~~~~
 146 option:-h, option:--help::
 147     Show help.
 148
 149 option:-V, option:--version::
 150     Show version.
 151
 152
 153 ENVIRONMENT VARIABLES
 154 ---------------------
 155 `LTTNG_ABORT_ON_ERROR`::
 156     Set to 1 to abort the process after the first error is encountered.
 157
 158 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 159     Socket connection, receive and send timeout (milliseconds). A value
 160     of 0 or -1 uses the timeout of the operating system (default).
 161
 162 `LTTNG_RELAYD_HEALTH`::
 163     Path to relay daemon health's socket.
 164
 165 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
 166     Set to 1 to enable TCP keep-alive.
 167 +
 168 The TCP keep-alive mechanism allows the detection of dead peers
 169 (man:lttng-sessiond(8)) in cases of unclean termination
 170 (for example, a hard reset) of a peer.
 171 +
 172 Supported on Linux and Solaris only. The default behaviour of the TCP
 173 keep-alive mechanism is OS-specific.
 174 +
 175 Search for `tcp_keepalive` in man:tcp(7) for more information.
 176
 177 `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
 178    The time threshold in seconds to abort a TCP connection after the keep-alive
 179    probing mechanism has failed.
 180 +
 181 Set to 0 or -1 to use the value chosen by the operating system (default).
 182 +
 183 Supported on Solaris 11 only.
 184 +
 185 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information.
 186
 187 `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
 188     Number of seconds a connection needs to be idle before TCP begins
 189     sending out keep-alive probes.
 190 +
 191 Set to 0 or -1 to use the value chosen by the operating system (default).
 192 +
 193 Supported on Linux and Solaris 11 only.
 194 +
 195 On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000.
 196 +
 197 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
 198 in man:tcp(7) on Solaris 11 for more information.
 199
 200 `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
 201     Maximum number of TCP keep-alive probes to send before giving up and
 202     killing the connection if no response is obtained from the other end.
 203 +
 204 Set to 0 or -1 to use the value chosen by the operating system (default).
 205 +
 206 Supported on Linux only.
 207 +
 208 Search for `tcp_keepalive_probes` in man:tcp(7) for more information.
 209
 210 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
 211     Number of seconds between TCP keep-alive probes.
 212 +
 213 Set to 0 or -1 to use the value chosen by the operating system (default).
 214 +
 215 Supported on Linux only.
 216 +
 217 Search for `tcp_keepalive_intvl` in man:tcp(7) for more information.
 218
 219
 220 FILES
 221 -----
 222 `$LTTNG_HOME/.lttng`::
 223     User LTTng runtime and configuration directory.
 224
 225 `$LTTNG_HOME/lttng-traces`::
 226     Default output directory of LTTng traces. This can be overridden
 227     with the option:--output option.
 228
 229 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
 230
 231
 232 EXIT STATUS
 233 -----------
 234 *0*::
 235     Success
 236
 237 *1*::
 238     Error
 239
 240 *3*::
 241     Fatal error
 242
 243
 244 LIMITATIONS
 245 -----------
 246 As of this version, only the TCP protocol is supported for both control
 247 and data ports. In future versions, TCP will remain the sole available
 248 protocol for control data since those communications are low-volume and
 249 need absolute reliability; trace data could be carried over UDP.
 250
 251 For an unprivileged user running `lttng-relayd`, the maximum number of
 252 file descriptors per process is usually 1024. This limits the number of
 253 connections and opened trace files. This limit can be configured with
 254 *ulimit*(3).
 255
 256
 257 include::common-footer.txt[]
 258
 259
 260 SEE ALSO
 261 --------
 262 man:lttng(1),
 263 man:lttng-sessiond(8),
 264 man:lttng-crash(1),
 265 man:lttng-ust(3),
 266 man:babeltrace(1)