doc/man: use double quotes when referring to internal section

[lttng-tools.git] / doc / man / lttng-relayd.8.txt

lttng-relayd(8)
===============
:revdate: 30 April 2021
:daemon-bin-name: lttng-relayd
:daemon-ini-section: relayd


NAME
----
lttng-relayd - LTTng relay daemon


SYNOPSIS
--------
[verse]
*lttng-relayd* [option:--background | option:--daemonize] [option:--config='PATH']
             [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT']
             [option:--live-port='URL'] [option:--output='DIR'] [option:--group='GROUP']
             [option:--verbose]... [option:--working-directory='DIR']
             [option:--group-output-by-host | option:--group-output-by-session] [option:--disallow-clear]


DESCRIPTION
-----------
include::common-intro.txt[]

An LTTng relay daemon, `lttng-relayd`, is a program which receives trace
data from (possibly remote) LTTng session/consumer daemons and which
writes it to the local file system. The relay daemon also accepts LTTng
live connections from compatible readers (for example,
man:babeltrace2(1)); this is the recommended approach to read trace data
while the remote tracing session is active.

By default, a relay daemon listens on all network interfaces to receive
trace data, but only on `localhost` for LTTng live connections. Override
the listening URLs with the option:--control-port, option:--data-port,
and option:--live-port options (see the ``<<url-format,URL format>>''
section below). For example, use the
option:--live-port=+tcp://0.0.0.0:{default_network_viewer_port}+ option
to make a relay daemon listen to LTTng live connections on all network
interfaces.

Once LTTng has completely sent a trace to a relay daemon{nbsp}__RD__,
any LTTng trace reader can read the trace located on the local file
system of{nbsp}__RD__.

By default, `lttng-relayd` doesn't start as a daemon. Make it a daemon
with the option:--daemonize or option:--background option. With those
options, `lttng-relayd` ensures the daemon is listening to incoming
connections before it exits.


include::common-daemon-cfg.txt[]

INI configuration file example:

[source,ini]
----
[relayd]
daemonize=yes
live-port=tcp://0.0.0.0:4567
disallow-clear=yes
----


[[output-directory]]
Output directory
~~~~~~~~~~~~~~~~
The relay daemon uses different output path patterns depending on:

* Its configuration.
+
See the ``<<cfg,Daemon configuration>>'' section above.

* The tracing session configuration of the connected peer.
* The LTTng session daemon (see man:lttng-sessiond(8)) version
  of the connected peer.

Consider the following variables:

'BASE'::
    Base output directory: `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
    defaults to `$HOME`) or the argument of the option:--output option.

'HOSTNAME'::
    Hostname of the connected peer.

'SESSION'::
    Tracing session name.

'DATETIME'::
    Unique tracing session date/time.

'TRACEDIR'::
    Custom trace directory path ('TRACEDIR' part of the argument of the
    nloption:--set-url option of the man:lttng-create(1) command, if
    any).

'SESSIONDV'::
    The version of the LTTng session daemon of the connected peer.

The relay daemon output path patterns are:

With the option:--group-output-by-host option (hostname grouping)::
    Without a custom trace directory:::
+
[verse]
'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'

With a custom trace directory:::
+
[verse]
'BASE'/'HOSTNAME'/'TRACEDIR'

With the option:--group-output-by-session option (tracing session grouping)::
    Without a custom trace directory:::
        'SESSIONDV' is at least{nbsp}2.4::::
+
[verse]
'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'

Otherwise::::
    Defaults to the hostname grouping pattern:
+
[verse]
'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'

With a custom trace directory:::
    'SESSIONDV' is at least 2.4::::
+
[verse]
'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEDIR'

Otherwise::::
    Defaults to the hostname grouping pattern:
+
[verse]
'BASE'/'HOSTNAME'/'TRACEDIR'


[[url-format]]
URL format
~~~~~~~~~~
The argument of the option:--control-port='URL',
option:--data-port='URL', and option:--live-port='URL' options is an
URL.

The format of 'URL' is:

[verse]
tcp://('HOST' | 'IPADDR'):__PORT__

with:

('HOST' | 'IPADDR')::
    Binding hostname or IP address.
+
IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].

'PORT'::
    TCP port.


[[options]]
OPTIONS
-------
General daemon configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:-b, option:--background::
    Start as a Unix daemon, but keep file descriptors (console) open.
+
With this option, `lttng-relayd` ensures the daemon is listening
to incoming connections before it exits.
+
Use the option:--daemonize option instead to close the file descriptors.

option:-f 'PATH', option:--config='PATH'::
    Configure the daemon using the INI configuration file 'PATH' in
    addition to the default configuration files and the command-line
    options.
+
See the ``<<cfg,Daemon configuration>>'' section above.

option:-d, option:--daemonize::
    Start as a Unix daemon and close file descriptors (console).
+
With this option, `lttng-relayd` ensures the daemon is listening
to incoming connections before it exits.
+
Use the option:--background option instead to keep the file descriptors
open.

option:-x, option:--disallow-clear::
    Disallow clearing operations (see man:lttng-clear(1)).
+
See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable.

option:--fd-pool-size='SIZE'::
    Set the size of the file descriptor pool to 'SIZE' file descriptors.
+
'SIZE' is the maximum number of file descriptors that the relay daemon
may keep open simultaneously.
+
Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
man:getrlimit(2)).

option:-g 'GROUP', option:--group='GROUP'::
    Set the Unix tracing group to 'GROUP' instead of `tracing`.
+
This option is only meaningful when the `root` Unix user starts
`lttng-relayd`.
+
Members of the Unix tracing group may connect to the health check socket
of the relay daemon.
+
See also the `LTTNG_RELAYD_HEALTH` environment variable.

option:-w 'DIR', option:--working-directory='DIR'::
    Set the working directory of the processes the relay daemon creates
    to 'DIR'.
+
See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.

option:-v, option:--verbose::
    Increase verbosity.
+
Specify this option up to three times to get more levels of verbosity.


Output
~~~~~~
See the ``<<output-directory,Output directory>>'' section above to learn
more.

option:-p, option:--group-output-by-host::
    Group the written trace directories by hostname.
+
As of LTTng{nbsp}{lttng_version}, this is the default output grouping
strategy, but this may change in the future.

option:-s, option:--group-output-by-session::
    Group the written trace directories by tracing session name instead
    of by hostname.

option:-o 'DIR', option:--output='DIR'::
    Set the base output directory of the written trace directories to
    'DIR'.


Ports
~~~~~
See the ``<<url-format,URL format>>'' section above to learn more about
the syntax of the 'URL' argument of the following options.

option:-C 'URL', option:--control-port='URL'::
    Listen to control data on URL 'URL'.
+
Default:
+tcp://{default_network_control_bind_address}:{default_network_control_port}+.

option:-D 'URL', option:--data-port='URL'::
    Listen to trace data on URL 'URL'.
+
Default:
+tcp://{default_network_data_bind_address}:{default_network_data_port}+.

option:-L 'URL', option:--live-port='URL'::
    Listen to LTTng live connections on URL 'URL'.
+
Default:
+tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.


Program information
~~~~~~~~~~~~~~~~~~~
include::common-help-option.txt[]

option:-V, option:--version::
    Show version and quit.


EXIT STATUS
-----------
*0*::
    Success

*1*::
    Error

*3*::
    Fatal error


ENVIRONMENT
-----------
`LTTNG_ABORT_ON_ERROR`::
    Set to `1` to abort the process after the first error is
    encountered.

`LTTNG_NETWORK_SOCKET_TIMEOUT`::
    Socket connection, receive, and send timeout (milliseconds).
+
Set to `0` or `-1` to set an infinite timeout (default).

`LTTNG_RELAYD_DISALLOW_CLEAR`::
    Set to `1` to disallow clearing operations (see man:lttng-clear(1)).
+
The option:--disallow-clear option overrides this environment variable.

`LTTNG_RELAYD_HEALTH`::
    Path to the health check socket of the relay daemon.

`LTTNG_RELAYD_TCP_KEEP_ALIVE`::
    Set to `1` to enable TCP keep-alive.
+
The TCP keep-alive mechanism allows the detection of dead peers
(man:lttng-sessiond(8)) in cases of unclean termination (for example, a
hard reset) of a peer.
+
Supported on Linux and Solaris only. The default behaviour of the TCP
keep-alive mechanism is OS-specific.
+
Search for `tcp_keepalive` in man:tcp(7) to learn more.

`LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
   The time threshold (seconds) to abort a TCP connection after the
   keep-alive probing mechanism has failed.
+
Set to `0` or `-1` to use the value chosen by the operating system
(default).
+
Supported on Solaris 11 only.
+
Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more.

`LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
    Number of seconds a connection needs to be idle before TCP begins
    sending out keep-alive probes.
+
Set to `0` or `-1` to use the value chosen by the operating system
(default).
+
Supported on Linux and Solaris 11 only.
+
On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to
`864000`.
+
Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
in man:tcp(7) on Solaris{nbsp}11 to learn more.

`LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
    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.
+
Set to `0` or `-1` to use the value chosen by the operating system
(default).
+
Supported on Linux only.
+
Search for `tcp_keepalive_probes` in man:tcp(7) to learn more.

`LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
    Number of seconds between TCP keep-alive probes.
+
Set to `0` or `-1` to use the value chosen by the operating system
(default).
+
Supported on Linux only.
+
Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more.

`LTTNG_RELAYD_WORKING_DIRECTORY`::
    Working directory of the processes the relay daemon creates.
+
The option:--working-directory option overrides this environment
variable.


FILES
-----
`$LTTNG_HOME/.lttng`::
    Unix user's LTTng runtime and configuration directory.

`$LTTNG_HOME/lttng-traces`::
    Default base output directory of LTTng traces.
+
Override this path with the option:--output option.

NOTE: `$LTTNG_HOME` defaults to `$HOME`.


include::common-footer.txt[]


SEE ALSO
--------
man:babeltrace2(1),
man:lttng(1),
man:lttng-sessiond(8)