Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CAPSH(1)			 User Commands			      CAPSH(1)

       capsh - capability shell	wrapper

       capsh [OPTION]...

       Linux  capability  support and use can be explored and constrained with
       this tool. This tool provides a handy wrapper for certain types of  ca-
       pability	testing	and environment	creation. It also provides some	debug-
       ging features useful for	summarizing capability state.

       The tool	takes a	number of optional arguments, acting on	 them  in  the
       order they are provided.	They are as follows:

       --print		     Display prevailing	capability and related state.

       -- [args]	     Execute  /bin/bash	with trailing arguments. Note,
			     you can use -c 'command to	execute' for  specific

       ==		     Execute  capsh  again  with  remaining arguments.
			     Useful for	testing	exec() behavior.

       --caps=cap-set	     Set the prevailing	process	capabilities to	 those
			     specified	by  cap-set.  Where cap-set is a text-
			     representation  of	 capability   state   as   per

       --drop=cap-list	     Remove  the listed	capabilities from the prevail-
			     ing bounding set. The capabilities	 are  a	 comma
			     separated	list  of capabilities as recognized by
			     the cap_from_name(3) function. Use	of  this  fea-
			     ture requires that	the capsh program is operating
			     with CAP_SETPCAP in its effective set.

       --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  CAP_SETPCAP  in
			     its effective set.

       --user=username	     Assume  the  identity of the named	user. That is,
			     look up the user's	uid and	gid  with  getpwuid(3)
			     and  their	group memberships with getgrouplist(3)
			     and set them all.

       --uid=id		     Force all uid values to equal id  using  the  se-
			     tuid(2) system call.

       --gid=_id_	     Force  all	 gid values to equal id	using the set-
			     gid(2) system call.

       --groups=_id-list_    Set the supplementary  groups  to	the  numerical
			     list  provided.  The groups are set with the set-
			     groups(2) system call.

       --keep=_0|1_	     In	a non-pure capability mode,  the  kernel  pro-
			     vides  liberal  privilege to the super-user. How-
			     ever, it is normally the case that	when  the  su-
			     per-user  changes	uid  to	some lesser user, then
			     capabilities are dropped. For  these  situations,
			     the  kernel  can permit the process to retain its
			     capabilities after	a setuid(2) system call.  This
			     feature is	known as keep-caps support. The	way to
			     activate it using this script is with this	 argu-
			     ment. Setting the value to	1 will cause keep-caps
			     to	be active. Setting it to 0  will  cause	 keep-
			     caps  to  deactivate  for the current process. In
			     all  cases,  keep-caps  is	 deactivated  when  an
			     exec()  is	 performed.  See --secbits for ways to
			     disable this feature.

       --secbits=N	     XXX - need	to document this feature.

       --chroot=path	     Execute the chroot(2) system call	with  the  new
			     root-directory (/)	equal to path.	This operation
			     requires CAP_SYS_CHROOT to	be in effect.



       --decode=N	     This is a convenience feature.  If	 you  look  at
			     /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  ca-
			     pability vector represented in this form. For ex-
			     ample, the	missing	capability from	this effective
			     set is 0x0100. By running:

			      capsh --decode=0x0100

			     we	  observe  that	 the  missing  capability  is:

       --supports=xxx	     As	the  kernel  evolves,  more  capabilities  are
			     added.  This option can be	used to	verify the ex-
			     istence of	a capability on	the system. For	 exam-
			     ple,  --supports=cap_syslog  will	cause capsh to
			     promptly exit with	a status of 1 when run on ker-
			     nel  2.6.27.   However, when run on kernel	2.6.38
			     it	will silently succeed.

	      Following	successful execution the tool  exits  with  status  0.
	      Following	an error, the tool immediately exits with status 1.

       Written by Andrew G. Morgan <>.

       Please report bugs to the author.

       libcap(3), getcap(8),setcap(8) and capabilities(7).

libcap 2			  2011-04-24			      CAPSH(1)


Want to link to this manual page? Use this URL:

home | help