doc/man/lttng-sessiond.8.txt

   1 lttng-sessiond(8)
   2 =================
   3 :revdate: 21 April 2021
   4 :daemon-bin-name: lttng-sessiond
   5 :daemon-ini-section: sessiond
   6
   7
   8 NAME
   9 ----
  10 lttng-sessiond - LTTng session daemon
  11
  12
  13 SYNOPSIS
  14 --------
  15 [verse]
  16 *lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent]
  17                [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH']
  18                [option:--agent-tcp-port='PORT']
  19                [option:--apps-sock='PATH'] [option:--client-sock='PATH']
  20                [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...]
  21                               [option:--extra-kmod-probes='PROBE'[,'PROBE']...]
  22                               [option:--kconsumerd-err-sock='PATH']
  23                               [option:--kconsumerd-cmd-sock='PATH']]
  24                [option:--ustconsumerd32-err-sock='PATH']
  25                [option:--ustconsumerd64-err-sock='PATH']
  26                [option:--ustconsumerd32-cmd-sock='PATH']
  27                [option:--ustconsumerd64-cmd-sock='PATH']
  28                [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
  29                [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
  30                [option:--event-notifier-error-buffer-size-kernel='SLOTS']
  31                [option:--event-notifier-error-buffer-size-userspace='SLOTS']
  32                [option:--quiet | [option:--verbose]... [option:--verbose-consumer]]
  33
  34
  35 DESCRIPTION
  36 -----------
  37 include::common-intro.txt[]
  38
  39 An LTTng session daemon, `lttng-sessiond`, is a program which:
  40
  41 * Manages tracing sessions (see man:lttng-concepts(7) to learn more
  42   about tracing sessions).
  43
  44 * Controls the various components (like tracers and consumer daemons) of
  45   LTTng.
  46
  47 * Sends asynchronous notifications to user applications.
  48
  49 A session daemon receives commands from the man:lttng(1) command-line
  50 tool, as well as from any user application linked with the LTTng control
  51 library (`liblttng-ctl`).
  52
  53 Each Unix user may have its own independent running session daemon.
  54 However, the man:lttng(1) tool must connect to the session daemon of the
  55 `root` user (the root session daemon) to control Linux kernel tracing.
  56
  57 When you start `lttng-sessiond` as the `root` Unix user, a non-root Unix
  58 user can connect to it if it's part of the Unix tracing group. By
  59 default, the name of the tracing group is `tracing`. Override the
  60 tracing group name with the option:--group option.
  61
  62 See the ``Session daemon connection'' section of man:lttng(1) to learn
  63 how a user application connects to a session daemon.
  64
  65 A session daemon manages trace data consumer daemons, spawning them when
  66 necessary. You do :not: need to manage the consumer daemons yourself.
  67
  68 By default, `lttng-sessiond` doesn't start as a daemon. Make it a daemon
  69 with the option:--daemonize or option:--background option. With those
  70 options, `lttng-sessiond` ensures the daemon is ready to receive client
  71 commands before it exits.
  72
  73 NOTE: The LTTng project recommends that you start the session daemon at
  74 boot time for stable and long-term tracing.
  75
  76 [NOTE]
  77 ====
  78 For an unprivileged Unix user running `lttng-sessiond`, the maximum
  79 number of file descriptors per process is usually 1024. This limits the
  80 number of traceable applications, since, for each instrumented
  81 application, there are two file descriptors per CPU as well as one
  82 socket for bidirectional communication.
  83
  84 For the `root` user, the limit is usually 65,535.
  85 ====
  86
  87
  88 include::common-daemon-cfg.txt[]
  89
  90 INI configuration file example:
  91
  92 [source,ini]
  93 ----
  94 [sessiond]
  95 daemonize=yes
  96 extra-kmod-probes=my-driver,other-module
  97 ----
  98
  99
 100 [[load]]
 101 Tracing session configuration loading
 102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 103 When the session daemon starts, it loads tracing session configurations
 104 from:
 105
 106 Without the option:--load option::
 107     In this order:
 108 +
 109 --
 110 . All the files in `$LTTNG_HOME/.lttng/sessions/auto`.
 111 +
 112 `$LTTNG_HOME` defaults to `$HOME`.
 113
 114 . All the files in +{system_sessions_auto_dir}+.
 115 --
 116 +
 117 `lttng-sessiond` only loads tracing configuration files from the
 118 directories above if its UID and their UID are the same.
 119
 120 With the option:--load='PATH' option::
 121     'PATH' is a directory:::
 122         All the files in 'PATH'.
 123
 124     'PATH' is a file:::
 125         The file 'PATH'.
 126
 127
 128 [[options]]
 129 OPTIONS
 130 -------
 131 General daemon configuration
 132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 133 option:-b, option:--background::
 134     Start as a Unix daemon, but keep file descriptors (console) open.
 135 +
 136 With this option, `lttng-sessiond` ensures the daemon is ready to
 137 receive client commands before it exits.
 138 +
 139 Use the option:--daemonize option instead to close the file descriptors.
 140
 141 option:-f 'PATH', option:--config='PATH'::
 142     Configure the daemon using the INI configuration file 'PATH' in
 143     addition to the default configuration files and the command-line
 144     options.
 145 +
 146 See the <<cfg,Daemon configuration>> section above.
 147
 148 option:-d, option:--daemonize::
 149     Start as a Unix daemon and close file descriptors (console).
 150 +
 151 With this option, `lttng-sessiond` ensures the daemon is ready to
 152 receive client commands before it exits.
 153 +
 154 Use the option:--background option instead to keep the file descriptors
 155 open.
 156
 157 option:-g 'GROUP', option:--group='GROUP'::
 158     Set the Unix tracing group to 'GROUP' instead of `tracing`.
 159 +
 160 This option is only meaningful when the `root` Unix user starts
 161 `lttng-sessiond`.
 162 +
 163 Members of the Unix tracing group may connect to the root session daemon
 164 and, therefore, control LTTng kernel tracing.
 165
 166 option:-l 'PATH', option:--load='PATH'::
 167     Load tracing session configurations from 'PATH', either a directory
 168     or a file, instead of loading them from the default search
 169     directories.
 170 +
 171 See the <<load,Tracing session configuration loading>> section above.
 172
 173 option:-S, option:--sig-parent::
 174     Send the `USR1` signal to the parent process to notify readiness.
 175 +
 176 You can also use the option:--daemonize or option:--background option,
 177 in which case `lttng-sessiond` ensures the daemon is ready to receive
 178 client commands before it exits.
 179
 180
 181 Linux kernel tracing
 182 ~~~~~~~~~~~~~~~~~~~~
 183 At most one of:
 184
 185 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
 186     For each 'PROBE' argument, load the LTTng kernel probe module
 187     named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the
 188     default LTTng kernel probe modules.
 189 +
 190 See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable.
 191
 192 option:--kmod-probes='PROBE'[,'PROBE']...::
 193     Only load, for each 'PROBE' argument, the LTTng kernel probe
 194     module named ++lttng-probe-++__PROBE__++.ko++, instead of loading
 195     the default LTTng kernel probe modules.
 196 +
 197 See also the `LTTNG_KMOD_PROBES` environment variable.
 198
 199 option:--no-kernel::
 200     Disable Linux kernel tracing.
 201
 202
 203 Paths and ports
 204 ~~~~~~~~~~~~~~~
 205 option:--agent-tcp-port='PORT'::
 206     Listen on TCP port 'PORT' for agent application registration
 207     instead of a port within the range
 208     [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
 209
 210 option:-a 'PATH', option:--apps-sock='PATH'::
 211     Set the application Unix socket path to 'PATH'.
 212
 213 option:-c 'PATH', option:--client-sock='PATH'::
 214     Set the client Unix socket path to 'PATH'.
 215
 216 option:--consumerd32-libdir='PATH'::
 217     Set the 32-bit consumer daemon library directory to 'PATH'.
 218 +
 219 See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable.
 220
 221 option:--consumerd32-path='PATH'::
 222     Set the 32-bit consumer daemon binary path to 'PATH'.
 223 +
 224 See also the `LTTNG_CONSUMERD32_BIN` environment variable.
 225
 226 option:--consumerd64-libdir='PATH'::
 227     Set the 64-bit consumer daemon library directory to 'PATH'.
 228 +
 229 See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable.
 230
 231 option:--consumerd64-path='PATH'::
 232     Set the 64-bit consumer daemon binary path to 'PATH'.
 233 +
 234 See also the `LTTNG_CONSUMERD32_BIN` environment variable.
 235
 236 option:--kconsumerd-cmd-sock='PATH'::
 237     Set the command Unix socket path of the Linux kernel consumer daemon
 238     to 'PATH'.
 239
 240 option:--kconsumerd-err-sock='PATH'::
 241     Set the error Unix socket path of the Linux kernel consumer daemon
 242     to 'PATH'.
 243
 244 option:--ustconsumerd32-cmd-sock='PATH'::
 245     Set the Unix socket path of the 32-bit consumer daemon command to
 246     'PATH'.
 247
 248 option:--ustconsumerd64-cmd-sock='PATH'::
 249     Set the Unix socket path of the 64-bit consumer daemon command to
 250     'PATH'.
 251
 252 option:--ustconsumerd32-err-sock='PATH'::
 253     Set the Unix socket path of the 32-bit consumer daemon error to
 254     'PATH'.
 255
 256 option:--ustconsumerd64-err-sock='PATH'::
 257     Set the Unix socket path of the 64-bit consumer daemon error to
 258     'PATH'.
 259
 260
 261 Buffer size of event notifier error counters
 262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 263 option:--event-notifier-error-buffer-size-kernel='SLOTS'::
 264     Set the size of the kernel event notifier error counter buffers to
 265     'SLOTS'{nbsp}slots.
 266
 267 option:--event-notifier-error-buffer-size-userspace='SLOTS'::
 268     Set the size of the user space event notifier error counter buffers
 269     to 'SLOTS'{nbsp}slots.
 270
 271 As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
 272 may change in the future.
 273
 274
 275 Verbosity
 276 ~~~~~~~~~
 277 option:-q, option:--quiet::
 278     Suppress all messages, including warnings and errors.
 279 +
 280 You may :not: use this option with the option:--verbose and
 281 option:--verbose-consumer options.
 282
 283 option:-v, option:--verbose::
 284     Increase verbosity.
 285 +
 286 Specify this option up to three times to get more levels of verbosity.
 287 +
 288 You may :not: use this option with the option:--quiet option.
 289
 290 option:--verbose-consumer::
 291     Increase the verbosity of the consumer daemons which this session
 292     daemon spawns.
 293 +
 294 You may :not: use this option with the option:--quiet option.
 295
 296
 297 Program information
 298 ~~~~~~~~~~~~~~~~~~~
 299 include::common-help-option.txt[]
 300
 301 option:-V, option:--version::
 302     Show version and quit.
 303
 304
 305 EXIT STATUS
 306 -----------
 307 *0*::
 308     Success
 309
 310 *1*::
 311     Error
 312
 313 *3*::
 314     Fatal error
 315
 316
 317 ENVIRONMENT
 318 -----------
 319 `LTTNG_ABORT_ON_ERROR`::
 320     Set to `1` to abort the process after the first error is
 321     encountered.
 322
 323 `LTTNG_APP_SOCKET_TIMEOUT`::
 324     Timeout (in seconds) of the application socket when
 325     sending/receiving commands.
 326 +
 327 After this period of time, `lttng-sessiond` unregisters the application.
 328 +
 329 Set to `0` or `-1` to set an infinite timeout.
 330 +
 331 Default: +{default_app_socket_rw_timeout}+.
 332
 333 `LTTNG_CONSUMERD32_BIN`::
 334     32-bit consumer daemon binary path.
 335 +
 336 The option:--consumerd32-path option overrides this environment
 337 variable.
 338
 339 `LTTNG_CONSUMERD32_LIBDIR`::
 340     32-bit consumer daemon library directory path.
 341 +
 342 The option:--consumerd32-libdir option overrides this environment
 343 variable.
 344
 345 `LTTNG_CONSUMERD64_BIN`::
 346     64-bit consumer daemon binary path.
 347 +
 348 The option:--consumerd64-path option overrides this environment
 349 variable.
 350
 351 `LTTNG_CONSUMERD64_LIBDIR`::
 352     64-bit consumer daemon library directory path.
 353 +
 354 The option:--consumerd64-libdir option overrides this environment
 355 variable.
 356
 357 `LTTNG_DEBUG_NOCLONE`::
 358     Set to `1` to disable the use of man:clone(2)/man:fork(2).
 359 +
 360 Setting this environment variable is considered insecure, but it's
 361 required to allow debuggers to work with `lttng-sessiond` on some
 362 operating systems.
 363
 364 `LTTNG_EXTRA_KMOD_PROBES`::
 365     Extra LTTng kernel probe modules to load.
 366 +
 367 See the option:--extra-kmod-probes option which overrides this
 368 environment variable.
 369
 370 `LTTNG_KMOD_PROBES`::
 371     Exclusive LTTng kernel probe modules to load.
 372 +
 373 See the option:--kmod-probes option which overrides this environment
 374 variable.
 375
 376 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 377     Socket connection, receive, and send timeout (milliseconds).
 378 +
 379 Set to `0` or `-1` to use the timeout of the operating system (default).
 380
 381 `LTTNG_SESSION_CONFIG_XSD_PATH`::
 382     Tracing session configuration XML schema definition (XSD) path.
 383
 384
 385 FILES
 386 -----
 387 `$LTTNG_HOME/.lttng`::
 388     Unix user's LTTng runtime and configuration directory.
 389
 390 `$LTTNG_HOME/lttng-traces`::
 391     Default output directory of LTTng traces in local and snapshot
 392     modes.
 393 +
 394 Override this path with the nloption:--output option of the
 395 man:lttng-create(1) command.
 396
 397 `$LTTNG_HOME/.lttng/sessions/auto`::
 398     Directory from which `lttng-sessiond` loads Unix user tracing
 399     session configurations when starting.
 400 +
 401 See the <<load,Tracing session configuration loading>> section above to
 402 learn more.
 403
 404 +{system_sessions_auto_dir}+::
 405     Directory from which `lttng-sessiond` loads system-wide tracing
 406     session configurations when starting.
 407 +
 408 See the <<load,Tracing session configuration loading>> section above to
 409 learn more.
 410
 411 `$LTTNG_HOME/.lttng/lttng.conf`::
 412     Unix user's LTTng daemon INI configuration file.
 413 +
 414 See the <<cfg,Daemon configuration>> section above to learn more.
 415
 416 +{system_lttng_conf}+::
 417     System-wide LTTng daemon INI configuration file.
 418 +
 419 See the <<cfg,Daemon configuration>> section above to learn more.
 420
 421 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
 422
 423
 424 include::common-footer.txt[]
 425
 426
 427 SEE ALSO
 428 --------
 429 man:lttng(1),
 430 man:lttng-concepts(7)