Location: PHPKode > scripts > Virtual Mail ManaGer Interface > virtual-mail-manager-interface/doc/user.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <title>Virtual Mail ManaGer Interface - Users's Guide</title>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  <link rel=stylesheet type="text/css" href="site.css">
</head>
<body bgcolor="#FFFFFF">

<h2>User's guide</h2>

<h3><a name="1">1. Features</a></h3>

<p>
&bull; Easy to use<br>
&bull; Search for users (typo tolerant)<br>
&bull; Supports all vmailmgr features<br>
&bull; Templates<br>
&bull; Multiple Languages<br>
&bull; TCP/IP and UNIX domain sockets supported<br>
&bull; <a href="http://www.rfc-editor.org/rfc/rfc2606.txt" target="_blank">RFC2606</a> compliant<br>
</p>

<h3><a name="2">2. Requirements</a></h3>

<p>PHP >= 4.1.0 is an absolute must, as <i>vmmi</i> relies on the super global
  variables introduced in 4.1.0. You shouldn't be using a PHP version older
  than 4.1.1 anyway, due to the *serious*
  <a href="http://security.e-matters.de/advisories/012002.html" target="_blank">
  remote buffer overlow vulnerability</a>. <i>vmmi</i> will also work when
  register_globals is turned on.</p>

<h3><a name="3">3. Screenshots</a></h3>

<table border="0">
<tr>
  <td width="170"><a href="login.png" target="_blank"><img src="login_thumb.png" width="150" height="92" border="0"></a></td>
  <td>Login screen, where you can login with example.com or hide@address.com</td>
</tr>
<tr>
  <td width="170"><a href="overview.png" target="_blank"><img src="overview_thumb.png" width="150" height="114" border="0"></a></td>
  <td>Overview screen showing all available mailboxes and forwarding addresses.</td>
</tr>
<tr>
  <td width="170"><a href="search.png" target="_blank"><img src="search_thumb.png" width="150" height="89" border="0"></a></td>
  <td>Search for a user. Notice the wrong spelling.</td>
</tr>
<tr>
  <td width="170"><a href="add_account.png" target="_blank"><img src="add_account_thumb.png" width="150" height="132" border="0"></a></td>
  <td>Adding an account.</td>
</tr>
<tr>
  <td width="170" valign="top"><a href="autoresponse.png" target="_blank"><img src="autoresponse_thumb.png" width="150" height="73" border="0"></a></td>
  <td>Setting an autoresponder. Note that autoresponses only work if you have
    set up the autoresponder package (<a href="http://www.vmailmgr.org/docs/HOWTO.html">VMailMgr HOWTO</a>,
    Chapter 3.6 Enabling processing of autoresponse). The documentation is not right
    on how the script should look like, though. The correct script looks like
    this:
<pre>
#!/bin/sh
if test -s $MAILDIR/autoresponse/message.txt
then
  qmail-autoresponder message.txt $MAILDIR/autoresponse
fi
</pre>
    I've <a href="http://lists.em.ca/?command=showmsg&list=vmailmgr&month=200204&msgnum=6928&threadid=fhphfccjfimnkmpbapik" target="_blank">submitted</a> this already to the mailing list, but it has not yet
    been fixed in the documentation.
    </td>
</tr>
<tr>
  <td width="170"><a href="tsunamihost.png" target="_blank"><img src="tsunamihost_thumb.png" width="150" height="130" border="0"></a></td>
  <td>This is how it looks embedded into the control panel at <a href="http://tsunamihost.ch/" target="_blank">TsunamiHost</a>.
    I just changed the <a href="#5.1">template</a> colors a bit.</td>
</tr>
</table>

<h3><a name="4">4. Installation</a></h3>

<h3><a name="4.1">4.1 TCP/IP or Unix Domain sockets?</a></h3>

<p>First download and unpack the archive:</p>

<pre>
  wget http://daniel.lorch.cc/files/vmmi/vmmi-x.xx.tar.gz
  tar zxf vmmi-x.xx.tar.gz
</pre>

<p>Open config.php in your favorite editor. You have to tell <i>vmmi</i>
  whether you are running VMailMgr on TCP/IP or UNIX Domain sockets. By
  default, <i>vmmi</i> is set up to run on TCP/IP sockets. Verify whether
  host and port are correct:</p>

