Unleashed v1.4
[unleashed.git] / share / man / man8 / coreadm.8
blob5691b5af48b43c3c4d7cd15f25d5048abaea4ad2
1 '\" te
2 .\"  Copyright 1989 AT&T Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH COREADM 8 "Feb 28, 2014"
7 .SH NAME
8 coreadm \- core file administration
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcoreadm\fR [\fB-g\fR \fIpattern\fR] [\fB-G\fR \fIcontent\fR] [\fB-i\fR \fIpattern\fR] [\fB-I\fR \fIcontent\fR]
13      [\fB-d\fR \fIoption\fR]... [\fB-e\fR \fIoption\fR]...
14 .fi
16 .LP
17 .nf
18 \fBcoreadm\fR [\fB-p\fR \fIpattern\fR] [\fB-P\fR \fIcontent\fR] [\fIpid\fR]...
19 .fi
21 .SH DESCRIPTION
22 .sp
23 .LP
24 \fBcoreadm\fR specifies the name and location of core files produced by
25 abnormally-terminating processes. See \fBcore\fR(4).
26 .sp
27 .LP
28 Only users and roles that belong to the "Maintenance and Repair" RBAC profile
29 can execute the first form of the \fBSYNOPSIS\fR. This form configures
30 system-wide core file options, including a global core file name pattern and a
31 core file name pattern for the \fBinit\fR(8) process. All settings are saved
32 persistently and will be applied at boot.
33 .sp
34 .LP
35 Non-privileged users can execute the second form of the \fBSYNOPSIS\fR. This
36 form specifies the file name pattern and core file content that the operating
37 system uses to generate a per-process core file.
38 .sp
39 .LP
40 A core file name pattern is a normal file system path name with embedded
41 variables, specified with a leading \fB%\fR character. The variables are
42 expanded from values that are effective when a core file is generated by the
43 operating system. The possible embedded variables are as follows:
44 .sp
45 .ne 2
46 .na
47 \fB\fB%d\fR\fR
48 .ad
49 .sp .6
50 .RS 4n
51 Executable file directory name, up to a maximum of \fBMAXPATHLEN\fR characters
52 .RE
54 .sp
55 .ne 2
56 .na
57 \fB\fB%f\fR\fR
58 .ad
59 .sp .6
60 .RS 4n
61 Executable file name, up to a maximum of \fBMAXCOMLEN\fR characters
62 .RE
64 .sp
65 .ne 2
66 .na
67 \fB\fB%g\fR\fR
68 .ad
69 .sp .6
70 .RS 4n
71 Effective group-\fBID\fR
72 .RE
74 .sp
75 .ne 2
76 .na
77 \fB\fB%m\fR\fR
78 .ad
79 .sp .6
80 .RS 4n
81 Machine name (\fBuname\fR \fB-m\fR)
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fB%n\fR\fR
88 .ad
89 .sp .6
90 .RS 4n
91 System node name (\fBuname\fR \fB-n\fR)
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fB%p\fR\fR
98 .ad
99 .sp .6
100 .RS 4n
101 Process-\fBID\fR
105 .ne 2
107 \fB\fB%t\fR\fR
109 .sp .6
110 .RS 4n
111 Decimal value of \fBtime\fR(2)
115 .ne 2
117 \fB\fB%u\fR\fR
119 .sp .6
120 .RS 4n
121 Effective user-\fBID\fR
125 .ne 2
127 \fB\fB%z\fR\fR
129 .sp .6
130 .RS 4n
131 Name of the zone in which process executed (\fBzonename\fR)
135 .ne 2
137 .B %Z
139 .sp .6
140 .RS 4n
141 The path to the root of the zone in which process executed
145 .ne 2
147 \fB\fB%%\fR\fR
149 .sp .6
150 .RS 4n
151 Literal \fB%\fR
156 For example, the core file name pattern \fB/var/cores/core.%f.%p\fR would
157 result, for command \fBfoo\fR with process-\fBID\fR \fB1234\fR, in the core
158 file name \fB/var/cores/core.foo.1234\fR.
161 A core file content description is specified using a series of tokens to
162 identify parts of a process's binary image:
164 .ne 2
166 \fB\fBanon\fR\fR
168 .sp .6
169 .RS 4n
170 Anonymous private mappings, including thread stacks that are not main thread
171 stacks
175 .ne 2
177 \fB\fBctf\fR\fR
179 .sp .6
180 .RS 4n
181 CTF type information sections for loaded object files
185 .ne 2
187 \fB\fBdata\fR\fR
189 .sp .6
190 .RS 4n
191 Writable private file mappings
195 .ne 2
197 \fB\fBdism\fR\fR
199 .sp .6
200 .RS 4n
201 DISM mappings
205 .ne 2
207 \fB\fBheap\fR\fR
209 .sp .6
210 .RS 4n
211 Process heap
215 .ne 2
217 \fB\fBism\fR\fR
219 .sp .6
220 .RS 4n
221 ISM mappings
225 .ne 2
227 \fB\fBrodata\fR\fR
229 .sp .6
230 .RS 4n
231 Read-only private file mappings
235 .ne 2
237 \fB\fBshanon\fR\fR
239 .sp .6
240 .RS 4n
241 Anonymous shared mappings
245 .ne 2
247 \fB\fBshfile\fR\fR
249 .sp .6
250 .RS 4n
251 Shared mappings that are backed by files
255 .ne 2
257 \fB\fBshm\fR\fR
259 .sp .6
260 .RS 4n
261 System V shared memory
265 .ne 2
267 \fB\fBstack\fR\fR
269 .sp .6
270 .RS 4n
271 Process stack
275 .ne 2
277 \fB\fBsymtab\fR\fR
279 .sp .6
280 .RS 4n
281 Symbol table sections for loaded object files
285 .ne 2
287 \fB\fBtext\fR\fR
289 .sp .6
290 .RS 4n
291 Readable and executable private file mappings
296 In addition, you can use the token \fBall\fR to indicate that core files should
297 include all of these parts of the process's binary image. You can use the token
298 \fBnone\fR to indicate that no mappings are to be included. The \fBdefault\fR
299 token indicates inclusion of the system default content
300 (\fBstack+heap+shm+ism+dism+text+data+rodata+anon+shanon+ctf+symtab\fR). The
301 \fB/proc\fR file system data structures are always present in core files
302 regardless of the mapping content.
305 You can use \fB+\fR and \fB-\fR to concatenate tokens. For example, the core
306 file content \fBdefault-ism\fR would produce a core file with the default set
307 of mappings without any intimate shared memory mappings.
310 The \fBcoreadm\fR command with no arguments reports the current system
311 configuration, for example:
313 .in +2
315 $ coreadm
316     global core file pattern: /var/cores/core.%f.%p
317     global core file content: all
318       init core file pattern: core
319       init core file content: default
320            global core dumps: enabled
321       per-process core dumps: enabled
322      global setid core dumps: enabled
323 per-process setid core dumps: disabled
324     global core dump logging: disabled
326 .in -2
331 The \fBcoreadm\fR command with only a list of process-\fBID\fRs reports each
332 process's per-process core file name pattern, for example:
334 .in +2
336 $ coreadm 278 5678
337   278:   core.%f.%p default
338   5678:  /home/george/cores/%f.%p.%t all-ism
340 .in -2
345 Only the owner of a process or a user with the \fBproc_owner\fR privilege can
346 interrogate a process in this manner.
349 When a process is dumping core, up to three core files can be produced: one in
350 the per-process location, one in the system-wide global location, and, if the
351 process was running in a local (non-global) zone, one in the global location
352 for the zone in which that process was running. Each core file is generated
353 according to the effective options for the corresponding location.
356 When generated, a global core file is created in mode \fB600\fR and owned by
357 the superuser. Nonprivileged users cannot examine such files.
360 Ordinary per-process core files are created in mode \fB600\fR under the
361 credentials of the process. The owner of the process can examine such files.
364 A process that is or ever has been \fBsetuid\fR or \fBsetgid\fR since its last
365 \fBexec\fR(2) presents security issues that relate to dumping core. Similarly,
366 a process that initially had superuser privileges and lost those privileges
367 through \fBsetuid\fR(2) also presents security issues that are related to
368 dumping core. A process of either type can contain sensitive information in its
369 address space to which the current nonprivileged owner of the process should
370 not have access. If \fBsetid\fR core files are enabled, they are created mode
371 \fB600\fR and owned by the superuser.
372 .SH OPTIONS
375 The following options are supported:
377 .ne 2
379 \fB\fB-d\fR \fIoption\fR...\fR
381 .sp .6
382 .RS 4n
383 Disable the specified core file option. See the \fB-e\fR \fIoption\fR for
384 descriptions of possible options.
386 Multiple \fB-e\fR and \fB-d\fR options can be specified on the command line.
387 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
388 use this option.
392 .ne 2
394 \fB\fB-e\fR \fIoption\fR...\fR
396 .sp .6
397 .RS 4n
398 Enable the specified core file option. Specify \fIoption\fR as one of the
399 following:
401 .ne 2
403 \fBglobal\fR
405 .sp .6
406 .RS 4n
407 Allow core dumps that use global core pattern.
411 .ne 2
413 \fBglobal-setid\fR
415 .sp .6
416 .RS 4n
417 Allow set-id core dumps that use global core pattern.
421 .ne 2
423 \fBlog\fR
425 .sp .6
426 .RS 4n
427 Generate a \fBsyslog\fR(3C) message when generation of a global core file is
428 attempted.
432 .ne 2
434 \fBprocess\fR
436 .sp .6
437 .RS 4n
438 Allow core dumps that use per-process core pattern.
442 .ne 2
444 \fBproc-setid\fR
446 .sp .6
447 .RS 4n
448 Allow set-id core dumps that use per-process core pattern.
450 Multiple \fB-e\fR and \fB-d\fR options can be specified on the command line.
451 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
452 use this option.
458 .ne 2
460 \fB\fB-g\fR \fIpattern\fR\fR
462 .sp .6
463 .RS 4n
464 Set the global core file name pattern to \fIpattern\fR. The pattern must start
465 with a \fB/\fR and can contain any of the special \fB%\fR variables that are
466 described in the \fBDESCRIPTION\fR.
468 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
469 use this option.
473 .ne 2
475 \fB\fB-G\fR \fIcontent\fR\fR
477 .sp .6
478 .RS 4n
479 Set the global core file content to content. You must specify content by using
480 the tokens that are described in the \fBDESCRIPTION\fR.
482 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
483 use this option.
487 .ne 2
489 \fB\fB-i\fR \fIpattern\fR\fR
491 .sp .6
492 .RS 4n
493 Set the default per-process core file name to \fIpattern\fR. This changes the
494 per-process pattern for any process whose per-process pattern is still set to
495 the default. Processes that have had their per-process pattern set or are
496 descended from a process that had its per-process pattern set (using the
497 \fB-p\fR option) are unaffected. This default persists across reboot.
499 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
500 use this option.
504 .ne 2
506 \fB\fB-I\fR \fIcontent\fR\fR
508 .sp .6
509 .RS 4n
510 Set the default per-process core file content to \fIcontent\fR. This changes
511 the per-process content for any process whose per-process content is still set
512 to the default. Processes that have had their per-process content set or are
513 descended from a process that had its per-process content set (using the
514 \fB-P\fR option) are unaffected. This default persists across reboot.
516 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
517 use this option.
521 .ne 2
523 \fB\fB-p\fR \fIpattern\fR\fR
525 .sp .6
526 .RS 4n
527 Set the per-process core file name pattern to \fIpattern\fR for each of the
528 specified process-\fBID\fRs. The pattern can contain any of the special \fB%\fR
529 variables described in the \fBDESCRIPTION\fR and need not begin with \fB/\fR.
530 If the pattern does not begin with \fB/\fR, it is evaluated relative to the
531 directory that is current when the process generates a core file.
533 A nonprivileged user can apply the \fB-p\fR option only to processes that are
534 owned by that user. A user with the \fBproc_owner\fR privilege can apply the
535 option to any process. The per-process core file name pattern is inherited by
536 future child processes of the affected processes. See \fBfork\fR(2).
538 If no process-\fBID\fRs are specified, the \fB-p\fR option sets the per-process
539 core file name pattern to \fIpattern\fR on the parent process (usually the
540 shell that ran \fBcoreadm\fR).
544 .ne 2
546 \fB\fB-P\fR \fIcontent\fR\fR
548 .sp .6
549 .RS 4n
550 Set the per-process core file content to \fIcontent\fR for each of the
551 specified process-IDs. The content must be specified by using the tokens that
552 are described in the \fBDESCRIPTION\fR.
554 A nonprivileged user can apply the \fB-p\fR option only to processes that are
555 owned by that user. A user with the \fBproc_owner\fR privilege can apply the
556 option to any process. The per-process core file name pattern is inherited by
557 future child processes of the affected processes. See \fBfork\fR(2).
559 If no process-\fBID\fRs are specified, the \fB-P\fR option sets the per-process
560 file content to \fIcontent\fR on the parent process (usually the shell that ran
561 \fBcoreadm\fR).
564 .SH OPERANDS
567 The following operands are supported:
569 .ne 2
571 \fB\fIpid\fR\fR
573 .sp .6
574 .RS 4n
575 process-\fBID\fR
578 .SH EXAMPLES
580 \fBExample 1 \fRSetting the Core File Name Pattern
583 When executed from a user's \fB$HOME/.profile\fR or \fB$HOME/.login\fR, the
584 following command sets the core file name pattern for all processes that are
585 run during the login session:
588 .in +2
590 example$  coreadm -p core.%f.%p
592 .in -2
597 Note that since the process-\fBID\fR is omitted, the per-process core file name
598 pattern will be set in the shell that is currently running and is inherited by
599 all child processes.
602 \fBExample 2 \fRDumping a User's Files Into a Subdirectory
605 The following command dumps all of a user's core dumps into the \fBcorefiles\fR
606 subdirectory of the home directory, discriminated by the system node name. This
607 command is useful for users who use many different machines but have a shared
608 home directory.
611 .in +2
613 example$  coreadm -p $HOME/corefiles/%n.%f.%p 1234
615 .in -2
619 \fBExample 3 \fRCulling the Global Core File Repository
622 The following commands set up the system to produce core files in the global
623 repository only if the executables were run from \fB/usr/bin\fR or
624 \fB/usr/sbin\fR.
627 .in +2
629 example# mkdir -p /var/cores/usr/bin
630 example# mkdir -p /var/cores/usr/sbin
631 example# coreadm -G all -g /var/cores/%d/%f.%p.%n
633 .in -2
636 .SH FILES
638 .ne 2
640 \fB\fB/var/cores\fR\fR
642 .sp .6
643 .RS 4n
644 Directory provided for global core file storage.
647 .SH EXIT STATUS
650 The following exit values are returned:
652 .ne 2
654 \fB0\fR
656 .sp .6
657 .RS 4n
658 Successful completion.
662 .ne 2
664 \fB1\fR
666 .sp .6
667 .RS 4n
668 A fatal error occurred while either obtaining or modifying the system core file
669 configuration.
673 .ne 2
675 \fB2\fR
677 .sp .6
678 .RS 4n
679 Invalid command-line options were specified.
682 .SH SEE ALSO
685 \fBgcore\fR(1), \fBpfexec\fR(1), \fBsvcs\fR(1), \fBinit\fR(8),
686 \fBsvcadm\fR(8), \fBexec\fR(2), \fBfork\fR(2), \fBsetuid\fR(2), \fBtime\fR(2),
687 \fBsyslog\fR(3C), \fBcore\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4),
688 \fBattributes\fR(5), \fBsmf\fR(5)
689 .SH NOTES
692 In a local (non-global) zone, the global settings apply to processes running in
693 that zone. In addition, the global zone's apply to processes run in any zone.
696 The term \fBglobal settings\fR refers to settings which are applied to the
697 system or zone as a whole, and does not necessarily imply that the settings are
698 to take effect in the global zone.
701 The \fBcoreadm\fR service is managed by the service management facility,
702 \fBsmf\fR(5), under the service identifier:
704 .in +2
706 svc:/system/coreadm:default
708 .in -2
713 Administrative actions on this service, such as enabling, disabling, or
714 requesting restart, can be performed using \fBsvcadm\fR(8). The service's
715 status can be queried using the \fBsvcs\fR(1) command.
718 The \fB-g\fR, \fB-G\fR, \fB-i\fR, \fB-I\fR, \fB-e\fR, and \fB-d\fR options can
719 be also used by a user, role, or profile that has been granted both the
720 \fBsolaris.smf.manage.coreadm\fR and \fBsolaris.smf.value.coreadm\fR
721 authorizations.