path: root/usr/src/man/man8/coreadm.8

'\" te
.\"  Copyright 1989 AT&T Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
.\"  Copyright 2021 Oxide Computer Company
.\" 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.
.\" 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.
.\" 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]
.TH COREADM 8 "August 3, 2021"
.SH NAME
coreadm \- core file administration
.SH SYNOPSIS
.nf
\fBcoreadm\fR [\fB-g\fR \fIpattern\fR] [\fB-G\fR \fIcontent\fR] [\fB-i\fR \fIpattern\fR] [\fB-I\fR \fIcontent\fR]
     [\fB-d\fR \fIoption\fR]... [\fB-e\fR \fIoption\fR]...
.fi

.LP
.nf
\fBcoreadm\fR [\fB-p\fR \fIpattern\fR] [\fB-P\fR \fIcontent\fR] [\fIpid\fR]...
.fi

.SH DESCRIPTION
\fBcoreadm\fR specifies the name and location of core files produced by
abnormally-terminating processes. See \fBcore\fR(5).
.sp
.LP
Only users and roles that belong to the "Maintenance and Repair" RBAC profile
can execute the first form of the \fBSYNOPSIS\fR. This form configures
system-wide core file options, including a global core file name pattern and a
core file name pattern for the \fBinit\fR(8) process. All settings are saved
persistently and will be applied at boot.
.sp
.LP
Non-privileged users can execute the second form of the \fBSYNOPSIS\fR. This
form specifies the file name pattern and core file content that the operating
system uses to generate a per-process core file.
.sp
.LP
A core file name pattern is a normal file system path name with embedded
variables, specified with a leading \fB%\fR character. The variables are
expanded from values that are effective when a core file is generated by the
operating system. The possible embedded variables are as follows:
.sp
.ne 2
.na
\fB\fB%d\fR\fR
.ad
.sp .6
.RS 4n
Executable file directory name, up to a maximum of \fBMAXPATHLEN\fR characters
.RE

.sp
.ne 2
.na
\fB\fB%f\fR\fR
.ad
.sp .6
.RS 4n
Executable file name, up to a maximum of \fBMAXCOMLEN\fR characters
.RE

.sp
.ne 2
.na
\fB\fB%g\fR\fR
.ad
.sp .6
.RS 4n
Effective group-\fBID\fR
.RE

.sp
.ne 2
.na
\fB\fB%m\fR\fR
.ad
.sp .6
.RS 4n
Machine name (\fBuname\fR \fB-m\fR)
.RE

.sp
.ne 2
.na
\fB\fB%n\fR\fR
.ad
.sp .6
.RS 4n
System node name (\fBuname\fR \fB-n\fR)
.RE

.sp
.ne 2
.na
\fB\fB%p\fR\fR
.ad
.sp .6
.RS 4n
Process-\fBID\fR
.RE

.sp
.ne 2
.na
\fB\fB%t\fR\fR
.ad
.sp .6
.RS 4n
Decimal value of \fBtime\fR(2)
.RE

.sp
.ne 2
.na
\fB\fB%u\fR\fR
.ad
.sp .6
.RS 4n
Effective user-\fBID\fR
.RE

.sp
.ne 2
.na
\fB\fB%z\fR\fR
.ad
.sp .6
.RS 4n
Name of the zone in which process executed (\fBzonename\fR)
.RE

.sp
.ne 2
.na
.B %Z
.ad
.sp .6
.RS 4n
The path to the root of the zone in which process executed
.RE

.sp
.ne 2
.na
\fB\fB%%\fR\fR
.ad
.sp .6
.RS 4n
Literal \fB%\fR
.RE

.sp
.LP
For example, the core file name pattern \fB/var/cores/core.%f.%p\fR would
result, for command \fBfoo\fR with process-\fBID\fR \fB1234\fR, in the core
file name \fB/var/cores/core.foo.1234\fR.
.sp
.LP
A core file content description is specified using a series of tokens to
identify parts of a process's binary image:
.sp
.ne 2
.na
\fB\fBanon\fR\fR
.ad
.sp .6
.RS 4n
Anonymous private mappings, including thread stacks that are not main thread
stacks
.RE