<pre>
  /* uncomment if vmailmgr runs with TCP/IP sockets */

  class my_vmailmgr extends vmailmgr {
    var $tcp_host = "localhost";
    var $tcp_port = 322;
  }
</pre>

<p>If you are running VMailMgr on Unix Domain sockets instead, you have to
  comment out the above lines and uncomment the lines with the unix domain
  sockets:
  
<pre>
  /* uncomment if vmailmgr runs with TCP/IP sockets */

  // class my_vmailmgr extends vmailmgr {
  //   var $tcp_host = "localhost";
  //   var $tcp_port = 322;
  // }

  /* uncomment if vmailmgr runs with UNIX domain sockets */

  class my_vmailmgr extends vmailmgr {
    var $unix_socket = "/tmp/.vmailmgrd";
  }
</pre>

<p>Now scroll down to the bottom and look for the variable $salt:</p>

<pre>
  $salt = "";
</pre>

<p>Choose a passphrase and write it between "". This is explained
  further in 4.2.</p>

<h3><a name="4.2">4.2 Security Tips</a> - <b><font color="#FF0000">Important!</font></b></h3>

<p>Read this chapter carefully.</p>

<p>VMailMgr is a daemon that sits in the background and could be accessed
  by any user on your system. Therefore VMailMgr only accepts commands when
  it gets a valid user password. <i>vmmi</i> has to store this password
  somewhere and that's exactly the problem. The user password is stored in
  a session and PHP sessions are stored by default in /tmp. Although this
  password is encrypted (see chapter 4.1, passphrase $salt) someone who
  gains access to these files might crack another user's password.
  Our goal is to prevent malicious users of getting access to these files.</p>

<p>On most setups PHP is running as module and all scripts are executed
  as the user under which the webserver runs. Preventing the webserver
  from being able to read sessions would obviously not be a good solution
  as it would hinder people from actually <i>using</i> sessions.
  As you know, PHP session filenames are (intentionally) hard to guess
  - primarily to prevent
  <a href="http://www.securiteam.com/unixfocus/5AP0A1F61Q.html" target="_blank">session spoofing</a>.
  It is therefore sufficient to prevent PHP from being able to <i>list</i>
  the contents of a directory ("r"), while still being able to enter
  ("x") and create ("w") files in it - if a cracker does not know the filename,
  how should he be able to get access to it? The optimal permissions for
  our session directory would therefore be "wx".</p>

<p>We also have to keep someone of changing back these permissions.
  If our session directory would be owned by the webserver user, these
  permissions could be easily changed from a PHP script. We therefore
  let this directory be owned by root and only apply group ownership
  to the directory.</p>

<p>I chose /var/spool/php_sessions/ to be this directory, but you
  may also choose another name for it. I don't suggest you to put it in
  /tmp though, as this directory usually gets wiped on every server
  restart.
  
<p>In the following example I am assuming that the UID under which your
  webserver runs is 'www-data'. Change this otherwise:</p>

<pre>
  mkdir /var/spool/php_sessions/
  chmod 1733 /var/spool/php_sessions/
  chown root:www-data /var/spool/php_sessions/
</pre>

<p>You may have noticed the 1 in the chmod command. It applies the "sticky bit"
  to the directory which ensures that only the user who created a file in this
  directory is able to delete it. It's not necessary, but can't harm you either.
  The permissions should now look like this:</p>

<pre>
  drwx-wx-wt    2 root     www-data     4096 Aug  5 23:45 php_sessions
</pre>

<p>We have to let PHP know where to store the sessions in future. Open
php.ini and search for a directive called 'session.save_path':

<pre>
  session.save_path = /var/spool/php_sessions/
</pre>

<p>Restart your webserver to commit these changes ("apachectl graceful" with
  apache).</p>

<h3><a name="5">5. Customization</a></h3>

<h3><a name="5.1">5.1 Templates</a></h3>

<p><i>vmmi</i> allows you to entirely customize its look by creating
  templates. I suggest you to make a copy of ./templates/default/ and apply
  modifications to it, though, rather than starting from scratch.</p>

<p>All HTML is stored in template.html and all images/CSS files/flash files
  have to reside in the same directory. To enable your template, open config.php
  and look for:</p>

