doc/man/lttng-relayd.8.txt

   1 lttng-relayd(8)
   2 ===============
   3 :revdate: 14 June 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 recording 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 recording 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     Recording session name.
  90
  91 'DATETIME'::
  92     Unique recording 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 (recording 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 recording session name
 244     instead 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
 254 the 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 EXIT STATUS
 284 -----------
 285 *0*::
 286     Success
 287
 288 *1*::
 289     Error
 290
 291 *3*::
 292     Fatal error
 293
 294
 295 ENVIRONMENT
 296 -----------
 297 `LTTNG_ABORT_ON_ERROR`::
 298     Set to `1` to abort the process after the first error is
 299     encountered.
 300
 301 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 302     Socket connection, receive, and send timeout (milliseconds).
 303 +
 304 Set to `0` or `-1` to set an infinite timeout (default).
 305
 306 `LTTNG_RELAYD_DISALLOW_CLEAR`::
 307     Set to `1` to disallow clearing operations (see man:lttng-clear(1)).
 308 +
 309 The option:--disallow-clear option overrides this environment variable.
 310
 311 `LTTNG_RELAYD_HEALTH`::
 312     Path to the health check socket of the relay daemon.
 313
 314 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
 315     Set to `1` to enable TCP keep-alive.
 316 +
 317 The TCP keep-alive mechanism allows the detection of dead peers
 318 (man:lttng-sessiond(8)) in cases of unclean termination (for example, a
 319 hard reset) of a peer.
 320 +
 321 Supported on Linux and Solaris only. The default behaviour of the TCP
 322 keep-alive mechanism is OS-specific.
 323 +
 324 Search for `tcp_keepalive` in man:tcp(7) to learn more.
 325
 326 `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
 327    The time threshold (seconds) to abort a TCP connection after the
 328    keep-alive probing mechanism has failed.
 329 +
 330 Set to `0` or `-1` to use the value chosen by the operating system
 331 (default).
 332 +
 333 Supported on Solaris 11 only.
 334 +
 335 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more.
 336
 337 `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
 338     Number of seconds a connection needs to be idle before TCP begins
 339     sending out keep-alive probes.
 340 +
 341 Set to `0` or `-1` to use the value chosen by the operating system
 342 (default).
 343 +
 344 Supported on Linux and Solaris 11 only.
 345 +
 346 On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to
 347 `864000`.
 348 +
 349 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
 350 in man:tcp(7) on Solaris{nbsp}11 to learn more.
 351
 352 `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
 353     Maximum number of TCP keep-alive probes to send before giving up and
 354     killing the connection if no response is obtained from the other end.
 355 +
 356 Set to `0` or `-1` to use the value chosen by the operating system
 357 (default).
 358 +
 359 Supported on Linux only.
 360 +
 361 Search for `tcp_keepalive_probes` in man:tcp(7) to learn more.
 362
 363 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
 364     Number of seconds between TCP keep-alive probes.
 365 +
 366 Set to `0` or `-1` to use the value chosen by the operating system
 367 (default).
 368 +
 369 Supported on Linux only.
 370 +
 371 Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more.
 372
 373 `LTTNG_RELAYD_WORKING_DIRECTORY`::
 374     Working directory of the processes the relay daemon creates.
 375 +
 376 The option:--working-directory option overrides this environment
 377 variable.
 378
 379
 380 FILES
 381 -----
 382 `$LTTNG_HOME/.lttng`::
 383     Unix user's LTTng runtime and configuration directory.
 384
 385 `$LTTNG_HOME/lttng-traces`::
 386     Default base output directory of LTTng traces.
 387 +
 388 Override this path with the option:--output option.
 389
 390 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
 391
 392
 393 include::common-footer.txt[]
 394
 395
 396 SEE ALSO
 397 --------
 398 man:babeltrace2(1),
 399 man:lttng(1),
 400 man:lttng-sessiond(8)