You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-dev@james.apache.org by Apache Wiki <wi...@apache.org> on 2005/07/09 07:34:14 UTC
[James Wiki] Update of "VirtualUserTable" by IvanJouikov
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "James Wiki" for change notification.
The following page has been changed by IvanJouikov:
http://wiki.apache.org/james/VirtualUserTable
------------------------------------------------------------------------------
- James supports Virtual User Tables described by either XML or JDBC. See config.xml for an example. Will probably copy it to here and comment it in more detail.
+ James supports Virtual User Tables described by either XML or JDBC. See config.xml for an example.
+ == THEORY ==
+
+ Before I go into explaining how to set up one of the mapping mailets, I want to explain how they will work. Basically, all that a "virtual user table" does is forward emails. THAT'S it. If you think about it this way, it will be very easy to understand it. All we do is forward emails from one address to another. For instance:
+
+ * james@localhost -> tron@yahoo.com // forward to an outside domain
+ * sales@candy.com -> admin@candy.com // Pretty much set up an alias if candy is local
+ * info@candy.com -> admin@candy.com // Yet another alias
+
+ That's all there is to it. Now the trick is that this simple function allows us to do powerful things, such as having virutal domains.
+
+ Say, we're hosting 2 domains, cars.com and boats.com. Now the owners of both domains want to have "support@" email accounts. Normally, if we created an account "support", both support@cars.com and support@boats.com would be the same email account - and that would be unacceptable. So instead, we can set up the following forwards:
+
+ * support@cars.com -> support..cars.com@localhost
+ * support@boats.com -> support..boats.com@localhost
+
+ Obviously, we have to create two local accounts: "support..cars.com" and "support..boats.com". So, now when you send a support email to cars.com, it would go into a local account "support..cars.com". When you send an email to support@boats.com, the email would go into a local account "support..boats.com".
+
+ Now the whole "support..domain.com" thing is called a '''naming policy'''. It is important to keep and follow a strict policy, otherwise you'll have nightmare trying to manage your email accounts.
+
+ This is really how easy it is to set up virtual domains. There is however, one '''problem''', which I hope will soon be addressed: even though we have separate accounts for support@ email address, the following addresses would still be valid:
+
+ * support..cars.com@cars.com
+ * support..cars.com@boats.com
+ * support..boats.com@cars.com
+ * support..boats.com@boats.com
+
+ They're valid since they're still treated as normal local email accounts. So this is a '''TODO''' and I hope it's addressed soon. It's not really crucial and nobody probably would ever know about it except for the admin, but it still gives me a sense of insecurity.
+
+ == MORE TECHNICAL ==
+
+ Now that you understand the theory, in technical terms it's just as simple as the theory. Currently, there are two implementations of this that I know of - XML (XMLVirtualUserTable) and JDBC (JDBCVirtualUserTable) - both come packaged with james 2.2.
+
+ Both work exactly the same way, except XML gets its entries from the config file, and JDBC gets them from (you guessed) a database. I highly recommend that you use JDBC over XML if you're planning to have more than 10 different email accounts. If you use XML, every time you want to make a change or add something, you'd have to restart the server.
+
+ The entries that both of these mailets accept are:
+
+ user,domain,target_address
+
+ Compare this with our theory:
+
+ user@domain -> target_address
+
+ And that's pretty much all there is to it. If we want to have support@cars.com and support@boats.com, assuming that we use "account..domain.com" naming policy, we would have the following entries:
+
+ * '''User''': support '''Domain''': cars.com '''Target_Address''': support..cars.com@localhost
+ * '''User''': support '''Domain''': boats.com '''Target_Address''': support..boats.com@localhost
+
+ While it seems a bit complicated, in more simple language, the above entries are:
+
+ * support@cars.com -> support..cars.com@localhost
+ * support@boats.com -> support..boats.com@localhost
+
+ And this is all there is to it.
+
+ == JDBCVirtualUserTable ==
+
+ First of all, you should READ the following: http://james.apache.org/FAQ.html#7
+
+ Just read it, but don't do anything about it just yet. I'll walk you through the proccess to the best of my abilities.
+
+ === Setting Up Database ===
+
+ 1. Well first you need a database. I use MySQL (www.MySQL.com), but you can use whatever you want, as long as they have a Java driver. So get and install a database (I'm not going to walk you through this - they have entire books written on the subject; I assume if you're an admin, you should know how to install a database).
+
+ 1. After installing the database, create a db named "mail" or whatever you want to call it:
+
+ {{{
+ create database mail default charset utf8
+ }}}
+
+ 1.#3 Now you want to create a user with privileges on database "mail". I don't create users via raw SQL, I use MySQLCC, so I don't really know what the SQL for that is :(. '''TODO''': fill int the SQL for creating a user.
+
+ 1. Now we want to add the table for mappings:
+ {{{
+ CREATE TABLE VirtualUserTable
+ (
+ user varchar(64) NOT NULL default '',
+ domain varchar(255) NOT NULL default '',
+ target_address varchar(255) NOT NULL default '',
+ PRIMARY KEY (user,domain)
+ );
+ }}}
+
+ Ok we're half way there.
+
+ === Configuring XML ===
+
+ So now we just need to add that mailet in your xml configuration.
+
+ 1. Go to your james home directory (it's inside of whatever your installation folder was, /apps/james/), and go to SAR-INF, and open file "config.xml" (I suggest making a backup copy before editing).
+
+ 1. First of all you want to make sure that inside your "<servernames>" you have an entry "<servername>localhost</servername>". It's not really required since you can forward to any local address, but it's good practice.
+
+ 1. Now let's tell JAMES where our database is. Scroll all the way down to "<database-connections>". There are a couple examples in there that you could use. Here's my setup:
+
+ {{{
+ <data-source name="maildb" class="org.apache.james.util.dbcp.JdbcDataSource">
+ <driver>com.mysql.jdbc.Driver</driver>
+ <dburl>jdbc:mysql://127.0.0.1:3306/mail?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8</dburl> <!-- "mail" is the database name; change it if you used something different -->
+ <user>mail</user> <!-- Whatever the DB user is -->
+ <password>YourPassword</password>
+ <max>20</max>
+ </data-source>
+ }}}
+
+ Now notice there's a "driver" setting, which in my case is MySQL's JConnector driver, which you can find here: http://dev.mysql.com/downloads/connector/j/3.1.html
+
+ Download the driver, and stick the .jar file inside your $INSTALL_DIRECTORY/lib. If you use a different database or have a reason to use a different driver, don't forget to change the "<driver>" setting and put the driver itself on the classpath.
+
+ 1.#4 Notice that the "<data-source>" tag had a "name" attribute. This doesn't have to be "maildb", it can be anything. But stick to maildb as a standard.
+
+ 1. Now let's insert the mailet itself. Scroll up to "<spoolmanager>" and find "<proccessor name="root">". A couple lines below that you should have comments explaining how to set up an "XMLVirtualUserTable" mailet. Right after the "RelayLimit=30" mailet, insert the following:
+
+ {{{
+ <mailet match="All" class="JDBCVirtualUserTable">
+ <table>db://maildb/VirtualUserTable</table>
+ </mailet>
+ }}}
+
+ Note that you can change the "maildb" if your data source had a different name; or VirtualUserTable, if the table you created earlier has a different name. We're almost done.
+
+ === TESTING ===
+
+ 1. Restart the server by running $INSTALL_DIR/bin/phoenix.sh restart
+
+ 1. Let's assume that we have two users named "bob" and "jen", and bob owns "domain1.com" and jen owns "domain2.com". Both want their own name account and "sales@" account for their domains pointing to their names.
+
+ 1. Start by editing your database either by hand or through a GUI client (my pref), and insert a couple entries:
+
+ * '''user''': bob '''domain''': yourdomain1.com '''target_address''': bob..yourdomain1.com@localhost
+ * '''user''': jen '''domain''': yourdomain2.com '''target_address''': jen..yourdomain2.com@localhost
+ * '''user''': sales '''domain''': yourdomain1.com '''target_address''': bob..yourdomain1.com@localhost
+ * '''user''': sales '''domain''': yourdomain2.com '''target_address''': jen..yourdomain2.com@localhost
+
+ 1.#4 Create two users:
+
+ {{{
+ telnet localhost 4555
+ root
+ yourpassword
+ adduser bob..yourdomain1.com bobsPassword
+ adduser jen..yourdomain2.com jensPassword
+ quit
+ }}}
+
+ 1.#5 TADA! Now you should have two users: bob@yourdomain1.com and jen@yourdomain1.com. Emails sent to "jen@yourdomain1.com" will get a user not found message (unless of course you have another mapping for that domain name or a local user named simply "jen", which would break our naming policy).
+
+ Also, emails sent to sales@yourdomain1.com will go to bob's email; all sent to sales@yourdomain2.com will go to jen's email.
+
+ 1.#6 I should note that when giving Bob his login information, you should say the following:
+
+ {{{
+ Your email address is "bob@yourdomain1.com"
+ Your username is "bob..yourdomain1.com" (same as your email address, but with two dots instead of "at")
+ Your password is bobsPassword
+ }}}
+
+ 1.#7 By now you should be finished. It is now fairly easy to create a web-based management system for the accounts.
+
+ === TIPS ===
+
+ 1. Don't forget that besides virtual domains, you use the same approach to forward to outside domains. For instance, if jen from our previous example wanted all emails sent to "CEO@yourdomain2.com" to go to the US president, you would have to add the following entry in the VirtualUserTable table:
+
+ * '''user''': CEO '''domain''': yourdomain2.com '''target_address''': president@whitehouse.gov
+
+ 1.#2 The reason I mentioned that you should have a nameserver "localhost" in the very beginning is because I had some hard times figuring out why the virtual table wasn't working. The problem was my '''target_address''' entries - I'd specify them as simply "bob..yourdomain1.com". Turns out that JDBCVirtualUserTable automatically appends "@localhost" to target_address's that don't have a domain part. And I didn't have the "localhost" in my servernames, and as a result the message couldn't be delivered.
+
+ === TROUBLESHOOTING ===
+
+ 1. The only advice I have here is: read your logs. So far that helped me fix most of the problems.
+
+ 2. Also, don't be afraid to ask questions in the JAMES mail list
+
+ === THANKS ===
+
+ * I want to say thank you to the developers of JAMES; you made a truly great mail server compared with what's out there. Migrating from qmail was like switching from a wooden chair to a nice comfortable leather one. All of a sudden I'm in the driver's seat, I know exactly what's going on, and I'm not scared to mess around.
+
+ * Also I want to say thanks to the JAMES mail list - I couldn't have done it without you guys
+
+ * Special thanks go out to Daniel Perry and Illa Chipitsine for their invaluable help
+
+ == XMLVirtualUserTable ==
+
+ I am not qualified to write this since I haven't used it myself. However, if you read the '''Theory''' and '''More Technical''' sections, you should have no problem whatsoever setting it up. Besides, there are comments in the config.xml that pretty much give you an example.
+