1USERHELPER(8) System Manager's Manual USERHELPER(8)
2
6 userhelper - A helper interface to PAM.
7
9 userhelper [ -t ] [ -w prog args ] [ -c ] [ -f full-name ]
10 [ -o office ] [ -p office-phone ] [ -h home-phone ] [ -s shell ]
11 [ username ]
12
15 NOTE this program is NOT intended to be run interactively. If you want
16 to change this information on the command line use passwd(1), chfn(1),
17 or chsh(1).
18 This program provides a basic interface to change a user's password,
20 gecos information, and shell. The main difference between this program
21 and its traditional equivalents is that prompts are written to standard
22 out to make it easy for a GUI wrapper to interface to it as a child
23 process.
24 The output is in the form of:
26 <number> <string>
28 Where the number is the type of prompt returned from libpam, and the
30 string is the prompt to give the user.
31 The prompt numbers are as follows:
33 1 Prompt with visible input.
35 2 Prompt with invisible input.
37 3 Suggested answer for the current prompt.
39 4 Informational message.
41 5 Error message.
43 6 Count of messages sent in this block so far.
45 7 The name of the service being used.
47 8 Whether or not the command will be executed as the user if
49 authentication fails.
50 9 The name of the user being authenticated.
52
55 -t Use text mode authentication instead of the numbered message
56 types just described; only used with -w.
57 -w Specify a program name to be run and arguments to be passed to
59 it. userhelper will look in the file /etc/security/con‐
60 sole.apps/programname for the name of a user to authenticate,
61 the path of the binary to be run, and other settings described
62 below. userhelper will then attempt to authenticate the user
63 using PAM, specifying programname as the PAM service name. If
64 authentication succeeds, the binary will be run with superuser
65 privileges. If the configuration file specifies that PAM ses‐
66 sion management should be performed, userhelper will also open a
67 PAM session before starting the program, and close the session
68 when the program terminates. If authentication fails, user‐
69 helper can be configured run the program with the user's privi‐
70 leges instead.
71 -c Change the current user's password. Note that this option can‐
73 not be used with any of the other options. This is due to the
74 limitation in the interface to libpam.
75 -f Specify a new Full Name.
77 -o Specify a new Office.
79 -p Specify a new Office Phone.
81 -h Specify a new Home Phone.
83 -s Specify a new shell.
85
87 The wrapper configuration file used with -w contains variable assign‐
88 ments and file inclusions.
89 A file inclusion line has the following form:
91 . path
92 (that is a dot and a space, followed by path). If path is relative, it
93 is interpreted relative to the directory containing the current file.
94 The file inclusion line is interpreted by inserting contents of path to
95 the current file. Nested file inclusions are possible, recursive file
96 inclusion results in undefined behavior.
97 A variable assignment line has the following form:
99 name=value
100 No additional white space is allowed. If value is surrounded by a
101 matching pair of " or ' quotes, the quotes are removed; otherwise, the
102 \ characters are removed, except that \\ is replaced by a single \.
103 The following variables are recognized:
105 USER The name of the user userhelper should attempt to authenticate
107 the invoking user as. Typically this is root. The special
108 value <user> (which is also the default) indicates that user‐
109 helper should authenticate the invoking user.
110 The special value <none> indicates that access should be denied;
112 when used in conjunction with UGROUPS, members of the given
113 groups can authenticate but all others are given an Insufficient
114 Rights message.
115 UGROUPS
117 A comma-separated list of groups whose members will be authenti‐
118 cated as if USER were set to the special value <user>. If the
119 invoking user is not a member of one of these groups, the name
120 defined in USER will be used as normal. For example, setting
121 UGROUPS to wheel and USER to root allows members of wheel (tra‐
122 ditionally used for administrative privileges) to authenticate
123 with their own credentials and requires other users to provide
124 the root password.
125 PROGRAM
127 The name of the binary to execute if authentication succeeds.
128 This should always be specified as an absolute path. If not
129 specified, userhelper will attempt to run /sbin/programname
130 first, and failing that, it will attempt to run /usr/sbin/pro‐
131 gramname.
132 SESSION
134 Specifies whether or not userhelper should perform PAM session
135 management when running the program. Typically this is needed
136 if the PAM configuration uses a module such as pam_xauth.so to
137 forward X11 authentication tokens for use by the program. Valid
138 values are yes and no, with the default being no.
139 KEEP_ENV_VARS
141 A comma-separated list of names of environment variables that
142 should be kept in the environment of the wrapped program. The
143 environment is cleared by default and only a few selected vari‐
144 ables are kept in the environment if they do not contain any
145 potentially dangerous substrings.
146 RETRY Specifies the number of times userhelper should attempt to
148 authenticate the user if the initial attempt fails. The default
149 value is 2, which causes userhelper to attempt to authenticate
150 the user a total of 3 times.
151 FALLBACK
153 Specifies whether or not the specified binary should be run with
154 the invoking user's privileges if authentication fails. This
155 option is useful for running applications which gain additional
156 abilities when run with superuser privileges, but which are
157 still useful when run without them.
158 NOXOPTION
160 The name of an option which, if passed to userhelper as an argu‐
161 ment for the program it will run, will cause userhelper to
162 behave as if the -t flag had been passed to it.
163 GUI Specifies whether or not userhelper should use consolehelper to
165 present graphical dialog boxes when prompting the user for
166 information. This is the inverse of the -t option. Valid val‐
167 ues are yes and no, with the default being yes.
168 BANNER Specifies specific text which userhelper should present to the
170 user when userhelper prompts for information. The default is a
171 generic message based on the PAM service name.
172 BANNER_DOMAIN
174 Specifies the text domain in which translations of the banner
175 are stored. This setting is deprecated in favor of the DOMAIN
176 setting.
177 DOMAIN Specifies the text domain in which translations of strings are
179 stored. If this setting is specified, it overrides any setting
180 for BANNER_DOMAIN which may also be set.
181 STARTUP_NOTIFICATION_NAME
183 Specifies the startup notification name used for startup notifi‐
184 cation.
185 STARTUP_NOTIFICATION_DESCRIPTION
187 Specifies the startup notification name used for startup notifi‐
188 cation.
189 STARTUP_NOTIFICATION_WORKSPACE
191 Specifies the startup notification workspace used for startup
192 notification.
193 STARTUP_NOTIFICATION_WMCLASS
195 Specifies the startup notification binary wmclass used for
196 startup notification.
197 STARTUP_NOTIFICATION_BINARY_NAME
199 Specifies the startup notification binary name used for startup
200 notification.
201 STARTUP_NOTIFICATION_ICON_NAME
203 Specifies the startup notification icon name used for startup
204 notification.
205
208 A non-zero exit status indicates an error occurred. Those errors are:
209 1 The authentication passwords was incorrect.
211 2 One or more of the GECOS fields is invalid. This occurs when
213 there is a colon supplied in one of the fields.
214 3 Password resetting error.
216 4 Some system files are locked.
218 5 User unknown.
220 6 Insufficient rights.
222 7 Invalid call to this program.
224 8 The shell provided is not valid (i.e., does not exist in
226 /etc/shells).
227 9 Ran out of memory.
229 10 Could not find the program.
231 11 Executing the program failed even though it exists.
233 12 The user canceled the operation.
235 255 Unknown error.
237
239 /etc/passwd The gecos and shell information is stored in
240 this file.
241 /etc/shells This file is checked to see if the new shell
243 supplied is valid.
244 /etc/security/console.apps/prog
246 This file contains the values which will be
247 used for the variables when userhelper is used
248 with the -w flag.
249 /etc/pam.d/prog This file contains the PAM configuration used
251 when userhelper is used with the -w flag.
252
254 userpasswd(1), userinfo(1), consolehelper(8), chfn(1), chsh(1),
255 passwd(5)
256
258 Otto Hammersmith <otto@redhat.com>
259 Michael K. Johnson <johnsonm@redhat.com>
260Red Hat, Inc. January 8 2008 USERHELPER(8)