[pull] su.1 manual page

[pull] su.1 manual page

[Sami Kerola]

Hello,

Please find from my git a su(1) manual page candidate.  The text is
almost one to one copy with GNU Coreutils 'su invocation' info page,
so it is questionable if I "wrote" the man page.  To feel a little
less quilty stealing I added few examples, fix to return values, hint
about PAM configuration file and authors sections.

The other patch is a fix to groff macro usage error I spot in howto-man
while writing the su.1 file.


The following changes since commit 71681ee5ecd24ac19747dc692f2350a212e448e9:

  build-sys: move configure login options to one place (2012-05-29
15:24:04 +0200)

are available in the git repository at:

  git://github.com/kerolasa/lelux-utiliteetit.git su.1

for you to fetch changes up to deb744fbb7f7f5a52630d587691204eccfa48120:

  docs: fix email macro in manual example (2012-05-30 19:49:37 +0200)

----------------------------------------------------------------
Sami Kerola (2):
      docs: add su.1 manual page
      docs: fix email macro in manual example

 Documentation/howto-man-page.txt |    8 +-
 login-utils/su.1                 |  178 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 182 insertions(+), 4 deletions(-)
 create mode 100644 login-utils/su.1

diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt
index c217962..5ca4af0 100644
--- a/Documentation/howto-man-page.txt
+++ b/Documentation/howto-man-page.txt
@@ -143,13 +143,13 @@ etc
 .PD
 .RE
 .SH AUTHORS
-.UR rjh@\:example.org
+.MT rjh@\:example.org
 Random J. Hacker
-.UE
+.ME
 .br
-.UR fred@\:example.com
+.MT fred@\:example.com
 Fred Foobar
-.UE
+.ME
 .SH "SEE ALSO"
 .BR groff_man (7),
 .BR foo (1),
