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