3 :revdate: 30 April 2021
4 :daemon-bin-name: lttng-relayd
5 :daemon-ini-section: relayd
10 lttng-relayd - LTTng relay daemon
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]
25 include::common-intro.txt[]
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.
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
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__.
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.
53 include::common-daemon-cfg.txt[]
55 INI configuration file example:
61 live-port=tcp://0.0.0.0:4567
69 The relay daemon uses different output path patterns depending on:
73 See the ``<<cfg,Daemon configuration>>'' section above.
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.
79 Consider the following variables:
82 Base output directory: `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
83 defaults to `$HOME`) or the argument of the option:--output option.
86 Hostname of the connected peer.
92 Unique tracing session date/time.
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
100 The version of the LTTng session daemon of the connected peer.
102 The relay daemon output path patterns are:
104 With the option:--group-output-by-host option (hostname grouping)::
105 Without a custom trace directory:::
108 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
110 With a custom trace directory:::
113 'BASE'/'HOSTNAME'/'TRACEDIR'
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::::
120 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'
123 Defaults to the hostname grouping pattern:
126 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
128 With a custom trace directory:::
129 'SESSIONDV' is at least 2.4::::
132 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEDIR'
135 Defaults to the hostname grouping pattern:
138 'BASE'/'HOSTNAME'/'TRACEDIR'
144 The argument of the option:--control-port='URL',
145 option:--data-port='URL', and option:--live-port='URL' options is an
148 The format of 'URL' is:
151 tcp://('HOST' | 'IPADDR'):__PORT__
155 ('HOST' | 'IPADDR')::
156 Binding hostname or IP address.
158 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
159 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
168 General daemon configuration
169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170 option:-b, option:--background::
171 Start as a Unix daemon, but keep file descriptors (console) open.
173 With this option, `lttng-relayd` ensures the daemon is listening
174 to incoming connections before it exits.
176 Use the option:--daemonize option instead to close the file descriptors.
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
183 See the ``<<cfg,Daemon configuration>>'' section above.
185 option:-d, option:--daemonize::
186 Start as a Unix daemon and close file descriptors (console).
188 With this option, `lttng-relayd` ensures the daemon is listening
189 to incoming connections before it exits.
191 Use the option:--background option instead to keep the file descriptors
194 option:-x, option:--disallow-clear::
195 Disallow clearing operations (see man:lttng-clear(1)).
197 See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable.
199 option:--fd-pool-size='SIZE'::
200 Set the size of the file descriptor pool to 'SIZE' file descriptors.
202 'SIZE' is the maximum number of file descriptors that the relay daemon
203 may keep open simultaneously.
205 Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
208 option:-g 'GROUP', option:--group='GROUP'::
209 Set the Unix tracing group to 'GROUP' instead of `tracing`.
211 This option is only meaningful when the `root` Unix user starts
214 Members of the Unix tracing group may connect to the health check socket
217 See also the `LTTNG_RELAYD_HEALTH` environment variable.
219 option:-w 'DIR', option:--working-directory='DIR'::
220 Set the working directory of the processes the relay daemon creates
223 See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.
225 option:-v, option:--verbose::
228 Specify this option up to three times to get more levels of verbosity.
233 See the ``<<output-directory,Output directory>>'' section above to learn
236 option:-p, option:--group-output-by-host::
237 Group the written trace directories by hostname.
239 As of LTTng{nbsp}{lttng_version}, this is the default output grouping
240 strategy, but this may change in the future.
242 option:-s, option:--group-output-by-session::
243 Group the written trace directories by tracing session name instead
246 option:-o 'DIR', option:--output='DIR'::
247 Set the base output directory of the written trace directories to
253 See the ``<<url-format,URL format>>'' section above to learn more about
254 the syntax of the 'URL' argument of the following options.
256 option:-C 'URL', option:--control-port='URL'::
257 Listen to control data on URL 'URL'.
260 +tcp://{default_network_control_bind_address}:{default_network_control_port}+.
262 option:-D 'URL', option:--data-port='URL'::
263 Listen to trace data on URL 'URL'.
266 +tcp://{default_network_data_bind_address}:{default_network_data_port}+.
268 option:-L 'URL', option:--live-port='URL'::
269 Listen to LTTng live connections on URL 'URL'.
272 +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
277 include::common-help-option.txt[]
279 option:-V, option:--version::
280 Show version and quit.
297 `LTTNG_ABORT_ON_ERROR`::
298 Set to `1` to abort the process after the first error is
301 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
302 Socket connection, receive, and send timeout (milliseconds).
304 Set to `0` or `-1` to set an infinite timeout (default).
306 `LTTNG_RELAYD_DISALLOW_CLEAR`::
307 Set to `1` to disallow clearing operations (see man:lttng-clear(1)).
309 The option:--disallow-clear option overrides this environment variable.
311 `LTTNG_RELAYD_HEALTH`::
312 Path to the health check socket of the relay daemon.
314 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
315 Set to `1` to enable TCP keep-alive.
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.
321 Supported on Linux and Solaris only. The default behaviour of the TCP
322 keep-alive mechanism is OS-specific.
324 Search for `tcp_keepalive` in man:tcp(7) to learn more.
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.
330 Set to `0` or `-1` to use the value chosen by the operating system
333 Supported on Solaris 11 only.
335 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more.
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.
341 Set to `0` or `-1` to use the value chosen by the operating system
344 Supported on Linux and Solaris 11 only.
346 On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to
349 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
350 in man:tcp(7) on Solaris{nbsp}11 to learn more.
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.
356 Set to `0` or `-1` to use the value chosen by the operating system
359 Supported on Linux only.
361 Search for `tcp_keepalive_probes` in man:tcp(7) to learn more.
363 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
364 Number of seconds between TCP keep-alive probes.
366 Set to `0` or `-1` to use the value chosen by the operating system
369 Supported on Linux only.
371 Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more.
373 `LTTNG_RELAYD_WORKING_DIRECTORY`::
374 Working directory of the processes the relay daemon creates.
376 The option:--working-directory option overrides this environment
382 `$LTTNG_HOME/.lttng`::
383 Unix user's LTTng runtime and configuration directory.
385 `$LTTNG_HOME/lttng-traces`::
386 Default base output directory of LTTng traces.
388 Override this path with the option:--output option.
390 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
393 include::common-footer.txt[]
400 man:lttng-sessiond(8)