<pre>
  $template = 'default';
</pre>

<p>This name corresponds to the directory name you just created. Supposed your
  template is stored in ./templates/foobar/ your config should look like this:</p>

<pre>
  $template = 'foobar';
</pre>

<p>There is some additional <a href="http://daniel.lorch.cc/projects/templates/" target="_blank">information
  on the template engine</a> on my website, if you're interested. The pages are built up like this:</p>

<p><b>Login screen</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| index_header           |
+------------------------+
| index_welcome          |
+------------------------+
| index_language_element |
+------------------------+
| index_login            |
+------------------------+
| index_footer           |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>Main screen</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| main_header            |
+------------------------+
| navigation             |
+------------------------+
| quicksearch            |
+------------------------+
| main_table_start       |
+------------------------+
| main_table_element     |
+------------------------+
| main_table_end         |
+------------------------+
| main_catchall_start    |
+------------------------+
| main_catchall_element  |
+------------------------+
| main_catchall_end      |
+------------------------+
| main_footer            |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p>Required images: image_edit, image_remove, image_account, image_alias, image_edit,
  image_remove</p>
  
<p><b>Search</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| main_header            |
+------------------------+
| navigation             |
+------------------------+
| quicksearch            |
+------------------------+
| quicksearch_result     |
+------------------------+
| main_table_start       |
+------------------------+
| main_table_element     |
+------------------------+
| main_table_end         |
+------------------------+
| main_footer            |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p>Required images: image_edit, image_remove, image_account, image_alias, image_edit,
  image_remove</p>

<p><b>Add Account</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| add_account_header     |
+------------------------+
| navigation             |
+------------------------+
| add_account_form       |
+------------------------+
| add_account_footer     |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>Add Alias</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| add_alias_header       |
+------------------------+
| navigation             |
+------------------------+
| add_alias_form         |
+------------------------+
| add_alias_footer       |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>Settings</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| settings_header        |
+------------------------+
| navigation             |
+------------------------+
| settings_form          |
+------------------------+
| settings_footer        |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>User Account</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| user_account_header    |
+------------------------+
| user_account_form      |
+------------------------+
| user_account_footer    |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>User Alias</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| user_alias_header      |
+------------------------+
| user_alias_form        |
+------------------------+
| user_alias_footer      |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>Error</b></p>

<pre>
+------------------------+
| header                 |
+------------------------+
| error_header           |
+------------------------+
| error_message          |
+------------------------+
| error_footer           |
+------------------------+
| footer                 |
+------------------------+
</pre>

<p><b>Note:</b> All pages have the common header/footer parts, and also their own
  page_header/page_footer. You can also do a `grep \$parts filename.php` to see
  what template parts are used in a particular file.</p>

<h3><a name="5.2">5.2 Language Files</a></h3>

<p>Currently available languages:</p>

<div align="center">

<table width="450" bgcolor="#CCCCCC" cellspacing="1" cellpadding="3">
<tr>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>Language</b></td>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>Contributed by</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">Deutsch</td>
  <td bgcolor="#FFFFFF" align="center">Daniel Lorch</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">English</td>
  <td bgcolor="#FFFFFF" align="center">Daniel Lorch</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">Français</td>
  <td bgcolor="#FFFFFF" align="center"><a href="http://david.scarged.net/" target="_blank">David Rivier</a></td>
</tr>
</table>

</div>

<p>Language files are stored in ./languages/ using the INI-format. When creating
  new language files you first have to open ./inc/common.php and look for an 
  array that looks like this:</p>

<pre>
  $available_languages = array(
    'de' => 'Deutsch',
    'en' => 'English'
  );
</pre>

<p>This array tells <i>vmmi</i> what languages are available. The array key
  corresponds to the filename + ".lang". Now before you start working on a
  translation you might want to <a href="mailto:hide@address.com?vmmi-translation">
  ask me</a> whether someone is already working on your language.</p>
  
<p>Supposed you want to create a japanese translation, first add this language
  to the array shown above:</p>

<pre>
  $available_languages = array(
    'de' => 'Deutsch',
    'en' => 'English',
    'jp' => 'Japanese'
  );
</pre>

<p>And now create a copy of 'en.lang' to 'jp.lang'. The first few lines require
  some explanation:</p>

