Learn the UNIX/Linux command line
Home Man Pages
USERHELPER(8) USERHELPER(8)
NAME
userhelper - A helper interface to pam.
SYNOPSIS
userhelper [ -t ] [ -w prog args ] [ -c ] [ -f full-name ]
[ -o office ] [ -p office-phone ] [ -h home-phone ] [ -s shell ]
[ username ]
DESCRIPTION
NOTE this program is NOT intended to be run interactively. If you
want to change this information on the command line use passwd(1),
chfn(1), or chsh(1).
This program provides a basic interface to change a user's password,
gecos information, and shell. The main differnce between this program
and its traditional equivilents is that prompts are written to stan-
dard out to make it easy for a GUI wrapper to interface to it as a
child process.
The output is in the form of:
Where the number is the type of prompt returned from pamlib, and the
string is the prompt to give the user.
The prompt numbers are as follows:
1 Prompt with visible input.
2 Prompt with invisible input.
3 Suggested answer for the current prompt.
4 Informational message.
5 Error message.
6 Count of messages sent in this block so far.
7 The name of the service being used.
8 Whether or not the command will be executed as the user if
authentication fails.
9 The name of the user being authenticated.
OPTIONS
-t Use text mode authentication instead of the numbered message
types just described; only used with -w.
-w Specify a program name to be run and arguments to be passed to
it. userhelper will look in the file /etc/security/con-
sole.apps/programname for the name of a user to authenticate,
the path of the binary to be run, and other settings described
below. userhelper will then attempt to authenticate the user
using PAM, specifying programname as the PAM service name. If
authentication succeeds, the binary will be run with superuser
privileges. If the configuration file specifies that PAM ses-
sion management should be performed, userhelper will also open
a PAM session before starting the program, and close the ses-
sion when the program terminates. If authentication fails,
userhelper can be configured run the program with the user's
privileges instead.
-c Change the current user's password. Note that this option can-
not be used with any of the other options. This is due to the
limitation in the interface to pamlib.
-f Specify a new Full Name.
-o Specify a new Office.
-p Specify a new Office Phone.
-h Specify a new Home Phone.
-s Specify a new shell.
VARIABLES
USER The name of the user userhelper should attempt to authenticate
the invoking user as. Typically this is root. The special
value (which is also the default) indicates that user-
helper should authenticate the invoking user.
The special value indicates that access should be
denied; when used in conjunction with UGROUPS, members of the
given groups can authenticate but all others are given an
Insufficient Rights message.
UGROUPS
A comma-separated list of groups whose members will be authen-
ticated as if USER were set to the special value . If the
invoking user is not a member of one of these groups, the name
defined in USER will be used as normal. For example, setting
UGROUPS to wheel and USER to root allows members of wheel (tra-
ditionally used for administrative privileges) to authenticate
with their own credentials and requires other users to provide
the root password.
PROGRAM
The name of the binary to execute if authentication succeeds.
This should always be specified as an absolute path. If not
specified, userhelper will attempt to run /sbin/programname
first, and failing that, it will attempt to run /usr/sbin/pro-
gramname.
SESSION
Specifies whether or not userhelper should perform PAM session
management when running the program. Typically this is needed
if the PAM configuration uses a module such as pam_xauth.so to
forward X11 authentication tokens for use by the program.
Valid values are yes and no, with the default being no.
RETRY Specifies the number of times userhelper should attempt to
authenticate the user if the initial attempt fails. The
default value is 2, which causes userhelper to attempt to
authenticate the user a total of 3 times.
FALLBACK
Specifies whether or not the specified binary should be run
with the invoking user's privileges if authentication fails.
This option is useful for running applications which gain addi-
tional abilities when run with superuser privileges, but which
are still useful when run without them.
NOXOPTION
The name of an option which, if passed to userhelper as an
argument for the program it will run, will cause userhelper to
behave as if the -t flag had been passed to it.
GUI Specifies whether or not userhelper should use consolehelper to
present graphical dialog boxes when prompting the user for
information. This is the inverse of the -t option. Valid val-
ues are yes and no, with the default being yes.
BANNER Specifies specific text which userhelper should present to the
user when userhelper prompts for information. The default is a
generic message based on the PAM service name.
BANNER_DOMAIN
Specifies the text domain in which translations of the banner
are stored. This setting is deprecated in favor of the DOMAIN
setting.
DOMAIN Specifies the text domain in which translations of strings are
stored. If this setting is specified, it overrides any setting
for BANNER_DOMAIN which may also be set.
STARTUP_NOTIFICATION_NAME
Specifies the startup notification name used for startup noti-
fication.
STARTUP_NOTIFICATION_DESCRIPTION
Specifies the startup notification name used for startup noti-
fication.
STARTUP_NOTIFICATION_WORKSPACE
Specifies the startup notification workspace used for startup
notification.
STARTUP_NOTIFICATION_WMCLASS
Specifies the startup notification binary wmclass used for
startup notification.
STARTUP_NOTIFICATION_BINARY_NAME
Specifies the startup notification binary name used for startup
notification.
STARTUP_NOTIFICATION_ICON_NAME
Specifies the startup notification icon name used for startup
notification.
EXIT STATUS
A non-zero exit status indicates an error occured. Those errors are:
1 The authentication passwords was incorrect.
2 One or more of the GECOS fields is invalid. This occurs when
there is a colon supplied in one of the fields.
3 Password resetting error.
4 Some system files are locked.
5 User unknown.
6 Insufficent rights.
7 Invalid call to this program.
8 The shell provided is not valid (i.e., does not exist in
/etc/shells).
9 Ran out of memory.
10 Could not find the program.
11 exec failed even though program exists.
12 the user canceled the operation.
255 Unknown error.
FILES
/etc/passwd The gecos and shell information is stored in
this file.
/etc/shells This file is checked to see if the new shell
supplied is valid.
/etc/security/console.apps/prog
This file contains the values which will be
used for the variables when userhelper is
used with the -w flag.
/etc/pam.d/prog This file contains the PAM configuration used
when userhelper is used with the -w flag.
SEE ALSO
userpasswd(1), userinfo(1), consolehelper(8), chfn(1), chsh(1),
passwd(5)
AUTHOR
Otto Hammersmith
Michael K. Johnson
Red Hat, Inc. 18 February 2003 USERHELPER(8)
UNIX/Linux commands referenced on this page: