Man Linux: Main Page and Category List


       userhelper - A helper interface to PAM.


       userhelper     [ -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(1),  chfn(1),
       or chsh(1).

       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

       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:

       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.


       -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/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.

       -c     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.

       -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.


       The  wrapper  configuration  file  used  with  -w   contains   variable
       assignments and file inclusions.

       A file inclusion line has the following form:
              . path
       (that is a dot and a space, followed by path).  If path is relative, it
       is interpreted relative to the directory containing the  current  file.
       The file inclusion line is interpreted by inserting contents of path 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 " or ’ quotes, the quotes are removed; otherwise,  the
       \ characters are removed, except that \\ is replaced by a single \.

       The following variables are recognized:

       USER   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 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

              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  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.

       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.

              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.

       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
              values 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.

              Specifies the text domain in which translations  of  the  banner
              are  stored.   This setting is deprecated in favor of the DOMAIN

       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.

              Specifies  the  startup  notification  name  used  for   startup

              Specifies   the  startup  notification  name  used  for  startup

              Specifies the startup notification workspace  used  for  startup

              Specifies  the  startup  notification  binary  wmclass  used for
              startup notification.

              Specifies the startup notification binary name used for  startup

              Specifies  the  startup  notification icon name used for startup


       A non-zero exit status indicates an error occurred.  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      Insufficient rights.

       7      Invalid call to this program.

       8      The  shell  provided  is  not  valid  (i.e.,  does  not exist in

       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.


       /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.

                                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.


       userpasswd(1),   userinfo(1),   consolehelper(8),   chfn(1),   chsh(1),


       Otto Hammersmith <>
       Michael K. Johnson <>