<pre>
  [author]

  name   = Daniel Lorch
  e-mail = hide@address.com
  web    = http://daniel.lorch.cc/

  [language]

  name     = English
  encoding = iso-8859-1
</pre>

<p>The author-section is obvious: Enter your contact info for credits. The
  "encoding" part is the character encoding inserted in the header of every
  HTML file. Here's a list: </p>

<pre>
  utf-8 (Unicode, worldwide)
  iso-8859-1 (Western Europe)
  iso-8859-2 (Central Europe)
  iso-8859-3 (Maltese)
  iso-8859-4 (Baltic Rim)
  iso-8859-5 (Cyrillic)
  iso-8859-6-i (Arabic)
  iso-8859-7 (Greek)
  iso-8859-8-i (Hebrew)
  iso-8859-9 (Turkish)
  iso-8859-10 (Latin 6)
  iso-8859-13 (Latin 7)
  iso-8859-14 (Celtic)
  iso-8859-15 (Latin 9)
  us-ascii (basic English)
  euc-jp (Japanese, Unix)
  shift_jis (Japanese, Win/Mac)
  iso-2022-jp (Japanese, email)
  euc-kr (Korean)
  gb2312 (Chinese, simplified)
  big5 (Chinese, traditional)
  tis-620 (Thai)
  koi8-r (Russian)
  koi8-u (Ukrainian)
  macintosh (MacRoman)
  windows-1250 (Central Europe)
  windows-1251 (Cyrillic)
  windows-1252 (Western Europe)
  windows-1253 (Greek)
  windows-1254 (Turkish)
  windows-1255 (Hebrew)
  windows-1256 (Arabic)
  windows-1257 (Baltic Rim)
</pre>

<p>If you don't know which one to pick just leave it blank and I'll fill it out for
  you. If you want to share your translation with the community, just
  <a href="mailto:hide@address.com?subject=vmmi-translation">send it to me</a> and
  I'll include it with the vmmi package.</p>

<h3><a name="6">6. Showcase mode</a></h3>

<h3><a name="6.1">6.1 Introduction</a></h3>

<p>The showcase module imitates the behaviour of the VMailMgr daemon. This is
  useful for:</p>

<p>
&bull; Showcases (demonstration of <i>vmmi</i>)<br>
&bull; Creating templates / writing language files on an environment where no
  VMailMgr daemon is available
</p>

<p>Because the showcase module fakes all functions of VMailMgr there is no need
  for a daemon and there is absolutely no risk involved, as all changes applied
  only happen virtually - the users can mess around as much as they like. To
  enable the showcase module you have to make vm.php point to another file.
  vm.php is a softlink pointing to the module which should be used:</p>

<pre>
  cd vm
  ln -sf vm.showcase.php vm.php
</pre>

<p>If you'd like to go back to the <i>real</i> mode again, just make vm.php point
  to vm.interface.php, which is the real interface:</p>

<pre>
  cd vm
  ln -sf vm.interface.php vm.php
</pre>

<p>The default domain and password is demo.com/demo.</p>

<h3><a name="6.1">6.2 Customization</a></h3>

<p>Open ./vm/vm.showcase.php in your favorite editor. There is an array called
  $_SESSION['userlist'] with some demo data (Peter and Linda). This is the
  initial setting of what people will see when they log in.</p>

<p>To change the domain/password scroll down some lines where it says:</p>

<pre>
  /* configuration part */
  var $my_domain = 'demo.com';
  var $my_pass   = 'demo';
</pre>

<p>I also suggest you to modify the HTML template to automatically insert the
  domain/password so the users don't have to type it in. Open ./templates/default/template.html
  and go to section 'index_login' and add 'value=' parameters to the text input fields:</p>

<pre>
  &lt;input type="text" name="form[domain]" class="text" <b>value="demo.com"</b>&gt;&lt;br&gt;
  ..
  &lt;input type="password" name="form[password]" class="text" <b>value="demo"</b>&gt;&lt;br&gt&lt;br&gt;
</pre>

<p align="center"><small>by <a href="http://daniel.lorch.cc/" target="_blank">Daniel Lorch</a> 2002</small></p>

</body>
</html>
Return current item: Virtual Mail ManaGer Interface