'\" t
.\"     Title: lttng-relayd
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2 April 2020
.\"    Manual: LTTng Manual
.\"    Source: LTTng 2.12.3
.\"  Language: English
.\"
.TH "LTTNG\-RELAYD" "8" "2 April 2020" "LTTng 2\&.12\&.3" "LTTng Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
lttng-relayd \- LTTng 2 relay daemon
.SH "SYNOPSIS"
.sp
.nf
\fBlttng\-relayd\fR [\fB--background\fR | \fB--daemonize\fR] [\fB--config\fR=\fIPATH\fR]
             [\fB--control-port\fR=\fIURL\fR] [\fB--data-port\fR=\fIURL\fR] [\fB--fd-pool-size\fR=\fICOUNT\fR]
             [\fB--live-port\fR=\fIURL\fR] [\fB--output\fR=\fIPATH\fR]
             [\fB-v\fR | \fB-vv\fR | \fB-vvv\fR] [\fB--working-directory\fR=\fIPATH\fR]
             [\fB--group-output-by-session\fR] [\fB--disallow-clear\fR]
.fi
.SH "DESCRIPTION"
.sp
The \fILinux Trace Toolkit: next generation\fR <https://lttng.org/> is an open source software package used for correlated tracing of the Linux kernel, user applications, and user libraries\&.
.sp
LTTng consists of Linux kernel modules (for Linux kernel tracing) and dynamically loaded libraries (for user application and library tracing)\&.
.sp
The \fILTTng relay daemon\fR is responsible for receiving trace data from possibly remote LTTng session/consumer daemons and for writing it to the local file system\&. The relay daemon also accepts \fILTTng live\fR connections from compatible viewers; this is the official approach to viewing LTTng events as they are emitted\&.
.sp
The relay daemon listens by default on all network interfaces to gather trace data, but only on localhost for LTTng live connections\&.
.sp
The relay daemon does not require any particular permissions, as long as it can write to the output directory and listen on the configured ports\&. If a user is within a secured network and/or has proper firewall settings, \fBlttng-relayd\fR can listen to LTTng live connections from \fIall\fR network interfaces by specifying \fB--live-port=tcp://0.0.0.0:5344\fR\&.
.sp
Once a trace has been streamed completely, the trace can be processed by any tool that can process an LTTng trace located on the local file system\&.
.SS "Output directory"
.sp
The relay daemon uses different output path patterns depending on:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Its configuration\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The connected peer\(cqs tracing session configuration\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The connected peer\(cqs LTTng session daemon (see
\fBlttng-sessiond\fR(8)) version\&.
.RE
.sp
Consider the following variables:
.PP
\fIBASE\fR
.RS 4
Base output directory:
\fB$LTTNG_HOME/lttng-traces\fR
or the argument of the
\fB--output\fR
option\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
\fB$LTTNG_HOME\fR
defaults to
\fB$HOME\fR
when not explicitly set\&.
.sp .5v
.RE
.RE
.PP
\fIHOSTNAME\fR
.RS 4
Peer\(cqs hostname\&.
.RE
.PP
\fISESSION\fR
.RS 4
Tracing session name\&.
.RE
.PP
\fIDATETIME\fR
.RS 4
Unique tracing session date/time\&.
.RE
.PP
\fITRACEPATH\fR
.RS 4
Custom trace path (\fITRACEPATH\fR
part of the
\fBlttng-create\fR(1)
command\(cqs
\fB--set-url\fR
option\(cqs argument, if any)\&.
.RE
.sp
The relay daemon output path patterns are:
.PP
Hostname grouping (without \fB--group-output-by-session\fR)
.RS 4
.PP
Without a custom trace path
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
\fIBASE\fR/\fIHOSTNAME\fR/\fISESSION\fR\-\fIDATETIME\fR
.fi
.if n \{\
.RE
.\}
.RE
.PP
With a custom trace path
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
\fIBASE\fR/\fIHOSTNAME\fR/\fITRACEPATH\fR
.fi
.if n \{\
.RE
.\}
.RE
.RE
.PP
Tracing session grouping (with \fB--group-output-by-session\fR)
.RS 4
.PP
Without a custom trace path
.RS 4
.PP
The peer\(cqs LTTng session daemon version is at least 2\&.4
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
\fIBASE\fR/\fISESSION\fR/\fIHOSTNAME\fR\-\fIDATETIME\fR
.fi
.if n \{\
.RE
.\}
.RE
.PP
Otherwise
.RS 4
Defaults to the hostname grouping pattern:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIBASE\fR/\fIHOSTNAME\fR/\fISESSION\fR\-\fIDATETIME\fR
.fi
.if n \{\
.RE
.\}
.RE
.RE
.PP
With a custom trace path
.RS 4
.PP
The peer\(cqs LTTng session daemon version is at least 2\&.4
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
\fIBASE\fR/\fISESSION\fR/\fIHOSTNAME\fR\-\fIDATETIME\fR/\fITRACEPATH\fR
.fi
.if n \{\
.RE
.\}
.RE
.PP
Otherwise
.RS 4
Defaults to the hostname grouping pattern:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIBASE\fR/\fIHOSTNAME\fR/\fITRACEPATH\fR
.fi
.if n \{\
.RE
.\}
.RE
.RE
.RE
.SS "URL format"
.sp
The \fB--control-port\fR, \fB--data-port\fR, and \fB--live-port\fR options specify URLs\&.
.sp
The format of those URLs is:
.sp
.if n \{\
.RS 4
.\}
.nf
tcp://(\fIHOST\fR | \fIIPADDR\fR):\fIPORT\fR
.fi
.if n \{\
.RE
.\}
.sp
with:
.PP
(\fIHOST\fR | \fIIPADDR\fR)
.RS 4
Binding hostname or IP address (IPv6 address
\fBmust\fR
be enclosed in brackets (\fB[\fR
and
\fB]\fR); see
RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>)\&.
.RE
.PP
\fIPORT\fR
.RS 4
TCP port\&.
.RE
.SH "OPTIONS"
.SS "Daemon"
.PP
\fB-b\fR, \fB--background\fR
.RS 4
Start as Unix daemon, but keep file descriptors (console) open\&. Use the
\fB--daemonize\fR
option instead to close the file descriptors\&.
.RE
.PP
\fB-f\fR \fIPATH\fR, \fB--config\fR=\fIPATH\fR
.RS 4
Load relay daemon configuration from path
\fIPATH\fR\&.
.RE
.PP
\fB-d\fR, \fB--daemonize\fR
.RS 4
Start as Unix daemon, and close file descriptors (console)\&. Use the
\fB--background\fR
option instead to keep the file descriptors open\&.
.RE
.PP
\fB-x\fR, \fB--disallow-clear\fR
.RS 4
Disallow clearing operations (see
\fBlttng-clear\fR(1))\&.
.sp
See also the
\fBLTTNG_RELAYD_DISALLOW_CLEAR\fR
environment variable\&.
.RE
.PP
\fB--fd-pool-size\fR=\fISIZE\fR
.RS 4
Set the size of the file descriptor pool to
\fISIZE\fR\&.
.sp
\fISIZE\fR
is the maximum number of file descriptors that may be kept opened simultaneously by the relay daemon\&.
.sp
Default: the soft
\fBRLIMIT_NOFILE\fR
resource limit of the process (see
\fBgetrlimit\fR(2))\&.
.RE
.PP
\fB-g\fR \fIGROUP\fR, \fB--group\fR=\fIGROUP\fR
.RS 4
Use
\fIGROUP\fR
as Unix tracing group (default:
\fBtracing\fR)\&.
.RE
.PP
\fB-w\fR \fIPATH\fR, \fB--working-directory\fR=\fIPATH\fR
.RS 4
Set the working directory of the processes the relay daemon creates to
\fIPATH\fR\&.
.sp
See also the
\fBLTTNG_RELAYD_WORKING_DIRECTORY\fR
environment variable\&.
.RE
.PP
\fB-v\fR, \fB--verbose\fR
.RS 4
Increase verbosity\&.
.sp
Three levels of verbosity are available, which are triggered by appending additional
\fBv\fR
letters to the option (that is,
\fB-vv\fR
and
\fB-vvv\fR)\&.
.RE
.SS "Output"
.sp
See the \fIOutput directory\fR section above for more information\&.
.PP
\fB-p\fR, \fB--group-output-by-host\fR
.RS 4
Group the written trace directories by hostname (default)\&.
.RE
.PP
\fB-s\fR, \fB--group-output-by-session\fR
.RS 4
Group the written trace directories by tracing session name instead of by hostname\&.
.RE
.PP
\fB-o\fR \fIPATH\fR, \fB--output\fR=\fIPATH\fR
.RS 4
Set the base output directory of the written trace directories to
\fIPATH\fR\&.
.RE
.SS "Ports"
.sp
See the \fIURL format\fR section above for more information about the syntax of the following \fIURL\fR argument\&.
.PP
\fB-C\fR \fIURL\fR, \fB--control-port\fR=\fIURL\fR
.RS 4
Listen to control data on URL
\fIURL\fR
(default:
\fBtcp://0.0.0.0:5342\fR)\&.
.RE
.PP
\fB-D\fR \fIURL\fR, \fB--data-port\fR=\fIURL\fR
.RS 4
Listen to trace data on URL
\fIURL\fR
(default:
\fBtcp://0.0.0.0:5343\fR)\&.
.RE
.PP
\fB-L\fR \fIURL\fR, \fB--live-port\fR=\fIURL\fR
.RS 4
Listen to LTTng live connections on URL
\fIURL\fR
(default:
\fBtcp://localhost:5344\fR)\&.
.RE
.SS "Program information"
.PP
\fB-h\fR, \fB--help\fR
.RS 4
Show help\&.
.RE
.PP
\fB-V\fR, \fB--version\fR
.RS 4
Show version\&.
.RE
.SH "ENVIRONMENT VARIABLES"
.PP
\fBLTTNG_ABORT_ON_ERROR\fR
.RS 4
Set to 1 to abort the process after the first error is encountered\&.
.RE
.PP
\fBLTTNG_NETWORK_SOCKET_TIMEOUT\fR
.RS 4
Socket connection, receive and send timeout (milliseconds)\&. A value of 0 or \-1 uses the timeout of the operating system (default)\&.
.RE
.PP
\fBLTTNG_RELAYD_DISALLOW_CLEAR\fR
.RS 4
Set to 1 to disallow clearing operations (see
\fBlttng-clear\fR(1))\&.
.sp
The
\fB--disallow-clear\fR
option overrides this variable\&.
.RE
.PP
\fBLTTNG_RELAYD_HEALTH\fR
.RS 4
Path to relay daemon health\(cqs socket\&.
.RE
.PP
\fBLTTNG_RELAYD_TCP_KEEP_ALIVE\fR
.RS 4
Set to 1 to enable TCP keep\-alive\&.
.sp
The TCP keep\-alive mechanism allows the detection of dead peers (\fBlttng-sessiond\fR(8)) in cases of unclean termination (for example, a hard reset) of a peer\&.
.sp
Supported on Linux and Solaris only\&. The default behaviour of the TCP keep\-alive mechanism is OS\-specific\&.
.sp
Search for
\fBtcp_keepalive\fR
in
\fBtcp\fR(7)
for more information\&.
.RE
.PP
\fBLTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD\fR
.RS 4
The time threshold in seconds to abort a TCP connection after the keep\-alive probing mechanism has failed\&.
.sp
Set to 0 or \-1 to use the value chosen by the operating system (default)\&.
.sp
Supported on Solaris 11 only\&.
.sp
Search for
\fBtcp_keepalive_abort_threshold\fR
in
\fBtcp\fR(7)
for more information\&.
.RE
.PP
\fBLTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME\fR
.RS 4
Number of seconds a connection needs to be idle before TCP begins sending out keep\-alive probes\&.
.sp
Set to 0 or \-1 to use the value chosen by the operating system (default)\&.
.sp
Supported on Linux and Solaris 11 only\&.
.sp
On Solaris\ \&11, the accepted values are \-1, 0, and 10 to 864000\&.
.sp
Search for
\fBtcp_keepalive_time\fR
and
\fBtcp_keepalive_interval\fR
in
\fBtcp\fR(7)
on Solaris 11 for more information\&.
.RE
.PP
\fBLTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT\fR
.RS 4
Maximum number of TCP keep\-alive probes to send before giving up and killing the connection if no response is obtained from the other end\&.
.sp
Set to 0 or \-1 to use the value chosen by the operating system (default)\&.
.sp
Supported on Linux only\&.
.sp
Search for
\fBtcp_keepalive_probes\fR
in
\fBtcp\fR(7)
for more information\&.
.RE
.PP
\fBLTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL\fR
.RS 4
Number of seconds between TCP keep\-alive probes\&.
.sp
Set to 0 or \-1 to use the value chosen by the operating system (default)\&.
.sp
Supported on Linux only\&.
.sp
Search for
\fBtcp_keepalive_intvl\fR
in
\fBtcp\fR(7)
for more information\&.
.RE
.PP
\fBLTTNG_RELAYD_WORKING_DIRECTORY\fR
.RS 4
Working directory of the processes the relay daemon creates\&.
.sp
The
\fB--working-directory\fR
option overrides this variable\&.
.RE
.SH "FILES"
.PP
\fB$LTTNG_HOME/.lttng\fR
.RS 4
User LTTng runtime and configuration directory\&.
.RE
.PP
\fB$LTTNG_HOME/lttng-traces\fR
.RS 4
Default base output directory of LTTng traces\&. This can be overridden with the
\fB--output\fR
option\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
\fB$LTTNG_HOME\fR defaults to \fB$HOME\fR when not explicitly set\&.
.sp .5v
.RE
.SH "EXIT STATUS"
.PP
\fB0\fR
.RS 4
Success
.RE
.PP
\fB1\fR
.RS 4
Error
.RE
.PP
\fB3\fR
.RS 4
Fatal error
.RE
.SH "LIMITATIONS"
.sp
As of this version, only the TCP protocol is supported for both control and data ports\&. In future versions, TCP will remain the sole available protocol for control data since those communications are low\-volume and need absolute reliability; trace data could be carried over UDP\&.
.sp
For an unprivileged user running \fBlttng-relayd\fR, the maximum number of file descriptors per process is usually 1024\&. This limits the number of connections and opened trace files\&. This limit can be configured with \fBulimit\fR(3)\&.
.SH "BUGS"
.sp
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>\&.
.SH "RESOURCES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng project website <https://lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng documentation <https://lttng.org/docs>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Git repositories <http://git.lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GitHub organization <http://github.com/lttng>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Continuous integration <http://ci.lttng.org/>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Mailing list <http://lists.lttng.org>
for support and development:
\fBlttng-dev@lists.lttng.org\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
IRC channel <irc://irc.oftc.net/lttng>:
\fB#lttng\fR
on
\fBirc.oftc.net\fR
.RE
.SH "COPYRIGHTS"
.sp
This program is part of the LTTng\-tools project\&.
.sp
LTTng\-tools is distributed under the GNU General Public License version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>\&. See the \fBLICENSE\fR <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details\&.
.SH "THANKS"
.sp
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at \('Ecole Polytechnique de Montr\('eal for the LTTng journey\&.
.sp
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases\&.
.SH "SEE ALSO"
.sp
\fBlttng\fR(1), \fBlttng-sessiond\fR(8), \fBlttng-crash\fR(1), \fBlttng-ust\fR(3), \fBbabeltrace2\fR(1)