.sp
.ne 2
.na
\fB\fBctf\fR\fR
.ad
.sp .6
.RS 4n
CTF type information sections for loaded object files
.RE

.sp
.ne 2
.na
\fB\fBdata\fR\fR
.ad
.sp .6
.RS 4n
Writable private file mappings
.RE

.sp
.ne 2
.na
\fB\fBdebug\fR\fR
.ad
.sp .6
.RS 4n
Debug sections, commonly DWARF. All sections that begin with '.debug_'.
Note, this does capture non-DWARF related sections that begin with the
string pattern; however, at this time other debug formats such as STABS
are not included. Other debug formats would be included here in the
future.
.RE

.sp
.ne 2
.na
\fB\fBdism\fR\fR
.ad
.sp .6
.RS 4n
DISM mappings
.RE

.sp
.ne 2
.na
\fB\fBheap\fR\fR
.ad
.sp .6
.RS 4n
Process heap
.RE

.sp
.ne 2
.na
\fB\fBism\fR\fR
.ad
.sp .6
.RS 4n
ISM mappings
.RE

.sp
.ne 2
.na
\fB\fBrodata\fR\fR
.ad
.sp .6
.RS 4n
Read-only private file mappings
.RE

.sp
.ne 2
.na
\fB\fBshanon\fR\fR
.ad
.sp .6
.RS 4n
Anonymous shared mappings
.RE

.sp
.ne 2
.na
\fB\fBshfile\fR\fR
.ad
.sp .6
.RS 4n
Shared mappings that are backed by files
.RE

.sp
.ne 2
.na
\fB\fBshm\fR\fR
.ad
.sp .6
.RS 4n
System V shared memory
.RE

.sp
.ne 2
.na
\fB\fBstack\fR\fR
.ad
.sp .6
.RS 4n
Process stack
.RE

.sp
.ne 2
.na
\fB\fBsymtab\fR\fR
.ad
.sp .6
.RS 4n
Symbol table sections for loaded object files
.RE

.sp
.ne 2
.na
\fB\fBtext\fR\fR
.ad
.sp .6
.RS 4n
Readable and executable private file mappings
.RE

.sp
.LP
In addition, you can use the token \fBall\fR to indicate that core files should
include all of these parts of the process's binary image. You can use the token
\fBnone\fR to indicate that no mappings are to be included. The \fBdefault\fR
token indicates inclusion of the system default content
(\fBstack+heap+shm+ism+dism+text+data+rodata+anon+shanon+ctf+symtab\fR). The
\fB/proc\fR file system data structures are always present in core files
regardless of the mapping content.
.sp
.LP
You can use \fB+\fR and \fB-\fR to concatenate tokens. For example, the core
file content \fBdefault-ism\fR would produce a core file with the default set
of mappings without any intimate shared memory mappings.
.sp
.LP
The \fBcoreadm\fR command with no arguments reports the current system
configuration, for example:
.sp
.in +2
.nf
$ coreadm
    global core file pattern: /var/cores/core.%f.%p
    global core file content: all
      init core file pattern: core
      init core file content: default
           global core dumps: enabled
      per-process core dumps: enabled
     global setid core dumps: enabled
per-process setid core dumps: disabled
    global core dump logging: disabled
.fi
.in -2
.sp

.sp
.LP
The \fBcoreadm\fR command with only a list of process-\fBID\fRs reports each
process's per-process core file name pattern, for example:
.sp
.in +2
.nf
$ coreadm 278 5678
  278:   core.%f.%p default
  5678:  /home/george/cores/%f.%p.%t all-ism
.fi
.in -2
.sp

