doc/man/lttng-relayd.8.txt

   1 lttng-relayd(8)
   2 ===============
   3 :revdate: 30 April 2021
   4 :daemon-bin-name: lttng-relayd
   5 :daemon-ini-section: relayd
   6
   7
   8 NAME
   9 ----
  10 lttng-relayd - LTTng relay daemon
  11
  12
  13 SYNOPSIS
  14 --------
  15 [verse]
  16 *lttng-relayd* [option:--background | option:--daemonize] [option:--config='PATH']
  17              [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT']
  18              [option:--live-port='URL'] [option:--output='DIR'] [option:--group='GROUP']
  19              [option:--verbose]... [option:--working-directory='DIR']
  20              [option:--group-output-by-host | option:--group-output-by-session] [option:--disallow-clear]
  21
  22
  23 DESCRIPTION
  24 -----------
  25 include::common-intro.txt[]
  26
  27 An LTTng relay daemon, `lttng-relayd`, is a program which receives trace
  28 data from (possibly remote) LTTng session/consumer daemons and which
  29 writes it to the local file system. The relay daemon also accepts LTTng
  30 live connections from compatible readers (for example,
  31 man:babeltrace2(1)); this is the recommended approach to read trace data
  32 while the remote tracing session is active.
  33
  34 By default, a relay daemon listens on all network interfaces to receive
  35 trace data, but only on `localhost` for LTTng live connections. Override
  36 the listening URLs with the option:--control-port, option:--data-port,
  37 and option:--live-port options (see the <<url-format,URL format>>
  38 section below). For example, use the
  39 option:--live-port=+tcp://0.0.0.0:{default_network_viewer_port}+ option
  40 to make a relay daemon listen to LTTng live connections on all network
  41 interfaces.
  42
  43 Once LTTng has completely sent a trace to a relay daemon{nbsp}__RD__,
  44 any LTTng trace reader can read the trace located on the local file
  45 system of{nbsp}__RD__.
  46
  47 By default, `lttng-relayd` doesn't start as a daemon. Make it a daemon
  48 with the option:--daemonize or option:--background option. With those
  49 options, `lttng-relayd` ensures the daemon is listening to incoming
  50 connections before it exits.
  51
  52
  53 include::common-daemon-cfg.txt[]
  54
  55 INI configuration file example:
  56
  57 [source,ini]
  58 ----
  59 [relayd]
  60 daemonize=yes
  61 live-port=tcp://0.0.0.0:4567
  62 disallow-clear=yes
  63 ----
  64
  65
  66 [[output-directory]]
  67 Output directory
  68 ~~~~~~~~~~~~~~~~
  69 The relay daemon uses different output path patterns depending on:
  70
  71 * Its configuration.
  72 +
  73 See the <<cfg,Daemon configuration>> section above.
  74
  75 * The tracing session configuration of the connected peer.
  76 * The LTTng session daemon (see man:lttng-sessiond(8)) version
  77   of the connected peer.
  78
  79 Consider the following variables:
  80
  81 'BASE'::
  82     Base output directory: `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
  83     defaults to `$HOME`) or the argument of the option:--output option.
  84
  85 'HOSTNAME'::
  86     Hostname of the connected peer.
  87
  88 'SESSION'::
  89     Tracing session name.
  90
  91 'DATETIME'::
  92     Unique tracing session date/time.
  93
  94 'TRACEDIR'::
  95     Custom trace directory path ('TRACEDIR' part of the argument of the
  96     nloption:--set-url option of the man:lttng-create(1) command, if
  97     any).
  98
  99 'SESSIONDV'::
 100     The version of the LTTng session daemon of the connected peer.
 101
 102 The relay daemon output path patterns are:
 103
 104 With the option:--group-output-by-host option (hostname grouping)::
 105     Without a custom trace directory:::
 106 +
 107 [verse]
 108 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
 109
 110 With a custom trace directory:::
 111 +
 112 [verse]
 113 'BASE'/'HOSTNAME'/'TRACEDIR'
 114
 115 With the option:--group-output-by-session option (tracing session grouping)::
 116     Without a custom trace directory:::
 117         'SESSIONDV' is at least{nbsp}2.4::::
 118 +
 119 [verse]
 120 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'
 121
 122 Otherwise::::
 123     Defaults to the hostname grouping pattern:
 124 +
 125 [verse]
 126 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
 127
 128 With a custom trace directory:::
 129     'SESSIONDV' is at least 2.4::::
 130 +
 131 [verse]
 132 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEDIR'
 133
 134 Otherwise::::
 135     Defaults to the hostname grouping pattern:
 136 +
 137 [verse]
 138 'BASE'/'HOSTNAME'/'TRACEDIR'
 139
 140
 141 [[url-format]]
 142 URL format
 143 ~~~~~~~~~~
 144 The argument of the option:--control-port='URL',
 145 option:--data-port='URL', and option:--live-port='URL' options is an
 146 URL.
 147
 148 The format of 'URL' is:
 149
 150 [verse]
 151 tcp://('HOST' | 'IPADDR'):__PORT__
 152
 153 with:
 154
 155 ('HOST' | 'IPADDR')::
 156     Binding hostname or IP address.
 157 +
 158 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
 159 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
 160
 161 'PORT'::
 162     TCP port.
 163
 164
 165 [[options]]
 166 OPTIONS
 167 -------
 168 General daemon configuration
 169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 170 option:-b, option:--background::
 171     Start as a Unix daemon, but keep file descriptors (console) open.
 172 +
 173 With this option, `lttng-relayd` ensures the daemon is listening
 174 to incoming connections before it exits.
 175 +
 176 Use the option:--daemonize option instead to close the file descriptors.
 177
 178 option:-f 'PATH', option:--config='PATH'::
 179     Configure the daemon using the INI configuration file 'PATH' in
 180     addition to the default configuration files and the command-line
 181     options.
 182 +
 183 See the <<cfg,Daemon configuration>> section above.
 184
 185 option:-d, option:--daemonize::
 186     Start as a Unix daemon and close file descriptors (console).
 187 +
 188 With this option, `lttng-relayd` ensures the daemon is listening
 189 to incoming connections before it exits.
 190 +
 191 Use the option:--background option instead to keep the file descriptors
 192 open.
 193
 194 option:-x, option:--disallow-clear::
 195     Disallow clearing operations (see man:lttng-clear(1)).
 196 +
 197 See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable.
 198
 199 option:--fd-pool-size='SIZE'::
 200     Set the size of the file descriptor pool to 'SIZE' file descriptors.
 201 +
 202 'SIZE' is the maximum number of file descriptors that the relay daemon
 203 may keep open simultaneously.
 204 +
 205 Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
 206 man:getrlimit(2)).
 207
 208 option:-g 'GROUP', option:--group='GROUP'::
 209     Set the Unix tracing group to 'GROUP' instead of `tracing`.
 210 +
 211 This option is only meaningful when the `root` Unix user starts
 212 `lttng-relayd`.
 213 +
 214 Members of the Unix tracing group may connect to the health check socket
 215 of the relay daemon.
 216 +
 217 See also the `LTTNG_RELAYD_HEALTH` environment variable.
 218
 219 option:-w 'DIR', option:--working-directory='DIR'::
 220     Set the working directory of the processes the relay daemon creates
 221     to 'DIR'.
 222 +
 223 See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.
 224
 225 option:-v, option:--verbose::
 226     Increase verbosity.
 227 +
 228 Specify this option up to three times to get more levels of verbosity.
 229
 230
 231 Output
 232 ~~~~~~
 233 See the <<output-directory,Output directory>> section above to learn
 234 more.
 235
 236 option:-p, option:--group-output-by-host::
 237     Group the written trace directories by hostname.
 238 +
 239 As of LTTng{nbsp}{lttng_version}, this is the default output grouping
 240 strategy, but this may change in the future.
 241
 242 option:-s, option:--group-output-by-session::
 243     Group the written trace directories by tracing session name instead
 244     of by hostname.
 245
 246 option:-o 'DIR', option:--output='DIR'::
 247     Set the base output directory of the written trace directories to
 248     'DIR'.
 249
 250
 251 Ports
 252 ~~~~~
 253 See the <<url-format,URL format>> section above to learn more about the
 254 syntax of the 'URL' argument of the following options.
 255
 256 option:-C 'URL', option:--control-port='URL'::
 257     Listen to control data on URL 'URL'.
 258 +
 259 Default:
 260 +tcp://{default_network_control_bind_address}:{default_network_control_port}+.
 261
 262 option:-D 'URL', option:--data-port='URL'::
 263     Listen to trace data on URL 'URL'.
 264 +
 265 Default:
 266 +tcp://{default_network_data_bind_address}:{default_network_data_port}+.
 267
 268 option:-L 'URL', option:--live-port='URL'::
 269     Listen to LTTng live connections on URL 'URL'.
 270 +
 271 Default:
 272 +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
 273
 274
 275 Program information
 276 ~~~~~~~~~~~~~~~~~~~
 277 include::common-help-option.txt[]
 278
 279 option:-V, option:--version::
 280     Show version and quit.
 281
 282
 283 ENVIRONMENT VARIABLES
 284 ---------------------
 285 `LTTNG_ABORT_ON_ERROR`::
 286     Set to `1` to abort the process after the first error is
 287     encountered.
 288
 289 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 290     Socket connection, receive, and send timeout (milliseconds).
 291 +
 292 Set to `0` or `-1` to set an infinite timeout (default).
 293
 294 `LTTNG_RELAYD_DISALLOW_CLEAR`::
 295     Set to `1` to disallow clearing operations (see man:lttng-clear(1)).
 296 +
 297 The option:--disallow-clear option overrides this environment variable.
 298
 299 `LTTNG_RELAYD_HEALTH`::
 300     Path to the health check socket of the relay daemon.
 301
 302 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
 303     Set to `1` to enable TCP keep-alive.
 304 +
 305 The TCP keep-alive mechanism allows the detection of dead peers
 306 (man:lttng-sessiond(8)) in cases of unclean termination (for example, a
 307 hard reset) of a peer.
 308 +
 309 Supported on Linux and Solaris only. The default behaviour of the TCP
 310 keep-alive mechanism is OS-specific.
 311 +
 312 Search for `tcp_keepalive` in man:tcp(7) to learn more.
 313
 314 `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
 315    The time threshold (seconds) to abort a TCP connection after the
 316    keep-alive probing mechanism has failed.
 317 +
 318 Set to `0` or `-1` to use the value chosen by the operating system
 319 (default).
 320 +
 321 Supported on Solaris 11 only.
 322 +
 323 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more.
 324
 325 `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
 326     Number of seconds a connection needs to be idle before TCP begins
 327     sending out keep-alive probes.
 328 +
 329 Set to `0` or `-1` to use the value chosen by the operating system
 330 (default).
 331 +
 332 Supported on Linux and Solaris 11 only.
 333 +
 334 On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to
 335 `864000`.
 336 +
 337 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
 338 in man:tcp(7) on Solaris{nbsp}11 to learn more.
 339
 340 `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
 341     Maximum number of TCP keep-alive probes to send before giving up and
 342     killing the connection if no response is obtained from the other end.
 343 +
 344 Set to `0` or `-1` to use the value chosen by the operating system
 345 (default).
 346 +
 347 Supported on Linux only.
 348 +
 349 Search for `tcp_keepalive_probes` in man:tcp(7) to learn more.
 350
 351 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
 352     Number of seconds between TCP keep-alive probes.
 353 +
 354 Set to `0` or `-1` to use the value chosen by the operating system
 355 (default).
 356 +
 357 Supported on Linux only.
 358 +
 359 Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more.
 360
 361 `LTTNG_RELAYD_WORKING_DIRECTORY`::
 362     Working directory of the processes the relay daemon creates.
 363 +
 364 The option:--working-directory option overrides this environment
 365 variable.
 366
 367
 368 FILES
 369 -----
 370 `$LTTNG_HOME/.lttng`::
 371     Unix user's LTTng runtime and configuration directory.
 372
 373 `$LTTNG_HOME/lttng-traces`::
 374     Default base output directory of LTTng traces.
 375 +
 376 Override this path with the option:--output option.
 377
 378 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
 379
 380
 381 EXIT STATUS
 382 -----------
 383 *0*::
 384     Success
 385
 386 *1*::
 387     Error
 388
 389 *3*::
 390     Fatal error
 391
 392
 393 include::common-footer.txt[]
 394
 395
 396 SEE ALSO
 397 --------
 398 man:lttng(1),
 399 man:lttng-sessiond(8),
 400 man:babeltrace2(1)