userhelper - A helper interface to PAM.
[ -t ]
[ -w prog args ] [ -c ]
[ -f full-name ] [ -o office ]
[ -p office-phone ]
[ -h home-phone ] [ -s shell ]
[ username ]
NOTE this program is NOT intended to be run interactively. If you want to change
this information on the command line use passwd
This program provides a basic interface to change a user's password, gecos
information, and shell. The main difference between this program and its
traditional equivalents is that prompts are written to standard out to make it
easy for a GUI wrapper to interface to it as a child process.
The output is in the form of:
- <number> <string>
Where the number is the type of prompt returned from libpam, and the string is
the prompt to give the user.
The prompt numbers are as follows:
- Prompt with visible input.
- Prompt with invisible input.
- Suggested answer for the current prompt.
- Informational message.
- Error message.
- Count of messages sent in this block so far.
- The name of the service being used.
- Whether or not the command will be executed as the user if
- The name of the user being authenticated.
- Use text mode authentication instead of the numbered
message types just described; only used with -w.
- Specify a program name to be run and arguments to be passed
to it. userhelper will look in the file /etc/security/console.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 session management should be performed, userhelper will also open a
PAM session before starting the program, and close the session when the
program terminates. If authentication fails, userhelper can be configured
run the program with the user's privileges instead.
- Change the current user's password. Note that this option
cannot be used with any of the other options. This is due to the
limitation in the interface to libpam.
- Specify a new Full Name.
- Specify a new Office.
- Specify a new Office Phone.
- Specify a new Home Phone.
- Specify a new shell.
The wrapper configuration file used with -w
contains variable assignments
and file inclusions.
A file inclusion line has the following form:
(that is a dot and a space, followed by path
). If path
relative, it is interpreted relative to the directory containing the current
file. The file inclusion line is interpreted by inserting contents of
to the current file. Nested file inclusions are possible,
recursive file inclusion results in undefined behavior.
A variable assignment line has the following form:
No additional white space is allowed. If value
is surrounded by a
matching pair of "
quotes, the quotes are removed;
otherwise, the \
characters are removed, except that \\
replaced by a single \
The following variables are recognized:
- The name of the user userhelper should attempt to
authenticate the invoking user as. Typically this is root. The
special value <user> (which is also the default) indicates
that userhelper should authenticate the invoking user.
The special value <none> 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
- A comma-separated list of groups whose members will be
authenticated as if USER were set to the special value
<user>. 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 (traditionally used for administrative privileges) to
authenticate with their own credentials and requires other users to
provide the root password.
- 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/
- 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.
- A comma-separated list of names of environment variables
that should be kept in the environment of the wrapped program. The
environment is cleared by default and only a few selected variables are
kept in the environment if they do not contain any potentially dangerous
- 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
- 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 additional abilities when
run with superuser privileges, but which are still useful when run without
- 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.
- 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 values
are yes and no, with the default being yes.
- 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.
- Specifies the text domain in which translations of the
banner are stored. This setting is deprecated in favor of the
- 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.
- Specifies the startup notification name used for startup
- Specifies the startup notification name used for startup
- Specifies the startup notification workspace used for
- Specifies the startup notification binary wmclass used for
- Specifies the startup notification binary name used for
- Specifies the startup notification icon name used for
A non-zero exit status indicates an error occurred. Those errors are:
- The authentication passwords was incorrect.
- One or more of the GECOS fields is invalid. This occurs
when there is a colon supplied in one of the fields.
- Password resetting error.
- Some system files are locked.
- User unknown.
- Insufficient rights.
- Invalid call to this program.
- The shell provided is not valid (i.e., does not exist in
- Ran out of memory.
- Could not find the program.
- exec failed even though program exists.
- the user canceled the operation.
- Unknown error.
- The gecos and shell information is stored in this
- This file is checked to see if the new shell supplied is
- This file contains the values which will be used for the
variables when userhelper is used with the -w flag.
- This file contains the PAM configuration used when
userhelper is used with the -w flag.
Otto Hammersmith <firstname.lastname@example.org>
Michael K. Johnson <email@example.com>