INSTALLATION

Use the following to install this module:

    shell$ perl Makefile.PL
    shell$ make
    shell$ make test
    shell# make install
    

NAME

Qmail::Control - Perl extension for interfacing with Qmail's control files.

DESCRIPTION

Qmail::Control provides an interface for reliably modifying Qmail's control files from your Perl programs. It only provides an object oriented interface.

SYNOPSIS

  use Qmail::Control;

  my $control = Qmail::Control->new();

  # Get a shared lock on the control system.  This is important, because
  # when we're making decisions based on the return values of multiple
  # methods, we don't want to be fooled by a race condition.
  my $lock = $control->lock('shared');

  # Print all hosts which we accept mail for.
  my @rcpthosts = $control->get_rcpthosts();
  foreach (@rcpthosts) {
    print "Found a rcpthost for $_->{'host'}.";
    }

  # Print the list of virtual domains.
  my @virtualdomains = $control->get_virtualdomains();
  foreach (@virtualdomains) {
    print "Found a vdom for $_->{'domain'}, user is $_->{'user'}.";
    }

  # Get our default domain name.
  my $defaultdomain = $control->defaultdomain();

  # Now, we're going to start changing things in the system.  We must
  # get an exclusive lock before we do.
  $control->relock($lock, 'exclusive');

  # Add a rcpthost.
  # Multiple hash references are legal.
  $control->add_rcpthosts( {host => 'domain2.com'} );

  # Add a virtualdomain entry.
  # Multiple hash references are legal.
  $control->add_virtualdomain({
    domain => 'domain2.com',
    user   => 'domain2systemaccount',
    }); 

  # Set our default domain name.
  # Also, this works with defaulthost, and me.
  # Setting this to undef for any control file (except 'me', which is
  # required) will delete that file.  Use '' to clear out a file.
  $control->defaultdomain({ set => 'domain.com' }); 
 
  $control->unlock($lock);

METHODS

Qmail::Control->new()

Creates a new Qmail::Control object.

Returns a reference to the newly created object.

Takes no arguments, currently. This may change, but the argumentless form will always exist.

$control->lock();

Locks the Qmail control file subsystem. Note that currently, only Qmail::Control itself uses this locking system, and that it is entirely advisory. You should always lock the control file system before getting information from more than one Qmail control file.

Returns a Qmail::Control::Lock object. You must keep track of this.

Takes a single argument, either 'shared' or 'exclusive'. The Qmail::Control::Lock object that is returned will be locked in the way specified. If no argument is given, the lock object returned will not be locked at all!

It's ok to use the relock() and unlock() methods provided by the lock object.

$control->get_rcpthosts();

Gets the list of hosts the system is set to accept mail for.

Returns a list of strings, each corresponding to a host that the system accepts mail for. If an error occurs, a list will be returned in which the first element is undef, the second element is a numeric error code, and the third argument is a detailed text explaining the error.

Takes no arguments at the current time.

The numeric error code is 0 for a system error or 1 for a control file syntax error.

$control->get_virtualdomains();

Gets the list of virtualdomains on this system, and the user associated with each.

Returns a list, each element representing one virtual domain. Each element is also a hash reference, with the keys 'domain' and 'user'. It can also return an error code, like the one for get_rcpthosts().

Takes no arguments.

AUTHOR

Paul Prince, <princep@charter.net>

SEE ALSO

perl. Qmail::Control::Lock.