Install guide 

QmailAdmin 1.2.0 and later requires Vpopmail 5.4.0 or later.

If you are installing on x86_64 platform (64-bit Intel/AMD processor),
or if configure exits with an "Invalid configuration" error,
you will need to run `libtoolize --force` in the QmailAdmin source
directory before following any other instructions in this guide.

Please note that any time you reconfigure and install vpopmail
you will need to rebuild and install QmailAdmin.  QmailAdmin
statically links libvpopmail, so you need to recompile it
whenever libvpopmail changes.

If you are upgrading to 1.2.1 or later from 1.2.0 or earlier,
and you have compiled vpopmail with the --enable-valias option,
be sure to run dotqmail2valias from vpopmail 5.4.1 to convert
old-style .qmail-alias files to valias table entries.

qmailadmin must be configured and installed as root.  Why?
vpopmail protects it's libraries from regular users.
qmailadmin needs to access those libraries, hence it needs root.
qmailadmin also needs to install into system directories
/usr/local/share/qmailadmin, the web server's cgi-bin directory
and the web server's html directory. Hence root.

Since qmailadmin is a suid binary, make sure it's installed on
a volume that isn't mounted with the 'nosuid' option in /etc/fstab.

Be root before you follow the rest of the instructions or
your installation will fail. 

If you have problems using 'make', try using 'gmake' instead.

Note to people who did not read the above paragraph:
When you give up on your installation, try reading
the above information then starting from scratch.

0. fast install guide.. 
   type as root: 
   		# ./configure
		# make
		# make install-strip

   If it works, you are done!
   If it doesn't.. read below.

1. Before we can make and install there are a few things to consider..
   a. do you have a vpopmail user and vchkpw group?
   b. where is your cgi bin directory?
   c. where is your ezmlm directory? default /usr/local/bin/ezmlm
   d. where is your autorespond directory? /usr/local/bin

   If you are missing any one of the above, stop reading this now and
   go install the missing software. 

2. Below is a list of possible configuration options 
	
	Note: Decide now which features you will want/need for your
	./configure

*Use this if your cgi bin is not in a standard location
	 --enable-cgibindir={dir}   HTTP server's cgi-bin directory.

Since qmailadmin is a suid binary, make sure the cgi-bin directory is
on a volume that isn't mounted with the 'nosuid' option in /etc/fstab.

*Use this if your don't want the HTML templates to be 
 in /usr/local/share/qmailadmin
	--enable-htmllibdir={dir}  qmailadmin HTML library directory.

*Use this if your qmail directory is not in /var/qmail  
	--enable-qmaildir={dir}   directory where qmail is installed.

*Use this if your URL PATH for cgi-bin is elsewhere   
	--enable-cgipath={/cgi-bin/qmailadmin}   URL path for cgi.

*use this to set the vchkpw user if it is not vpopuser.
	--enable-vpopuser={vpopuser}   user vchkpw was installed as.

*use this to set the vchkpw group if it is not vchkpw.
	--enable-vpopgroup={vchkpw}   group vchkpw was installed as.

*Use this if your autorespond is not in /user/local/bin   
	--enable-autoresponder-bin={path}  Path to autoresponder binary.
   
*Use this if ezmlm is not in /usr/local/bin/ezmlm
	--enable-ezmlmdir={dir}  Directory that holds the ezmlm package.

*MODIFY SPAM: If you want spam detection available to the end-user:
   --enable-modify-spam=Y
 (default spam command is 
  "|preline /usr/local/bin/maildrop /etc/mailfilter"
  If you wnat something else, use 
  --enable-spam-command="|spamcommand"
  NOTE: This command must deliver the mail)
  If you do not want to use maildrop (the default), there is a program
  called tomaildir (a part of qtools, located at
  http://www.superscript.com/qtools/intro.html) that can be combined with
  spamc to scan the mail and then deliver to the maildir)

