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 the
254 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.
283 ENVIRONMENT VARIABLES
284 ---------------------
285 `LTTNG_ABORT_ON_ERROR`::
286 Set to `1` to abort the process after the first error is
289 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
290 Socket connection, receive, and send timeout (milliseconds).
292 Set to `0` or `-1` to set an infinite timeout (default).
294 `LTTNG_RELAYD_DISALLOW_CLEAR`::
295 Set to `1` to disallow clearing operations (see man:lttng-clear(1)).
297 The option:--disallow-clear option overrides this environment variable.
299 `LTTNG_RELAYD_HEALTH`::
300 Path to the health check socket of the relay daemon.
302 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
303 Set to `1` to enable TCP keep-alive.
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.
309 Supported on Linux and Solaris only. The default behaviour of the TCP
310 keep-alive mechanism is OS-specific.
312 Search for `tcp_keepalive` in man:tcp(7) to learn more.
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.
318 Set to `0` or `-1` to use the value chosen by the operating system
321 Supported on Solaris 11 only.
323 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more.
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.
329 Set to `0` or `-1` to use the value chosen by the operating system
332 Supported on Linux and Solaris 11 only.
334 On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to
337 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
338 in man:tcp(7) on Solaris{nbsp}11 to learn more.
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.
344 Set to `0` or `-1` to use the value chosen by the operating system
347 Supported on Linux only.
349 Search for `tcp_keepalive_probes` in man:tcp(7) to learn more.
351 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
352 Number of seconds between TCP keep-alive probes.
354 Set to `0` or `-1` to use the value chosen by the operating system
357 Supported on Linux only.
359 Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more.
361 `LTTNG_RELAYD_WORKING_DIRECTORY`::
362 Working directory of the processes the relay daemon creates.
364 The option:--working-directory option overrides this environment
370 `$LTTNG_HOME/.lttng`::
371 Unix user's LTTng runtime and configuration directory.
373 `$LTTNG_HOME/lttng-traces`::
374 Default base output directory of LTTng traces.
376 Override this path with the option:--output option.
378 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
393 include::common-footer.txt[]
399 man:lttng-sessiond(8),