Users-Agent 1.2 INSTALL

OVERVIEW

    Users-Agent runs as a standalone process that connects to a Jabber
    server over TCP. It stores user data in a dedicated MySQL database.
    
    A running Users-Agent setup consists of three elements:
    
    * 'users-agent'     - Perl Script
    * 'config.xml'      - Configuration File
    * 'JUD'             - MySQL Database
    
    The 'users-agent' Perl script is the running program that provides
    the JUD service. The 'users-agent' script relies on the 'config.xml'
    file for configuration. The 'config.xml' file must be in the same
    path from which 'users-agent' is run, or the '-c' option must be
    used to specify the location of 'config-xml'. 'users-agent' stores
    all data in a MySQL database named 'JUD' by default.
    
INSTALLATION STEPS

    1)  Install the required Perl Modules:
    
            Net::Jabber v2.0
            DBI
        
        These modules are available at http://www.cpan.org.

    2)  Untar the Users-Agent package into the directory from which it
        will be run.    
        
    3)  Create the 'JUD' database. The Users-Agent package contains a
        script named 'createDB' that creates the MySQL 'JUD' database. 
        
        The 'createDB' script requires temporary access to a running
        MySQL database in order to connect and create the 'JUD'
        database. This access can be provided by temporarily disabling
        the root MySQL password:
        
            $ mysqladmin -u root -p password ""
            
        Alternately, the 'createDB' script can be edited so that it
        contains the root MySQL password. If the MySQL password is *not*
        disabled, the 'DBI_DRIVER' environment variable must be set to a
        value of 'dbi:mysql:test:localhost', where 'test' is a working
        MySQL database.
        
        Once the root password is disabled (or 'createDB' edited and
        'DBI_DRIVER' set), run 'createDB':
        
            $ ./createDB
            
        Reset your MySQL password ('mysqladmin -u root -p password
        "oldpassword"') if disabled above.
        
    4)  Set Permissions for 'JUD' database. If you have an existing 
        MySQL user that wish to use with Users-Agent, grant it 
        permissions to the 'JUD' database from the MySQL console (where 
        'someone' is your MySQL user):
        
            mysql> use JUD;
            mysql> GRANT ALL PRIVILEGES ON *.* 
                -> TO 'someone'@'localhost' WITH GRANT OPTION;
                
        If you wish to create a new MySQL user for Users-Agent, run this
        grant command (where 'someone' is the user to be created and
        'something' is the user password):
        
            mysql> use JUD;
            mysql> GRANT ALL PRIVILEGES ON *.* TO 'someone'@'localhost'
                -> IDENTIFIED BY 'something' WITH GRANT OPTION; 
                
    5)  Configure 'config.xml' for your installation. Make sure that
        values for these elements match your installation:
    
            <hostname>
            <port>
            <secret>
            <name>
            <username>
            <password>
            
        hostname: Hostname of your Jabber server. 
        
        port: Port that your Jabber server listens for connections to
        Users-Agent. For Jabber 1.4x servers, this port is set in the
        'service' section of the main configuration file (step 6). For
        Jabberd 2x servers, this is the port that the 'router' component
        listens on (default is 5347).
        
        secret: Shared secret that the Jabber server uses to
        authenticate the Users-Agent. For Jabber 1.4x servers, this will
        be the 'secret' in the 'service' section for this component
        (step 6). For Jabber 2x servers, this secret is contained in
        'router.xml'.
        
        name: Hostname for the Users-Agent.  This name must be
        resolvable by clients that will use Users-Agent.
        
        username: MySQL user name for connections to the 'JUD' database.
        This should be the 'someone' user created or used in step 4.
        
        password: MySQL user password.  This should be the password for
        the 'username' above.
        
    6)  Configure your Jabber server.

        Jabber 1.4x servers: Create a 'service' section similar to this
        in the main Jabber configuration file:
        
            <service id="users.jabber.server">
              <accept>
                <ip/>
                <port>5226</port>
                <secret>foobar</secret>
              </accept>
            </service>     
        
        Where:  'id' is set to the 'name' used in step 5.
                'port' is set to the 'port' used in step 5.
                'secret' is set to the secret used in step 5. 
                
        Add a 'browse' section similar to this in the 'browse' section:
        
            <service type="jud" jid="users.jabber.server" 
                     name="Jabber User Directory"/>
            
        Where: 'jid' is set to the 'name' used in step 5.            

        Jabber 2x servers: No additional configuration should be
        necessary.
        
    7)  Make sure your Jabber and MySQL servers are running and then
        start 'users-agent':
        
            $ ./users-agent
            
    8)  You should now be able to use a Jabber client to register to- 
        and search from your Users-Agent JUD.