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