Repository files navigation

vQadmin is a web based control panel that allows system administrators to perform actions which require root access — for example, adding and deleting domains.

vQadmin comes with full HTML templates. This means that the CGIdoes not generate any HTML at all, and that the templatesare responsible for providing the correct information to the CGI.Generally a CGI will generate things such as forms, or portionsof forms like input tags. This is not the case with vQadmin, sobe careful not to remove, or change any variable names insidethe template forms. It also comes with an example access list file,which explains pretty well how to set access restrictions upon users,and their usergroups.

1. What's needed to install vQadmin
2. Installing and configuring vQadmin
3. Setting up Apache
4. All of the above key-by-key
5. Troubleshooting
6. More info and support

vQadmin will run on any Unix-based system that hasvpopmail 4.9.8 or higher, Apache, and a C compiler installed.

$ ./configure # make# make install-strip

Now you want to edit your vqadmin.acl file, which is your access listdefinitions. Please read that file for information on how to define usersand usergroups.

If you haven't changed anything else, and your libraries are set properly,typing 'make' here should compile the CGI with no errors. Once that's done,typing 'make install' should install the CGI. Any errors that appear duringthese two command-line operations are going to be very hard to documentbecause of the system-specific nature of this portion of the installation.(See section 5)

vQadmin will require it's own CGI-allowed, access-protected,directory to operate. First, you will need to create a tag inside your Apache configuration, which sets the directoryto have ExecCGI permissions, allows the directory to overrideauthority, and sets the directory to deny everyone by default.vQadmin will not function without this setup.

Define QMAILROOT /var/www/qmail/<VirtualHost *:80>  ServerName vqadminyourdomain.tld  DocumentRoot ${QMAILROOT}  ScriptAlias /cgi-bin/ ${QMAILROOT}/cgi-bin/  AddHandler cgi-script .cgi  <Directory ${QMAILROOT}>    AllowOverride None    Require all granted  </Directory>  <Directory ${QMAILROOT}/cgi-bin>    AllowOverride None    Options ExecCGI    Require all granted  </Directory>  <Directory ${QMAILROOT}/cgi-bin/vqadmin>    Require all denied    Options ExecCGI    AllowOverride AuthConfig  </Directory>  Alias /assets/ ${QMAILROOT}/cgi-bin/vqadmin/assets/  <Directory ${QMAILROOT}/cgi-bin/vqadmin/assets>    Require all granted  </Directory></VirtualHost>

After you've created the directory, you will need to create anhtaccess for the directory so Apache knows how to authenticateusers trying to access the directory. In our example directory/usr/local/apache/cgi-bin/vqadmin, you'd create a '.htaccess' filedescribing the authentication we're using. You should store thepassword file somewhere the webserver isn't capable of displaying,such as the conf directory. The realm (AuthName) is not important,so you may call it whatever you'd like. You will want to chownthe file to the webserver user, and chmod it 600.

AuthType BasicAuthUserFile /etc/httpdpwd/vqadmin.passwdAuthName "Authentication required"Require valid-user

Now, create a user. In your Apache installation root directory, underthe bin subdirectory is a program called 'htpasswd'. This program is usedto create, and maintain the vqadmin.passwd file.

  Usage:htpasswd [-cmdps] passwordfile usernamehtpasswd -b[cmdps] passwordfile username password   -c  Create a new file.   -m  Force MD5 encryption of the password.   -d  Force CRYPT encryption of the password (default).   -p  Do not encrypt the password (plaintext).   -s  Force SHA encryption of the password.   -b  Use the password from the command line rather than prompting for it.  On Windows and TPF systems the '-m' flag is used by default.  On all other systems, the '-p' flag will probably not work.

We're only interested in the c (or maybe b) option for now.To create a vqadmin.passwd file, with a login of 'test', and apassword of 'test'.

  htpasswd -bc /etc/httpdpwd/vqadmin.passwd test test

That's it. Just remember that you made a user named 'test'! You needto know this for configuring vqadmin.

After you've done all this, you'll need to reload your configurationfiles.

Note for isoqlog support: the isoqlog.domains file must exist (but can beempty) for adding or deleting domains to/from isoqlog to work. This maybe changed in a later version.

Here we go, a very quick and dirty key-by-key installation guide...

# tar zxf vqadmin-X.X.tar.gz # cd vqadmin* # ./configure# make# make install# cd /etc/httpd# vi httpd.confDefine QMAILROOT /var/www/qmail/<VirtualHost *:80>  ServerName vqadminyourdomain.tld  DocumentRoot ${QMAILROOT}  ScriptAlias /cgi-bin/ ${QMAILROOT}/cgi-bin/  AddHandler cgi-script .cgi      <Directory ${QMAILROOT}>    AllowOverride None    Require all granted  </Directory>  <Directory ${QMAILROOT}/cgi-bin>    AllowOverride None    Options ExecCGI    Require all granted  </Directory>  <Directory ${QMAILROOT}/cgi-bin/vqadmin>    Require all denied    Options ExecCGI    AllowOverride AuthConfig  </Directory>  Alias /assets/ ${QMAILROOT}/cgi-bin/vqadmin/assets/  <Directory ${QMAILROOT}/cgi-bin/vqadmin/assets>    Require all granted  </Directory></VirtualHost># cd /var/www//cgi-bin/vqadmin# vi vqadmin.acl# vi .htaccess  AuthType Basic  AuthUserFile /etc/httpd/httpdpwd/vqadmin.passwd  AuthName "Authentication required"  Require valid-user# chown nobody .htaccess# chmod 600 .htaccess# htpasswd -bc /etc/httpd/httpdpwd/vqadmin.passwd admin adminpass# apachectl restart

As you can see, once you've done it once, it's pretty simple to just runthrough it in 5 or 10 minutes.

I could only think of a few troubleshooting things to document.Just little problems I ran into when coding, or installing it duringproduction testing.

  * Apache shuts down after re-starting, and wont re-start  + The <Directory> information you entered was probably in an invalid    format, or you forgot your </Directory> tag.      * Compile-time errors  + vQadmin compiles on all Unix-based systems.  If you get any    errors when compiling, check to see if you have the required    libraries compiled in at link time.   * '500 Internal Server Error' message from the webserver    when trying to use the CGI.  + This could be a great deal of things.  Most likely it's    related to the .htaccess file you setup.  Make sure it's    readable by the webserver.

You can find more info and ask for support athttps://notes.sagredo.eu/en/qmail-notes-185/vqadmin-26.html.