Changeset 577


Ignore:
Timestamp:
Feb 16, 2011, 12:07:45 AM (10 years ago)
Author:
zerodeux
Message:

Documented most BearMail::Backend API, had to change a few things in BearMail::Config - see #21 and see #22

Location:
bearmail
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • bearmail/conf/bearmail.conf

    r526 r577  
    66# backend - Choose where and how account configuration is stored
    77#
    8 # Files (path)
    9 #   Store mail account credentials in a plain text file ("mailmap").
     8# FlatFiles
     9#   Store mail account credentials in a plain text file ("mailmap"),
     10#   and various daemon configuration also as flat files (which might
     11#   be in turned hash into a Berkeley DB like Postfix does).
     12#
    1013#   Useful to handle a few thousand accounts with your favourite
    1114#   editor and VCS, adminsys and grep-friendly.
    1215#
    13 #   The 'path' argument is optional. The default path is
    14 #   /etc/bearmail/mailmap.
    15 #
    16 # SQL (DSN)
     16# SQL
    1717#   TODO
    1818#
     19# The backend configuration is specified in the [backend <name>] section.
     20#
    1921# Example:
    20 # backend = Files /var/lib/bearmail/mailmap
     22# backend = FlatFiles
    2123#
    22 backend = Files /etc/bearmail/mailmap
     24backend = FlatFiles
    2325
    2426
     
    3739
    3840
    39 #
    40 # Bearmail webui configuration
    41 #
    42 # These parameters affect the Bearmail webUI only.
    43 
    4441# template_path - Webui template path
    4542#
    4643template_path = /usr/share/bearmail/web/template
     44
     45
     46# TODO: document backend-specific parameters
     47
     48[backend FlatFiles]
     49mailmap = /etc/bearmail/mailmap
     50postfix = /etc/postfix
     51dovecot = /etc/dovecot
     52
     53[backend SQL]
     54db_host = localhost
     55db_name = bearmail
     56db_user = bearmail
     57db_pass = b34rm41l
     58
  • bearmail/lib/BearMail/Backend.pm

    r576 r577  
    1212    use BearMail::Backend;
    1313    use BearMail::Account;
    14    
     14
    1515    my $bb = BearMail::Backend->new();
    1616
     
    4646configure it.
    4747
    48 For instance C<BearMail::Backend::Files> can configure a Postfix+Dovecot setup
     48For instance C<BearMail::Backend::FlatFiles> can configure a Postfix+Dovecot setup
    4949with only the help of the filesystem. It works and scales very well up to
    5050a few thousands accounts, and is adminsys friendly (you can version control
     
    5454interface, you might prefer the C<BearMail::Backend::SQL> interface.
    5555
    56 TODO: describe accounts, targets, autorization model.
     56TODO: point to a POD describing how to setup a Postfix+Dovecot setup (depends
     57on backend). Mention that the job is done via packaging in Debian.
     58
     59=head2 Basic model
     60
     61C<BearMail::Backend> is based on a simple model: it assumes that the whole
     62configuration of your email platform is a list of C<BearMail::Account>.
     63
     64A C<BearMail::Account> in turn is a simple entry which ties a given email
     65adress to a specific C<BearMail::Target>. The target describes how email
     66received at the given address is handled : it can be stored in a mail
     67spool, re-sent to a list of other email addresses, handled by a third
     68party application (filter, vacation notifier), etc.
     69
     70A C<BearMail::Account> can also optionnally carray data such as authentication
     71information (password).
     72
     73Note that although the C<BearMail::Domain> module exists, domains cannot
     74be manipulated but only queried. You don't create a domain, you create a
     75C<BearMail::Account> with a new domain.
     76
     77=head2 Security model
     78
     79The backend must endorse a given identity which is of C<BearMail::Account>
     80type. Then every access to data is checked again this current identity
     81(see C<su>, C<login> and C<user>).
     82
     83There are three level of autorization (roles) with specific capabilities:
     84
     85=item * I<Admin> let you query and modify any information. This is a special
     86account whose identity is kept outside of regular accounts; for instance
     87as of now its password is stored in the main configuration file and can
     88only be modified by a sysadmin with proper server access. This is the only
     89role which may create accounts within new domains.
     90
     91=item * I<Postmaster> let you query and modify whole domains (add, modify and
     92remove accounts within existing domains). A postmaster has a postmaster@domain
     93address or is an alias target of one or more postmaster@domain addresses. Eg.
     94if postmaster@foo.net and postmaster@bar.org have both an alias target of
     95chief@quux.com, then chief@quux.com is postmaster for the @foo.net and
     96@bar.org domains.
     97
     98=item * I<User> is the lowest level. A user may query and modify (but not
     99create or delete) its own account. Such a end user may thus modify her
     100password, change her aliases, (un)configure an answering machine, etc.
    57101
    58102
     
    67111    my $bb = BearMail::Backend->new(
    68112        config  => BearMail::Config->new->load('mymail.cfg'),
    69         backend => BearMail::Backend::Files->new
     113        backend => BearMail::Backend::FlatFiles->new
    70114    );
    71115
     
    79123C<BearMail::Config>), you may provide your own config object here.
    80124
    81 You may also pass an undef value; in this case you will have to explictly
    82 create other needed ressources for the backend.
    83 
    84125=item * backend
    85126
     
    95136Next step is to C<su> or C<login> to setup an autorization context.
    96137
    97 =head2 su
    98 
    99 Endorse some identity without authentication (root power !).
    100 
    101 =head2 login
     138=head2 su $address
     139
     140Endorse some identity without authentication. The three levels of autorization
     141are specified via $address as (see 'Security Model' below):
     142
     143=item I<Admin>: use the 'admin' string
     144=item I<Postmaster>: use an email adress whose LHS (left hand side) is postmaster@
     145=item I<User>: use any email adress whose LHS is I<not> postmaster@
     146
     147Except for the 'admin' role, email addresses will be looked up to retrieve the
     148corresponding C<BearMail::Account>. If the look up fails, C<su> fails and
     149returns undef.
     150
     151It is I<not> possible to call C<su> multiple time to switch identities, it
     152will fail and return undef (although any currently endorsed identity is
     153preserved).
     154
     155Otherwise C<su> returns a C<BearMail::Account>.
     156
     157Authentications is I<not> checked. Use C<login> for this.
     158
     159
     160=head2 login $address, $password
    102161
    103162Endorse some identity with authentication check via the current
    104 backend.
     163backend. C<login> works exactly like C<su>, except that it will
     164check authentication information.
     165
     166Thus for C<login> to succeed, the corresponding account must exist and
     167the proper authentication verified. For the special 'admin' account,
     168the I<master_password> from the global I<bearmail.cfg> configuration file
     169is used.
     170
     171Currently only (plain) password authentication is supported (although the
     172backend might choose to store it hashed, for instance MD5 hashing is the
     173default for the 'files' backend).
    105174
    106175=head2 user
    107176
    108 Retrieve current endorsed identity.
     177Retrieve current endorsed identity as a C<BearMail::Account> object.
     178
     179This method returns undef if no C<su> or C<login> call where issued or
     180succeeded.
    109181
    110182
     
    141213
    142214
     215use Carp;
     216
     217
     218sub new {
     219    my $class = shift;
     220    my (%args) = @_;
     221
     222    my $cfg = $args{config}  || BearMail::Config->new->load();
     223    my $be  = $args{backend} || _get_backend($cfg);
     224
     225    bless { cfg => $cfg, be => $be }, $class;
     226}
     227
     228sub _get_backend {
     229    my $cfg = shift;
     230
     231    my $be_name = $cfg->{_}->{backend};
     232    if ($be_name eq 'FlatFiles') {
     233        require BearMail::Backend::FlatFiles;
     234        return  BearMail::Backend::FlatFiles->new($cfg->{"backend FlatFiles"});
     235    }
     236    carp "Unknown backend '$be_name' (missing BearMail::Backend::$be_name module ?)";
     237}
     238
    1432391;
  • bearmail/lib/BearMail/Config.pm

    r575 r577  
    1313   
    1414    my $conf = BearMail::Config->new();
    15     $conf->load('test.cfg') or die;
    16     my $tmpl_path = $conf->param('template_path') || '/usr/share/template';
     15    $conf->read('test.cfg') or die;
     16    my $tmpl_path = $conf->{_}->{template_path} || '/usr/share/template';
    1717
    1818
     
    2121C<BearMail::Config> ... FIXME
    2222
     23This is a subclass of C<Config::Tiny>, it has (at least) the same API.
     24
    2325
    2426=head1 CONFIGURATION FILE SYNTAX
    2527
    26 The format is based on C<Config::Tiny> parser and is a INI-like one. Right now
    27 it only uses "root-level" parameter and thus no sections : it is a simple list
    28 of "key = value" pairs.
     28The format is based on C<Config::Tiny> parser and is a INI-like one.
    2929
    3030The parameters, their values and meanings are self-documented in the template
     
    3939
    4040The constructor C<new> creates and returns an empty C<BearMail::Config> object.
    41 You must call its C<load> method next or explictly define a few parameters with
    42 an hashref:
     41You must call its C<read> method next or explictly define a few root parameters
     42with a hashref:
    4343
    4444    my $conf = BearMail::Config->new(
     
    4747    );
    4848
    49 =head2 load $filename
     49=head2 read $filename
    5050
    5151Reads a config file. When an error occurs, this method carps and return a
    5252zero (false) value.
    53 
    54 If C<load> succeeds, you can use the C<param> method to access the parameter
    55 values.
    56 
    57 C<load> only creates or updates value for the parsed keys: it might be called
    58 several times to overlay values already set via the constructor or via previous
    59 calls from C<load>.
    60 
    61 =head2 param $key
    62 
    63 Return the parsed value for the $key parameter, C<undef> if not defined.
    6453
    6554=head1 SUPPORT
     
    9685
    9786use strict;
     87use Carp;
    9888use Config::Tiny;
     89use base qw(Config::Tiny);
    9990
    10091
    10192sub new {
    10293    my $class = shift @_;
    103     my $self  = {};
     94    my $self  = $class->SUPER::new();
    10495
    10596    bless $self, $class;
    10697}
    10798
    108 sub load {
     99sub read {
    109100    my ($filename) = @_;
    110101    $filename = '/etc/bearmail/bearmail.cfg' if not defined $filename;
    111102
    112103    carp "BearMail::Config::load() not implemented";
    113     return 0;
     104    # return $self->SUPER::read($filename);
    114105}
    115106
    116 sub param {
    117     my ($name) = @_;
    118 
    119     carp "BearMail::Config::param() not implemented";
    120     return undef;
    121 }
    122 
    123 # I don't think we need a save(). The global configuration file is
     107# I don't think we need a write(). The global configuration file is
    124108# for the adminsys and deployment needs.
    125109#
    126 # Tunable for postmasters should implemented in something like BearMail::Settings
    127 # backed by a database.
     110# Tunable for postmasters should be implemented in something like
     111# BearMail::Settings backed by a database.
    128112
    1291131;
Note: See TracChangeset for help on using the changeset viewer.