doc/man/lttng-sessiond.8.txt

   1 lttng-sessiond(8)
   2 =================
   3 :revdate: 14 June 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 recording sessions (see man:lttng-concepts(7) to learn more
  42   about recording 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 Recording session configuration loading
 102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 103 When the session daemon starts, it loads recording session
 104 configurations 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 recording session configuration files from
 118 the 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 recording session configurations from 'PATH', either a
 168     directory or a file, instead of loading them from the default search
 169     directories.
 170 +
 171 See the ``<<load,Recording session configuration loading>>'' section
 172 above.
 173
 174 option:-S, option:--sig-parent::
 175     Send the `USR1` signal to the parent process to notify readiness.
 176 +
 177 You can also use the option:--daemonize or option:--background option,
 178 in which case `lttng-sessiond` ensures the daemon is ready to receive
 179 client commands before it exits.
 180
 181
 182 Linux kernel tracing
 183 ~~~~~~~~~~~~~~~~~~~~
 184 At most one of:
 185
 186 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
 187     For each 'PROBE' argument, load the LTTng kernel probe module
 188     named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the
 189     default LTTng kernel probe modules.
 190 +
 191 See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable.
 192
 193 option:--kmod-probes='PROBE'[,'PROBE']...::
 194     Only load, for each 'PROBE' argument, the LTTng kernel probe
 195     module named ++lttng-probe-++__PROBE__++.ko++, instead of loading
 196     the default LTTng kernel probe modules.
 197 +
 198 See also the `LTTNG_KMOD_PROBES` environment variable.
 199
 200 option:--no-kernel::
 201     Disable Linux kernel tracing.
 202
 203
 204 Paths and ports
 205 ~~~~~~~~~~~~~~~
 206 option:--agent-tcp-port='PORT'::
 207     Listen on TCP port 'PORT' for agent application registration
 208     instead of a port within the range
 209     [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
 210
 211 option:-a 'PATH', option:--apps-sock='PATH'::
 212     Set the application Unix socket path to 'PATH'.
 213
 214 option:-c 'PATH', option:--client-sock='PATH'::
 215     Set the client Unix socket path to 'PATH'.
 216
 217 option:--consumerd32-libdir='PATH'::
 218     Set the 32-bit consumer daemon library directory to 'PATH'.
 219 +
 220 See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable.
 221
 222 option:--consumerd32-path='PATH'::
 223     Set the 32-bit consumer daemon binary path to 'PATH'.
 224 +
 225 See also the `LTTNG_CONSUMERD32_BIN` environment variable.
 226
 227 option:--consumerd64-libdir='PATH'::
 228     Set the 64-bit consumer daemon library directory to 'PATH'.
 229 +
 230 See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable.
 231
 232 option:--consumerd64-path='PATH'::
 233     Set the 64-bit consumer daemon binary path to 'PATH'.
 234 +
 235 See also the `LTTNG_CONSUMERD32_BIN` environment variable.
 236
 237 option:--kconsumerd-cmd-sock='PATH'::
 238     Set the command Unix socket path of the Linux kernel consumer daemon
 239     to 'PATH'.
 240
 241 option:--kconsumerd-err-sock='PATH'::
 242     Set the error Unix socket path of the Linux kernel consumer daemon
 243     to 'PATH'.
 244
 245 option:--ustconsumerd32-cmd-sock='PATH'::
 246     Set the Unix socket path of the 32-bit consumer daemon command to
 247     'PATH'.
 248
 249 option:--ustconsumerd64-cmd-sock='PATH'::
 250     Set the Unix socket path of the 64-bit consumer daemon command to
 251     'PATH'.
 252
 253 option:--ustconsumerd32-err-sock='PATH'::
 254     Set the Unix socket path of the 32-bit consumer daemon error to
 255     'PATH'.
 256
 257 option:--ustconsumerd64-err-sock='PATH'::
 258     Set the Unix socket path of the 64-bit consumer daemon error to
 259     'PATH'.
 260
 261
 262 Buffer size of event notifier error counters
 263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 264 option:--event-notifier-error-buffer-size-kernel='SLOTS'::
 265     Set the size of the kernel event notifier error counter buffers to
 266     'SLOTS'{nbsp}slots.
 267
 268 option:--event-notifier-error-buffer-size-userspace='SLOTS'::
 269     Set the size of the user space event notifier error counter buffers
 270     to 'SLOTS'{nbsp}slots.
 271
 272 As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
 273 may change in the future.
 274
 275
 276 Verbosity
 277 ~~~~~~~~~
 278 option:-q, option:--quiet::
 279     Suppress all messages, including warnings and errors.
 280 +
 281 You may :not: use this option with the option:--verbose and
 282 option:--verbose-consumer options.
 283
 284 option:-v, option:--verbose::
 285     Increase verbosity.
 286 +
 287 Specify this option up to three times to get more levels of verbosity.
 288 +
 289 You may :not: use this option with the option:--quiet option.
 290
 291 option:--verbose-consumer::
 292     Increase the verbosity of the consumer daemons which this session
 293     daemon spawns.
 294 +
 295 You may :not: use this option with the option:--quiet option.
 296
 297
 298 Program information
 299 ~~~~~~~~~~~~~~~~~~~
 300 include::common-help-option.txt[]
 301
 302 option:-V, option:--version::
 303     Show version and quit.
 304
 305
 306 EXIT STATUS
 307 -----------
 308 *0*::
 309     Success
 310
 311 *1*::
 312     Error
 313
 314 *3*::
 315     Fatal error
 316
 317
 318 ENVIRONMENT
 319 -----------
 320 `LTTNG_ABORT_ON_ERROR`::
 321     Set to `1` to abort the process after the first error is
 322     encountered.
 323
 324 `LTTNG_APP_SOCKET_TIMEOUT`::
 325     Timeout (in seconds) of the application socket when
 326     sending/receiving commands.
 327 +
 328 After this period of time, `lttng-sessiond` unregisters the application.
 329 +
 330 Set to `0` or `-1` to set an infinite timeout.
 331 +
 332 Default: +{default_app_socket_rw_timeout}+.
 333
 334 `LTTNG_CONSUMERD32_BIN`::
 335     32-bit consumer daemon binary path.
 336 +
 337 The option:--consumerd32-path option overrides this environment
 338 variable.
 339
 340 `LTTNG_CONSUMERD32_LIBDIR`::
 341     32-bit consumer daemon library directory path.
 342 +
 343 The option:--consumerd32-libdir option overrides this environment
 344 variable.
 345
 346 `LTTNG_CONSUMERD64_BIN`::
 347     64-bit consumer daemon binary path.
 348 +
 349 The option:--consumerd64-path option overrides this environment
 350 variable.
 351
 352 `LTTNG_CONSUMERD64_LIBDIR`::
 353     64-bit consumer daemon library directory path.
 354 +
 355 The option:--consumerd64-libdir option overrides this environment
 356 variable.
 357
 358 `LTTNG_DEBUG_NOCLONE`::
 359     Set to `1` to disable the use of man:clone(2)/man:fork(2).
 360 +
 361 Setting this environment variable is considered insecure, but it's
 362 required to allow debuggers to work with `lttng-sessiond` on some
 363 operating systems.
 364
 365 `LTTNG_EXTRA_KMOD_PROBES`::
 366     Extra LTTng kernel probe modules to load.
 367 +
 368 See the option:--extra-kmod-probes option which overrides this
 369 environment variable.
 370
 371 `LTTNG_KMOD_PROBES`::
 372     Exclusive LTTng kernel probe modules to load.
 373 +
 374 See the option:--kmod-probes option which overrides this environment
 375 variable.
 376
 377 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 378     Socket connection, receive, and send timeout (milliseconds).
 379 +
 380 Set to `0` or `-1` to use the timeout of the operating system (default).
 381
 382 `LTTNG_SESSION_CONFIG_XSD_PATH`::
 383     Recording session configuration XML schema definition (XSD) path.
 384
 385
 386 FILES
 387 -----
 388 `$LTTNG_HOME/.lttng`::
 389     Unix user's LTTng runtime and configuration directory.
 390
 391 `$LTTNG_HOME/lttng-traces`::
 392     Default output directory of LTTng traces in local and snapshot
 393     modes.
 394 +
 395 Override this path with the nloption:--output option of the
 396 man:lttng-create(1) command.
 397
 398 `$LTTNG_HOME/.lttng/sessions/auto`::
 399     Directory from which `lttng-sessiond` loads Unix user recording
 400     session configurations when starting.
 401 +
 402 See the ``<<load,Recording session configuration loading>>'' section
 403 above to learn more.
 404
 405 +{system_sessions_auto_dir}+::
 406     Directory from which `lttng-sessiond` loads system-wide recording
 407     session configurations when starting.
 408 +
 409 See the ``<<load,Recording session configuration loading>>'' section
 410 above to learn more.
 411
 412 `$LTTNG_HOME/.lttng/lttng.conf`::
 413     Unix user's LTTng daemon INI configuration file.
 414 +
 415 See the ``<<cfg,Daemon configuration>>'' section above to learn more.
 416
 417 +{system_lttng_conf}+::
 418     System-wide LTTng daemon INI configuration file.
 419 +
 420 See the ``<<cfg,Daemon configuration>>'' section above to learn more.
 421
 422 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
 423
 424
 425 include::common-footer.txt[]
 426
 427
 428 SEE ALSO
 429 --------
 430 man:lttng(1),
 431 man:lttng-concepts(7)