Section: Maintenance Commands (8)
Updated: January 8 2008
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
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.
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 authentication fails.
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
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
is relative, it is interpreted relative to the directory containing the current
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.
is surrounded by a matching pair of
quotes, the quotes are removed;
characters are removed, except that
is 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
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 message.
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/programname.
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 substrings.
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.
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 them.
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
which may also be set.
Specifies the startup notification name used for startup notification.
Specifies the startup notification name used for startup notification.
Specifies the startup notification workspace used for startup notification.
Specifies the startup notification binary wmclass used for startup notification.
Specifies the startup notification binary name used for startup notification.
Specifies the startup notification icon name used for startup notification.
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.
Invalid call to this program.
The shell provided is not valid (i.e., does not exist in /etc/shells).
Ran out of memory.
Could not find the program.
Executing the program failed even though it exists.
The user canceled the operation.
The gecos and shell information is stored in this file.
This file is checked to see if the new shell supplied is valid.
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 <email@example.com
Michael K. Johnson <firstname.lastname@example.org