doc/man/manpage.xsl: do not indent the title of an admonition block

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

lttng-sessiond(8)
=================
:revdate: 21 April 2021


NAME
----
lttng-sessiond - LTTng session daemon


SYNOPSIS
--------
[verse]
*lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent]
               [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH']
               [option:--agent-tcp-port='PORT']
               [option:--apps-sock='PATH'] [option:--client-sock='PATH']
               [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...]
                              [option:--extra-kmod-probes='PROBE'[,'PROBE']...]
                              [option:--kconsumerd-err-sock='PATH']
                              [option:--kconsumerd-cmd-sock='PATH']]
               [option:--ustconsumerd32-err-sock='PATH']
               [option:--ustconsumerd64-err-sock='PATH']
               [option:--ustconsumerd32-cmd-sock='PATH']
               [option:--ustconsumerd64-cmd-sock='PATH']
               [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
               [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
               [option:--event-notifier-error-buffer-size-kernel='SLOTS']
               [option:--event-notifier-error-buffer-size-userspace='SLOTS']
               [option:--quiet | [option:--verbose]... [option:--verbose-consumer]]


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

An LTTng session daemon, `lttng-sessiond`, is a program which:

* Manages tracing sessions (see man:lttng-create(1) to learn more about
  tracing sessions).

* Controls the various components (like tracers and consumer daemons) of
  LTTng.

* Sends asynchronous notifications to user applications.

A session daemon receives commands from the man:lttng(1) command-line
tool, as well as from any user application linked with the LTTng control
library (`liblttng-ctl`).

Each Unix user may have its own independent running session daemon.
However, the man:lttng(1) tool must connect to the session daemon of the
`root` user (the root session daemon) to control Linux kernel tracing.

When you start `lttng-sessiond` as the `root` Unix user, a non-root Unix
user can connect to it if it's part of the Unix tracing group. By
default, the name of the tracing group is `tracing`. Override the
tracing group name with the option:--group option.

See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.

A session daemon manages trace data consumer daemons, spawning them when
necessary. You do :not: need to manage the consumer daemons yourself.

By default, `lttng-sessiond` doesn't start as a daemon. Make it a daemon
with the option:--daemonize or option:--background option. With those
options, `lttng-sessiond` ensures the daemon is ready to receive client
commands before it exits.

NOTE: The LTTng project recommends that you start the session daemon at
boot time for stable and long-term tracing.


[[cfg]]
Daemon configuration
~~~~~~~~~~~~~~~~~~~~
When you run `lttng-sessiond`, it configures itself from, in this order:

. The INI configuration file +{system_lttng_conf}+, if any.

. The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any.
+
`$LTTNG_HOME` defaults to `$HOME`.

. With the option:--config='PATH' option: the INI configuration file
  'PATH'.

. The command-line options.

Each step can override a previous configuration property.

In INI configuration files, the session daemon only reads the properties
under the `sessiond` INI section. Each INI property is:

Key::
    The long name of a command-line option to set (see the
    <<options,OPTIONS>> section below).

Value::
    The selected command-line option accepts an argument:::
        Option argument (string).

    The selected command-line option is a switch:::
        `true`::::
        `yes`::::
        `on`::::
            Enable the option.

        `false`::::
        `no`::::
        `off`::::
            Disable the option.

INI configuration file example:

[source,ini]
----
[sessiond]
daemonize=yes
extra-kmod-probes=my-driver,other-module
----


[[load]]
Tracing session configuration loading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When the session daemon starts, it loads tracing session configurations
from:

Without the option:--load option::
    In this order:
+
--
. All the files in `$LTTNG_HOME/.lttng/sessions/auto`.
+
`$LTTNG_HOME` defaults to `$HOME`.

. All the files in +{system_sessions_auto_dir}+.
--
+
`lttng-sessiond` only loads tracing configuration files from the
directories above if its UID and their UID are the same.

With the option:--load='PATH' option::
    'PATH' is a directory:::
        All the files in 'PATH'.

    'PATH' is a file:::
        The file 'PATH'.


[[options]]
OPTIONS
-------
Daemon configuration
~~~~~~~~~~~~~~~~~~~~
option:-b, option:--background::
    Start as a Unix daemon, but keep file descriptors (console) open.
+
With this option, `lttng-sessiond` ensures the daemon is ready to
receive client commands 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-sessiond` ensures the daemon is ready to
receive client commands before it exits.
+
Use the option:--background option instead to keep the file descriptors
open.

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-sessiond`.
+
Members of the Unix tracing group may connect to the root session daemon
and, therefore, control LTTng kernel tracing.

option:-l 'PATH', option:--load='PATH'::
    Load tracing session configurations from 'PATH', either a directory
    or a file, instead of loading them from the default search
    directories.
+
See the <<load,Tracing session configuration loading>> section above.

option:-S, option:--sig-parent::
    Send the `USR1` signal to the parent process to notify readiness.
+
You can also use the option:--daemonize or option:--background option,
in which case `lttng-sessiond` ensures the daemon is ready to receive
client commands before it exits.


Linux kernel tracing
~~~~~~~~~~~~~~~~~~~~
At most one of:

option:--extra-kmod-probes='PROBE'[,'PROBE']...::
    For each 'PROBE' argument, load the LTTng kernel probe module
    named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the
    default LTTng kernel probe modules.

option:--kmod-probes='PROBE'[,'PROBE']...::
    Only load, for each 'PROBE' argument, the LTTng kernel probe
    module named ++lttng-probe-++__PROBE__++.ko++, instead of loading
    the default LTTng kernel probe modules.

option:--no-kernel::
    Disable Linux kernel tracing.


Paths and ports
~~~~~~~~~~~~~~~
option:--agent-tcp-port='PORT'::
    Listen on TCP port 'PORT' for agent application registration
    instead of a port within the range
    [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).

option:-a 'PATH', option:--apps-sock='PATH'::
    Set the application Unix socket path to 'PATH'.

option:-c 'PATH', option:--client-sock='PATH'::
    Set the client Unix socket path to 'PATH'.

option:--consumerd32-libdir='PATH'::
    Set the 32-bit consumer daemon library directory to 'PATH'.

option:--consumerd32-path='PATH'::
    Set the 32-bit consumer daemon binary path to 'PATH'.

option:--consumerd64-libdir='PATH'::
    Set the 64-bit consumer daemon library directory to 'PATH'.

option:--consumerd64-path='PATH'::
    Set the 64-bit consumer daemon binary path to 'PATH'.

option:--kconsumerd-cmd-sock='PATH'::
    Set the command Unix socket path of the Linux kernel consumer daemon
    to 'PATH'.

option:--kconsumerd-err-sock='PATH'::
    Set the error Unix socket path of the Linux kernel consumer daemon
    to 'PATH'.

option:--ustconsumerd32-cmd-sock='PATH'::
    Set the Unix socket path of the 32-bit consumer daemon command to
    'PATH'.

option:--ustconsumerd64-cmd-sock='PATH'::
    Set the Unix socket path of the 64-bit consumer daemon command to
    'PATH'.

option:--ustconsumerd32-err-sock='PATH'::
    Set the Unix socket path of the 32-bit consumer daemon error to
    'PATH'.

option:--ustconsumerd64-err-sock='PATH'::
    Set the Unix socket path of the 64-bit consumer daemon error to
    'PATH'.


Buffer size of event notifier error counters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:--event-notifier-error-buffer-size-kernel='SLOTS'::
    Set the size of the kernel event notifier error counter buffers to
    'SLOTS'{nbsp}slots.

option:--event-notifier-error-buffer-size-userspace='SLOTS'::
    Set the size of the user space event notifier error counter buffers
    to 'SLOTS'{nbsp}slots.

As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
may change in the future.


Verbosity
~~~~~~~~~
option:-q, option:--quiet::
    Suppress all messages, including warnings and errors.
+
You may :not: use this option with the option:--verbose and
option:--verbose-consumer options.

option:-v, option:--verbose::
    Increase verbosity.
+
Specify this option up to three times to get more levels of verbosity.
+
You may :not: use this option with the option:--quiet option.

option:--verbose-consumer::
    Increase the verbosity of the consumer daemons which this session
    daemon spawns.
+
You may :not: use this option with the option:--quiet option.


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

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


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

`LTTNG_APP_SOCKET_TIMEOUT`::
    Timeout (in seconds) of the application socket when
    sending/receiving commands.
+
After this period of time, `lttng-sessiond` unregisters the application.
+
Set to `0` or `-1` to set an infinite timeout.
+
Default: +{default_app_socket_rw_timeout}+.

`LTTNG_CONSUMERD32_BIN`::
    32-bit consumer daemon binary path.
+
The option:--consumerd32-path option overrides this variable.

`LTTNG_CONSUMERD32_LIBDIR`::
    32-bit consumer daemon library directory path.
+
The option:--consumerd32-libdir option overrides this variable.

`LTTNG_CONSUMERD64_BIN`::
    64-bit consumer daemon binary path.
+
The option:--consumerd64-path option overrides this variable.

`LTTNG_CONSUMERD64_LIBDIR`::
    64-bit consumer daemon library directory path.
+
The option:--consumerd64-libdir option overrides this variable.

`LTTNG_DEBUG_NOCLONE`::
    Set to `1` to disable the use of man:clone(2)/man:fork(2).
+
Setting this variable is considered insecure, but it's required to allow
debuggers to work with `lttng-sessiond` on some operating systems.

`LTTNG_EXTRA_KMOD_PROBES`::
    Extra LTTng kernel probe modules to load.
+
See the option:--extra-kmod-probes option which overrides this
environment variable.

`LTTNG_KMOD_PROBES`::
    Exclusive LTTng kernel probe modules to load.
+
See the option:--kmod-probes option which overrides this environment
variable.

`LTTNG_NETWORK_SOCKET_TIMEOUT`::
    Socket connection, receive, and send timeout (milliseconds).
+
Set to `0` or `-1` to use the timeout of the operating system (default).

`LTTNG_SESSION_CONFIG_XSD_PATH`::
    Tracing session configuration XML schema definition (XSD) path.


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

`$LTTNG_HOME/lttng-traces`::
    Default output directory of LTTng traces in local and snapshot
    modes.
+
Override this path with the nloption:--output option of the
man:lttng-create(1) command.

`$LTTNG_HOME/.lttng/sessions/auto`::
    Directory from which `lttng-sessiond` loads Unix user tracing
    session configurations when starting.
+
See the <<load,Tracing session configuration loading>> section above to
learn more.

+{system_sessions_auto_dir}+::
    Directory from which `lttng-sessiond` loads system-wide tracing
    session configurations when starting.
+
See the <<load,Tracing session configuration loading>> section above to
learn more.

`$LTTNG_HOME/.lttng/lttng.conf`::
    Unix user's LTTng daemon INI configuration file.
+
See the <<cfg,Daemon configuration>> section above to learn more.

+{system_lttng_conf}+::
    System-wide LTTng daemon INI configuration file.
+
See the <<cfg,Daemon configuration>> section above to learn more.

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


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

*1*::
    Error

*3*::
    Fatal error


LIMITATIONS
-----------
For an unprivileged Unix user running `lttng-sessiond`, the maximum
number of file descriptors per process is usually 1024. This limits the
number of traceable applications, since, for each instrumented
application, there are two file descriptors per CPU as well as one
socket for bidirectional communication.

For the `root` user, the limit is usually 65,535.


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1)