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 differnce between this program
21 and its traditional equivilents 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 pamlib, 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 pamlib.
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 USER The name of the user userhelper should attempt to authenticate
88 the invoking user as. Typically this is root. The special
89 value <user> (which is also the default) indicates that user‐
90 helper should authenticate the invoking user.
91 The special value <none> indicates that access should be denied;
93 when used in conjunction with UGROUPS, members of the given
94 groups can authenticate but all others are given an Insufficient
95 Rights message.
96 UGROUPS
98 A comma-separated list of groups whose members will be authenti‐
99 cated as if USER were set to the special value <user>. If the
100 invoking user is not a member of one of these groups, the name
101 defined in USER will be used as normal. For example, setting
102 UGROUPS to wheel and USER to root allows members of wheel (tra‐
103 ditionally used for administrative privileges) to authenticate
104 with their own credentials and requires other users to provide
105 the root password.
106 PROGRAM
108 The name of the binary to execute if authentication succeeds.
109 This should always be specified as an absolute path. If not
110 specified, userhelper will attempt to run /sbin/programname
111 first, and failing that, it will attempt to run /usr/sbin/pro‐
112 gramname.
113 SESSION
115 Specifies whether or not userhelper should perform PAM session
116 management when running the program. Typically this is needed
117 if the PAM configuration uses a module such as pam_xauth.so to
118 forward X11 authentication tokens for use by the program. Valid
119 values are yes and no, with the default being no.
120 KEEP_ENV_VARS
122 A comma-separated list of names of environment variables that
123 should be kept in the environment of the wrapped program. The
124 environment is cleard by default and only a few selected vari‐
125 ables are kept in the environment if they do not contain any
126 potentially dangerous substrings.
127 RETRY Specifies the number of times userhelper should attempt to
129 authenticate the user if the initial attempt fails. The default
130 value is 2, which causes userhelper to attempt to authenticate
131 the user a total of 3 times.
132 FALLBACK
134 Specifies whether or not the specified binary should be run with
135 the invoking user's privileges if authentication fails. This
136 option is useful for running applications which gain additional
137 abilities when run with superuser privileges, but which are
138 still useful when run without them.
139 NOXOPTION
141 The name of an option which, if passed to userhelper as an argu‐
142 ment for the program it will run, will cause userhelper to
143 behave as if the -t flag had been passed to it.
144 GUI Specifies whether or not userhelper should use consolehelper to
146 present graphical dialog boxes when prompting the user for
147 information. This is the inverse of the -t option. Valid val‐
148 ues are yes and no, with the default being yes.
149 BANNER Specifies specific text which userhelper should present to the
151 user when userhelper prompts for information. The default is a
152 generic message based on the PAM service name.
153 BANNER_DOMAIN
155 Specifies the text domain in which translations of the banner
156 are stored. This setting is deprecated in favor of the DOMAIN
157 setting.
158 DOMAIN Specifies the text domain in which translations of strings are
160 stored. If this setting is specified, it overrides any setting
161 for BANNER_DOMAIN which may also be set.
162 STARTUP_NOTIFICATION_NAME
164 Specifies the startup notification name used for startup notifi‐
165 cation.
166 STARTUP_NOTIFICATION_DESCRIPTION
168 Specifies the startup notification name used for startup notifi‐
169 cation.
170 STARTUP_NOTIFICATION_WORKSPACE
172 Specifies the startup notification workspace used for startup
173 notification.
174 STARTUP_NOTIFICATION_WMCLASS
176 Specifies the startup notification binary wmclass used for
177 startup notification.
178 STARTUP_NOTIFICATION_BINARY_NAME
180 Specifies the startup notification binary name used for startup
181 notification.
182 STARTUP_NOTIFICATION_ICON_NAME
184 Specifies the startup notification icon name used for startup
185 notification.
186
189 A non-zero exit status indicates an error occured. Those errors are:
190 1 The authentication passwords was incorrect.
192 2 One or more of the GECOS fields is invalid. This occurs when
194 there is a colon supplied in one of the fields.
195 3 Password resetting error.
197 4 Some system files are locked.
199 5 User unknown.
201 6 Insufficent rights.
203 7 Invalid call to this program.
205 8 The shell provided is not valid (i.e., does not exist in
207 /etc/shells).
208 9 Ran out of memory.
210 10 Could not find the program.
212 11 exec failed even though program exists.
214 12 the user canceled the operation.
216 255 Unknown error.
218
220 /etc/passwd The gecos and shell information is stored in
221 this file.
222 /etc/shells This file is checked to see if the new shell
224 supplied is valid.
225 /etc/security/console.apps/prog
227 This file contains the values which will be
228 used for the variables when userhelper is used
229 with the -w flag.
230 /etc/pam.d/prog This file contains the PAM configuration used
232 when userhelper is used with the -w flag.
233
235 userpasswd(1), userinfo(1), consolehelper(8), chfn(1), chsh(1),
236 passwd(5)
237
239 Otto Hammersmith <otto@redhat.com>
240 Michael K. Johnson <johnsonm@redhat.com>
241Red Hat, Inc. March 17 2007 USERHELPER(8)