2008-07-09 11:38:16 +00:00
|
|
|
.\" written by Andrew Morgan <morgan@kernel.org>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" may be distributed as per GPL
|
|
|
|
.\" Modified by David A. Wheeler <dwheeler@ida.org>
|
|
|
|
.\" Modified 2004-05-27, mtk
|
|
|
|
.\" Modified 2004-06-21, aeb
|
2008-07-09 11:38:16 +00:00
|
|
|
.\" Modified 2008-04-28, morgan of kernel.org
|
|
|
|
.\" Update in line with addition of file capabilities and
|
|
|
|
.\" 64-bit capability sets in kernel 2.6.2[45].
|
2009-01-27 00:42:01 +00:00
|
|
|
.\" Modified 2009-01-26, andi kleen
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
_exit.2, brk.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, getdtablesize.2, gethostname.2, getpagesize.2, getsid.2, killpg.2, mknod.2, mknodat.2, poll.2, posix_fadvise.2, pread.2, readlink.2, setpgid.2, setreuid.2, sigaltstack.2, stat.2, symlink.2, sync.2, truncate.2, vfork.2, wait.2, wait4.2, a64l.3, abs.3, acos.3, acosh.3, asin.3, asinh.3, atan.3, atan2.3, atoi.3, cbrt.3, ceil.3, copysign.3, cosh.3, dirfd.3, div.3, ecvt.3, erf.3, erfc.3, exp.3, exp2.3, fabs.3, fdim.3, ffs.3, floor.3, fma.3, fmax.3, fmin.3, fmod.3, fpclassify.3, frexp.3, ftw.3, fwide.3, gcvt.3, getcwd.3, getdate.3, getgrent.3, gethostid.3, getpass.3, getpwent.3, getsubopt.3, getw.3, hypot.3, ilogb.3, index.3, isalpha.3, isgreater.3, iswblank.3, j0.3, ldexp.3, lockf.3, log.3, log10.3, log1p.3, logb.3, lrint.3, lround.3, mkstemp.3, mktemp.3, modf.3, mq_receive.3, mq_send.3, nan.3, nextafter.3, posix_fallocate.3, posix_memalign.3, printf.3, qecvt.3, random.3, realpath.3, remainder.3, remquo.3, rint.3, round.3, scalb.3, scalbln.3, scanf.3, siginterrupt.3, signbit.3, sigset.3, sinh.3, sqrt.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strfry.3, strpbrk.3, strsep.3, strspn.3, strstr.3, strtod.3, strtok.3, strtol.3, strtoul.3, strxfrm.3, tanh.3, tgamma.3, trunc.3, ttyslot.3, ualarm.3, usleep.3, wprintf.3, armscii-8.7, cp1251.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-3.7, iso_8859-5.7, iso_8859-6.7, iso_8859-8.7, koi8-u.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-19 17:19:13 +00:00
|
|
|
.TH CAPGET 2 2010-09-20 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2008-07-09 11:38:16 +00:00
|
|
|
capget, capset \- set/get capabilities of thread(s)
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <sys/capability.h>
|
|
|
|
.sp
|
|
|
|
.BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
|
|
|
|
.sp
|
|
|
|
.BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
|
|
|
|
.SH DESCRIPTION
|
2008-07-09 11:38:16 +00:00
|
|
|
As of Linux 2.2,
|
|
|
|
the power of the superuser (root) has been partitioned into
|
2004-11-03 13:51:07 +00:00
|
|
|
a set of discrete capabilities.
|
2008-07-09 11:38:16 +00:00
|
|
|
Each thread has a set of effective capabilities identifying
|
2004-11-03 13:51:07 +00:00
|
|
|
which capabilities (if any) it may currently exercise.
|
2008-07-09 11:38:16 +00:00
|
|
|
Each thread also has a set of inheritable capabilities that may be
|
2004-11-03 13:51:07 +00:00
|
|
|
passed through an
|
|
|
|
.BR execve (2)
|
|
|
|
call, and a set of permitted capabilities
|
|
|
|
that it can make effective or inheritable.
|
|
|
|
.PP
|
|
|
|
These two functions are the raw kernel interface for getting and
|
2008-07-09 11:38:16 +00:00
|
|
|
setting thread capabilities.
|
2007-04-12 22:42:49 +00:00
|
|
|
Not only are these system calls specific to Linux,
|
2004-11-03 13:51:07 +00:00
|
|
|
but the kernel API is likely to change and use of
|
|
|
|
these functions (in particular the format of the
|
2007-12-24 22:25:11 +00:00
|
|
|
.I cap_user_*_t
|
2009-01-27 00:42:01 +00:00
|
|
|
types) is subject to extension with each kernel revision,
|
|
|
|
but old programs will keep working.
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
|
|
|
The portable interfaces are
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR cap_set_proc (3)
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR cap_get_proc (3);
|
2004-11-03 13:51:07 +00:00
|
|
|
if possible you should use those interfaces in applications.
|
|
|
|
If you wish to use the Linux extensions in applications, you should
|
|
|
|
use the easier-to-use interfaces
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR capsetp (3)
|
2007-04-12 22:42:49 +00:00
|
|
|
and
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR capgetp (3).
|
2004-11-03 13:51:07 +00:00
|
|
|
.SS "Current details"
|
|
|
|
Now that you have been warned, some current kernel details.
|
2008-07-09 11:38:16 +00:00
|
|
|
The structures are defined as follows.
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
|
|
|
.nf
|
|
|
|
.in +4n
|
2008-07-09 11:38:16 +00:00
|
|
|
#define _LINUX_CAPABILITY_VERSION_1 0x19980330
|
|
|
|
#define _LINUX_CAPABILITY_U32S_1 1
|
|
|
|
|
|
|
|
#define _LINUX_CAPABILITY_VERSION_2 0x20071026
|
|
|
|
#define _LINUX_CAPABILITY_U32S_2 2
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
typedef struct __user_cap_header_struct {
|
2008-07-09 11:38:16 +00:00
|
|
|
__u32 version;
|
|
|
|
int pid;
|
2004-11-03 13:51:07 +00:00
|
|
|
} *cap_user_header_t;
|
|
|
|
|
|
|
|
typedef struct __user_cap_data_struct {
|
2008-07-09 11:38:16 +00:00
|
|
|
__u32 effective;
|
|
|
|
__u32 permitted;
|
|
|
|
__u32 inheritable;
|
2004-11-03 13:51:07 +00:00
|
|
|
} *cap_user_data_t;
|
|
|
|
.fi
|
|
|
|
.in -4n
|
|
|
|
.sp
|
2009-01-27 00:42:01 +00:00
|
|
|
.I effective, permitted, inheritable
|
|
|
|
are bitmasks of the capabilities defined in
|
|
|
|
.I capability(7).
|
2009-02-09 02:12:23 +00:00
|
|
|
Note the
|
|
|
|
.I CAP_*
|
|
|
|
values are bit indexes and need to be bit-shifted before ORing into
|
2009-01-27 00:42:01 +00:00
|
|
|
the bit fields.
|
2009-02-09 02:12:23 +00:00
|
|
|
To define the structures for passing to the system call you have to use the
|
2009-01-27 00:42:01 +00:00
|
|
|
.I struct __user_cap_header_struct
|
2009-02-09 02:12:23 +00:00
|
|
|
and
|
|
|
|
.I struct __user_cap_data_struct
|
2009-01-27 00:42:01 +00:00
|
|
|
names because the typedefs are only pointers.
|
|
|
|
|
2008-07-09 11:38:16 +00:00
|
|
|
Kernels prior to 2.6.25 prefer
|
|
|
|
32-bit capabilities with version
|
|
|
|
.BR _LINUX_CAPABILITY_VERSION_1 ,
|
|
|
|
and kernels 2.6.25+ prefer 64-bit capabilities with version
|
|
|
|
.BR _LINUX_CAPABILITY_VERSION_2 .
|
|
|
|
Note, 64-bit capabilities use
|
|
|
|
.IR datap [0]
|
|
|
|
and
|
|
|
|
.IR datap [1],
|
|
|
|
whereas 32-bit capabilities only use
|
|
|
|
.IR datap [0].
|
|
|
|
.sp
|
|
|
|
Another change affecting the behavior of these system calls is kernel
|
|
|
|
support for file capabilities (VFS capability support).
|
|
|
|
This support is currently a compile time option (added in kernel 2.6.24).
|
|
|
|
.sp
|
|
|
|
For
|
|
|
|
.BR capget ()
|
|
|
|
calls, one can probe the capabilities of any process by specifying its
|
|
|
|
process ID with the
|
|
|
|
.I hdrp->pid
|
|
|
|
field value.
|
|
|
|
.SS With VFS Capability Support
|
|
|
|
VFS Capability support creates a file-attribute method for adding
|
|
|
|
capabilities to privileged executables.
|
|
|
|
This privilege model obsoletes kernel support for one process
|
|
|
|
asynchronously setting the capabilities of another.
|
|
|
|
That is, with VFS support, for
|
|
|
|
.BR capset ()
|
|
|
|
calls the only permitted values for
|
|
|
|
.I hdrp->pid
|
|
|
|
are 0 or
|
|
|
|
.BR getpid (2),
|
|
|
|
which are equivalent.
|
|
|
|
.SS Without VFS Capability Support
|
|
|
|
When the kernel does not support VFS capabilities,
|
|
|
|
.BR capset ()
|
|
|
|
calls can operate on the capabilities of the thread specified by the
|
2007-04-12 22:42:49 +00:00
|
|
|
.I pid
|
2006-05-02 01:49:32 +00:00
|
|
|
field of
|
2007-10-16 19:18:17 +00:00
|
|
|
.I hdrp
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
when that is nonzero, or on the capabilities of the calling thread if
|
2006-05-02 01:49:32 +00:00
|
|
|
.I pid
|
|
|
|
is 0.
|
2007-04-12 22:42:49 +00:00
|
|
|
If
|
2006-05-02 01:49:32 +00:00
|
|
|
.I pid
|
2007-04-12 22:42:49 +00:00
|
|
|
refers to a single-threaded process, then
|
2006-05-02 01:49:32 +00:00
|
|
|
.I pid
|
|
|
|
can be specified as a traditional process ID;
|
|
|
|
operating on a thread of a multithreaded process requires a thread ID
|
2007-04-12 22:42:49 +00:00
|
|
|
of the type returned by
|
2006-05-02 01:49:32 +00:00
|
|
|
.BR gettid (2).
|
2007-04-12 22:42:49 +00:00
|
|
|
For
|
|
|
|
.BR capset (),
|
2006-05-02 01:49:32 +00:00
|
|
|
.I pid
|
2006-08-08 16:34:16 +00:00
|
|
|
can also be: \-1, meaning perform the change on all threads except the
|
2006-05-02 01:49:32 +00:00
|
|
|
caller and
|
2007-05-14 20:39:44 +00:00
|
|
|
.BR init (8);
|
2006-05-02 01:49:32 +00:00
|
|
|
or a value less than \-1, in which case the change is applied
|
|
|
|
to all members of the process group whose ID is \-\fIpid\fP.
|
2007-04-12 22:42:49 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
For details on the data, see
|
|
|
|
.BR capabilities (7).
|
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
On success, zero is returned.
|
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
2009-01-27 00:42:01 +00:00
|
|
|
|
|
|
|
The calls will fail with the error
|
|
|
|
.BR EINVAL ,
|
|
|
|
and set the
|
|
|
|
.I version
|
|
|
|
field of
|
|
|
|
.I hdrp
|
|
|
|
to the kernel preferred value of
|
|
|
|
.B _LINUX_CAPABILITY_VERSION_?
|
|
|
|
when an unsupported
|
|
|
|
.I version
|
|
|
|
value is specified.
|
|
|
|
In this way, one can probe what the current
|
|
|
|
preferred capability revision is.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
2007-04-12 22:42:49 +00:00
|
|
|
Bad memory address.
|
2004-11-03 13:51:07 +00:00
|
|
|
.I hdrp
|
2008-07-09 11:38:16 +00:00
|
|
|
must not be NULL.
|
2004-11-03 13:51:07 +00:00
|
|
|
.I datap
|
2008-07-09 11:38:16 +00:00
|
|
|
may only be NULL when the user is trying to determine the preferred
|
|
|
|
capability version format supported by the kernel.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
One of the arguments was invalid.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
An attempt was made to add a capability to the Permitted set, or to set
|
|
|
|
a capability in the Effective or Inheritable sets that is not in the
|
|
|
|
Permitted set.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
2006-05-02 01:49:32 +00:00
|
|
|
The caller attempted to use
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR capset ()
|
2006-05-02 01:49:32 +00:00
|
|
|
to modify the capabilities of a thread other than itself,
|
2008-07-09 11:38:16 +00:00
|
|
|
but lacked sufficient privilege.
|
|
|
|
For kernels supporting VFS
|
|
|
|
capabilities, this is never permitted.
|
|
|
|
For kernels lacking VFS
|
|
|
|
support, the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B CAP_SETPCAP
|
|
|
|
capability is required.
|
2007-04-12 22:42:49 +00:00
|
|
|
(A bug in kernels before 2.6.11 meant that this error could also
|
2006-05-02 01:49:32 +00:00
|
|
|
occur if a thread without this capability tried to change its
|
2006-01-14 03:25:01 +00:00
|
|
|
own capabilities by specifying the
|
|
|
|
.I pid
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
field as a nonzero value (i.e., the value returned by
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR getpid (2))
|
2006-01-14 03:25:01 +00:00
|
|
|
instead of 0.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ESRCH
|
2006-05-02 01:49:32 +00:00
|
|
|
No such thread.
|
2006-08-04 09:41:28 +00:00
|
|
|
.SH "CONFORMING TO"
|
2007-12-25 21:28:09 +00:00
|
|
|
These system calls are Linux-specific.
|
2007-05-16 02:25:26 +00:00
|
|
|
.SH NOTES
|
2004-11-03 13:51:07 +00:00
|
|
|
The portable interface to the capability querying and setting
|
|
|
|
functions is provided by the
|
2007-06-23 07:19:07 +00:00
|
|
|
.I libcap
|
2007-06-23 08:17:33 +00:00
|
|
|
library and is available here:
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
2008-07-09 11:38:16 +00:00
|
|
|
http://www.kernel.org/pub/linux/libs/security/linux-privs
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
2006-08-08 16:34:16 +00:00
|
|
|
.BR clone (2),
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR gettid (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR capabilities (7)
|