1 files changed, 101 insertions, 15 deletions
diff --git a/doc/capsh.1 b/doc/capsh.1
index 20973b5..4f9273d 100644
--- a/doc/capsh.1
+++ b/doc/capsh.1
@@ -1,7 +1,7 @@
 .\"
-.\" capsh.1 Man page added 2009-11-22 Andrew G. Morgan <morgan@kernel.org>
+.\" capsh.1 Man page added 2009-12-23 Andrew G. Morgan <morgan@kernel.org>
 .\"
-.TH CAPSH 1 "2009-11-22" "libcap 2" "User Commands"
+.TH CAPSH 1 "2009-12-24" "libcap 2" "User Commands"
 .SH NAME
 capsh \- capability shell wrapper
 .SH SYNOPSIS
@@ -24,7 +24,7 @@ Execute
 .B /bin/bash
 with trailing arguments. Note, you can use
 .B -c 'command to execute'
-for commands.
+for specific commands.
 .TP
 .B ==
 Execute
@@ -41,29 +41,115 @@ Where
 is a text-representation of capability state as per
 .BR cap_from_text (3).
 .TP
-.BI --drop= <cap-list>
+.BI --drop= cap-list
+Remove the listed capabilities from the prevailing bounding set. The
+capabilites are a comma separated list of capabilities as recognized
+by the
+.BR cap_from_name (3)
+function. Use of this feature requires that the capsh program is
+operating with
+.B CAP_SETPCAP
+in its effective set.
 .TP
-.BI --inh= <cap-list>
+.BI --inh= cap-list
+Set the inheritable set of capabilities for the current process to
+equal those provided in the comma separated list. For this action to
+succeed, the prevailing process should already have each of these
+capabilities in the union of the current inheritable and permitted
+capability sets, or the capsh program is operating with
+.B CAP_SETPCAP
+in its effective set.
 .TP
-.BI --keep= <0|1>
+.BI --user= username
+Assume the identity of the named user. That is, look up the user's
+.IR uid " and " gid
+with
+.BR getpwuid (3)
+and their group memberships with
+.BR getgrouplist (3)
+and set them all.
 .TP
-.BI --chroot= <path>
+.BI --uid= id
+Force all
+.B uid
+values to equal
+.I id
+using the
+.BR setuid (2)
+system call.
 .TP
-.BI --secbits= <N>
+.BI --gid= <id>
+Force all
+.B gid
+values to equal
+.I id
+using the
+.BR setgid (2)
+system call.
 .TP
-.BI --forkfor= <sec>
+.BI --groups= <id-list>
+Set the supplementary groups to the numerical list provided. The
+groups are set with the
+.BR setgroups (2)
+system call.
 .TP
-.BI --killit= <sig>
+.BI --keep= <0|1>
+In a non-pure capability mode, the kernel provides liberal privilege
+to the super-user. However, it is normally the case that when the
+super-user changes
+.I uid
+to some lesser user, then capabilities are dropped. For these
+situations, the kernel can permit the process to retain its
+capabilities after a
+.BR setuid (2)
+system call. This feature is known as
+.I keep-caps
+support. The way to activate it using this script is with this
+argument. Setting the value to 1 will cause
+.I keep-caps
+to be active. Setting it to 0 will cause keep-caps to deactivate for
+the current process. In all cases,
+.I keep-caps
+is deactivated when an
+.BR exec ()
+is performed. See
+.B --secbits
+for ways to disable this feature.
 .TP
-.BI --uid= <id>
+.BI --secbits= N
+XXX - need to document this feature.
 .TP
-.BI --gid= <id>
+.BI --chroot= path
+Execute the
+.BR chroot (2)
+system call with the new root-directory (/) equal to
+.IR path .
+This operation requires
+.B CAP_SYS_CHROOT
+to be in effect.
 .TP
-.BI --groups= <gid-list>
+.BI --forkfor= sec
 .TP
-.BI --user= <username>
+.BI --killit= sig
 .TP
-.BI --decode= <N>
+.BI --decode= N
+This is a convenience feature. If you look at
+.B /proc/1/status
+there are some capability related fields of the following form:
+
+ CapInh:	0000000000000000
+ CapPrm:	ffffffffffffffff
+ CapEff:	fffffffffffffeff
+ CapBnd:	ffffffffffffffff
+
+This option provides a quick way to decode a capability vector
+represented in this form. For example, the missing capability from
+this effective set is 0x0100. By running:
+
+ capsh --decode=0x0100
+
+we observe that the missing capability is:
+.BR cap_setpcap .
 .SH "EXIT STATUS"
 Following successful execution the tool exits with status 0. Following
 an error, the tool immediately exits with status 1.