doc/man: use double quotes when referring to internal section
[lttng-tools.git] / 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
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 Tracing 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 tracing
400 session configurations when starting.
401 +
402 See the ``<<load,Tracing session configuration loading>>'' section above
403 to learn more.
404
405 +{system_sessions_auto_dir}+::
406 Directory from which `lttng-sessiond` loads system-wide tracing
407 session configurations when starting.
408 +
409 See the ``<<load,Tracing session configuration loading>>'' section above
410 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)
This page took 0.041146 seconds and 6 git commands to generate.