diff --git a/login-utils/su.1 b/login-utils/su.1
new file mode 100644
index 0000000..1847325
--- /dev/null
+++ b/login-utils/su.1
@@ -0,0 +1,178 @@
+.\" Contents of this manual page is copied from GNU Coreutils
+.\" info page at end of May 2012, with few additions such as
+.\" examples and see also sections.
+.TH SU "1" "May 2012" "util-linux" "User Commands"
+.SH NAME
+su \- run a shell with substitute user and group IDs
+.SH SYNOPSIS
+.B su
+[options] [\-]
+.I user
+[args]
+.SH DESCRIPTION
+.B su
+allows one user to temporarily become another user.  It runs a
+command (often an interactive shell) with the real and effective user
+ID, group ID, and supplemental groups of a given user.
+.PP
+If no user is given, the default is root, the super-user.  The shell
+to use is taken from user's passwd entry, or /bin/sh if none is
+specified there.  If user has a password,
+.B su
+prompts for the password unless run by a user with effective user ID
+of zero (the super-user).
+.PP
+By default,
+.B su
+does not change the current directory.  It sets the environment
+variables HOME and SHELL from the password entry for user, and if
+user is not the super-user, sets USER and LOGNAME to user.  By
+default, the shell is not a login shell.
+.PP
+Any additional
+.I args
+are passed as additional arguments to the shell.
+.PP
+.B su
+does not treat /bin/sh or any other shells specially (e.g., by
+setting argv[0] to -su, passing -c only to certain shells, etc.).
+.PP
+.B su
+can optionally be compiled to use syslog to report failed, and
+optionally successful,
+.B su
+attempts.  (If the system supports syslog.)  However,
+.B su
+does not check if the user is a member of the wheel group; see
+.BR NOTES .
+.SH OPTIONS
+.TP
+\fB\-c\fR, \fB\-\-command\fR [\fIcommand\fR]
+Pass command, a single command line to run, to the shell with a
+.I \-c
+option instead of starting an interactive shell.
+.TP
+\fB\-f\fR, \fB\-\-fast\fR
+Pass the
+.I \-f
+option to the shell.  This probably only makes sense if the shell run
+is csh or tcsh, for which the
+.I \-f
+option prevents reading the startup file (.cshrc).  With Bourne-like
+shells, the
+.I -f
+option disables file name pattern expansion (globbing), which is not
+likely to be useful.
+.TP
+\fB\-\fR, \fB\-l\fR, \fB\-\-login\fR
+Make the shell a login shell.  This means the following.  Unset all
+environment variables except TERM, HOME, and SHELL (which are set as
+described above), and USER and LOGNAME (which are set, even for the
+super-user, as described above), and set PATH to a compiled-in
+default value.  Change to user's home directory.  Prepend  '\-' to the
+shell's name, intended to make it read its login startup file(s).
+.TP
+\fB\-m\fR, \fB\-p\fR, \fB\-\-preserve\-environment\fR
+Do not change the environment variables HOME, USER, LOGNAME, or
+SHELL.  Run the shell given in the environment variable SHELL instead
+of the shell from user's passwd entry, unless the user running
+.B su
+is not the super-user and user's shell is restricted.  A restricted
+shell is one that is not listed in the file /etc/shells, or in a
+compiled-in list if that file does not exist.  Parts of what this
+option does can be overridden by
+.I \-\-login
+and
+.IR \-\-shell .
+.TP
+\fB\-s\fR, \fB\-\-shell\fR [\fIshell\fR]
+Run shell instead of the shell from user's passwd entry, unless the
+user running
+.B su
+is not the super-user and user's shell is restricted (see
+.I -m
+just above).
+.SH EXAMPLES
+.TP
+.B su \ \-m \ nobody \ \-c 'ls -l'
+Run ls as nobody user.  Notice that \-m is required since user nobody
+does not have a valid shell by default.
+.TP
+.B su \ \-l fred
+.TQ
+.B su \ \- fred
+Simulate a login for user fred.
+.TP
+.B su \ \-
+.br
+Simulate a login for root.
+.SH "EXIT STATUS"
+In common case
+.B su
+will exit with status of the subshell.  See other possibilities
+below.
+.PP
+.RS
+.PD 0
+.TP
+.B 0
+success
+.TP
+.B 1
+system and authentication errors
+.TP
+.B 126
+subshell is found but cannot be invoked
+.TP
+.B 127
+subshell cannot be found
+.PD
+.RE
+.SH FILES
+.TP
+.B /etc/pam.d/su
+PAM configuration for
+.BR su .
+.SH NOTES
+Why
+.B su
+does not support the
+.I wheel
+group by Richard Stallman.
+.PP
+Sometimes a few of the users try to hold total power over all the
+rest.  For example, in 1984, a few users at the MIT AI lab decided to
+seize power by changing the operator password on the Twenex system
+and keeping it secret from everyone else.  (I was able to thwart this
+coup and give power back to the users by patching the kernel, but I
+wouldn't know how to do that in Unix.)
+.PP
+However, occasionally the rulers do tell someone.  Under the usual
+.B su
+mechanism, once someone learns the root password who sympathizes with
+the ordinary users, he or she can tell the rest.  The "wheel group"
+feature would make this impossible, and thus cement the power of the
+rulers.
+.PP
+I'm on the side of the masses, not that of the rulers.  If you are
+used to supporting the bosses and sysadmins in whatever they do, you
+might find this idea strange at first.
+.SH AUTHORS
+.MT djm@gnu.ai.mit.edu
+David MacKenzie
+.ME
+.br
+.MT jim@meyering.net
+Jim Meyering
+.ME
+.SH "SEE ALSO"
+.BR login (1),
+.BR passwd (5),
+.BR sudo (8),
+.BR syslogd (8)
+.SH AVAILABILITY
+The example command is part of the util-linux package and is
+available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .

-- 
   Sami Kerola
   http://www.iki.fi/kerolasa/

Re: [pull] su.1 manual page

[Ludwig Nussel]

Sami Kerola wrote:
> Please find from my git a su(1) manual page candidate.  The text is
> almost one to one copy with GNU Coreutils 'su invocation' info page,
> so it is questionable if I "wrote" the man page.  To feel a little

Hmm, I was about to write a man page from scratch. Should I continue or
do we use the coreutils man page?

cu
Ludwig

PS: the section about the wheel group can be removed :)

-- 
 (o_   Ludwig Nussel
 //\
 V_/_  http://www.suse.de/
SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg) 

Re: [pull] su.1 manual page

[Sami Kerola]

