Debian Bug report logs - #471029
manpages: some errors and stylistic considerations in capabilities(7)

version graph

Package: manpages; Maintainer for manpages is Martin Schulze <joey@debian.org>; Source for manpages is src:manpages.

Reported by: Drake Wilson <drake@begriffli.ch>

Date: Sat, 15 Mar 2008 10:30:16 UTC

Severity: wishlist

Tags: fixed-upstream, patch

Found in version manpages/2.78-1

Fixed in version 3.15-1

Done: Simon Paillard <spaillard@debian.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#471029; Package manpages. Full text and rfc822 format available.

Acknowledgement sent to Drake Wilson <drake@begriffli.ch>:
New Bug report received and forwarded. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Drake Wilson <drake@begriffli.ch>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: manpages: some errors and stylistic considerations in capabilities(7)
Date: Sat, 15 Mar 2008 05:29:40 -0500
[Message part 1 (text/plain, inline)]
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.patch (text/plain, attachment)]

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#471029; Package manpages. (Fri, 28 Nov 2008 15:06:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to mtk.manpages@gmail.com:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Fri, 28 Nov 2008 15:06:03 GMT) Full text and rfc822 format available.

Message #10 received at 471029@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: 471029@bugs.debian.org
Cc: control@bugs.debian.org
Date: Fri, 28 Nov 2008 10:02:35 -0500
tags 471029 fixed-upstream
thanks

I've just seen this report.  Independently, I happen to have already
fixed much of what is suggested in the bug.  Most of those changes
were in man-pages-3.04.

What I will do for 3.15 is remove the ENFILE text as suggested.

Further comments on selected pieces of the patch below.  (I won't
comment on pieces already covered by the above comments.)

First though, a general comment: it would have been _very_ helpful to
split this patch into logically separate pieces (and bug reports) --
e.g., following should have been a separate patch/report:

[[
  - 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.
]]

> --- 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".)

Already fixed.

>  .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

Already fixed.

>  .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;

I don't agree with this.

>  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 current text is grammaticaly correct, I would say.  (the suggested
text would also be okay.)

>  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);

Fixed for 3.15.

> +perform

Already fixed.

>  .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)

Fixed for 3.15.

> -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)).

Fixed for 3.15.

>  .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

Cheers,

Michael




Tags added: fixed-upstream Request was from "Michael Kerrisk" <mtk.manpages@googlemail.com> to control@bugs.debian.org. (Fri, 28 Nov 2008 15:06:08 GMT) Full text and rfc822 format available.

Reply sent to Simon Paillard <spaillard@debian.org>:
You have taken responsibility. (Sat, 12 Feb 2011 18:36:03 GMT) Full text and rfc822 format available.

Notification sent to Drake Wilson <drake@begriffli.ch>:
Bug acknowledged by developer. (Sat, 12 Feb 2011 18:36:03 GMT) Full text and rfc822 format available.

Message #17 received at 471029-done@bugs.debian.org (full text, mbox):

From: Simon Paillard <spaillard@debian.org>
To: 471029-done@bugs.debian.org
Subject: Re: Bug#471029: manpages: some errors and stylistic considerations in capabilities(7)
Date: Sat, 12 Feb 2011 19:33:26 +0100
Version: 3.15-1

On Fri, Nov 28, 2008 at 10:02:35AM -0500, Michael Kerrisk wrote:
> tags 471029 fixed-upstream
> thanks
> 
> I've just seen this report.  Independently, I happen to have already
> fixed much of what is suggested in the bug.  Most of those changes
> were in man-pages-3.04.
> 
> What I will do for 3.15 is remove the ENFILE text as suggested.
[..]

This has been done as well, no more reference to ENFILE.
 

-- 
Simon Paillard




Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Sun, 13 Mar 2011 07:33:36 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Thu Apr 17 12:30:39 2014; Machine Name: buxtehude.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.