.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "vpopmail 3pm"
.TH vpopmail 3pm "2010-04-11" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::vpopmail \- Utility to get information about vpopmail managed email addresses
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Mail::vpopmail;
\&
\&    my $vchkpw = Mail::vpopmail\->new();
\&
\&    my $vchkpw = Mail::vpopmail\->new(cache       => 1,
\&                                     debug       => 0,
\&                                     vpopuser    => \*(Aqvpopmail\*(Aq,
\&                                     auth_module => \*(Aqcdb\*(Aq,
\&                                     dsn         => \*(AqDBI:mysql:host=localhost;database=vpopmail\*(Aq,
\&                                     dbun        => \*(Aqvpopmailuser\*(Aq,
\&                                     dbpw        => \*(Aqvpoppasswd\*(Aq,
\&                                    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Mail::vpopmail\*(C'\fR provides serveral functions for interacting with
vpopmail.  This module can be useful especially when hashing is turned
on, as you can not predict the location of the domain's nor the 
mailbox's directories.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new( [\s-1OPTIONS\s0] );" 4
.IX Item "new( [OPTIONS] );"
\&\f(CW\*(C`OPTIONS\*(C'\fR are passed in a hash like fashion, using key and value
pairs.  Possible options are:
.Sp
\&\fBcache\fR \- Cache results of queries (0=Off, 1=On).  Default=On.
.Sp
\&\fBdebug\fR \- Print debugging info to \s-1STDERR\s0 (0=Off, 1=On).  Default=On.
.Sp
\&\fBvpopuser\fR \- Specify vpopmail user.  Default=vpopmail
.Sp
\&\fBauth_module\fR \- cdb or sql.  Default=cdb, but
                    Default=sql if ~vpopmail/etc/vpopmail.mysql exists.
.Sp
\&\fBdsn\fR \- \s-1SQL DSN.\s0  Default='DBI:mysql:host=localhost;database=vpopmail'
         Autogenerated if ~vpopmail/etc/vpopmail.mysql exists.
.Sp
\&\fBdbun\fR \- \s-1SQL\s0 Username.  Default=vpopmailuser.
          Autogenerated if ~vpopmail/etc/vpopmail.mysql exists.
.Sp
\&\fBdbpw\fR \- \s-1SQL\s0 Password.  Default=vpoppasswd.
          Autogenerated if ~vpopmail/etc/vpopmail.mysql exists.
.ie n .IP "userinfo( email => $email, field => <fields> );" 4
.el .IP "userinfo( email => \f(CW$email\fR, field => <fields> );" 4
.IX Item "userinfo( email => $email, field => <fields> );"
\&\fBemail\fR \- the email address to get properties on
.Sp
\&\fBfield\fR \- the field(s) to be returned (may be comma separated):
.Sp
.Vb 1
\&    dir \- return this domain\*(Aqs vpopmail domains directory
\&
\&    crypt \- return the encrypted password
\&
\&    uid \- return the uid
\&
\&    gid \- return the gid
\&
\&    comment \- return the comment, if available
\&
\&    maildir \- return this user\*(Aqs maildir
\&    
\&    quota \- return the quota (you have to parse this yourself)
\&
\&    plain \- return the plain text password, if available
.Ve
.ie n .IP "domaininfo( domain => $domain, field => <field> );" 4
.el .IP "domaininfo( domain => \f(CW$domain\fR, field => <field> );" 4
.IX Item "domaininfo( domain => $domain, field => <field> );"
\&\fBdomain\fR \- the domain to get properties on
.Sp
\&\fBfield\fR \- the field to be returned:
.Sp
.Vb 1
\&   dir \- return the vpopmail domain directory
\&
\&   mailboxes \- return an array reference containing all the mailboxes
\&
\&   all \- return an array ref of hash refs of all data for the domain
.Ve
.IP "alldomains( field => <field> );" 4
.IX Item "alldomains( field => <field> );"
\&\fBfield\fR \- the field to be returned:
.Sp
.Vb 1
\&   name \- returns an array reference of the names of all domains
\&
\&   dir \- returns an array refrence of all domain directories
\&
\&   map \- returns a hash reference of domain name \-> domain directory
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 2
\&    use strict;
\&    use Mail::vpopmail;
\&
\&    my $vchkpw = Mail::vpopmail\->new(cache=>1, debug=>0);
\&
\&
\&    # find all domains
\&    my $domains_aref = $vchkpw\->alldomains(field => \*(Aqname\*(Aq);
\&    foreach my $domain (@${domains_aref}){
\&        print "$domain\en";
\&    }
\&
\&    # find all domains directories
\&    my $dirlist_aref = $vchkpw\->alldomains(field => \*(Aqdir\*(Aq);
\&    foreach my $dir (@${dirlist_aref}){
\&        print "$dir\en";
\&    }
\&
\&    # find all domains and their directories
\&    my $alllist_aref = $vchkpw\->alldomains(field => \*(Aqmap\*(Aq);
\&    foreach my $href (@${alllist_aref}){
\&        print "$href\->{name} => $href\->{dir}\en";
\&    }
\&
\&    my $domain = shift;
\&    unless(defined($domain)){
\&        print "enter domain: ";
\&        chop($domain=<STDIN>);
\&    }
\&
\&
\&    # find all mailboxes in a given domain
\&    my $mailboxes_aref = $vchkpw\->domaininfo(domain => $domain, field => \*(Aqmailboxes\*(Aq);
\&    foreach my $mailbox (@{$mailboxes_aref}){
\&        print "found mailbox: $mailbox for domain: $domain\en";
\&    }
\&
\&    # find all properties for a given domain
\&    my $alldata_aref = $vchkpw\->domaininfo(domain => $domain, field => \*(Aqall\*(Aq);
\&    foreach my $href (@{$alldata_aref}){
\&        print "found data for $domain:\en";
\&        while(my($key,$value) = each %{$href}){
\&            print " found $key => $value\en";
\&        }
\&    }
\&
\&    # individual user stuff
\&    my $email = shift;
\&    unless(defined($email)){
\&        print "email address: ";
\&        chop($email=<STDIN>);
\&    }
\&
\&    my $dir = $vchkpw\->userinfo(email => $email, field => \*(Aqdir\*(Aq);
\&    print "dir: $dir\en";
\&    my ($crypt,$uid,$gid) = $vchkpw\->userinfo(email => $email, field => \*(Aqcrypt,uid,gid\*(Aq);
\&    print "crypt/uid/gid: $crypt/$uid/$gid\en";
\&    my $comment = $vchkpw\->userinfo(email => $email, field => \*(Aqcomment\*(Aq);
\&    print "comment: $comment\en";
\&    my $maildir = $vchkpw\->userinfo(email => $email, field => \*(Aqmaildir\*(Aq);
\&    print "maildir: $maildir\en";
\&    my $quota = $vchkpw\->userinfo(email => $email, field => \*(Aqquota\*(Aq);
\&    print "quota: $quota\en";
\&    my $plain = $vchkpw\->userinfo(email => $email, field => \*(Aqplain\*(Aq);
\&    print "plain: $plain\en";
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
This version is the first that supports \s-1SQL\s0 auth modules.  It is not
tested and should be used with caution.  Feedback needed.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeremy Kister \- http://jeremy.kister.net/
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 107:" 4
.IX Item "Around line 107:"
You forgot a '=back' before '=head1'