On Thu, May 31, 2012 at 10:06 AM, Ludwig Nussel <ludwig.nussel@suse.de>=
 wrote:
>> Please find from my git a su(1) manual page candidate. =A0The text i=
s
>> almost one to one copy with GNU Coreutils 'su invocation' info page,
>> so it is questionable if I "wrote" the man page. =A0To feel a little
>
> Hmm, I was about to write a man page from scratch. Should I continue =
or
> do we use the coreutils man page?

1. Continue writing from scratch, and propose your own man page candida=
te.
2. Contribute to my branch.
3. Drop the task as the proposed man page is good enough.

> PS: the section about the wheel group can be removed :)

I think keeping some sort of note about wheel group not being checked
is valid information, but does it have to be RMS story is different
question. I'll have a look of that at evening.

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/
--
To unsubscribe from this list: send the line "unsubscribe util-linux" i=
n
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [pull] su.1 manual page

[Sami Kerola]

On Thu, May 31, 2012 at 11:04 AM, Sami Kerola <kerolasa@iki.fi> wrote:
>> PS: the section about the wheel group can be removed :)
>
> I think keeping some sort of note about wheel group not being checked
> is valid information, but does it have to be RMS story is different
> question. I'll have a look of that at evening.

I changed the original patch doing the following. Do you, or anyone
else, have other suggestions how the manual page could be better?

https://raw.github.com/kerolasa/lelux-utiliteetit/su.1/login-utils/su.1


diff --git a/login-utils/su.1 b/login-utils/su.1
index 1847325..8eac714 100644
--- a/login-utils/su.1
+++ b/login-utils/su.1
@@ -41,10 +41,11 @@ setting argv[0] to -su, passing -c only to certain
shells, etc.).
 can optionally be compiled to use syslog to report failed, and
 optionally successful,
 .B su
-attempts.  (If the system supports syslog.)  However,
+attempts.  (If the system supports syslog.)
+.PP
+This implementation of
 .B su
-does not check if the user is a member of the wheel group; see
-.BR NOTES .
+does not check if the user is a member of the wheel group.
 .SH OPTIONS
 .TP
 \fB\-c\fR, \fB\-\-command\fR [\fIcommand\fR]
@@ -133,30 +134,6 @@ subshell cannot be found
 .B /etc/pam.d/su
 PAM configuration for
 .BR su .
