NAME
    FS::UID - Subroutines for database login and assorted other
    stuff

SYNOPSIS
      use FS::UID qw(adminsuidsetup cgisuidsetup dbh datasrc getotaker
      checkeuid checkruid swapuid);

      adminsuidsetup $user;

      $cgi = new CGI;
      $dbh = cgisuidsetup($cgi);

      $dbh = dbh;

      $datasrc = datasrc;

DESCRIPTION
    Provides a hodgepodge of subroutines.

SUBROUTINES
    adminsuidsetup USER
        Sets the user to USER (see config.html from the base
        documentation). Cleans the environment. Make sure the script
        is running as freeside, or setuid freeside. Opens a
        connection to the database. Swaps real and effective UIDs.
        Runs any defined callbacks (see below). Returns the DBI
        database handle (usually you don't need this).

    cgisuidsetup CGI_object
        Stores the CGI (see the CGI manpage) object for later use.
        (CGI::Base is depriciated) Runs adminsuidsetup.

    cgi Returns the CGI (see the CGI manpage) object.

    dbh Returns the DBI database handle.

    datasrc
        Returns the DBI data source.

    getotaker
        Returns the current Freeside user.

    cgisetotaker
        Sets and returns the CGI REMOTE_USER. $cgi should be defined
        as a CGI.pm object. Support for CGI::Base and derived
        classes is depriciated.

    checkeuid
        Returns true if effective UID is that of the freeside user.

    checkruid
        Returns true if the real UID is that of the freeside user.

    swapuid
        Swaps real and effective UIDs.

    getsecrets [ USER ]
        Sets the user to USER, if supplied. Sets and returns the DBI
        datasource, username and password for this user from the
        `/usr/local/etc/freeside/mapsecrets' file.

CALLBACKS
    Warning: this interface is likely to change in future releases.

    A package can install a callback to be run in adminsuidsetup by
    putting a coderef into the hash %FS::UID::callback :

        $coderef = sub { warn "Hi, I'm returning your call!" };
        $FS::UID::callback{'Package::Name'};

BUGS
    Too many package-global variables.

    Not OO.

    No capabilities yet. When mod_perl and Authen::DBI are
    implemented, cgisuidsetup will go away as well.

    Goes through contortions to support non-OO syntax with multiple
    datasrc's.

    Callbacks are inelegant.

SEE ALSO
    the FS::Record manpage, the CGI manpage, the DBI manpage,
    config.html from the base documentation.

HISTORY
    ivan@voicenet.com 97-jun-4 - 9 untaint otaker ivan@voicenet.com
    97-jul-7

    generalize and auto-get uid (getotaker still needs to be db'ed)
    ivan@sisd.com 97-nov-10

    &cgisuidsetup logs into database. other cleaning. ivan@sisd.com
    97-nov-22,23

    &adminsuidsetup logs into database with otaker='freeside' (for
    automated tasks like billing) ivan@sisd.com 97-dec-13

    added sub datasrc for fs-setup ivan@sisd.com 98-feb-21

    datasrc, user and pass now come from conf/secrets ivan@sisd.com
    98-jun-28

    added ChopBlanks to DBI call (see man DBI) ivan@sisd.com 98-aug-
    16

    pod, use FS::Conf, implemented cgisuidsetup as adminsuidsetup,
    inlined suidsetup ivan@sisd.com 98-sep-12

    $Log: UID.txt,v $
    Revision 1.2  1998-11-13 09:56:37  ivan
    change configuration file layout to support multiple distinct databases (with
    own set of config files, export, etc.)
 Revision 1.3 1998/11/08 10:45:42 ivan got sub
    cgi for FS::CGI

    Revision 1.2 1998/11/08 09:38:43 ivan cgisuidsetup complains if
    you pass it a isa CGI::Base instead of an isa CGI (first step in
    migrating from CGI-modules to CGI.pm)