*If you have different domains accessing the same qmailadmin, you 
 may want to automatically fill the domain field with the domain the 
 user accessed the qmailadmin cgi with:
   --enable-domain-autofill

  With autofill enabled, qmailadmin will search the file
  /var/qmail/control/virtualdomains for an entry that matches the
  hostname of the HTTP request.  So, if test.com appears in your
  virtualdomains file, <http://www.test.com/cgi-bin/qmailadmin>
  will pre-fill the domain field with "test.com".

  Note that with or without autofill enabled, you can pass parameters
  to qmailadmin to pre-fill the "User Account" and "Domain" fields.
  <http://www.test.com/cgi-bin/qmailadmin?dom=xyz.net&user=john> will
  prefill "Domain" with xyz.net and "User Account" with john.

3. Ok, now configure, using any options that you need to. For example:

	./configure  --enable-cgibindir=/my/wierd/cgi-bin/dir ....

4.	make

5.	make install or 
	make install-strip (for a smaller binary)

To run it, type into your webrowser:
	http://yourdomain/cgi-bin/qmailadmin

Now.. some fine tuning..

6. If you want to set per domain limits on the number of:

        a) pop accounts  
        b) aliases
        c) forwards
        d) mailing lists 
        e) autoresponders

 Then create a .qmailadmin-limits file in the virtual domain directory
 for the domain you wish to limit. The syntax of the .qmailadmin-limits
 file is as follows:

maxpopaccounts          X
maxaliases              X
maxforwards             X
maxmailinglists         X
maxautoresponders       X

Where X is the maximum number you wish. Be sure the vpopmail user
has read permissions to this file. The default is unlimited.
   
If you set any of the above values to 0 it will effectually disable
that part of the menu and that feature.

In addition, you can use qmailadmin-limits to disable services on a per 
domain basis for the creation of new users.  If you choose to disable
services on a domain that has existing user accounts, you will need to
modify the existing user accounts manually with vmoduser.

You may disable these services:

	a) POP Access
	b) IMAP Access
	c) Roaming Users (External Relaying)
	d) Webmail Access
	e) Dialup Access
	f) Password Changing

The syntax of the .qmailadmin-limits file for disabling the above 
services, respectively, is:

disable_pop
disable_imap
disable_external_relay
disable_webmail
disable_dialup
disable_password_changing

These services are enabled by default, unless manually changed
via vmoduser.

Lastly, you can set default quotas on a per domain basis.  Just include this
line in your .qmailadmin-limits file:

default_quota <quota>

The format of <quota> is the same used for other command line tools like 
vadduser, vsetuserquota, and vmoduser.  NOTE: the same restrictions apply as
the "disable" options above: this only applies to *new* users.  Any existing
users will need to me manually changed via vmoduser.

7. If you want to modify the "look" of qmail admin:
   
   Edit the html template files in /usr/local/share/qmailadmin/
   or if you changed the location with the --enable-htmllibdir={dir}
   then edit the files in that directory. The HTML elements for some
   not-very-often used features are included in comments in the
   template files. Remove the comment tags to see the relevant bits.

8. If you want more than one administrator of a domain:

   As of the 9/25/01 (5.0 version) of vpopmail and 0.84 of qmailadmin, you
   can issue 'vmoduser -a <user@domain>' to grant qmailadmin administrator
   privileges to non-postmaster users for a domain.  To remove the these
   privileges, just clear the gid flags for that user with 
   'vmoduser -x <user@domain>'

9. To log into the interface you will first need to
   create a domain using the vpopmail vadddomain program.

   as root:
   ~vpopmail/bin/vadddomain "your new domain name" "pick a postmaster password"

   Then you can log into qmailadmin with "your new domain name" and
   the password you set with the vadddomain command.

10. There are a number of things you can pass to qmailadmin when you run
it.  I believe they can be sent via either post or get. 

   domain = set the domain name in the login page.

   user = set the user name in the login page.

   returnhttp and returntext (both must be used) = create a link to 
   returnhttp on all qmailadmin pages with returntext for its label.


11. Enjoy

If you have any questions or comments please email
support@inter7.com or join the mailing list at
http://www.inter7.com/qmailadmin/

$Id: INSTALL,v 1.5.2.5 2005/03/14 07:22:00 tomcollins Exp $

