Annotation of src/usr.bin/su/su.1, Revision 1.1
1.1 ! deraadt 1: .\" Copyright (c) 1988, 1990 The Regents of the University of California.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Redistribution and use in source and binary forms, with or without
! 5: .\" modification, are permitted provided that the following conditions
! 6: .\" are met:
! 7: .\" 1. Redistributions of source code must retain the above copyright
! 8: .\" notice, this list of conditions and the following disclaimer.
! 9: .\" 2. Redistributions in binary form must reproduce the above copyright
! 10: .\" notice, this list of conditions and the following disclaimer in the
! 11: .\" documentation and/or other materials provided with the distribution.
! 12: .\" 3. All advertising materials mentioning features or use of this software
! 13: .\" must display the following acknowledgement:
! 14: .\" This product includes software developed by the University of
! 15: .\" California, Berkeley and its contributors.
! 16: .\" 4. Neither the name of the University nor the names of its contributors
! 17: .\" may be used to endorse or promote products derived from this software
! 18: .\" without specific prior written permission.
! 19: .\"
! 20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
! 21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 30: .\" SUCH DAMAGE.
! 31: .\"
! 32: .\" from: @(#)su.1 6.12 (Berkeley) 7/29/91
! 33: .\" $Id: su.1,v 1.7 1994/09/05 00:27:10 mycroft Exp $
! 34: .\"
! 35: .Dd July 29, 1991
! 36: .Dt SU 1
! 37: .Os
! 38: .Sh NAME
! 39: .Nm su
! 40: .Nd substitute user identity
! 41: .Sh SYNOPSIS
! 42: .Nm su
! 43: .Op Fl Kflm
! 44: .Op Ar login Op Ar "shell arguments"
! 45: .Sh DESCRIPTION
! 46: .Nm Su
! 47: requests the Kerberos password for
! 48: .Ar login
! 49: (or for
! 50: .Dq Ar login Ns .root ,
! 51: if no login is provided), and switches to
! 52: that user and group ID after obtaining a Kerberos ticket granting ticket.
! 53: A shell is then executed, and any additional
! 54: .Ar "shell arguments"
! 55: after the login name
! 56: are passed to the shell.
! 57: .Nm Su
! 58: will resort to the local password file to find the password for
! 59: .Ar login
! 60: if there is a Kerberos error.
! 61: If
! 62: .Nm su
! 63: is executed by root, no password is requested and a shell
! 64: with the appropriate user ID is executed; no additional Kerberos tickets
! 65: are obtained.
! 66: .Pp
! 67: Alternately, if the user enters the password "s/key", they will be
! 68: authenticated using the S/Key one-time password system as described in
! 69: .Xr skey 1 .
! 70: S/Key is a Trademark of Bellcore.
! 71: .Pp
! 72: By default, the environment is unmodified with the exception of
! 73: .Ev USER ,
! 74: .Ev HOME ,
! 75: and
! 76: .Ev SHELL .
! 77: .Ev HOME
! 78: and
! 79: .Ev SHELL
! 80: are set to the target login's default values.
! 81: .Ev USER
! 82: is set to the target login, unless the target login has a user ID of 0,
! 83: in which case it is unmodified.
! 84: The invoked shell is the target login's.
! 85: This is the traditional behavior of
! 86: .Nm su .
! 87: .Pp
! 88: The options are as follows:
! 89: .Bl -tag -width Ds
! 90: .It Fl K
! 91: Do not attempt to use Kerberos to authenticate the user.
! 92: .It Fl f
! 93: If the invoked shell is
! 94: .Xr csh 1 ,
! 95: this option prevents it from reading the
! 96: .Dq Pa .cshrc
! 97: file.
! 98: .It Fl l
! 99: Simulate a full login.
! 100: The environment is discarded except for
! 101: .Ev HOME ,
! 102: .Ev SHELL ,
! 103: .Ev PATH ,
! 104: .Ev TERM ,
! 105: and
! 106: .Ev USER .
! 107: .Ev HOME
! 108: and
! 109: .Ev SHELL
! 110: are modified as above.
! 111: .Ev USER
! 112: is set to the target login.
! 113: .Ev PATH
! 114: is set to
! 115: .Dq Pa /bin:/usr/bin .
! 116: .Ev TERM
! 117: is imported from your current environment.
! 118: The invoked shell is the target login's, and
! 119: .Nm su
! 120: will change directory to the target login's home directory.
! 121: .It Fl m
! 122: Leave the environment unmodified.
! 123: The invoked shell is your login shell, and no directory changes are made.
! 124: As a security precaution, if the target user's shell is a non-standard
! 125: shell (as defined by
! 126: .Xr getusershell 3 )
! 127: and the caller's real uid is
! 128: non-zero,
! 129: .Nm su
! 130: will fail.
! 131: .El
! 132: .Pp
! 133: The
! 134: .Fl l
! 135: and
! 136: .Fl m
! 137: options are mutually exclusive; the last one specified
! 138: overrides any previous ones.
! 139: .Pp
! 140: Only users in group 0 (normally
! 141: .Dq wheel )
! 142: can
! 143: .Nm su
! 144: to
! 145: .Dq root .
! 146: .Pp
! 147: By default (unless the prompt is reset by a startup file) the super-user
! 148: prompt is set to
! 149: .Dq Sy \&#
! 150: to remind one of its awesome power.
! 151: .Sh SEE ALSO
! 152: .Xr csh 1 ,
! 153: .Xr login 1 ,
! 154: .Xr sh 1 ,
! 155: .Xr skey 1 ,
! 156: .Xr kinit 1 ,
! 157: .Xr kerberos 1 ,
! 158: .Xr passwd 5 ,
! 159: .Xr group 5 ,
! 160: .Xr environ 7
! 161: .Sh ENVIRONMENT
! 162: Environment variables used by
! 163: .Nm su :
! 164: .Bl -tag -width HOME
! 165: .It Ev HOME
! 166: Default home directory of real user ID unless modified as
! 167: specified above.
! 168: .It Ev PATH
! 169: Default search path of real user ID unless modified as specified above.
! 170: .It Ev TERM
! 171: Provides terminal type which may be retained for the substituted
! 172: user ID.
! 173: .It Ev USER
! 174: The user ID is always the effective ID (the target user ID) after an
! 175: .Nm su
! 176: unless the user ID is 0 (root).
! 177: .El
! 178: .Sh HISTORY
! 179: A
! 180: .Nm
! 181: command appeared in
! 182: .At v7 .
! 183: The version described
! 184: here is an adaptation of the
! 185: .Tn MIT
! 186: Athena Kerberos command.