USERHELPER(8)                                                    USERHELPER(8)


       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 differnce between this  program
       and its traditional equivilents 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 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.


       -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 session
              when the program terminates.   If  authentication  fails,  user-
              helper  can be configured run the program with the user’s privi-
              leges 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.


       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  user-
              helper 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 authenti-
              cated  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  (tra-
              ditionally  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/pro-

              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.

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

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

              Specifies the startup notification name used for startup notifi-

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

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

Red Hat, Inc.                  18 February 2003                  USERHELPER(8)

Man(1) output converted with man2html