Man: move [SESSION] before options
[lttng-tools.git] / doc / man / lttng-relayd.8.txt
CommitLineData
f5595c32
PP
1lttng-relayd(8)
2===============
3
4
5NAME
6----
7lttng-relayd - LTTng 2 relay daemon
8
9
10SYNOPSIS
11--------
12[verse]
13*lttng-relayd* [option:--background | option:--daemonize]
14 [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL']
15 [option:--output='PATH'] [option:-v | option:-vv | option:-vvv]
16
17
18DESCRIPTION
19-----------
20The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
21source software package used for correlated tracing of the Linux kernel,
22user applications, and user libraries.
23
24LTTng consists of Linux kernel modules (for Linux kernel tracing) and
25dynamically loaded libraries (for user application and library tracing).
26
27The _LTTng relay daemon_ is responsible for receiving trace data from
28possibly remote LTTng session/consumer daemons and for writing it to
29the local file system. The relay daemon also accepts _LTTng live_
30connections from compatible viewers; this is the official approach to
31viewing LTTng events as they are emitted.
32
33The relay daemon listens by default on all network interfaces to gather
34trace data, but only on localhost for LTTng live connections.
35
36The relay daemon does not require any particular permissions, as long as
37it can write to the output directory and listen on the configured ports.
38If a user is within a secured network and/or has proper firewall
39settings, `lttng-relayd` can listen to LTTng live connections from _all_
c93eadad
PP
40network interfaces by specifying
41+--live-port=tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
f5595c32
PP
42
43Once a trace has been streamed completely, the trace can be processed by
44any tool that can process an LTTng trace located on the local
45file system.
46
47
48[[output-directory]]
49Output directory
50~~~~~~~~~~~~~~~~
51By default, the relay daemon writes the traces to:
52
53[verse]
2ff6d569 54$LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
f5595c32
PP
55
56with:
57
58'HOSTNAME'::
59 Remote hostname.
60
61'SESSION'::
62 Full session name.
63
64'DOMAIN'::
65 Tracing domain.
66
67You can override the default output directory prefix
2ff6d569 68(`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other
f5595c32
PP
69parts depend on the remote configuration.
70
71
72[[url-format]]
73URL format
74~~~~~~~~~~
75The option:--control-port, option:--data-port, and option:--live-port
76options specify URLs.
77
78The format of those URLs is:
79
80[verse]
81tcp://('HOST' | 'IPADDR'):__PORT__
82
83with:
84
85('HOST' | 'IPADDR')::
86 Binding hostname or IP address (IPv6 address *must* be enclosed in
87 brackets (`[` and `]`); see
88 https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
89
90'PORT'::
91 TCP port.
92
93
94OPTIONS
95-------
96Daemon
97~~~~~~
98option:-b, option:--background::
99 Start as Unix daemon, but keep file descriptors (console) open.
100 Use the option:--daemonize option instead to close the file
101 descriptors.
102
103option:-d, option:--daemonize::
104 Start as Unix daemon, and close file descriptors (console). Use the
105 option:--background option instead to keep the file descriptors
106 open.
107
59b19c3c 108option:-g 'GROUP', option:--group='GROUP'::
f5595c32
PP
109 Use 'GROUP' as Unix tracing group (default: `tracing`).
110
59b19c3c 111option:-o 'PATH', option:--output='PATH'::
f5595c32
PP
112 Set base directory of written trace data to 'PATH'.
113+
114See the <<output-directory,Output directory>> section above for more
115information.
116
117option:-v, option:--verbose::
118 Increase verbosity.
119+
120Three levels of verbosity are available, which are triggered by
121appending additional `v` letters to the option
122(that is, `-vv` and `-vvv`).
123
124
125Ports
126~~~~~
127See the <<url-format,URL format>> section above for more information
128about the syntax of the following options' 'URL' argument.
129
59b19c3c 130option:-C 'URL', option:--control-port='URL'::
c93eadad
PP
131 Listen to control data on URL 'URL' (default:
132 +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
f5595c32 133
59b19c3c 134option:-D 'URL', option:--data-port='URL'::
c93eadad
PP
135 Listen to trace data on URL 'URL' (default:
136 +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
f5595c32 137
59b19c3c 138option:-L 'URL', option:--live-port='URL'::
f5595c32 139 Listen to LTTng live connections on URL 'URL'
c93eadad
PP
140 (default:
141 +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
f5595c32
PP
142
143
144Program information
145~~~~~~~~~~~~~~~~~~~
146option:-h, option:--help::
147 Show help.
148
149option:-V, option:--version::
150 Show version.
151
152
153ENVIRONMENT VARIABLES
154---------------------
9bbd8e06
MD
155`LTTNG_ABORT_ON_ERROR`::
156 Set to 1 to abort the process after the first error is encountered.
157
f5595c32
PP
158`LTTNG_NETWORK_SOCKET_TIMEOUT`::
159 Socket connection, receive and send timeout (milliseconds). A value
160 of 0 or -1 uses the timeout of the operating system (default).
161
162`LTTNG_RELAYD_HEALTH`::
163 Path to relay daemon health's socket.
164
165
900690ca
PP
166FILES
167-----
168`$LTTNG_HOME/.lttng`::
169 User LTTng runtime and configuration directory.
170
171`$LTTNG_HOME/lttng-traces`::
172 Default output directory of LTTng traces. This can be overridden
173 with the option:--output option.
174
175NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
176
177
f5595c32
PP
178EXIT STATUS
179-----------
180*0*::
181 Success
182
183*1*::
184 Error
185
186*3*::
187 Fatal error
188
189
190LIMITATIONS
191-----------
192As of this version, only the TCP protocol is supported for both control
193and data ports. In future versions, TCP will remain the sole available
194protocol for control data since those communications are low-volume and
195need absolute reliability; trace data could be carried over UDP.
196
197For an unprivileged user running `lttng-relayd`, the maximum number of
198file descriptors per process is usually 1024. This limits the number of
199connections and opened trace files. This limit can be configured with
200*ulimit*(3).
201
202
203include::common-footer.txt[]
204
205
206SEE ALSO
207--------
7c1a4458
PP
208man:lttng(1),
209man:lttng-sessiond(8),
210man:lttng-crash(1),
211man:lttng-ust(3),
212man:babeltrace(1)
This page took 0.032276 seconds and 4 git commands to generate.