This is the Administrator Panel used by Fripost - the Free E-mail
Association.

Visit our website for more information:
https://fripost.org/

Please send patches, bug reports and comments to:
guilhem@fripost.org

* Installation

Read installation file INSTALL and follow those instructions.

** LDAP

The panel, or rather the Fripost::Schema library itself, requires
Fripost's LDAP schema, and base directory. See our other repository

  git clone gitolite@git.fripost.org:fripost-admin.git

for how to install those.

** Configuration

The configuration file 'default.in' is not to be modified. (Also, some of
the keys defined there are required.) Instead use the 'config.in' for
custom modifications.
Both files are equal separated (e.g., key=value) configuration file.
Comments (prefixed with a hash #) and blank/empty lines are ignored.

** Web server (nginx)

	location = / {
        rewrite ^ /cgi-bin/ permanent;
    }
    location ^~ /cgi-bin/ {
        fastcgi_split_path_info ^(/cgi-bin)(/.*)$;
        include fastcgi/params;
        fastcgi_pass unix:/var/run/fcgi/fripost-panel.socket;
    }
    location ^~ /img/ { }
    location ^~ /css/ { }
    location ^~ / { return 404; }

Start the FastCGI process with './bin/fripost-panel start'.

** Development

For testing purposes, the developers may want to install
HTTP::Server::Simple and use our custom clone of
CGI::Application::Server.
./dev/server.pl will start a server listening to localhost:8080.
Visit http://127.0.0.1:8080/cgi-bin/ to log in and browse the panel.

* Usage

** URL formats.

The following URL formats are accepted. (The user needs to be logged in
to browse those.)

*** /cgi-bin/

List domains known (visible) by the logged in user.

*** /cgi-bin/?a=add

Add a domain

*** /cgi-bin/example.org/

List mailboxes, aliases and mailing lists under the domain 'example.org'.

*** /cgi-bin/example.org/?a=edit

Edit domain 'example.org'.

*** /cgi-bin/example.org/?a=add&t=mailbox

Add a new mailbox under the domain 'example.org'.

*** /cgi-bin/example.org/?a=add&t=alias

Add a new alias under the domain 'example.org'.

*** /cgi-bin/example.org/?a=add&t=list

Add a new mailing list under the domain 'example.org'.

*** /cgi-bin/example.org/test/

Edit the mailbox, alias or mailing list 'test@example.org'.

*** /cgi-bin/example.org/test/?a=delete

Delete the mailbox, alias or mailing list 'test@example.org'.

*** /...?a=login

Login. (Force logout first).

*** /...?a=logout

Logout.

** Passwords

When a someone wants to change a password, the authenticated user
(either the owner of the password, or his/her postmaster) has to bind
with his/her own credential first. The reason is, we want to prevent an
attacker from changing a password, for instance on a session that was
left open, and browse the e-mail afterwards.

No one should have read access to the (hashed) passwords, not even its
owner.

** Internationalization

UTF-8 is handled smoothly by the library, as far as descriptions are
concerned.

Internationalized Domain Names (IDN) are also allowed, but are stored
punycode-encoded. This is because Postfix itself doesn't accept IDNs
(SMTP is a ASCII protocol), and requires the client to do the
transformation itself. Our library takes/returns unicode data, and does
the conversion under the hood. The owner of a IDN mailbox (e.g.,
peace@☮.net) can login to the panel using unicode or punycode, but other
services (Webmail, IMAP, SASL,...) may require him/her to use the punycode
version.

*** Limitations

Net::IDN::Encode is used for the conversion from unicode to punycode and
back (RFC 2821/2822). As of version 1.102 it does not support
internationalization of the local-part, so our panel does not either.

Email::Valid is used to check the validity of email (RFC 822), which in
turns uses Net::Domain::TLD to check the validity of top level domains.
However, as of version 1.69, Net::Domain::TLD does not support
internationalized TLDs (neither unicode nor punycode), so our panel does
not either. See also:
  - https://rt.cpan.org/Public/Bug/Display.html?id=62964
  - https://en.wikipedia.org/wiki/Tld#IDN_test_domains