doc/man: add FILES section
[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_
40network interfaces by specifying `--live-port=tcp://0.0.0.0:5344`.
41
42Once a trace has been streamed completely, the trace can be processed by
43any tool that can process an LTTng trace located on the local
44file system.
45
46
47[[output-directory]]
48Output directory
49~~~~~~~~~~~~~~~~
50By default, the relay daemon writes the traces to:
51
52[verse]
53$HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
54
55with:
56
57'HOSTNAME'::
58 Remote hostname.
59
60'SESSION'::
61 Full session name.
62
63'DOMAIN'::
64 Tracing domain.
65
66You can override the default output directory prefix
67(`$HOME/lttng-traces`) with the option:--output option. The other
68parts depend on the remote configuration.
69
70
71[[url-format]]
72URL format
73~~~~~~~~~~
74The option:--control-port, option:--data-port, and option:--live-port
75options specify URLs.
76
77The format of those URLs is:
78
79[verse]
80tcp://('HOST' | 'IPADDR'):__PORT__
81
82with:
83
84('HOST' | 'IPADDR')::
85 Binding hostname or IP address (IPv6 address *must* be enclosed in
86 brackets (`[` and `]`); see
87 https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
88
89'PORT'::
90 TCP port.
91
92
93OPTIONS
94-------
95Daemon
96~~~~~~
97option:-b, option:--background::
98 Start as Unix daemon, but keep file descriptors (console) open.
99 Use the option:--daemonize option instead to close the file
100 descriptors.
101
102option:-d, option:--daemonize::
103 Start as Unix daemon, and close file descriptors (console). Use the
104 option:--background option instead to keep the file descriptors
105 open.
106
107option:-g, option:--group='GROUP'::
108 Use 'GROUP' as Unix tracing group (default: `tracing`).
109
110option:-o, option:--output='PATH'::
111 Set base directory of written trace data to 'PATH'.
112+
113See the <<output-directory,Output directory>> section above for more
114information.
115
116option:-v, option:--verbose::
117 Increase verbosity.
118+
119Three levels of verbosity are available, which are triggered by
120appending additional `v` letters to the option
121(that is, `-vv` and `-vvv`).
122
123
124Ports
125~~~~~
126See the <<url-format,URL format>> section above for more information
127about the syntax of the following options' 'URL' argument.
128
129option:-C, option:--control-port='URL'::
130 Listen to control data on URL 'URL' (default: `tcp://0.0.0.0:5342`).
131
132option:-D, option:--data-port='URL'::
133 Listen to trace data on URL 'URL' (default: `tcp://0.0.0.0:5343`).
134
135option:-L, option:--live-port='URL'::
136 Listen to LTTng live connections on URL 'URL'
137 (default: `tcp://0.0.0.0:5344`).
138
139
140Program information
141~~~~~~~~~~~~~~~~~~~
142option:-h, option:--help::
143 Show help.
144
145option:-V, option:--version::
146 Show version.
147
148
149ENVIRONMENT VARIABLES
150---------------------
151`LTTNG_NETWORK_SOCKET_TIMEOUT`::
152 Socket connection, receive and send timeout (milliseconds). A value
153 of 0 or -1 uses the timeout of the operating system (default).
154
155`LTTNG_RELAYD_HEALTH`::
156 Path to relay daemon health's socket.
157
158
900690ca
PP
159FILES
160-----
161`$LTTNG_HOME/.lttng`::
162 User LTTng runtime and configuration directory.
163
164`$LTTNG_HOME/lttng-traces`::
165 Default output directory of LTTng traces. This can be overridden
166 with the option:--output option.
167
168NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
169
170
f5595c32
PP
171EXIT STATUS
172-----------
173*0*::
174 Success
175
176*1*::
177 Error
178
179*3*::
180 Fatal error
181
182
183LIMITATIONS
184-----------
185As of this version, only the TCP protocol is supported for both control
186and data ports. In future versions, TCP will remain the sole available
187protocol for control data since those communications are low-volume and
188need absolute reliability; trace data could be carried over UDP.
189
190For an unprivileged user running `lttng-relayd`, the maximum number of
191file descriptors per process is usually 1024. This limits the number of
192connections and opened trace files. This limit can be configured with
193*ulimit*(3).
194
195
196include::common-footer.txt[]
197
198
199SEE ALSO
200--------
201linklttng:lttng(1),
202linklttng:lttng-sessiond(8),
203linklttng:lttng-crash(1),
204linklttng:lttng-ust(3),
205linklttng:babeltrace(1)
This page took 0.042365 seconds and 4 git commands to generate.