1CAPSH(1)                         User Commands                        CAPSH(1)
2
3
4

NAME

6       capsh - capability shell wrapper
7

SYNOPSIS

9       capsh [OPTION]...
10

DESCRIPTION

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

OPTIONS

18       capsh takes a number of optional arguments, acting on them in the order
19       they are provided. They are as follows:
20
21       --help Display the list of commands supported by capsh.
22
23       --print
24              Display prevailing capability and related state.
25
26       -- [args]
27              Execute  /bin/bash with trailing arguments. Note, you can use -c
28              'command to execute' for specific commands.
29
30       ==     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
38       --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
43       --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
50       --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
58       --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
66       --modes
67              Lists all of the libcap modes supported by --mode.
68
69       --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
74       --inmode=<mode>
75              Confirm that the prevailing mode is that specified in <mode>, or
76              exit with a status 1.
77
78       --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
83       --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
89       --is-uid=<id>
90              Exit with status 1 unless the current UID equals <id>.
91
92       --gid=<id>
93              Force all GID values to equal  id  using  the  setgid(2)  system
94              call.
95
96       --is-gid=<id>
97              Exit with status 1 unless the current GIQ equals <id>.
98
99       --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
104       --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
117       --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
125       --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
130       --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
138       --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
144       --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
148              CapInh:   0000000000000000
149              CapPrm:   0000003fffffffff
150              CapEff:   0000003fffffffff
151              CapBnd:   0000003fffffffff
152              CapAmb:   0000000000000000
153
154              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
158              $ capsh --decode=3
159              0x0000000000000003=cap_chown,cap_dac_override
160
161       --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
168       --has-p=xxx
169              Exit  with  status  1 unless the permitted vector has capability
170              xxx raised.
171
172       --has-ambient
173              Performs a check to see if the running kernel  supports  ambient
174              capabilities. If not, capsh exits with status 1.
175
176       --has-a=xxx
177              Exit  with status 1 unless the ambient vector has capability xxx
178              raised.
179
180       --addamb=xxx
181              Adds the specified ambient capability to the running process.
182
183       --delamb=xxx
184              Removes  the  specified  ambient  capability  from  the  running
185              process.
186
187       --noamb
188              Drops all ambient capabilities from the running process.
189

EXIT STATUS

191       Following successful execution, capsh exits with status 0. Following an
192       error, capsh immediately exits with status 1.
193

AUTHOR

195       Written by Andrew G. Morgan <morgan@kernel.org>.
196

REPORTING BUGS

198       Please report bugs via:
199
200       https://bugzilla.kernel.org/buglist.cgi?component=lib
201       cap&list_id=1047723&product=Tools&resolution=---
202

SEE ALSO

204       libcap(3), getcap(8), setcap(8) and capabilities(7).
205
206
207
208libcap 2                          2020-10-27                          CAPSH(1)
Impressum