NAME

News::Collabra - Access to Collabra administrative functions

SYNOPSIS

  use News::Collabra;

  # Create an administrator object
  my $admin = new News::Collabra('username', 'password',
        'myhost.mydomain.com', 'myhost', '1234');

  # Administrate newsgroups
  my $result = $admin->add_newsgroup('junk.test',
        'Testing newsgroup', 'A newsgroup for testing Collabra.pm');
  my $result = $admin->remove_newsgroup('junk.test');
  my $result = $admin->delete_all_articles('junk.test');
  my $result = $admin->get_ng_acls('junk.test');
  my $result = $admin->add_ng_acl('junk.test', 'nbailey', 'manager');
  my $result = $admin->get_properties('junk.test');
  my $result = $admin->set_properties('junk.test',
        'Post your tests here!', 'A test group for FL&T');

  # Administrate the server
  my $result = $admin->server_start;
  my $result = $admin->server_status;
  my $result = $admin->server_stop;

DESCRIPTION

This module provides an incomplete but growing implementation of a Collabra admin interface. Collabra administrative functions are based on HTTP, not NNTP, so most of these functions use LWP::UserAgent, rather than News::NNTP/News::NNTPClient.

For the uninitiated, Collabra is iPlanet's hacked over version of inews, with LDAP-based access control. Unfortunately, this otherwise fairly good idea is clouded by a crufty JavaScript interface. This module is intended to provide direct access to the functions, to save administrators the pain of the JavaScript interface.

new($username, $password, $host, $alias, $port)

Creates a News::Collabra object given the necessary details. This method does not currently test that the username/password combination is valid, but it may soon. Watch this space.

add_newsgroup($ngname, $prettyname, $description)

Create a new newsgroup on a Collabra news server.

remove_newsgroup($ngname)

Remove an existing newsgroup on a Collabra news server.

delete_all_articles($ngname)

Delete all articles in the specified newsgroup (untested as a yet).

get_ng_acls($ngname)

Get the ACLs for the specified newsgroup.

add_ng_acl($ngname,$users,$groups,$role)

Add a new ACL to the specified newsgroup.

get_properties($ngname)

Get the display properties for the specified newsgroup.

set_properties($ngname,$pretty_name,$description)

Set the display properties for the specified newsgroup.

_is_server_port_listening

A fundamental check for the server, used by server_status -- if we can't run a command, is the server listening at all? If this fails, manual action is required to start the admin server (i.e. the command line scripts to start the HTTP admin server -- look for a file called 'start-admin' in your server installation directory).

server_start

Start the Collabra newsserver instance. Returns 1 on success, 0 if the server was already running (no other error states have been observed).

server_status

Returns status information about the Collabra newsserver instance (in HTML -- grep for '<b>not</b>' if you want an off/on indicator).

server_stop

Start the Collabra newsserver instance. Returns 1 on success, 0 if the server was already stopped (no other error states have been observed).

BUGS

This module has only been tested on a newsserver with the local (ie. supplied with Collabra) directory. Reports on servers with full directory servers would be appreciated! Also, the test server only had one newsserver instance. Tests with multiple newsservers on the one admin server or multiple newsservers on different servers would also be appreciated.

Some return values aren't particularly meaningful at the moment.

AUTHOR

Nathan Bailey, <nate@cpan.org>

COPYRIGHT

Copyright 1999-2002 Nathan Bailey. All rights reserved. This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.