1CAPSH(1) User Commands CAPSH(1)
2
6 capsh - capability shell wrapper
7
9 capsh [OPTION]...
10
12 Linux capability support and use can be explored and constrained with
13 this tool. This tool provides a handy wrapper for certain types of
14 capability testing and environment creation. It also provides some
15 debugging features useful for summarizing capability state.
16
18 capsh takes a number of optional arguments, acting on them in the order
19 they are provided. They are as follows:
20 --help Display the list of commands supported by capsh.
22 --print
24 Display prevailing capability and related state.
25 -- [args]
27 Execute /bin/bash with trailing arguments. Note, you can use -c
28 'command to execute' for specific commands.
29 == Execute capsh again with the remaining arguments. Useful for
31 testing exec() behavior. Note, PATH is searched when the running
32 capsh was found via the shell's PATH searching. If the exec
33 occurs after a --chroot=/some/path argument the PATH located
34 binary may not be resolve to the same binary as that running
35 initially. This behavior is an intented feature as it can com‐
36 plete the chroot transition.
37 --caps=cap-set
39 Set the prevailing process capabilities to those specified by
40 cap-set. Where cap-set is a text-representation of capability
41 state as per cap_from_text(3).
42 --drop=cap-list
44 Remove the listed capabilities from the prevailing bounding set.
45 The capabilities are a comma-separated list of capabilities as
46 recognized by the cap_from_name(3) function. Use of this feature
47 requires that capsh is operating with CAP_SETPCAP in its effec‐
48 tive set.
49 --inh=cap-list
51 Set the inheritable set of capabilities for the current process
52 to equal those provided in the comma separated list. For this
53 action to succeed, the prevailing process should already have
54 each of these capabilities in the union of the current inherita‐
55 ble and permitted capability sets, or capsh should be operating
56 with CAP_SETPCAP in its effective set.
57 --user=username
59 Assume the identity of the named user. That is, look up the
60 user's UID and GID with getpwuid(3) and their group memberships
61 with getgrouplist(3) and set them all using cap_setuid(3) and
62 cap_setgroups(3). Following this command, the effective capa‐
63 bilities will be cleared, but the permitted set will not be, so
64 the running program is still privileged.
65 --modes
67 Lists all of the libcap modes supported by --mode.
68 --mode=<mode>
70 Force the program into a cap_set_mode(3) security mode. This is
71 a set of securebits and prevailing capability arrangement recom‐
72 mended for its pre-determined security stance.
73 --inmode=<mode>
75 Confirm that the prevailing mode is that specified in <mode>, or
76 exit with a status 1.
77 --uid=id
79 Force all UID values to equal id using the setuid(2) system
80 call. This argument may require explicit preparation of the
81 effective set.
82 --cap-uid=<uid>
84 use the cap_setuid(3) function to set the UID of the current
85 process. This performs all preparations for setting the UID
86 without dropping capabilities in the process. Following this
87 command the prevailing effective capabilities will be lowered.
88 --is-uid=<id>
90 Exit with status 1 unless the current UID equals <id>.
91 --gid=<id>
93 Force all GID values to equal id using the setgid(2) system
94 call.
95 --is-gid=<id>
97 Exit with status 1 unless the current GIQ equals <id>.
98 --groups=<gid-list>
100 Set the supplementary groups to the numerical list provided. The
101 groups are set with the setgroups(2) system call. See --user for
102 a more convenient way of doing this.
103 --keep=<0|1>
105 In a non-pure capability mode, the kernel provides liberal priv‐
106 ilege to the super-user. However, it is normally the case that
107 when the super-user changes UID to some lesser user, then capa‐
108 bilities are dropped. For these situations, the kernel can per‐
109 mit the process to retain its capabilities after a setuid(2)
110 system call. This feature is known as keep-caps support. The way
111 to activate it using this program is with this argument. Setting
112 the value to 1 will cause keep-caps to be active. Setting it to
113 0 will cause keep-caps to deactivate for the current process. In
114 all cases, keep-caps is deactivated when an exec() is performed.
115 See --secbits for ways to disable this feature.
116 --secbits=N
118 Set the security-bits for the program. This is done using the
119 prctl(2) PR_SET_SECUREBITS operation. The list of supported
120 bits and their meaning can be found in the <sys/secbits.h>
121 header file. The program will list these bits via the --print
122 command. The argument is expressed as a numeric bitmask, in any
123 of the formats permitted by strtoul(3).
124 --chroot=/some/path
126 Execute the chroot(2) system call with the new root-directory
127 (/) equal to path. This operation requires CAP_SYS_CHROOT to be
128 in effect.
129 --forkfor=sec
131 This command causes the program to fork a child process for so
132 many seconds. The child will sleep that long and then exit with
133 status 0. The purpose of this command is to support exploring
134 the way processes are killable in the face of capability
135 changes. See the --killit command. Only one fork can be active
136 at a time.
137 --killit=sig
139 This commands causes a --forkfor child to be kill(2)d with the
140 specified signal. The command then waits for the child to exit.
141 If the exit status does not match the signal being used to kill
142 it, the capsh program exits with status 1.
143 --decode=N
145 This is a convenience feature. If you look at /proc/1/status
146 there are some capability related fields of the following form:
147 CapInh: 0000000000000000
149 CapPrm: 0000003fffffffff
150 CapEff: 0000003fffffffff
151 CapBnd: 0000003fffffffff
152 CapAmb: 0000000000000000
153 This option provides a quick way to decode a capability vector
155 represented in this hexadecimal form. Here's an example that
156 decodes the two lowest capability bits:
157 $ capsh --decode=3
159 0x0000000000000003=cap_chown,cap_dac_override
160 --supports=xxx
162 As the kernel evolves, more capabilities are added. This option
163 can be used to verify the existence of a capability on the sys‐
164 tem. For example, --supports=cap_syslog will cause capsh to
165 promptly exit with a status of 1 when run on kernel 2.6.27.
166 However, when run on kernel 2.6.38 it will silently succeed.
167 --has-p=xxx
169 Exit with status 1 unless the permitted vector has capability
170 xxx raised.
171 --has-ambient
173 Performs a check to see if the running kernel supports ambient
174 capabilities. If not, capsh exits with status 1.
175 --has-a=xxx
177 Exit with status 1 unless the ambient vector has capability xxx
178 raised.
179 --addamb=xxx
181 Adds the specified ambient capability to the running process.
182 --delamb=xxx
184 Removes the specified ambient capability from the running
185 process.
186 --noamb
188 Drops all ambient capabilities from the running process.
189
191 Following successful execution, capsh exits with status 0. Following an
192 error, capsh immediately exits with status 1.
193
195 Written by Andrew G. Morgan <morgan@kernel.org>.
196
198 Please report bugs via:
199 https://bugzilla.kernel.org/buglist.cgi?component=lib‐
201 cap&list_id=1047723&product=Tools&resolution=---
202
204 libcap(3), getcap(8), setcap(8) and capabilities(7).
205libcap 2 2020-10-27 CAPSH(1)