doc/man: use double quotes when referring to internal section
[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
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)
This page took 0.042779 seconds and 6 git commands to generate.