path: root/usr/src/man/man1/ppriv.1

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" 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 PPRIV 1 "Feb 24, 2008"
.SH NAME
ppriv \- inspect or modify process privilege sets and attributes
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/ppriv\fR \fB-e\fR [\fB-D\fR | \fB-N\fR] [\fB-M\fR] [\fB-s\fR \fIspec\fR] \fIcommand\fR [\fIarg\fR]...
.fi

.LP
.nf
\fB/usr/bin/ppriv\fR [\fB-v\fR] [\fB-S\fR] [\fB-D\fR | \fB-N\fR] [\fB-s\fR \fIspec\fR]
     [\fIpid\fR | \fIcore\fR]...
.fi

.LP
.nf
\fB/usr/bin/ppriv\fR \fB-l\fR [\fB-v\fR] [\fIprivilege-specification\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The first invocation of the \fBppriv\fR command runs the \fIcommand\fR
specified with the privilege sets and flags modified according to the arguments
on the command line.
.sp
.LP
The second invocation examines or changes the privilege state of running
process and core files.
.sp
.LP
The third invocation lists the privileges defined and information about
specified privileges or privileges set specifications.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 11n
Turns on privilege debugging for the processes or command supplied.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 11n
Interprets the remainder of the arguments as a command line and runs the
command line with specified privilege attributes and sets.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 11n
Lists all currently defined privileges on stdout.
.RE

.sp
.ne 2
.na
\fB\fB-M\fR\fR
.ad
.RS 11n
When a system is configured with Trusted Extensions, this option turns on the
\fBNET_MAC_AWARE\fR and \fBNET_MAC_AWARE_INHERIT\fR process attributes.
.sp
A process with these attributes and the \fBnet_mac_aware\fR privilege can
communicate with lower-level remote peers.
.RE

.sp
.ne 2
.na
\fB\fB-N\fR\fR
.ad
.RS 11n
Turns off privilege debugging for the processes or command supplied.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIspec\fR\fR
.ad
.RS 11n
Modifies a process's privilege sets according to \fIspec\fR, a specification
with the format \fB[AEILP][+-=]\fR\fIprivsetspec\fR, containing no spaces,
where:
.sp
.ne 2
.na
\fB\fBAEILP\fR\fR
.ad
.RS 15n
Indicates one or more letters indicating which privilege sets to change. These
are case insensitive, for example, either \fBa\fR or \fBA\fR indicates all
privilege sets.
.RE

.sp
.ne 2
.na
\fB\fB+-=\fR\fR
.ad
.RS 15n
Indicates a modifier to respectively add (\fB+\fR), remove (\fB-\fR), or assign
(\fB=\fR) the listed privileges to the specified set(s) in \fIprivsetspec\fR.
.RE

.sp
.ne 2
.na
\fB\fIprivsetspec\fR\fR
.ad
.RS 15n
Indicates a comma-separated privilege set specification
(\fBpriv1\fR,\fBpriv2\fR, and so on), as described in
\fBpriv_str_to_set\fR(3C).
.RE

Modifying the same set with multiple \fB-s\fR options is possible as long as
there is either precisely one assignment to an individual set or any number of
additions and removals. That is, assignment and addition or removal for one set
are mutually exclusive.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.RS 11n
Short. Reports the shortest possible output strings for sets. The default is
portable output. See \fBpriv_str_to_set\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 11n
Verbose. Reports privilege sets using privilege names.
.RE

.SH USAGE
.sp
.LP
The \fBppriv\fR utility examines processes and core files and prints or changes
their privilege sets.
.sp
.LP
\fBppriv\fR can run commands with privilege debugging on or off or with fewer
privileges than the invoking process.
.sp
.LP
When executing a sub process, the only sets that can be modified are \fBL\fR
and \fBI\fR. Privileges can only be removed from \fBL\fR and \fBI\fR as
\fBppriv\fR starts with \fBP=E=I\fR.
.sp
.LP
\fBppriv\fR can also be used to remove privileges from processes or to convey
privileges to other processes. In order to control a process, the effective set
of the \fBppriv\fR utility must be a super set of the controlled process's
\fBE\fR, \fBI\fR, and \fBP\fR. The utility's limit set must be a super set of
the target's limit set. If the target's process uids do not match, the
\fB{PRIV_PROC_OWNER}\fR privilege must be asserted in the utility's effective
set. If the controlled processes have any uid with the value \fB0\fR, more
restrictions might exist. See \fBprivileges\fR(5).
.SH EXAMPLES
.LP
\fBExample 1 \fRObtaining the Process Privileges of the Current Shell
.sp
.LP
The following example obtains the process privileges of the current shell:

.sp
.in +2
.nf
example$ \fBppriv $$\fR
387:   -sh
flags = <none>
         E: basic
         I: basic
         P: basic
         L: all
.fi
.in -2
.sp

.LP
\fBExample 2 \fRRemoving a Privilege From Your Shell's Inheritable and
Effective Set
.sp
.LP
The following example removes a privilege from your shell's inheritable and
effective set.

.sp
.in +2
.nf
example$ \fBppriv -s EI-proc_session $$\fR
.fi
.in -2
.sp

.sp
.LP
The subprocess can still inspect the parent shell but it can no longer
influence the parent because the parent has more privileges in its Permitted
set than the \fBppriv\fR child process:

.sp
.in +2
.nf
example$ \fBtruss -p $$\fR
truss: permission denied: 387

example$ \fBppriv $$\fR
387:   -sh
flags = <none>
         E: basic,!proc_session
         I: basic,!proc_session
         P: basic
         L: all
.fi
.in -2
.sp

.LP
\fBExample 3 \fRRunning a Process with Privilege Debugging
.sp
.LP
The following example runs a process with privilege debugging:

.sp
.in +2
.nf
example$ \fBppriv -e -D cat /etc/shadow\fR
cat[418]: missing privilege "file_dac_read" (euid = 21782),
                    needed at ufs_access+0x3c
cat: cannot open /etc/shadow
.fi
.in -2
.sp

.sp
.LP
The privilege debugging error messages are sent to the controlling terminal of
the current process. The \fBneeded at\fR address specification is an artifact
of the kernel implementation and it can be changed at any time after a software
update.

.sp
.LP
The system call number can be mapped to a system call using
\fB/etc/name_to_sysnum\fR.

.LP
\fBExample 4 \fRListing the Privileges Available in the Current Zone
.sp
.LP
The following example lists the privileges available in the current zone (see
\fBzones\fR(5)). When run in the global zone, all defined privileges are
listed.

.sp
.in +2
.nf
example$ \fBppriv -l zone\fR
 ... listing of all privileges elided ...
.fi
.in -2
.sp

.LP
\fBExample 5 \fRExamining a Privilege Aware Process
.sp
.LP
The following example examines a privilege aware process:

.sp
.in +2
.nf
example$ \fBppriv -S `pgrep rpcbind`\fR


928:    /usr/sbin/rpcbind
flags = PRIV_AWARE
        E: net_privaddr,proc_fork,sys_nfs
        I: none
        P: net_privaddr,proc_fork,sys_nfs
        L: none
.fi
.in -2
.sp

.sp
.LP
See \fBsetpflags\fR(2) for explanations of the flags.

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful operation.
.RE

.sp
.ne 2
.na
\fBnon-zero\fR
.ad
.RS 12n
An error has occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/proc/*\fR\fR
.ad
.RS 23n
Process files
.RE

.sp
.ne 2
.na
\fB\fB/etc/name_to_sysnum\fR\fR
.ad
.RS 23n
system call name to number mapping
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The invocation is Committed. The output is Uncommitted.
.SH SEE ALSO
.sp
.LP
\fBgcore\fR(1), \fBtruss\fR(1), \fBsetpflags\fR(2), \fBpriv_str_to_set\fR(3C),
\fBproc\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5), \fBzones\fR(5)