doc: Fix bind address example for lttng-relayd
[lttng-tools.git] / doc / man / lttng-relayd.8.txt
CommitLineData
f5595c32
PP
1lttng-relayd(8)
2===============
4605890e 3:revdate: 5 June 2018
f5595c32
PP
4
5
6NAME
7----
8lttng-relayd - LTTng 2 relay daemon
9
10
11SYNOPSIS
12--------
13[verse]
14*lttng-relayd* [option:--background | option:--daemonize]
15 [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL']
16 [option:--output='PATH'] [option:-v | option:-vv | option:-vvv]
6ab3f69a 17 [option:--working-directory='PATH']
04dedfc0 18 [option:--group-output-by-session | option:--group-output-by-host]
f5595c32
PP
19
20DESCRIPTION
21-----------
a18d9544 22The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
f5595c32
PP
23source software package used for correlated tracing of the Linux kernel,
24user applications, and user libraries.
25
26LTTng consists of Linux kernel modules (for Linux kernel tracing) and
27dynamically loaded libraries (for user application and library tracing).
28
29The _LTTng relay daemon_ is responsible for receiving trace data from
30possibly remote LTTng session/consumer daemons and for writing it to
31the local file system. The relay daemon also accepts _LTTng live_
32connections from compatible viewers; this is the official approach to
33viewing LTTng events as they are emitted.
34
35The relay daemon listens by default on all network interfaces to gather
36trace data, but only on localhost for LTTng live connections.
37
38The relay daemon does not require any particular permissions, as long as
39it can write to the output directory and listen on the configured ports.
40If a user is within a secured network and/or has proper firewall
41settings, `lttng-relayd` can listen to LTTng live connections from _all_
c93eadad 42network interfaces by specifying
e9b02942 43+--live-port=tcp://0.0.0.0:{default_network_viewer_port}+.
f5595c32
PP
44
45Once a trace has been streamed completely, the trace can be processed by
46any tool that can process an LTTng trace located on the local
47file system.
48
49
50[[output-directory]]
51Output directory
52~~~~~~~~~~~~~~~~
04dedfc0
JR
53By default (option:--group-output-by-host), the relay daemon writes the traces
54to:
f5595c32
PP
55
56[verse]
2ff6d569 57$LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
f5595c32
PP
58
59with:
60
61'HOSTNAME'::
62 Remote hostname.
63
64'SESSION'::
65 Full session name.
66
67'DOMAIN'::
68 Tracing domain.
69
04dedfc0
JR
70You can group the output per session instead of per hostname with the
71option:--group-output-by-session option. This result in the following:
72
73[verse]
74
75$LTTNG_HOME/lttng-traces/'SESSION'/'HOST'/'DOMAIN'
76
f5595c32 77You can override the default output directory prefix
2ff6d569 78(`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other
f5595c32
PP
79parts depend on the remote configuration.
80
04dedfc0
JR
81Grouping by session is not supported for peers with version inferior to 2.4.
82In such cases, the grouping of output for that particular peer will be per host
83(default).
84
85A best effort backward compatibility is done for peers version greater or equal to
862.4 and smaller than 2.11.
f5595c32
PP
87
88[[url-format]]
89URL format
90~~~~~~~~~~
91The option:--control-port, option:--data-port, and option:--live-port
92options specify URLs.
93
94The format of those URLs is:
95
96[verse]
97tcp://('HOST' | 'IPADDR'):__PORT__
98
99with:
100
101('HOST' | 'IPADDR')::
102 Binding hostname or IP address (IPv6 address *must* be enclosed in
103 brackets (`[` and `]`); see
104 https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
105
106'PORT'::
107 TCP port.
108
109
110OPTIONS
111-------
112Daemon
113~~~~~~
114option:-b, option:--background::
115 Start as Unix daemon, but keep file descriptors (console) open.
116 Use the option:--daemonize option instead to close the file
117 descriptors.
118
119option:-d, option:--daemonize::
120 Start as Unix daemon, and close file descriptors (console). Use the
121 option:--background option instead to keep the file descriptors
122 open.
123
59b19c3c 124option:-g 'GROUP', option:--group='GROUP'::
f5595c32
PP
125 Use 'GROUP' as Unix tracing group (default: `tracing`).
126
59b19c3c 127option:-o 'PATH', option:--output='PATH'::
f5595c32
PP
128 Set base directory of written trace data to 'PATH'.
129+
130See the <<output-directory,Output directory>> section above for more
131information.
132
04dedfc0
JR
133option:-p, option:--group-output-by-host::
134 Organize the output directory by host. Default behavior.
135+
136See the <<output-directory,Output directory>> section above for more
137information.
138
139option:-s, option:--group-output-by-session::
140 Organize the output directory by session.
141+
142See the <<output-directory,Output directory>> section above for more
143information.
144
6ab3f69a
JR
145option:-w 'PATH', option:--working-directory='PATH'::
146 Set the working directory of the processes this relay daemon creates.
147
f5595c32
PP
148option:-v, option:--verbose::
149 Increase verbosity.
150+
151Three levels of verbosity are available, which are triggered by
152appending additional `v` letters to the option
153(that is, `-vv` and `-vvv`).
154
155
156Ports
157~~~~~
158See the <<url-format,URL format>> section above for more information
159about the syntax of the following options' 'URL' argument.
160
59b19c3c 161option:-C 'URL', option:--control-port='URL'::
c93eadad
PP
162 Listen to control data on URL 'URL' (default:
163 +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
f5595c32 164
59b19c3c 165option:-D 'URL', option:--data-port='URL'::
c93eadad
PP
166 Listen to trace data on URL 'URL' (default:
167 +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
f5595c32 168
59b19c3c 169option:-L 'URL', option:--live-port='URL'::
f5595c32 170 Listen to LTTng live connections on URL 'URL'
c93eadad
PP
171 (default:
172 +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
f5595c32
PP
173
174
175Program information
176~~~~~~~~~~~~~~~~~~~
177option:-h, option:--help::
178 Show help.
179
180option:-V, option:--version::
181 Show version.
182
183
184ENVIRONMENT VARIABLES
185---------------------
9bbd8e06
MD
186`LTTNG_ABORT_ON_ERROR`::
187 Set to 1 to abort the process after the first error is encountered.
188
f5595c32
PP
189`LTTNG_NETWORK_SOCKET_TIMEOUT`::
190 Socket connection, receive and send timeout (milliseconds). A value
191 of 0 or -1 uses the timeout of the operating system (default).
192
06e1d71f
MD
193`LTTNG_RELAYD_DISALLOW_CLEAR`::
194 Set to 1 to disallow the use of lttng-clear(1) on sessions collected by
195 this relay daemon.
196
f5595c32
PP
197`LTTNG_RELAYD_HEALTH`::
198 Path to relay daemon health's socket.
199
e0512bf5
JR
200`LTTNG_RELAYD_TCP_KEEP_ALIVE`::
201 Set to 1 to enable TCP keep-alive.
202+
203The TCP keep-alive mechanism allows the detection of dead peers
204(man:lttng-sessiond(8)) in cases of unclean termination
205(for example, a hard reset) of a peer.
206+
207Supported on Linux and Solaris only. The default behaviour of the TCP
208keep-alive mechanism is OS-specific.
209+
210Search for `tcp_keepalive` in man:tcp(7) for more information.
211
212`LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
213 The time threshold in seconds to abort a TCP connection after the keep-alive
214 probing mechanism has failed.
215+
216Set to 0 or -1 to use the value chosen by the operating system (default).
217+
218Supported on Solaris 11 only.
219+
220Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information.
221
222`LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
223 Number of seconds a connection needs to be idle before TCP begins
224 sending out keep-alive probes.
225+
226Set to 0 or -1 to use the value chosen by the operating system (default).
227+
228Supported on Linux and Solaris 11 only.
229+
230On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000.
231+
232Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
233in man:tcp(7) on Solaris 11 for more information.
234
235`LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
236 Maximum number of TCP keep-alive probes to send before giving up and
237 killing the connection if no response is obtained from the other end.
238+
239Set to 0 or -1 to use the value chosen by the operating system (default).
240+
241Supported on Linux only.
242+
243Search for `tcp_keepalive_probes` in man:tcp(7) for more information.
244
245`LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
246 Number of seconds between TCP keep-alive probes.
247+
248Set to 0 or -1 to use the value chosen by the operating system (default).
249+
250Supported on Linux only.
251+
252Search for `tcp_keepalive_intvl` in man:tcp(7) for more information.
253
508a802c
JR
254`LTTNG_RELAYD_WORKING_DIRECTORY`::
255 Working directory of the processes this relay daemon creates.
256+
257The option:--working-directory option overrides this variable.
258
f5595c32 259
900690ca
PP
260FILES
261-----
262`$LTTNG_HOME/.lttng`::
263 User LTTng runtime and configuration directory.
264
265`$LTTNG_HOME/lttng-traces`::
266 Default output directory of LTTng traces. This can be overridden
267 with the option:--output option.
268
269NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
270
271
f5595c32
PP
272EXIT STATUS
273-----------
274*0*::
275 Success
276
277*1*::
278 Error
279
280*3*::
281 Fatal error
282
283
284LIMITATIONS
285-----------
286As of this version, only the TCP protocol is supported for both control
287and data ports. In future versions, TCP will remain the sole available
288protocol for control data since those communications are low-volume and
289need absolute reliability; trace data could be carried over UDP.
290
291For an unprivileged user running `lttng-relayd`, the maximum number of
292file descriptors per process is usually 1024. This limits the number of
293connections and opened trace files. This limit can be configured with
294*ulimit*(3).
295
296
297include::common-footer.txt[]
298
299
300SEE ALSO
301--------
7c1a4458
PP
302man:lttng(1),
303man:lttng-sessiond(8),
304man:lttng-crash(1),
305man:lttng-ust(3),
306man:babeltrace(1)
This page took 0.039046 seconds and 4 git commands to generate.