coreadm(1M)						  System Administration Commands					       coreadm(1M)

NAME

       coreadm - core file administration

SYNOPSIS

       coreadm [-g pattern] [-G content] [-i pattern] [-I content]
	    [-d option]... [-e option]...

       coreadm [-p pattern] [-P content] [pid]...

DESCRIPTION

       coreadm specifies the name and location of core files produced by abnormally-terminating processes. See core(4).

       Only users and roles that belong to the "Maintenance and Repair" RBAC profile can execute the first form of the SYNOPSIS. This form config-
       ures system-wide core file options, including a global core file name pattern and a core file name pattern for the  init(1M)  process.  All
       settings are saved persistently and will be applied at boot.

       Non-privileged  users can execute the second form of the SYNOPSIS. This form specifies the file name pattern and core file content that the
       operating system uses to generate a per-process core file.

       A core file name pattern is a normal file system path name with embedded variables, specified with a leading % 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 fol-
       lows:

       %d

	   Executable file directory name, up to a maximum of MAXPATHLEN characters

       %f

	   Executable file name, up to a maximum of MAXCOMLEN characters

       %g

	   Effective group-ID

       %m

	   Machine name (uname -m)

       %n

	   System node name (uname -n)

       %p

	   Process-ID

       %t

	   Decimal value of time(2)

       %u

	   Effective user-ID

       %z

	   Name of the zone in which process executed (zonename)

       %%

	   Literal %

       For example, the core file name pattern /var/cores/core.%f.%p would result, for command foo with process-ID 1234, in  the  core	file  name
       /var/cores/core.foo.1234.

       A core file content description is specified using a series of tokens to identify parts of a process's binary image:

       anon

	   Anonymous private mappings, including thread stacks that are not main thread stacks

       ctf

	   CTF type information sections for loaded object files

       data

	   Writable private file mappings

       dism

	   DISM mappings

       heap

	   Process heap

       ism

	   ISM mappings

       rodata

	   Read-only private file mappings

       shanon

	   Anonymous shared mappings

       shfile

	   Shared mappings that are backed by files

       shm

	   System V shared memory

       stack

	   Process stack

       symtab

	   Symbol table sections for loaded object files

       text

	   Readable and executable private file mappings

       In addition, you can use the token all to indicate that core files should include all of these parts of the process's binary image. You can
       use the token none to indicate that no mappings are to be included. The default token indicates inclusion of  the  system  default  content
       (stack+heap+shm+ism+dism+text+data+rodata+anon+shanon+ctf+symtab).  The	/proc file system data structures are always present in core files
       regardless of the mapping content.

       You can use + and - to concatenate tokens. For example, the core file content default-ism would produce a core file with the default set of
       mappings without any intimate shared memory mappings.

       The coreadm command with no arguments reports the current system configuration, for example:

	 $ 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

       The coreadm command with only a list of process-IDs reports each process's per-process core file name pattern, for example:

	 $ coreadm 278 5678
	   278:   core.%f.%p default
	   5678:  /home/george/cores/%f.%p.%t all-ism

       Only the owner of a process or a user with the proc_owner privilege can interrogate a process in this manner.

       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.

       When generated, a global core file is created in mode 600 and owned by the superuser. Nonprivileged users cannot examine such files.

       Ordinary  per-process  core  files  are created in mode 600 under the credentials of the process. The owner of the process can examine such
       files.

       A process that is or ever has been setuid or setgid since its last exec(2) presents security issues that relate to dumping core. Similarly,
       a  process  that  initially  had  superuser  privileges	and lost those privileges through setuid(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 setid core files are enabled, they are created mode 600 and owned by the superuser.

OPTIONS

       The following options are supported:

       -d option...

	   Disable the specified core file option. See the -e option for descriptions of possible options.

	   Multiple  -e  and  -d options can be specified on the command line. Only users and roles belonging to the "Maintenance and Repair" RBAC
	   profile can use this option.

       -e option...

	   Enable the specified core file option. Specify option as one of the following:

	   global

	       Allow core dumps that use global core pattern.

	   global-setid

	       Allow set-id core dumps that use global core pattern.

	   log

	       Generate a syslog(3C) message when generation of a global core file is attempted.

	   process

	       Allow core dumps that use per-process core pattern.

	   proc-setid

	       Allow set-id core dumps that use per-process core pattern.

	       Multiple -e and -d options can be specified on the command line. Only users and roles belonging to  the	"Maintenance  and  Repair"
	       RBAC profile can use this option.

       -g pattern

	   Set	the  global core file name pattern to pattern. The pattern must start with a / and can contain any of the special % variables that
	   are described in the DESCRIPTION.

	   Only users and roles belonging to the "Maintenance and Repair" RBAC profile can use this option.

       -G content

	   Set the global core file content to content. You must specify content by using the tokens that are described in the DESCRIPTION.

	   Only users and roles belonging to the "Maintenance and Repair" RBAC profile can use this option.

       -i pattern

	   Set the default per-process core file name to pattern. 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 -p option) are unaffected. This default persists across reboot.

	   Only users and roles belonging to the "Maintenance and Repair" RBAC profile can use this option.

       -I content

	   Set the default per-process core file content to content. This changes the per-process content for any process whose  per-process  con-
	   tent  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 -P option) are unaffected. This default persists across reboot.

	   Only users and roles belonging to the "Maintenance and Repair" RBAC profile can use this option.

       -p pattern

	   Set the per-process core file name pattern to pattern for each of the specified process-IDs. The pattern can contain any of the special
	   %  variables  described in the DESCRIPTION and need not begin with /. If the pattern does not begin with /, it is evaluated relative to
	   the directory that is current when the process generates a core file.

	   A nonprivileged user can apply the -p option only to processes that are owned by that user. A user with the	proc_owner  privilege  can
	   apply  the  option  to  any process. The per-process core file name pattern is inherited by future child processes of the affected pro-
	   cesses. See fork(2).

	   If no process-IDs are specified, the -p option sets the per-process core file name pattern to pattern on the  parent  process  (usually
	   the shell that ran coreadm).

       -P content

	   Set	the  per-process  core	file  content to content for each of the specified process-IDs. The content must be specified by using the
	   tokens that are described in the DESCRIPTION.

	   A nonprivileged user can apply the -p option only to processes that are owned by that user. A user with the	proc_owner  privilege  can
	   apply  the  option  to  any process. The per-process core file name pattern is inherited by future child processes of the affected pro-
	   cesses. See fork(2).

	   If no process-IDs are specified, the -P option sets the per-process file content to content on the parent process  (usually	the  shell
	   that ran coreadm).

