usr/src/man/man1m/coreadm.1m

   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 1M "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
  15
  16 .LP
  17 .nf
  18 \fBcoreadm\fR [\fB-p\fR \fIpattern\fR] [\fB-P\fR \fIcontent\fR] [\fIpid\fR]...
  19 .fi
  20
  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(1M) 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
  53
  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
  63
  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
  73
  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
  83
  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
  93
  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
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fB%t\fR\fR
 108 .ad
 109 .sp .6
 110 .RS 4n
 111 Decimal value of \fBtime\fR(2)
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fB%u\fR\fR
 118 .ad
 119 .sp .6
 120 .RS 4n
 121 Effective user-\fBID\fR
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB%z\fR\fR
 128 .ad
 129 .sp .6
 130 .RS 4n
 131 Name of the zone in which process executed (\fBzonename\fR)
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 .B %Z
 138 .ad
 139 .sp .6
 140 .RS 4n
 141 The path to the root of the zone in which process executed
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fB%%\fR\fR
 148 .ad
 149 .sp .6
 150 .RS 4n
 151 Literal \fB%\fR
 152 .RE
 153
 154 .sp
 155 .LP
 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.
 159 .sp
 160 .LP
 161 A core file content description is specified using a series of tokens to
 162 identify parts of a process's binary image:
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBanon\fR\fR
 167 .ad
 168 .sp .6
 169 .RS 4n
 170 Anonymous private mappings, including thread stacks that are not main thread
 171 stacks
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBctf\fR\fR
 178 .ad
 179 .sp .6
 180 .RS 4n
 181 CTF type information sections for loaded object files
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBdata\fR\fR
 188 .ad
 189 .sp .6
 190 .RS 4n
 191 Writable private file mappings
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBdism\fR\fR
 198 .ad
 199 .sp .6
 200 .RS 4n
 201 DISM mappings
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBheap\fR\fR
 208 .ad
 209 .sp .6
 210 .RS 4n
 211 Process heap
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBism\fR\fR
 218 .ad
 219 .sp .6
 220 .RS 4n
 221 ISM mappings
 222 .RE
 223
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBrodata\fR\fR
 228 .ad
 229 .sp .6
 230 .RS 4n
 231 Read-only private file mappings
 232 .RE
 233
 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fBshanon\fR\fR
 238 .ad
 239 .sp .6
 240 .RS 4n
 241 Anonymous shared mappings
 242 .RE
 243
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBshfile\fR\fR
 248 .ad
 249 .sp .6
 250 .RS 4n
 251 Shared mappings that are backed by files
 252 .RE
 253
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fBshm\fR\fR
 258 .ad
 259 .sp .6
 260 .RS 4n
 261 System V shared memory
 262 .RE
 263
 264 .sp
 265 .ne 2
 266 .na
 267 \fB\fBstack\fR\fR
 268 .ad
 269 .sp .6
 270 .RS 4n
 271 Process stack
 272 .RE
 273
 274 .sp
 275 .ne 2
 276 .na
 277 \fB\fBsymtab\fR\fR
 278 .ad
 279 .sp .6
 280 .RS 4n
 281 Symbol table sections for loaded object files
 282 .RE
 283
 284 .sp
 285 .ne 2
 286 .na
 287 \fB\fBtext\fR\fR
 288 .ad
 289 .sp .6
 290 .RS 4n
 291 Readable and executable private file mappings
 292 .RE
 293
 294 .sp
 295 .LP
 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.
 303 .sp
 304 .LP
 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.
 308 .sp
 309 .LP
 310 The \fBcoreadm\fR command with no arguments reports the current system
 311 configuration, for example:
 312 .sp
 313 .in +2
 314 .nf
 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
 325 .fi
 326 .in -2
 327 .sp
 328
 329 .sp
 330 .LP
 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:
 333 .sp
 334 .in +2
 335 .nf
 336 $ coreadm 278 5678
 337   278:   core.%f.%p default
 338   5678:  /home/george/cores/%f.%p.%t all-ism
 339 .fi
 340 .in -2
 341 .sp
 342
 343 .sp
 344 .LP
 345 Only the owner of a process or a user with the \fBproc_owner\fR privilege can
 346 interrogate a process in this manner.
 347 .sp
 348 .LP
 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.
 354 .sp
 355 .LP
 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.
 358 .sp
 359 .LP
 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.
 362 .sp
 363 .LP
 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
 373 .sp
 374 .LP
 375 The following options are supported:
 376 .sp
 377 .ne 2
 378 .na
 379 \fB\fB-d\fR \fIoption\fR...\fR
 380 .ad
 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.
 385 .sp
 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.
 389 .RE
 390
 391 .sp
 392 .ne 2
 393 .na
 394 \fB\fB-e\fR \fIoption\fR...\fR
 395 .ad
 396 .sp .6
 397 .RS 4n
 398 Enable the specified core file option. Specify \fIoption\fR as one of the
 399 following:
 400 .sp
 401 .ne 2
 402 .na
 403 \fBglobal\fR
 404 .ad
 405 .sp .6
 406 .RS 4n
 407 Allow core dumps that use global core pattern.
 408 .RE
 409
 410 .sp
 411 .ne 2
 412 .na
 413 \fBglobal-setid\fR
 414 .ad
 415 .sp .6
 416 .RS 4n
 417 Allow set-id core dumps that use global core pattern.
 418 .RE
 419
 420 .sp
 421 .ne 2
 422 .na
 423 \fBlog\fR
 424 .ad
 425 .sp .6
 426 .RS 4n
 427 Generate a \fBsyslog\fR(3C) message when generation of a global core file is
 428 attempted.
 429 .RE
 430
 431 .sp
 432 .ne 2
 433 .na
 434 \fBprocess\fR
 435 .ad
 436 .sp .6
 437 .RS 4n
 438 Allow core dumps that use per-process core pattern.
 439 .RE
 440
 441 .sp
 442 .ne 2
 443 .na
 444 \fBproc-setid\fR
 445 .ad
 446 .sp .6
 447 .RS 4n
 448 Allow set-id core dumps that use per-process core pattern.
 449 .sp
 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.
 453 .RE
 454
 455 .RE
 456
 457 .sp
 458 .ne 2
 459 .na
 460 \fB\fB-g\fR \fIpattern\fR\fR
 461 .ad
 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.
 467 .sp
 468 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
 469 use this option.
 470 .RE
 471
 472 .sp
 473 .ne 2
 474 .na
 475 \fB\fB-G\fR \fIcontent\fR\fR
 476 .ad
 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.
 481 .sp
 482 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
 483 use this option.
 484 .RE
 485
 486 .sp
 487 .ne 2
 488 .na
 489 \fB\fB-i\fR \fIpattern\fR\fR
 490 .ad
 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.
 498 .sp
 499 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
 500 use this option.
 501 .RE
 502
 503 .sp
 504 .ne 2
 505 .na
 506 \fB\fB-I\fR \fIcontent\fR\fR
 507 .ad
 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.
 515 .sp
 516 Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
 517 use this option.
 518 .RE
 519
 520 .sp
 521 .ne 2
 522 .na
 523 \fB\fB-p\fR \fIpattern\fR\fR
 524 .ad
 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.
 532 .sp
 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).
 537 .sp
 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).
 541 .RE
 542
 543 .sp
 544 .ne 2
 545 .na
 546 \fB\fB-P\fR \fIcontent\fR\fR
 547 .ad
 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.
 553 .sp
 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).
 558 .sp
 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).
 562 .RE
 563
 564 .SH OPERANDS
 565 .sp
 566 .LP
 567 The following operands are supported:
 568 .sp
 569 .ne 2
 570 .na
 571 \fB\fIpid\fR\fR
 572 .ad
 573 .sp .6
 574 .RS 4n
 575 process-\fBID\fR
 576 .RE
 577
 578 .SH EXAMPLES
 579 .LP
 580 \fBExample 1 \fRSetting the Core File Name Pattern
 581 .sp
 582 .LP
 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:
 586
 587 .sp
 588 .in +2
 589 .nf
 590 example$  coreadm -p core.%f.%p
 591 .fi
 592 .in -2
 593 .sp
 594
 595 .sp
 596 .LP
 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.
 600
 601 .LP
 602 \fBExample 2 \fRDumping a User's Files Into a Subdirectory
 603 .sp
 604 .LP
 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.
 609
 610 .sp
 611 .in +2
 612 .nf
 613 example$  coreadm -p $HOME/corefiles/%n.%f.%p 1234
 614 .fi
 615 .in -2
 616 .sp
 617
 618 .LP
 619 \fBExample 3 \fRCulling the Global Core File Repository
 620 .sp
 621 .LP
 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.
 625
 626 .sp
 627 .in +2
 628 .nf
 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
 632 .fi
 633 .in -2
 634 .sp
 635
 636 .SH FILES
 637 .sp
 638 .ne 2
 639 .na
 640 \fB\fB/var/cores\fR\fR
 641 .ad
 642 .sp .6
 643 .RS 4n
 644 Directory provided for global core file storage.
 645 .RE
 646
 647 .SH EXIT STATUS
 648 .sp
 649 .LP
 650 The following exit values are returned:
 651 .sp
 652 .ne 2
 653 .na
 654 \fB0\fR
 655 .ad
 656 .sp .6
 657 .RS 4n
 658 Successful completion.
 659 .RE
 660
 661 .sp
 662 .ne 2
 663 .na
 664 \fB1\fR
 665 .ad
 666 .sp .6
 667 .RS 4n
 668 A fatal error occurred while either obtaining or modifying the system core file
 669 configuration.
 670 .RE
 671
 672 .sp
 673 .ne 2
 674 .na
 675 \fB2\fR
 676 .ad
 677 .sp .6
 678 .RS 4n
 679 Invalid command-line options were specified.
 680 .RE
 681
 682 .SH SEE ALSO
 683 .sp
 684 .LP
 685 \fBgcore\fR(1), \fBpfexec\fR(1), \fBsvcs\fR(1), \fBinit\fR(1M),
 686 \fBsvcadm\fR(1M), \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
 690 .sp
 691 .LP
 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.
 694 .sp
 695 .LP
 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.
 699 .sp
 700 .LP
 701 The \fBcoreadm\fR service is managed by the service management facility,
 702 \fBsmf\fR(5), under the service identifier:
 703 .sp
 704 .in +2
 705 .nf
 706 svc:/system/coreadm:default
 707 .fi
 708 .in -2
 709 .sp
 710
 711 .sp
 712 .LP
 713 Administrative actions on this service, such as enabling, disabling, or
 714 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
 715 status can be queried using the \fBsvcs\fR(1) command.
 716 .sp
 717 .LP
 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.