694eb49955852411ad650ef6c0cd30213a5d2a57
[lttng-tools.git] / 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)
This page took 0.040243 seconds and 5 git commands to generate.