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