.sp
.LP
Only the owner of a process or a user with the \fBproc_owner\fR privilege can
interrogate a process in this manner.
.sp
.LP
When a process is dumping core, up to three core files can be produced: one in
the per-process location, one in the system-wide global location, and, if the
process was running in a local (non-global) zone, one in the global location
for the zone in which that process was running. Each core file is generated
according to the effective options for the corresponding location.
.sp
.LP
When generated, a global core file is created in mode \fB600\fR and owned by
the superuser. Nonprivileged users cannot examine such files.
.sp
.LP
Ordinary per-process core files are created in mode \fB600\fR under the
credentials of the process. The owner of the process can examine such files.
.sp
.LP
A process that is or ever has been \fBsetuid\fR or \fBsetgid\fR since its last
\fBexec\fR(2) presents security issues that relate to dumping core. Similarly,
a process that initially had superuser privileges and lost those privileges
through \fBsetuid\fR(2) also presents security issues that are related to
dumping core. A process of either type can contain sensitive information in its
address space to which the current nonprivileged owner of the process should
not have access. If \fBsetid\fR core files are enabled, they are created mode
\fB600\fR and owned by the superuser.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-d\fR \fIoption\fR...\fR
.ad
.sp .6
.RS 4n
Disable the specified core file option. See the \fB-e\fR \fIoption\fR for
descriptions of possible options.
.sp
Multiple \fB-e\fR and \fB-d\fR options can be specified on the command line.
Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
use this option.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIoption\fR...\fR
.ad
.sp .6
.RS 4n
Enable the specified core file option. Specify \fIoption\fR as one of the
following:
.sp
.ne 2
.na
\fBglobal\fR
.ad
.sp .6
.RS 4n
Allow core dumps that use global core pattern.
.RE

.sp
.ne 2
.na
\fBglobal-setid\fR
.ad
.sp .6
.RS 4n
Allow set-id core dumps that use global core pattern.
.RE

.sp
.ne 2
.na
\fBlog\fR
.ad
.sp .6
.RS 4n
Generate a \fBsyslog\fR(3C) message when generation of a global core file is
attempted.
.RE

.sp
.ne 2
.na
\fBprocess\fR
.ad
.sp .6
.RS 4n
Allow core dumps that use per-process core pattern.
.RE

.sp
.ne 2
.na
\fBproc-setid\fR
.ad
.sp .6
.RS 4n
Allow set-id core dumps that use per-process core pattern.
.sp
Multiple \fB-e\fR and \fB-d\fR options can be specified on the command line.
Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
use this option.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-g\fR \fIpattern\fR\fR
.ad
.sp .6
.RS 4n
Set the global core file name pattern to \fIpattern\fR. The pattern must start
with a \fB/\fR and can contain any of the special \fB%\fR variables that are
described in the \fBDESCRIPTION\fR.
.sp
Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
use this option.
.RE

.sp
.ne 2
.na
\fB\fB-G\fR \fIcontent\fR\fR
.ad
.sp .6
.RS 4n
Set the global core file content to content. You must specify content by using
the tokens that are described in the \fBDESCRIPTION\fR.
.sp
Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
use this option.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIpattern\fR\fR
.ad
.sp .6
.RS 4n
Set the default per-process core file name to \fIpattern\fR. This changes the
per-process pattern for any process whose per-process pattern is still set to
the default. Processes that have had their per-process pattern set or are
descended from a process that had its per-process pattern set (using the
\fB-p\fR option) are unaffected. This default persists across reboot.
.sp
Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
use this option.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR \fIcontent\fR\fR
.ad
.sp .6
.RS 4n
Set the default per-process core file content to \fIcontent\fR. This changes
the per-process content for any process whose per-process content is still set
to the default. Processes that have had their per-process content set or are
descended from a process that had its per-process content set (using the
\fB-P\fR option) are unaffected. This default persists across reboot.
.sp
Only users and roles belonging to the "Maintenance and Repair" RBAC profile can
use this option.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpattern\fR\fR
.ad
.sp .6
.RS 4n
Set the per-process core file name pattern to \fIpattern\fR for each of the
specified process-\fBID\fRs. The pattern can contain any of the special \fB%\fR
variables described in the \fBDESCRIPTION\fR and need not begin with \fB/\fR.
If the pattern does not begin with \fB/\fR, it is evaluated relative to the
directory that is current when the process generates a core file.
.sp
A nonprivileged user can apply the \fB-p\fR option only to processes that are
owned by that user. A user with the \fBproc_owner\fR privilege can apply the
option to any process. The per-process core file name pattern is inherited by
future child processes of the affected processes. See \fBfork\fR(2).
.sp
If no process-\fBID\fRs are specified, the \fB-p\fR option sets the per-process
core file name pattern to \fIpattern\fR on the parent process (usually the
shell that ran \fBcoreadm\fR).
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIcontent\fR\fR
.ad
.sp .6
.RS 4n
Set the per-process core file content to \fIcontent\fR for each of the
specified process-IDs. The content must be specified by using the tokens that
are described in the \fBDESCRIPTION\fR.
.sp
A nonprivileged user can apply the \fB-p\fR option only to processes that are
owned by that user. A user with the \fBproc_owner\fR privilege can apply the
option to any process. The per-process core file name pattern is inherited by
future child processes of the affected processes. See \fBfork\fR(2).
.sp
If no process-\fBID\fRs are specified, the \fB-P\fR option sets the per-process
file content to \fIcontent\fR on the parent process (usually the shell that ran
\fBcoreadm\fR).
.RE