-.SH NOTES
-Why
-.B su
-does not support the
-.I wheel
-group by Richard Stallman.
-.PP
-Sometimes a few of the users try to hold total power over all the
-rest.  For example, in 1984, a few users at the MIT AI lab decided to
-seize power by changing the operator password on the Twenex system
-and keeping it secret from everyone else.  (I was able to thwart this
-coup and give power back to the users by patching the kernel, but I
-wouldn't know how to do that in Unix.)
-.PP
-However, occasionally the rulers do tell someone.  Under the usual
-.B su
-mechanism, once someone learns the root password who sympathizes with
-the ordinary users, he or she can tell the rest.  The "wheel group"
-feature would make this impossible, and thus cement the power of the
-rulers.
-.PP
-I'm on the side of the masses, not that of the rulers.  If you are
-used to supporting the bosses and sysadmins in whatever they do, you
-might find this idea strange at first.
 .SH AUTHORS
 .MT djm@gnu.ai.mit.edu
 David MacKenzie

-- 
   Sami Kerola
   http://www.iki.fi/kerolasa/

Re: [pull] su.1 manual page

[Ludwig Nussel]

[-- Attachment #1: Type: text/plain, Size: 710 bytes --]

Sami Kerola wrote:
> On Thu, May 31, 2012 at 10:06 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
>>> Please find from my git a su(1) manual page candidate.  The text is
>>> almost one to one copy with GNU Coreutils 'su invocation' info page,
>>> so it is questionable if I "wrote" the man page.  To feel a little
>>
>> Hmm, I was about to write a man page from scratch. Should I continue or
>> do we use the coreutils man page?
> 
> 1. Continue writing from scratch, and propose your own man page candidate.

I've attached my suggestion

cu
Ludwig

-- 
 (o_   Ludwig Nussel
 //\
 V_/_  http://www.suse.de/
SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg) 

[-- Attachment #2: su.1 --]
[-- Type: text/plain, Size: 4149 bytes --]

.TH SU 1 "May 2012" "util-linux" "User Commands"
.SH NAME
su \- Run a command with substitute user and group ID
.SH SYNOPSIS
.B su
[OPTIONS...] [\-] [USER [ARGS...]]
.SH DESCRIPTION
.B su
allows to run commands with substitute user and group ID.

When called without arguments \fBsu\fR defaults to running an interactive shell
as \fIroot\fR.

For backward compatibilty \fBsu\fR defaults to not change the
current directory and to only set the enviroment variables
\fBHOME\fR and \fBSHELL\fR (plus \fBUSER\fR and \fBLOGNAME\fR if the
target user is not root). It's recommended to always use the
\fB\-\-login\fR option (resp it's shortcut \fB-\fR) to avoid side
effects caused by mixing environments.

This version of \fBsu\fR uses PAM for authentication, account and
session management. Some configuration options found in other
\fBsu\fR implementations such as e.g. support of a wheel group have
to be configured via PAM.


.SH OPTIONS
.TP
\fB\-c\fR \fICOMMAND\fR, \fB\-\-command\fR=\fICOMMAND\fR
Pass COMMAND to the shell with the
.B -c
option

.TP
\fB\-\-session\-command\fR=\fICOMMAND\fR
Same as \fB-c\fR but do not create a new session (discouraged)

.TP
\fB\-f\fR, \fB\-\-fast\fR
Pass \fB\-f\fR to the shell which may or may not be useful depending
on the shell.

.TP
\fB\-\fR, \fB\-l\fR, \fB\-\-login\fR
Starts the shell as login shell with an environment similar to a
real login:

\- clears all environment variables except for \fBTERM\fR

\- initializes the environment variables \fBHOME\fR, \fBSHELL\fR,
\fBUSER\fR, \fBLOGNAME\fR, \fBPATH\fR

\- changes to the target user's home directory

\- sets argv[0] of the shell to \fB\-\fR in order to make the shell
a login shell

.TP
\fB\-m\fR, \fB\-p\fR, \fB\-\-preserve-environment\fR
Preserves the whole environment, ie does not set \fBHOME\fR,
\fBSHELL\fR, \fBUSER\fR nor \fBLOGNAME\fR.

.TP
\fB\-s\fR \fISHELL\fR, \fB\-\-shell\fR=\fISHELL\fR
Runs the specified shell instead of the default. The shell to run is
selected according to the following rules in order:

\- the shell specified with \fB\-\-shell\fR

\- The shell specified in the environment variable \fBSHELL\fR if
the \fB\-\-preserve-environment\fR option is used.

\- the shell listed in the passwd entry of the target user

\- /bin/sh

If the target user has a restricted shell (ie not listed in
/etc/shells) the \fB\-\-shell\fR option and the \fBSHELL\fR
environment variables are ignored unless the calling user is root.

.TP
\fB\-\-help\fR
Display help text and exit

.TP
\fB\-\-version\fR
Display version information and exit

.SH CONFIG FILES
.B su
reads the
.IR /etc/default/su
and
.IR /etc/login.defs
configuration files.
The following configuration items are relevant for
.BR su (1):
.PP
\fBFAIL_DELAY\fR (number)
.RS 4
Delay in seconds in case of authentication failure.
.RE
.PP
\fBENV_PATH\fR (string)
.RS 4
Defines the PATH environment variable for a regular
user. The default value is "/usr/local/bin:/bin:/usr/bin".
.RE
.PP
\fBENV_ROOTPATH\fR (string), \fBENV_SUPATH\fR (string)
.RS 4
Defines the PATH environment variable for root. The default value is
"/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin".
.RE
.PP
\fBALWAYS_SET_PATH\fR (boolean)
.RS 4
If set to "yes" and \-\-login and \-\-preserve\-environment were
not specified initializes \fBPATH\fR
.RE
.SH EXIT STATUS
\fBsu\fR normall returns the exit status of the command it executed.
If the command was killed by a signal, \fBsu\fR returns the number
of the signal plus 128.

Exit status generated by \fBsu\fR itself:
.TP
1
Generic error before executing the requested command
.TP
126
The requested command could not be executed
.TP
127
The requested command could was not found
.SH FILES
.nf
/etc/pam.d/su   \- default PAM configuration file
/etc/pam.d/su-l \- PAM configuration file if \-\-login is specified
/etc/default/su
/etc/login.defs
.fi
.SH "SEE ALSO"
.BR pam (8),
.BR shells (5),
.BR login.defs (5),
.SH AUTHOR
Derived from coreutils' su which was based on an implemenation from David MacKenzie
.SH AVAILABILITY
The su command is part of the util-linux package and is available from
ftp://ftp.kernel.org/pub/linux/utils/util-linux/.

Re: [pull] su.1 manual page

[Sami Kerola]

On Fri, Jun 1, 2012 at 11:23 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
> Sami Kerola wrote:
>> On Thu, May 31, 2012 at 10:06 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
>>> Hmm, I was about to write a man page from scratch. Should I continue or
>>> do we use the coreutils man page?
>>
>> 1. Continue writing from scratch, and propose your own man page candidate.
>
> I've attached my suggestion

Hi Ludwig,

Your manual is better, so I took liberty to add it to my branch and
make few groff changes.

https://github.com/kerolasa/lelux-utiliteetit/commit/2ab15cb0c3b6fe81697713ce6dc56b85e44a00fe#login-utils/su.1

Have also a look of how the pager will show the end result.

https://raw.github.com/kerolasa/lelux-utiliteetit/su.1/login-utils/su.1

I would like to hear you are OK with that. Without other comments I
reckon the su.1 is ready to be merged.

-- 
   Sami Kerola
   http://www.iki.fi/kerolasa/

Re: [pull] su.1 manual page

[Ludwig Nussel]

Sami Kerola wrote:
> On Fri, Jun 1, 2012 at 11:23 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
>> Sami Kerola wrote:
>>> On Thu, May 31, 2012 at 10:06 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
>>>> Hmm, I was about to write a man page from scratch. Should I continue or
>>>> do we use the coreutils man page?
>>>
>>> 1. Continue writing from scratch, and propose your own man page candidate.
>>
>> I've attached my suggestion
> 
> Hi Ludwig,
> 
> Your manual is better, so I took liberty to add it to my branch and
> make few groff changes.
> 
> https://github.com/kerolasa/lelux-utiliteetit/commit/2ab15cb0c3b6fe81697713ce6dc56b85e44a00fe#login-utils/su.1
> 
> Have also a look of how the pager will show the end result.
> 
> https://raw.github.com/kerolasa/lelux-utiliteetit/su.1/login-utils/su.1
> 
> I would like to hear you are OK with that. Without other comments I
> reckon the su.1 is ready to be merged.

Fine with me, thanks!

cu
Ludwig

-- 
 (o_   Ludwig Nussel
 //\
 V_/_  http://www.suse.de/
SUSE LINUX Products GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer, HRB 16746 (AG Nürnberg) 

Re: [pull] su.1 manual page

[Karel Zak]

On Mon, Jun 04, 2012 at 09:28:06AM +0200, Ludwig Nussel wrote:
> Sami Kerola wrote:
> > On Fri, Jun 1, 2012 at 11:23 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
> >> Sami Kerola wrote:
> >>> On Thu, May 31, 2012 at 10:06 AM, Ludwig Nussel <ludwig.nussel@suse.de> wrote:
> >>>> Hmm, I was about to write a man page from scratch. Should I continue or
> >>>> do we use the coreutils man page?
> >>>
> >>> 1. Continue writing from scratch, and propose your own man page candidate.
> >>
> >> I've attached my suggestion
> > 
> > Hi Ludwig,
> > 
> > Your manual is better, so I took liberty to add it to my branch and
> > make few groff changes.
> > 
> > https://github.com/kerolasa/lelux-utiliteetit/commit/2ab15cb0c3b6fe81697713ce6dc56b85e44a00fe#login-utils/su.1
> > 
> > Have also a look of how the pager will show the end result.
> > 
> > https://raw.github.com/kerolasa/lelux-utiliteetit/su.1/login-utils/su.1
> > 
> > I would like to hear you are OK with that. Without other comments I
> > reckon the su.1 is ready to be merged.
> 
> Fine with me, thanks!

 Merged, thanks!


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com