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