Menu
▾
▴
[panda-admin-commits] SF.net SVN: panda-admin: [38] trunk/doc
|
From: <ag...@us...> - 2008-02-26 10:43:22
|
Revision: 38
http://panda-admin.svn.sourceforge.net/panda-admin/?rev=38&view=rev
Author: agrassi
Date: 2008-02-26 02:43:27 -0800 (Tue, 26 Feb 2008)
Log Message:
-----------
Merged CREDITS into INSTALL
Modified Paths:
--------------
trunk/doc/INSTALL
Removed Paths:
-------------
trunk/doc/CREDITS
Deleted: trunk/doc/CREDITS
===================================================================
--- trunk/doc/CREDITS 2008-02-26 10:07:25 UTC (rev 37)
+++ trunk/doc/CREDITS 2008-02-26 10:43:27 UTC (rev 38)
@@ -1,14 +0,0 @@
-
- ~~~~ PANDA Credits ~~~~~
-
- Panda was initially created as a stub by Marco Nenciarini, and developed
- by Alessandro Grassi with some help from Marco
-
- We thank grafica-web.it for having sponsored our project til the first release
-
-
- Contacts:
-
- Alessandro Grassi <ale...@gr...> (xstasi @ irc.freenode.org)
- Marco Nenciarini <mn...@gr...> (mnencia @ irc.freenode.org)
-
\ No newline at end of file
Modified: trunk/doc/INSTALL
===================================================================
--- trunk/doc/INSTALL 2008-02-26 10:07:25 UTC (rev 37)
+++ trunk/doc/INSTALL 2008-02-26 10:43:27 UTC (rev 38)
@@ -1,81 +1,549 @@
- ~~~~~ PANDA Installation Procedure ~~~~~
+
+ PaNDA Web Administrator installation howto
+
+
+Table of contents:
+
+1. About PaNDA
+2. Having a PaNDA-compliant system
+2.1 PostgreSQL
+2.2 Postfix
+2.3 Dovecot
+2.4 ClamAV
+2.5 Amavisd-new
+3. Installing PaNDA
+4. Anything else
+5. Copyright and Credits
+
+
+
+
+
+1. ~~~~~~~~~~ About PaNDA ~~~~~~~~~~
+
+PaNDA is a tool for the management of email domains, email addresses and newsletters.
+It is thought with security, ease and lightweightness in mind.
+
+The project started as a replacement for the Qmail/qpopmail/whatnot system,
+but i'm not telling you this.
+
+
+
+
+2. ~~~~~~~~~~ Having a PaNDA-compliant system ~~~~~~~~~~
+
+You can use a single server, or separate machines.
+In the following howto, we will use different servers running Debian etch.
+We will use vmail/vpass as DB user/pass, "dbserver" as DB server, and /srv/vmail as mailbox base.
+
+We recommend using both Debian's volatile repository, and our dovecot repository, which hosts
+newer stable releases of Dovecot, with managesieve patch already included, gently packaged and
+maintained by Marco Nenciarini.
+You can have more informations on this by checking out our home page: http://panda-admin.sourceforge.net
+
+
+First of all, we need the following packages on the mail server:
+
+ # apt-get install dovecot-{imapd,pop3d} postfix postfix-{pcre,pgsql}
+
+If we want antispam/antivirus support, we should install these too:
+
+ # apt-get install amavisd-new spamassassin clamav clamav-daemon lha arj unrar zoo lzop cabextract unzip libdbd-pg-perl
+
+Install the PostgreSQL DBMS on the DB server:
+
+ # apt-get install postgresql-8.1
+
+Install apache2 and the required modules on the webserver:
+
+ # apt-get install apache2-mpm-prefork apache2 libapache2-mod-php5 php-db php-mail php-mail-mime php-net-smtp php-pear php5-pgsql
+
+Once the system is ready with all the packages installed, we set up the mail system.
+
+On our mailserver, we should create the UID/GID couple for dovecot, like this:
+ # adduser --system --home /srv/vmail --group vmail
+Remember the UID and GID it prints, because you will need them in the near future.
+
+If you make use of the newsletter feature, you should also install the newsletter handler:
+ # cp panda-x.y/setup/bin/newsletter /srv/vmail/bin/
+ # cp panda-x.y/setup/bin/newsletter.conf /srv/vmail/etc
+
+You may need to edit newsletter and newsletter.conf to suit your needs.
+
+Done with the preparations, we can go on and configure our engines
+
+
+
+2.1 ~~~~~~~~~~ PostgreSQL ~~~~~~~~~~
+
+
+First of all, if the database is on a separate machine, we need to tell him to listen to the network interface too:
+
+ # vi /etc/postgresql/8.1/main/pg_hba.conf
+
+Under this line:
+ host all all 127.0.0.1/32 md5
+We should add a line such as:
+ host all all 192.168.99.0/24 md5
+
+
+Then, we edit the main configuration:
+
+ # vi /etc/postgresql/8.1/main/postgresql.conf
+
+And add the following line:
+ listen_addresses = 'localhost,192.168.99.16'
+
+After PG is configured, we have to prepare it to be used by PaNDA:
+Here we assume to have PaNDA's SQL scripts in /tmp/sql
+
+ # su - postgres
+ $ createuser vmail
+ $ createdb -O vmail vmail
+ $ createlang plpgsql vmail
+ $ psql
+ =# ALTER ROLE vmail WITH PASSWORD 'vpass' INHERIT LOGIN;
+ =# \q
+ $ cd /tmp/sql
+ $ psql -h localhost -U vmail vmail
+ => \i create.sql
+ => \i functions.sql
+ => \i users.sql
+ => \q
+
+Now Postgres is ready.
+
+
+2.2 ~~~~~~~~~~ Postfix ~~~~~~~~~~
+
+We need to tell postfix where the virtual users and domains are.
+For this, we will enable a few stuff, and then we will create a few database files with SQL instructions,
+and tell postfix what-is-what.
+
+First to be enabled are regexps:
+ # vi /etc/postfix/dynamicmaps.cf
+Add the following:
+ pcre /usr/lib/postfix/dict_pcre.so dict_pcre_open
+
+
+Then we edit main.cf
+ # vi /etc/postfix/main.cf
+And tell him where to look up domains and all
+
+ # Alias domains and mailboxes
+ virtual_alias_domains = proxy:pgsql:/etc/postfix/sql/virtual_alias_domains.pg
+ virtual_alias_maps = proxy:pgsql:/etc/postfix/sql/virtual_alias_maps.pg
+
+ # Real mailboxes and transports
+ virtual_mailbox_domains = proxy:pgsql:/etc/postfix/sql/virtual_mailbox_domains.pg
+ transport_maps = proxy:pgsql:/etc/postfix/sql/transport.pg
+
+ # Dovecot relays mail, not postfix
+ virtual_transport = dovecot
+
+ # Without this, CC/Bcc won't work
+ dovecot_destination_recipient_limit = 1
+
+If we use amavisd, add this too:
+
+ content_filter = smtp-amavis:[127.0.0.1]:10024
+
+
+Done this, we edit master.cf
+ # vi /etc/postfix/master.cf
+And add the following:
+
+ submission inet n - - - - smtpd
+ -o smtpd_enforce_tls=yes
+ -o smtpd_sasl_auth_enable=yes
+ -o smtpd_client_restrictions=permit_sasl_authenticated,reject
+ -o cleanup_service_name=pre-cleanup
+ dovecot unix - n n - - pipe
+ flags=ORhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${user}@${nexthop} -n -m ${extension}
+ pre-cleanup unix n - - - 0 cleanup
+ -o virtual_alias_maps=
+ -o canonical_maps=
+ -o sender_canonical_maps=
+ -o recipient_canonical_maps=
+ -o masquerade_domains=
+
+ # Panda newsletters
+ newsletter unix - n n - - pipe
+ flags= user=vmail argv=/srv/vmail/bin/newsletter
+ ${sender} ${recipient}
+
+
+If we use amavisd, add this too:
+
+ smtp-amavis unix - - n - 4 lmtp
+ -o lmtp_data_done_timeout=1200
+ -o lmtp_send_xforward_command=yes
+ -o disable_dns_lookups=yes
+ -o max_use=20
+
+ 127.0.0.1:10025 inet n - n - - smtpd
+ -o content_filter=
+ -o local_recipient_maps=
+ -o relay_recipient_maps=
+ -o smtpd_restriction_classes=
+ -o smtpd_delay_reject=no
+ -o smtpd_client_restrictions=permit_mynetworks,reject
+ -o smtpd_helo_restrictions=
+ -o smtpd_sender_restrictions=
+ -o smtpd_recipient_restrictions=permit_mynetworks,reject
+ -o smtpd_data_restrictions=reject_unauth_pipelining
+ -o smtpd_end_of_data_restrictions=
+ -o mynetworks=127.0.0.0/8
+ -o smtpd_error_sleep_time=0
+ -o smtpd_soft_error_limit=1001
+ -o smtpd_hard_error_limit=1000
+ -o smtpd_client_connection_count_limit=0
+ -o smtpd_client_connection_rate_limit=0
+ -o strict_rfc821_envelopes=yes
+ -o smtpd_authorized_xforward_hosts=127.0.0.0/8
+ -o receive_override_options=no_header_body_checks,no_unknown_recipient_checks
+
+Done with postfix' main configuration, we create the scripts that postfix has to use for lookups:
+Every file must contain the DB informations, like this:
+
+hosts = dbserver
+dbname = vmail
+user = vmail
+password = vmpass
+
+We fill all the files with these lines, and the needed query:
+
+---- /etc/postfix/sql/transport.pg
+query = SELECT 'newsletter:' FROM newsletter_maps WHERE id = get_nwl_id('%s');
+
+hosts = dbserver
+dbname = vmail
+user = vmail
+password = vmpass # I will omit this part from now on
+
+---- /etc/postfix/sql/virtual_alias_maps.pg
+query = SELECT '@'||destination FROM alias_domains WHERE ('@'||name) = '%s'
+ UNION
+ SELECT unknown_to FROM virtual_domains
+ WHERE ('@'||name) = '%s' AND have_default_delivery('%s') AND NOT deleted
+ UNION
+ SELECT COALESCE(
+ u.name||'@localdelivery.%d'||' '||destination,
+ destination,
+ u.name||'@localdelivery.%d'
+ )
+ FROM virtual_domain_users AS u NATURAL FULL JOIN virtual_domain_aliases AS a
+ WHERE id_domain = get_id_domain('%d') AND name = extract_user('%s')
+ UNION
+ SELECT name||'@transportdelivery.%d' FROM newsletter_maps
+ WHERE id_domain = get_id_domain('%d') AND name = extract_user('%s');
+
+---- /etc/postfix/sql/virtual_mailbox_domains.pg
+query = SELECT 'DUMMY_IGNORED'::text FROM virtual_domains
+ WHERE ('localdelivery.'||name) = '%s' AND NOT deleted
+
+---- /etc/postfix/sql/virtual_mailbox_maps.pg
+query = SELECT maildir FROM virtual_domain_users
+ WHERE id_domain = get_id_domain_local('%d') AND name = '%u';
+
+
+----
+
+
+We should now be able to safely shut down and restart postfix
+ # /etc/init.d/postfix restart
+
+
+2.5 ~~~~~~~~~~ Amavisd-new ~~~~~~~~~~
+
+For amavis to run correctly, it should be enough to add the following lines to /etc/amavis/conf.d/50-user, before the 1:
+
+# Enable spam and virus checks
+@bypass_spam_checks_maps = (
+ \%bypass_spam_checks, \@bypass_spam_checks_acl, \$bypass_spam_checks_re);
+@bypass_virus_checks_maps = (
+ \%bypass_virus_checks, \@bypass_virus_checks_acl, \$bypass_virus_checks_re);
+
+# Make spam go anyway into inbox, although marked
+$final_spam_destiny = D_PASS;
+
+# Send scanned mail back to postfix
+$forward_method = 'smtp:127.0.0.1:10025';
+
+# local domain list
+@lookup_sql_dsn = (
+ ['DBI:Pg:database=vmail;host=localhost;port=5432','vmail','vmpass'],
+ );
+
+$sql_select_policy = "SELECT 1 FROM virtual_domains WHERE NOT deleted AND '\@'||name IN (\%k)";
+
+## Don't send mail
+undef($virus_admin);
+
+That's it.
+
+2.3 ~~~~~~~~~~ Dovecot ~~~~~~~~~~
+
+We need to tell Dovecot that the authentication system we use is on SQL, and what should he ask to Postgres to have
+what he needs.
+All is made with the following steps....
+
+
+/etc/dovecot/dovecot-sql.conf should look like this:
+
+ driver = pgsql
+ connect = host=dbserver dbname=vmail user=vmail password=vmpass
+ default_pass_scheme = CRYPT
+ password_query = SELECT '.dovecot.sieve' AS sieve, 123 AS userdb_uid, 321 AS userdb_gid, name AS user, passwd AS password,
+ '/srv/vmail/domains/'||maildir as userdb_home, 'maildir:/srv/vmail/domains/'||maildir||'/Maildir' as userdb_mail,
+ 'maildir:storage='||quota_kb AS userdb_quota FROM virtual_domain_users WHERE name = '%n' AND id_domain = get_id_domain('%d')
+
+Dovecot needs a separate instance for the local delivery, so we copy dovecot-sql.conf to dovecot-sql-lda.conf,
+and use these password/user_query fields:
+
+ user_query = SELECT '.dovecot.sieve' AS sieve, 123 as uid, 321 as gid, '/srv/vmail/domains/'||maildir as home,
+ 'maildir:/srv/vmail/domains/'||maildir||'/Maildir' as mail, 'maildir:storage='||quota_kb as quota from virtual_domain_users
+ where name = '%n' and id_domain = get_id_domain('%14.d')
+
+ password_query = SELECT '.dovecot.sieve' AS sieve, 123 AS userdb_uid, 321 AS userdb_gid, name AS user, passwd AS password,
+ '/srv/vmail/domains/'||maildir as userdb_home, 'maildir:/srv/vmail/domains/'||maildir||'/Maildir' as userdb_mail,
+ 'maildir:storage='||quota_kb AS userdb_quota FROM virtual_domain_users WHERE name = '%n' AND id_domain = get_id_domain('%14.d')
+
+Please note that in the above lines, uid is 123 and gid is 321, remind to adjust those numbers to your case (remember when i said to remember UID/GID?).
+Also, be aware that SQL queries have to be written in just one line, so, even if I've written them in separate lines for the sake of readability,
+you should join them in a single one.
+
+Now that the definition files are ready, we configure dovecot to use them.
+Edit /etc/dovecot/dovecot.conf this way:
+
+Change
+ protocols =
+ listen =
+To
+ protocols = imap imaps pop3 pop3s managesieve
+ listen = *
+
+And add the following lines, adjusting them to your needs:
+
+ syslog_facility = mail
+
+ ssl_disable = no
+ ssl_cert_file = /etc/ssl/certs/dovecot.pem
+ ssl_key_file = /etc/ssl/private/dovecot.pem
+ ssl_cipher_list = ALL:!LOW
+ verbose_ssl = no
+
+ login_chroot = yes
+ login_user = dovecot
+ login_process_size = 64
+ login_greeting = Foo Bar mail daemon ready.
+
+ mail_location = maildir:/srv/mail/domains/
+
+ first_valid_uid = 123 # Insert vmail's uid/gid
+ last_valid_uid = 123 #
+ first_valid_gid = 321 #
+ last_valid_gid = 321 #
+
+ maildir_stat_dirs = yes
+
+ protocol managesieve {
+ listen = *:2000
+ login_executable = /usr/lib/dovecot/managesieve-login
+ mail_executable = /usr/lib/dovecot/managesieve
+ sieve=~/.dovecot.sieve
+ sieve_storage=~/sieve
+ }
+
+< Under protocol imap {} >
+
+ login_executable = /usr/lib/dovecot/imap-login
+ mail_executable = /usr/lib/dovecot/imap
+ mail_plugins = quota imap_quota
+ mail_plugin_dir = /usr/lib/dovecot/modules/imap
+</>
+
+< Under protocol pop3 {} >
+
+ login_executable = /usr/lib/dovecot/pop3-login
+ mail_executable = /usr/lib/dovecot/pop3
+ mail_plugins = quota
+ mail_plugin_dir = /usr/lib/dovecot/modules/pop3
+</>
+ protocol lda {
+ postmaster_address = postmaster@yourdomain.xy
+ hostname = your.host.name
+ mail_plugins = quota cmusieve
+ mail_plugin_dir = /usr/lib/dovecot/modules/lda
+ auth_socket_path = /var/run/dovecot/auth-master-rewrite
+ }
+
+ auth_executable = /usr/lib/dovecot/dovecot-auth
+
+< Under auth default {} >
+ Change
+ mechanisms = plain
+ To
+ mechanisms = plain login
+
+ Delete or comment out
+ passdb pam {}
+ userdb passwd {}
+
+
+ passdb sql {
+ args = /etc/dovecot/dovecot-sql.conf
+ }
+ userdb prefetch {
+ }
+
+ socket listen {
+ master {
+ path = /var/run/dovecot/auth-master
+ mode = 0600
+ user = vmail
+ group = vmail
+ }
+ }
+</>
+
+ auth postfix {
+
+ mechanisms = plain login
+
+ userdb prefetch {
+ }
+
+ passdb sql {
+ args = /etc/dovecot/dovecot-sql.conf
+ }
+
+ socket listen {
+ client {
+ path = /var/spool/postfix/private/auth
+ mode = 0660
+
+ user = postfix
+ group = postfix
+ }
+ }
+ }
+
+ auth other_with_listener {
+ userdb sql {
+ args = /etc/dovecot/dovecot-sql-lda.conf
+ }
+ passdb sql {
+ args = /etc/dovecot/dovecot-sql-lda.conf
+ }
+ user = root
+
+ socket listen {
+ master {
+ path = /var/run/dovecot/auth-master-rewrite
+ mode = 0600
+ user = vmail
+ group = vmail
+ }
+ }
+ }
+
+< Under plugin {} >
+
+ quota = maildir
+
+
+
+This should be the end of dovecot configuration.
+
+2.4 ~~~~~~~~~~ ClamAV ~~~~~~~~~~
+
+Clamav is quite easy to configure, but to make him live in symbiosis with amavis, you have to tweak a few settings
+First file to edit:
+ /etc/clamav/clamd.conf
+Change
+ User clamav
+To
+ User amavis
+
+Delete the "NodalCoreAcceleration" line, if present
+
+Add the following lines:
+
+ PhishingScanURLs true
+ PhishingRestrictedScan true
+ PhishingAlwaysBlockSSLMismatch false
+ PhishingAlwaysBlockCloak false
+ DetectPUA false
+(Mind that these only work if you're using debian's volatile repository, or anyway lastest clamav version)
+End of clamd.conf
+Other file to edit:
+ /etc/clamav/freshclam.conf
+Add the following lines:
+ LogTime false
+ User amavis
+
+This should be all with ClamAV
+
+
+3. ~~~~~~~~~~ Installing PaNDA ~~~~~~~~~~
+
+Once your mail system is ready, we can set up the GUI on the webserver.
+This is a very easy task, all you need to do is unpacking the .tar.gz into your website.
+We assume that PaNDA is being installed under /panda
+
+ # cd /srv/www/mysite.com
+ # tar zxvf ~/panda-x.y.tar.gz
+ # cd panda
+ # vi config.php
+
+In config.php, we need to configure a few settings.
+DSN is the Database connection string, in form:
+ psql://user:pass@dbserver:port/database
+Which, in a standard installation, with the data we've used before, would be:
+ psql://vmail:vpass@dbserver:5432/vmail
+
+EMAIL_PER_PAGE sets how many email address per page are to be displayed under the mail management
+
+DOMAIN_ONLY_FIRST_LETTER is just a matter of taste.
+If you like to see your domains sorted like a -> c (dictionary like), set this to TRUE
+Otherwise, if you would like to have more detailed links (alpha.net -> charlie.biz), set this to FALSE
+
+DOMAIN_SEPARATOR is again a matter of taste. Normally the default (->) is ok
+
+MAIL_FROM is the address your newsletter subscription mails will come from, and
+SMTP_HOST is the smarthost to be used for sending mails
+
+If you make use of the newsletters feature, mind configuring nwadmin/config.php, which has similar options.
+
+After you're done configuring panda, you can login on yoursite.com/panda (or where you've installed it) with admin/admin (default user/pass),
+change them, create new users, add domains, and do whatever you like
+
+
+4. ~~~~~~~~~~ Anything else... ~~~~~~~~~~
+
+PaNDA comes with a very nice daemon, vmaild.
+Whenever a new email is created, it creates the directory tree, sets up default anti-spam filter, sets up permissions and so on.
+We recommend you to install it (say on /srv/vmail/bin/vmaild) and use the shipped init.d script
+ # cp vmaild-init.d /etc/init.d/vmaild
+ # cd /etc/rc2.d
+ # ln -s ../init.d/vmaild S80vmaild
+
+
+5. ~~~~~~~~~~ Copyright and Credits ~~~~~~~~~~
+
+PaNDA is distributed under the GNU General Public License, so you can do what you want with it, as long as you respect the GPL terms.
+
+PaNDA was initially created as a stub by Marco Nenciarini, and developed
+by Alessandro Grassi with some help from Marco
+We thank grafica-web.it for having sponsored our project til the first release
- 1- General requirements for optimal work:
+ Contacts:
- - Postfix (we use 2.3.8)
- - PostgreSQL (8.1 or higher)
- - Apache (we use 2.2, 1.x should work though)
- - PHP5
- - Dovecot (We use 1.0, ATM 1.1 is not out, beware that you may encounter problems with it, since it changes a lot)
- - AMAVIS (We use 2.4.2)
-
- 2- Apache/PHP5 requirements
-
- You should make sure that there is a working php5 environment in your apache, and that the
- following mods are included:
-
- - php-pear
- - php-db
- - php-mail
- - php-mail-mime
- - php-net-smtp
- - php5-pgsql
-
- 3- Installation (Web)
-
- PANDA is designed to be installed under any path, so feel free to do it
- Copy the whole panda/ directory somewhere in your web space (e.g. /, reachable via /panda)
- Please remember that setup/ is not necessary for daily usage, it only contains installation-related
- files and contrib scripts, so you can (and should) delete it after install is complete
-
-
- 4- Installation (DB)
-
- You should create an user and a database for panda, and also enable the 'plpgsql' language for that database.
- Instructions on how to do it follow (assuming shell access is provided, platform used in examples is Debian):
-
- # su - postgres
- $ createuser vmail
- $ createdb -O vmail vmail
- $ createlang plpgsql vmail
- $ psql vmail
- vmail=# ALTER ROLE vmail WITH PASSWORD 'vmailpass';
-
- After the database is ready for setup, we can load the SQL dumps:
-
- $ cd /wherever/panda/setup/sql/
- $ psql -h localhost -U vmail vmail
- vmail=> \i create.sql
- vmail=> \i functions.sql
- vmail=> \i users.sql
-
- Whenever you want to destroy all data in the DB, you can use drop.sql
- If it gives you warnings about plpgsql language, be sure to have created it
-
-
- 5- Installation (System)
-
- A few scripts are provided, here follows a list with description:
-
- - vmaild -- It checks once in a while for new mailboxes and changes in the DB, and
- prepares the environment for them (ATM only premade anti-spam filters).
+ Alessandro Grassi <ale...@gr...> (xstasi @ irc.freenode.org)
+ Marco Nenciarini <mn...@gr...> (mnencia @ irc.freenode.org)
- - vmaild-init.d -- Script for automatic vmaild launching (needs to be configured)
- e.g.: # cp vmaild-init.d /etc/init.d/vmaild
- # cd /etc/rc2.d
- # ln -s ../init.d/vmaild S80vmaild
-
- - newsletter -- This script is meant to be the destination for newsletter addresses.
- it simply takes mails and puts them in the DB, for further moderation
- Please remember to modify newsletter.conf and install it in the same directory
-
-
- 6- Memo
-
- - Once installed, PANDA is accessible from the web with credentials admin/admin (it is **HIGHLY** recommended
- that you change them at first run)
-
-
\ No newline at end of file
+
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|