Package: manpages
Version: 2.78-1
Severity: wishlist
Tags: patch
A patch is attached that does some copy editing on capabilities(7),
namely:
- The grammar of the capability list is inconsistent; some entries
describe directly what the holder of a capability can do, but some
entries use a word like "permit" or "allow" from the perspective
of the capability itself. Change such entries to describe
directly what the holder of a capability can do.
- Delete duplicate subentry for KEYCTL_CHOWN/KEYCTL_SETPERM
operations in the CAP_SYS_ADMIN entry. (It feels like that
capability entry should be converted to a list, but I've left it
in semicolon-delimited form for now.)
- Remove text about ENFILE from the text about the
/proc/sys/fs/file-max limit in the CAP_SYS_ADMIN entry, since this
is already described in the man pages for the relevant
ofile-creating system calls.
- Disambiguate "directory sticky bit" to "the containing directory's
sticky bit" in the CAP_FOWNER entry.
- Correct or clarify a few other bits of grammar and such; see the
diff file itself for details.
These changes are suggested, not demanded, and may be cherrypicked. I
claim no copyright on these changes. This patch does not contain
changelog messages of any form, though I can provide such if desired.
No sentence in this paragraph is intended to imply that the situation
would have been otherwise had the sentence not been included in this
mesage. :-)
Feedback is appreciated.
---> Drake Wilson
-- System Information:
Debian Release: lenny/sid
APT prefers unstable
APT policy: (500, 'unstable')
Architecture: amd64 (x86_64)
Kernel: Linux 2.6.24.2 (SMP w/2 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash
-- no debconf information
--- capabilities.7.old 2008-03-15 04:45:48.000000000 -0500
+++ capabilities.7 2008-03-15 04:59:02.000000000 -0500
@@ -53,15 +53,15 @@
retrieve auditing status and filtering rules.
.TP
.BR CAP_AUDIT_WRITE " (since Linux 2.6.11)"
-Allow records to be written to kernel auditing log.
+Write records to the kernel auditing log.
.TP
.B CAP_CHOWN
-Allow arbitrary changes to file UIDs and GIDs (see
+Make arbitrary changes to file UIDs and GIDs (see
.BR chown (2)).
.TP
.B CAP_DAC_OVERRIDE
Bypass file read, write, and execute permission checks.
-(DAC = "discretionary access control".)
+(DAC is "discretionary access control".)
.TP
.B CAP_DAC_READ_SEARCH
Bypass file read permission checks and
@@ -73,7 +73,7 @@
the file (e.g.,
.BR chmod (2),
.BR utime (2)),
-excluding those operations covered by the
+excluding those operations covered by
.B CAP_DAC_OVERRIDE
and
.BR CAP_DAC_READ_SEARCH ;
@@ -81,7 +81,7 @@
.BR chattr (1))
on arbitrary files;
set Access Control Lists (ACLs) on arbitrary files;
-ignore directory sticky bit on file deletion;
+ignore the containing directory's sticky bit on file deletion;
specify
.B O_NOATIME
for arbitrary files in
@@ -91,11 +91,11 @@
.TP
.B CAP_FSETID
Don't clear set-user-ID and set-group-ID bits when a file is modified;
-permit setting of the set-group-ID bit for a file whose GID does not match
+permit setting the set-group-ID bit for a file whose GID does not match
the file system or any of the supplementary GIDs of the calling process.
.TP
.B CAP_IPC_LOCK
-Permit memory locking
+Lock memory
.RB ( mlock (2),
.BR mlockall (2),
.BR mmap (2),
@@ -117,12 +117,12 @@
.\" for this?
.TP
.B CAP_LEASE
-(Linux 2.4 onwards) Allow file leases to be established on
+(Linux 2.4 onwards) Establish file leases on
arbitrary files (see
.BR fcntl (2)).
.TP
.B CAP_LINUX_IMMUTABLE
-Allow setting of the
+Set the
.B EXT2_APPEND_FL
and
.B EXT2_IMMUTABLE_FL
@@ -132,52 +132,54 @@
.TP
.B CAP_MKNOD
(Linux 2.4 onwards)
-Allow creation of special files using
+Create special files using
.BR mknod (2).
.TP
.B CAP_NET_ADMIN
-Allow various network-related operations
+Perform various network-related operations
(e.g., setting privileged socket options,
enabling multicasting, interface configuration,
modifying routing tables).
.TP
.B CAP_NET_BIND_SERVICE
-Allow binding to Internet domain reserved socket ports
+Bind to Internet domain reserved socket ports
(port numbers less than 1024).
.TP
.B CAP_NET_BROADCAST
-(Unused) Allow socket broadcasting, and listening multicasts.
+(Unused) Use socket broadcasting and listening multicasts.
.TP
.B CAP_NET_RAW
-Permit use of RAW and PACKET sockets.
+Use RAW and PACKET sockets.
.\" Also various IP options and setsockopt(SO_BINDTODEVICE)
.TP
.B CAP_SETGID
-Allow arbitrary manipulations of process GIDs and supplementary GID list;
-allow forged GID when passing socket credentials via Unix domain sockets.
+Arbitrarily manipulate process GIDs and supplementary GID list;
+forge GID when passing socket credentials via Unix domain sockets.
.TP
.B CAP_SETPCAP
Grant or remove any capability in the caller's
permitted capability set to or from any other process.
.TP
.B CAP_SETUID
-Allow arbitrary manipulations of process UIDs
+Arbitrarily manipulate process UIDs
.RB ( setuid (2),
.BR setreuid (2),
.BR setresuid (2),
.BR setfsuid (2));
-allow forged UID when passing socket credentials via Unix domain sockets.
+forge UID when passing socket credentials via Unix domain sockets.
.\" FIXME CAP_SETUID also an effect in exec(); document this.
.TP
.B CAP_SYS_ADMIN
-Permit a range of system administration operations including:
+A wide range of system administration operations. Use
.BR quotactl (2),
.BR mount (2),
.BR umount (2),
.BR swapon (2),
.BR swapoff (2),
.BR sethostname (2),
-.BR setdomainname (2),
+and
+.BR setdomainname (2);
+perform
.B IPC_SET
and
.B IPC_RMID
@@ -202,73 +204,64 @@
.B KEYCTL_CHOWN
and
.B KEYCTL_SETPERM
-operations.
-allow forged UID when passing socket credentials;
+operations;
+forge UID when passing socket credentials;
exceed
-.IR /proc/sys/fs/file-max ,
-the system-wide limit on the number of open files,
+.IR /proc/sys/fs/file-max
+(the system-wide limit on the number of open files)
in system calls that open files (e.g.,
.BR accept (2),
.BR execve (2),
.BR open (2),
-.BR pipe (2);
-without this capability these system calls will fail with the error
-.B ENFILE
-if this limit is encountered);
-employ
+.BR pipe (2));
+use the
.B CLONE_NEWNS
flag with
.BR clone (2)
and
-.BR unshare (2);
-perform
-.B KEYCTL_CHOWN
-and
-.B KEYCTL_SETPERM
-.BR keyctl (2)
-operations.
+.BR unshare (2).
.TP
.B CAP_SYS_BOOT
-Permit calls to
+Call
.BR reboot (2)
and
.BR kexec_load (2).
.TP
.B CAP_SYS_CHROOT
-Permit calls to
+Call
.BR chroot (2).
.TP
.B CAP_SYS_MODULE
-Allow loading and unloading of kernel modules;
-allow modifications to capability bounding set (see
+Load and unload kernel modules;
+modify the capability bounding set (see
.BR init_module (2)
and
.BR delete_module (2)).
.TP
.B CAP_SYS_NICE
-Allow raising process nice value
+Raise the nice value of processes
.RB ( nice (2),
-.BR setpriority (2))
-and changing of the nice value for arbitrary processes;
-allow setting of real-time scheduling policies for calling process,
-and setting scheduling policies and priorities for arbitrary processes
+.BR setpriority (2));
+change the nice value for arbitrary processes;
+set real-time scheduling policies for the calling process;
+set scheduling policies and priorities for arbitrary processes
.RB ( sched_setscheduler (2),
.BR sched_setparam (2));
set CPU affinity for arbitrary processes
.RB ( sched_setaffinity (2));
set I/O scheduling class and priority for arbitrary processes
.RB ( ioprio_set (2));
-allow
+use
.BR migrate_pages (2)
-to be applied to arbitrary processes and allow processes
-to be migrated to arbitrary nodes;
+on arbitrary processes and migrate processes
+to arbitrary nodes;
.\" FIXME CAP_SYS_NICE also has the following effect for
.\" migrate_pages(2):
.\" do_migrate_pages(mm, &old, &new,
.\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE);
-allow
+apply
.BR move_pages (2)
-to be applied to arbitrary processes;
+to arbitrary processes;
use the
.B MPOL_MF_MOVE_ALL
flag with
@@ -277,15 +270,15 @@
.BR move_pages (2).
.TP
.B CAP_SYS_PACCT
-Permit calls to
+Call
.BR acct (2).
.TP
.B CAP_SYS_PTRACE
-Allow arbitrary processes to be traced using
-.BR ptrace (2)
+Trace arbitrary processes using
+.BR ptrace (2).
.TP
.B CAP_SYS_RAWIO
-Permit I/O port operations
+Perform I/O port operations
.RB ( iopl (2)
and
.BR ioperm (2));
@@ -293,32 +286,33 @@
.IR /proc/kcore .
.TP
.B CAP_SYS_RESOURCE
-Permit: use of reserved space on ext2 file systems;
+Use reserved space on ext2 file systems; make
.BR ioctl (2)
calls controlling ext3 journaling;
-disk quota limits to be overridden;
-resource limits to be increased (see
+override disk quota limits;
+increase resource limits (see
.BR setrlimit (2));
+override the
.B RLIMIT_NPROC
-resource limit to be overridden;
+resource limit;
+raise the
.I msg_qbytes
-limit for a message queue to be
-raised above the limit in
+limit for a message queue above the limit in
.I /proc/sys/kernel/msgmnb
(see
.BR msgop (2)
and
-.BR msgctl (2).
+.BR msgctl (2)).
.TP
.B CAP_SYS_TIME
-Allow modification of system clock
+Modify the system clock
.RB ( settimeofday (2),
.BR stime (2),
.BR adjtimex (2));
-allow modification of real-time (hardware) clock
+modify the real-time (hardware) clock.
.TP
.B CAP_SYS_TTY_CONFIG
-Permit calls to
+Call
.BR vhangup (2).
.SS Capability Sets
Each thread has three capability sets containing zero or more
