1USERHELPER(8)               System Manager's Manual              USERHELPER(8)
2
3
4

NAME

6       userhelper - A helper interface to PAM.
7

SYNOPSIS

9       userhelper     [ -t ]    [ -w prog args ]    [ -c ]    [ -f full-name ]
10       [ -o office ]   [ -p office-phone ]   [ -h home-phone ]    [ -s shell ]
11       [ username ]
12
13

DESCRIPTION

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
19       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
25       The output is in the form of:
26
27       <number> <string>
28
29       Where  the  number  is the type of prompt returned from libpam, and the
30       string is the prompt to give the user.
31
32       The prompt numbers are as follows:
33
34       1      Prompt with visible input.
35
36       2      Prompt with invisible input.
37
38       3      Suggested answer for the current prompt.
39
40       4      Informational message.
41
42       5      Error message.
43
44       6      Count of messages sent in this block so far.
45
46       7      The name of the service being used.
47
48       8      Whether or not the command will  be  executed  as  the  user  if
49              authentication fails.
50
51       9      The name of the user being authenticated.
52
53

OPTIONS

55       -t     Use  text  mode  authentication  instead of the numbered message
56              types just described; only used with -w.
57
58       -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
72       -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
76       -f     Specify a new Full Name.
77
78       -o     Specify a new Office.
79
80       -p     Specify a new Office Phone.
81
82       -h     Specify a new Home Phone.
83
84       -s     Specify a new shell.
85

WRAPPER CONFIGURATION

87       The wrapper configuration file used with -w contains  variable  assign‐
88       ments and file inclusions.
89
90       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
98       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
104       The following variables are recognized:
105
106       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
111              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
116       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
126       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
133       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
140       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
147       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
152       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
159       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
164       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
169       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
173       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
178       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
182       STARTUP_NOTIFICATION_NAME
183              Specifies the startup notification name used for startup notifi‐
184              cation.
185
186       STARTUP_NOTIFICATION_DESCRIPTION
187              Specifies the startup notification name used for startup notifi‐
188              cation.
189
190       STARTUP_NOTIFICATION_WORKSPACE
191              Specifies the startup notification workspace  used  for  startup
192              notification.
193
194       STARTUP_NOTIFICATION_WMCLASS
195              Specifies  the  startup  notification  binary  wmclass  used for
196              startup notification.
197
198       STARTUP_NOTIFICATION_BINARY_NAME
199              Specifies the startup notification binary name used for  startup
200              notification.
201
202       STARTUP_NOTIFICATION_ICON_NAME
203              Specifies  the  startup  notification icon name used for startup
204              notification.
205
206

EXIT STATUS

208       A non-zero exit status indicates an error occurred.  Those errors are:
209
210       1      The authentication passwords was incorrect.
211
212       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
215       3      Password resetting error.
216
217       4      Some system files are locked.
218
219       5      User unknown.
220
221       6      Insufficient rights.
222
223       7      Invalid call to this program.
224
225       8      The  shell  provided  is  not  valid  (i.e.,  does  not exist in
226              /etc/shells).
227
228       9      Ran out of memory.
229
230       10     Could not find the program.
231
232       11     Executing the program failed even though it exists.
233
234       12     The user canceled the operation.
235
236       255    Unknown error.
237

FILES

239       /etc/passwd              The gecos and shell information is  stored  in
240                                this file.
241
242       /etc/shells              This  file  is checked to see if the new shell
243                                supplied is valid.
244
245       /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
250       /etc/pam.d/prog          This file contains the PAM configuration  used
251                                when userhelper is used with the -w flag.
252

SEE ALSO

254       userpasswd(1),   userinfo(1),   consolehelper(8),   chfn(1),   chsh(1),
255       passwd(5)
256

AUTHOR

258       Otto Hammersmith <otto@redhat.com>
259       Michael K. Johnson <johnsonm@redhat.com>
260
261
262
263Red Hat, Inc.                   January 8 2008                   USERHELPER(8)
Impressum