Internationalization.

1 files changed, 132 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..0066727
--- /dev/null
+++ b/README
@@ -0,0 +1,132 @@
+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
+
+TODO: instructions for Apache and Nginx.
+
+** Development
+
+For testing purposes, the developers may want to install
+HTTP::Server::Simple and use our custom clone of
+CGI::Application::Server. 
+./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
+