.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fB\fIpid\fR\fR
.ad
.sp .6
.RS 4n
process-\fBID\fR
.RE

.SH EXAMPLES
\fBExample 1 \fRSetting the Core File Name Pattern
.sp
.LP
When executed from a user's \fB$HOME/.profile\fR or \fB$HOME/.login\fR, the
following command sets the core file name pattern for all processes that are
run during the login session:

.sp
.in +2
.nf
example$  coreadm -p core.%f.%p
.fi
.in -2
.sp

.sp
.LP
Note that since the process-\fBID\fR is omitted, the per-process core file name
pattern will be set in the shell that is currently running and is inherited by
all child processes.

.LP
\fBExample 2 \fRDumping a User's Files Into a Subdirectory
.sp
.LP
The following command dumps all of a user's core dumps into the \fBcorefiles\fR
subdirectory of the home directory, discriminated by the system node name. This
command is useful for users who use many different machines but have a shared
home directory.

.sp
.in +2
.nf
example$  coreadm -p $HOME/corefiles/%n.%f.%p 1234
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCulling the Global Core File Repository
.sp
.LP
The following commands set up the system to produce core files in the global
repository only if the executables were run from \fB/usr/bin\fR or
\fB/usr/sbin\fR.

.sp
.in +2
.nf
example# mkdir -p /var/cores/usr/bin
example# mkdir -p /var/cores/usr/sbin
example# coreadm -G all -g /var/cores/%d/%f.%p.%n
.fi
.in -2
.sp

.SH FILES
.ne 2
.na
\fB\fB/var/cores\fR\fR
.ad
.sp .6
.RS 4n
Directory provided for global core file storage.
.RE

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB0\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.na
\fB1\fR
.ad
.sp .6
.RS 4n
A fatal error occurred while either obtaining or modifying the system core file
configuration.
.RE

.sp
.ne 2
.na
\fB2\fR
.ad
.sp .6
.RS 4n
Invalid command-line options were specified.
.RE

.SH SEE ALSO
.BR gcore (1),
.BR pfexec (1),
.BR svcs (1),
.BR exec (2),
.BR fork (2),
.BR setuid (2),
.BR time (2),
.BR syslog (3C),
.BR core (5),
.BR prof_attr (5),
.BR user_attr (5),
.BR attributes (7),
.BR smf (7),
.BR init (8),
.BR svcadm (8)
.SH NOTES
In a local (non-global) zone, the global settings apply to processes running in
that zone. In addition, the global zone's apply to processes run in any zone.
.sp
.LP
The term \fBglobal settings\fR refers to settings which are applied to the
system or zone as a whole, and does not necessarily imply that the settings are
to take effect in the global zone.
.sp
.LP
The \fBcoreadm\fR service is managed by the service management facility,
\fBsmf\fR(7), under the service identifier:
.sp
.in +2
.nf
svc:/system/coreadm:default
.fi
.in -2
.sp

.sp
.LP
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using \fBsvcadm\fR(8). The service's
status can be queried using the \fBsvcs\fR(1) command.
.sp
.LP
The \fB-g\fR, \fB-G\fR, \fB-i\fR, \fB-I\fR, \fB-e\fR, and \fB-d\fR options can
be also used by a user, role, or profile that has been granted both the
\fBsolaris.smf.manage.coreadm\fR and \fBsolaris.smf.value.coreadm\fR
authorizations.