OPERANDS

       The following operands are supported:

       pid

	   process-ID

EXAMPLES

       Example 1 Setting the Core File Name Pattern

       When  executed  from  a user's $HOME/.profile or $HOME/.login, the following command sets the core file name pattern for all processes that
       are run during the login session:

	 example$  coreadm -p core.%f.%p

       Note that since the process-ID 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.

       Example 2 Dumping a User's Files Into a Subdirectory

       The  following  command dumps all of a user's core dumps into the corefiles 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.

	 example$  coreadm -p $HOME/corefiles/%n.%f.%p 1234

       Example 3 Culling the Global Core File Repository

       The following commands set up the system to produce core files in the global repository only if the executables were run from  /usr/bin	or
       /usr/sbin.

	 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

FILES

       /var/cores

	   Directory provided for global core file storage.

EXIT STATUS

       The following exit values are returned:

       0

	   Successful completion.

       1

	   A fatal error occurred while either obtaining or modifying the system core file configuration.

       2

	   Invalid command-line options were specified.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       gcore(1),  pfexec(1), svcs(1), init(1M), svcadm(1M), exec(2), fork(2), setuid(2), time(2), syslog(3C), core(4), prof_attr(4), user_attr(4),
       attributes(5), smf(5)

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  pro-
       cesses run in any zone.

       The  term  global  settings  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.

       The coreadm service is managed by the service management facility, smf(5), under the service identifier:

	 svc:/system/coreadm:default

       Administrative actions on this service, such as enabling, disabling, or requesting restart, can be performed  using  svcadm(1M).  The  ser-
       vice's status can be queried using the svcs(1) command.

       The -g, -G, -i, -I, -e, and -d options can be also used by a user, role, or profile that has been granted both the solaris.smf.manage.core-
       adm and solaris.smf.value.coreadm authorizations.

SunOS 5.11							    30 Sep 2008 						       coreadm(1M)