chiark / gitweb /
changelog: Prep for Rebuild with arch:all packages included in the upload.
[chiark-utils.git] / cprogs / really.8
1 .TH really 8 2001-10-21 chiark-backup
2 .SH NAME
3 really \- gain privilege or run commands a different user
4 .SH SYNOPSIS
5 .B really
6 .RI [ options ]
7 .RI [ "command args... " ]
8 .SH DESCRIPTION
9 .B really
10 checks whether the caller is allowed, and if it is it changes its uids
11 and gids (and perhaps root directory) according to the command line
12 options and executes the specified command.
13 .PP
14 If no options are specified, the uid will be set to 0 and the gids
15 and root directory will be left unchanged.
16 .PP
17 If no command is specified,
18 .B really
19 will run
20 .BR "$SHELL -i" .
21 .PP
22 A caller is allowed if it has write access to
23 .BR /etc/inittab
24 and is also member of the group
25 .BR root .
26 This is most easily achieved by making inittab group-writeable by some
27 suitable group containing all the appropriate users, and making
28 .B /etc/inittab
29 group-owned by that group and group-writeable.  The root group is
30 perhaps a good choice if it isn't being used for anything else.
31 .SH OPTIONS
32 .TP
33 \fB-u\fR \fIusername\fR | \fB--user\fR \fIusername\fR
34 Sets the uid, gid, and supplementary group list, according to
35 .IR username 's
36 entry in the password and group databases.
37 .TP
38 \fB-i\fR \fIusername\fR | \fB--useronly\fR \fIusername\fR
39 Sets only the uid according to
40 .IR username 's
41 entry in the password database.
42 .TP
43 \fB-I\fR \fIuid\fR | \fB--uidonly\fR \fIuid\fR
44 Sets the uid to the numeric value
45 .I uid
46 (which need not correspond to any existing user in the password
47 database).
48 .TP
49 \fB-g\fR \fIgroupname\fR | \fB--group\fR \fIgroupname\fR
50 .I groupname
51 is looked up in the group database and its gid is appended to the
52 process's supplementary groups list.  If this is the first gid
53 specified it will also be set as the primary gid.
54 .TP
55 \fB-G\fR \fIgid\fR | \fB--gid\fR \fIgid\fR
56 .I gid
57 is appended to the process's supplementary groups list.
58 .RI ( gid
59 need not correspond to any existing group in the group database.)  If
60 this is the first gid specified it will also be set as the primary
61 gid.
62 .TP
63 \fB-z\fR | \fB--groupsclear\fR
64 Clears the process's supplementary groups list.  When using this
65 option you must also specify
66 .B -g
67 or
68 .BR -G .
69 The process's groups will then be exactly those specified.  The
70 relative position of
71 .B -z
72 in the argument list is not relevant.
73 .TP
74 \fB-R\fR \fIroot-dir\fR | \fB--chroot\fR \fIroot-dir\fR
75 The program will have its root directory set to
76 .IR root-dir .
77
78 .BR "Do not use this option unless you know what you are doing" :
79 Unlike chroot(8), the current working directory will remain unchanged.
80 This means that if the current directory isn't underneath the
81 specified new root, the program will still be able to access files
82 outside the new root by using relative pathnames.  If this isn't
83 what you want, please use the chroot utility instead.
84 .TP
85 .B \-\-
86 Indicates the end of the options.  The next argument (if present) will
87 be interpreted as the command name, even if it starts with a hyphen.
88 .SH SECURITY CONSIDERATIONS
89 .B really
90 is designed so that installing it setuid root is extremely unlikely to
91 compromise the security of any system.  It will check using
92 .BR access (2)
93 whether the real user is allowed to write to
94 .B /etc/inittab
95 and if this check fails
96 .B really
97 will exit without even attempting to parse its command line.
98 .PP
99 .B really
100 is
101 .B not
102 designed to be resistant to malicious command line arguments.  Do not
103 allow untrusted processes to pass options to really, or to specify the
104 command to be run.  Whether it is safe to allow relatively untrusted
105 processes to pass options to the command which is to be run depends on
106 the behaviour of that command and its security status.
107 .PP
108 Attempting to use
109 .B really
110 to drop privilege is dangerous unless the calling environment is very
111 well understood.  There are many inherited process properties and
112 resources which might be used by the callee to escalate its privilege
113 to that of the (root-equivalent) caller.  For this function, it is
114 usually better to use
115 .B userv
116 if possible.
117 .SH ENVIRONMENT
118 .B really
119 does not manipulate the environment at all.  The calling program is
120 run in exactly the same environment as the caller passes to
121 .BR really .
122 In particular,
123 .B really
124 will not add
125 .B sbin
126 directories to
127 .B PATH
128 so
129 .BR really -enabled
130 accounts will usually need to have these directories on their
131 configured
132 .B PATH
133 to start with.
134 .PP
135 .B SHELL
136 is used to find the default shell to use in interactive mode (ie, when
137 no command is specified).
138 .SH AUTHOR
139 This version of
140 .B really
141 was written by Ian Jackson <ian@chiark.greenend.org.uk>.
142 .PP
143 It and this manpage are Copyright (C) 1992-5,2004,2013 Ian Jackson
144 <ian@chiark.greenend.org.uk>.
145 .PP
146 .B really
147 is free software; you can redistribute it and/or modify
148 it under the terms of the GNU General Public License as
149 published by the Free Software Foundation; either version 3,
150 or (at your option) any later version.
151 .PP
152 .B really
153 is distributed in the hope that it will be useful, but
154 WITHOUT ANY WARRANTY; without even the implied warranty of
155 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
156 GNU General Public License for more details.
157 .PP
158 You should have received a copy of the GNU General Public
159 License along with this file; if not, consult the Free Software
160 Foundation's website at www.fsf.org, or the GNU Project website at
161 www.gnu.org.
162 .SH AVAILABILITY
163 .B really
164 is currently part of
165 .B chiark-utils
166 and is available for download from
167 ftp.chiark.greenend.org.uk in /users/ian/chiark-utils/,
168 in source and pre-compiled binary form, and also from Ian Jackson's
169 cvsweb.
170 .SH "SEE ALSO"
171 .BR userv (1),
172 .BR access (2),
173 .BR setresuid (2),
174 .BR setresgid (2),
175 .BR setgroups (2)