I’m new to Objective-C and programming for OS X in general, but I get frustrated when all articles, books and tutorials narrow themselves down to just one IDE and push you away from the glory of the command line. So how do you compile a simple “Hello World!” application in objective-C on a Mac?

This is a brief “Hello World!” tutorial for ObjC, on top of demonstrating the build process beyond XCode.

We’ll create a class called “Talker” which simply says things we tell it to, then we’ll run it from our main() function.

Create your directory structure

Simple enough. Make yourself a directory called “HelloWorld” or something like that, then create a sub-directory called “build”.

Create the interface and implementation files

HelloWorld/Talker.h

HelloWorld/Talker.m

Create your main() file

HelloWorld/hello.m

Compile it with gcc specifying -framework Foundation

Run it!

Enjoy :)

WordPress appears to have removed some formatting whitespace from my code, but it will still compile.

jMock provides only 3 different actions for returning values by default. There’s ReturnvalueAction which returns a reference to the object you give it, ReturnDefaultValueAction which returns a basic default matching the required type and ReturnIteratorAction which returns re-usable Iterator instances. ReturnIteratorAction was created to tackle a very similar problem.

When you use ReturnValueAction (or the returnValue() method of org.jmock.Expectations) you simply get a reference to your object. This means that for Iterators and Enumerations, once they’ve been iterated over they’re completely exhausted, or if you partially iterate over one your remaining tests will provide unpredictable results.

The objective here is to provide a cloned Enumeration every time you invoke the mocked method. Here’s how I did it:

(Apologies for the syntax highlighting. Not sure what GeSHi is doing with it).

You use it like this:

Hopefully this helps a few people :) I had googled for a solution before writing this and didn’t see any code despite several queries about it.

The idea behind a filter chain is that you create a container (the chain) which holds a series of strategies (filters). Each filter is called in turn and is passed a reference to the chain so that it can tell the chain to continue to the next filter. Anything one filter does to the object(s) it is passed should be available in subsequent filters.

I’m going to demonstrate an example by passing a pseudo request and response object along a chain during or before the routing phase in a controller.

test.php

FilterChain.php

Filter/Foo.php

Filter/Bar.php

Filter/Zip.php

The Request/Response classes I’ve used are only pseudo, but the code is available at the end of this article if you need to see them.

When we run that code we see this:

Each filter simply asked the chain to keep going, which is merely a case of array_shift()’ing the next filter and running it.

Now lets take a scenario where one of our filters is looking to break the chain on a certain condition.

Filter/Bar.php

Let’s test the theory this filter chain will go no further than the “Filter_Bar” stage if we set “module” to anything other than “good”.

Here’s the modified test.php.
test.php

Low and behold, the chain stops as we expect!

Now let’s see the beauty of the fact this is a chain. Maybe one of our other filters is there to try and correct problems with badly requested modules? It’s not a realistic example, but here goes anyway.

Filter/Foo.php

And the result now:

It’s a pretty simple pattern really, but one that comes in handy at times. You’ll see this exact same pattern used in Java servlet containers before the requested servlet is actually dispatched :)

* Here’s the Request/Response classes for those who wanted to see them (pseudo):
Request.php

Response.php

Unicode improvements aside, namespacing is something I’ve longed for in PHP for a long time. It’s not a rocket-science approach they’ve taken; effectively the implementation just prefixes the current namespace onto class and function names which are now permitted to contains the double-colon (::) syntax in their names.

You can achieve an almost Java-like package handling system by using __autoload() (or the SPL alternative) though.

My experimentation thus far is this:

autoload.php

Foo/Thing/Example.php

Foo/Thing/AnotherExample.php

Bar/Example.php

test.php

And the output…

It’s certainly a step in the right direction, but (and let’s not be too cruel — it only appeared in the past few weeks!) some quirks I have noticed.

1. You cannot import both Foo::Thing::Example and Bar::Example inside the same file. You need to use the full name for at least one of them.
2. No warnings are generated if you try to use something which doesn’t exist (No::Such::Namespace)
3. It’s not possible to import everything by wildcard (import Foo::Thing::*;) but I can live with that since it usually leads to poor programming

I’m looking forward to seeing how this pans out :)

To put it simply, a Front Controller is a gateway to an application. All requests hit the front controller leaving it to decide what to do next. Typically a front controller will set up the session, connect to the database and delegate requests to numerous page controllers (or action controllers). Everything that happens here is program flow logic.

You could create a really basic front controller by putting a simply switch() statement inside an index.php file:

Ths sort of procedural programming works, but I’ll try to convince you of the benefit of creating even a simple website in an object oriented fashion. The code we’ll produce to power an extremely scalable and flexible controller architecture should take no more than a couple of hundred lines. Of course, once you have the groundwork down it’s up to you how much fluff you begin to add to make it even more magical ;)

The object oriented approach

Typically a front controller will be a class with a known method name invoked to “launch” the application. We’ll call this class “FrontController” (can’t think why!) and we’ll name it’s dispatcher method “dispatch()”. Let’s start basic and add complexity as we progress. Usually an application powered by the Front Controller pattern will appear to have virtually no logic in its index file.

Some groundwork

index.php

FrontController.php

pages/guestbook/GuestbookActions.php

Now open up your browser and point it to http://localhost/index.php?page=guestbook&action=index

You should see “Index action called…”.

Change the URL to http://localhost/index.php?page=guestboook&action=createPost

Nice eh?

Ok, well we can do better than this. I mean, we don’t really want to be outputting stuff in our controller classes. That sort of logic should be inside a template. For our guestbook above we’ve got “index” and “createPost” actions. Lets’ make some templates associated with each of those actions.

Introducing the view

We’ll make some templates at pages/guestbook/indexView.php and pages/guestbook/createPostView.php. This is painfully straightfoward really.

pages/guestbook/indexView.php

pages/guestbook/createPostView.php

Now lets get these files included from our front controller. For now I’m just going to modify the dispatch() method a little bit.

Now lets just remove that yucky output from the action controller ;)

You should basically have the same results as before when you accessed those earlier URLs in your browser, except now our presentation logic is in the right place.

As it stands all we’ve done is introduced some naming conventions and gotten our website to run a contoller method before it includes our usual file. So how do we get some variables into the template? I’m going to add some logic to the GuestbookActions class which I’d like to be available to other action controllers. Time to refactor a little.

Passing data to the view

The first change I’d ike to make is to ensure all action controller classes can share some common features. I’ll create an ActionController class and I’ll make it abstract because it should only extended, not instantiated. I’ll move the responsibility for running it’s own action into this class too. This should clean up our front controller a little.

ActionController.php

Now we can tidy up the dispatch() method in our front controller.

Now if we make our GuestbookActions class extend the ActionController class we can get it to pass data into the template ;)

Cross your fingers and hope it works.

pages/guestbook/indexView.php

pages/guestbook/createPostView.php

Did it work? :)

Ok, great, for me personally I’d get sick of typing setVar() and getVar() everytime I want to make something available to the view so I’m going to add in a controversial setter/getter system. We’re using PHP 5 right?

The __set() and __get() methods are invoked whenever you try to access a property that doesn’t exist.

ActionController.php

Now in our GuestbookActions class we can simply pass data to the view by assigning it to non-existent properties.

This is great, it works nicely and we’ve got a clean separation of presentation logic and controller logic. One thing that’s missing though is a common featureset available to all components which form part of the controller layer. The controller layer will usually contain methods for getting a handle on the database, getting the request & response objects and getting the session. I’m not going to write all the code out for those components because I’m sure you can use your imagination so I’m just going to add some pseudo code at this point.

All controllers belong to the controller layer

Lets make an abstract class called quite simply “Controller”. Here we can add anything which needs to be available everywhere in the controller layer.

Controller.php

Just change FrontController and ActionController to extend this class and we’ve provided a complete new set of features everywhere in the controller layer.

FrontController.php

ActionController.php

There’s just one last thing I’d like to to introduce which sets this sort of architecture apart from procedural programming. Wouldn’t it be nice if t wasn’t only the front controller who could dispatch actions at runtime? I mean, it would be pretty cool if we could forward our request from one action controller to another right?

Enhancing program flow at the controller level

Imagine in our guestbook we block users temporarily if they submit more than say 2 posts in a minute. We could redirect away from our “createPost” action and send them to a “tryLater” action, but then the browser would have taken them away from the page. No, we can infact make this far more streamlined and “forward()” from one action to another.

We just created our Controller class, so why not stick a forward() method in there and rather than have FrontController locate and dispatch the action, we’ll get it to forward() to it. Effectively I’m just refactoring code here.

Controller.php

I’ve just moved the code and added a call to exit(), but now see what we can achieve.

Simplfy our Front Controller:

I’m not going to write the logic for tracking how many times the user has posted in the past minute I’ll just show that you can direct the flow of the application by invoking forward() from the action controller classes.

Add a new template:
pages/guestbook/tryLaterView.php

Beautiful! This sort of layout provides an immense amount of flexibility for creating highly scalable websites. Of course, this is only the groundwork but it should be enough to give you an understanding of the front controller design pattern (and aspects of MVC). Go away and play with the code. Starting by writing the code for getRequest() and getResponse() would be an idea ;)

This is perfectly sufficient if “joe” has a user account on that server (i.e. a record in /etc/shadow or /etc/passwd) and if that server does not belong to any domains other than “exmaple.com”. However, when you’re running a single server with perhaps only one IP address mapping to several domains and you want to have a different set of email addresses for each domain this becomes a problem. You may also want to have email addresses such as sales@yourdomain.com and support@yourdomain.com but you don’t need system accounts called “sales” and “support”. In this case we need to start hacking at the mail server configuration in order to allow the delivery of the email.

I have no doubts whatsoever that Exim4 (Exim4 is significantly different from Exim3!) is the best MTA/MX software to use for things like this. In fact, I would hands down say that you should use Exim for any MX server. It’s advanced, and very complicated to get working I’ll give it that. But with the complexity comes great flexibility. You can practically program the entire configuration and can modify the behaviour almost without restriction.

Lets not forget however, that your IMAP or POP3 server also needs to be hackable if you really want this to work. For years I used a patched version of UW-IMAP which did the job nicely but there was no configuration avaliable for it and whilst easy to get running this way, it was too restrictive because it tied me down to fixed paths and directory layouts. UW-IMAP also would not work with Maildir setups without even further patching. This article will focus on an IMAP/POP3 server called Dovecot. Dovecot has a very flexible configuration just like Exim, albeit much simpler to make sense of! However, the principles of virtual email hosting apply whichever software you use.

It’s very unlikely that there will not already be packages for exim4 and dovecot provided by your linux distro. If you can do so, install the packages as provided by your distro. If your distro does not provide suitable packages you can get them here:

• Exim4:
  • Website: http://www.exim.org/
  • Documentation: http://www.exim.org/docs.html
• Dovecot:
  • Website: http://www.dovecot.org/
  • Documentation: http://wiki.dovecot.org/

Who is that article targetted at?

This article from hereon in will assume you have a solid grasp of linux server administration, but not necessarily a deep understanding of Exim or Dovecot. If you’re not comfortable working on a linux server, editting configurtion files and making educated guesses then this article will likely be of no help to you.

Any Linux admin will know that this article is not going to give you copy and paste configuration directives (though if you’re lucky it might do) because linux package maintainers love to over-complicate things by adding their own sprinkle of salt to the configuration. I set this up on a Debian (sarge, then subsequently etch) server, however I have set this up in almost the same manner on a Gentoo server and an ArchLinux server previously. You may find that what’s written here does not directly apply to your situation but if you read the entire article rather than just the configuration excerpts you should be able to apply the principles on your own server.

Ok, lets go!

Principles involved

Traditionally, both SMTP and IMAP/POP3 will look in /etc/passwd or /etc/shadow for users. This actually works really well so we virtually copy this approach, except we provide a different passwd file for each domain we need to support. Although this article does not delve into it, both Exim and Dovecot will allow you to store your users in other ways; in a database such as MySQL for example.

passwd files are structured like this:

gecos, shell and extra are ignored in our case so they’ll appear empty, though the surrounding colon will appear.

For example, if “fred” on your server (UID=1001, GID=100) owns the domain “example.com” and wants a new email address setting up called “pete@example.com” there might be a file located at /etc/vmail/example.com/passwd with the contents:

From this we can check if pete is found in the passwd file for example.com, we can also see the uid, gid and home directory of pete, the domain owner. This is enough information for us to save the incoming email.

A domain can have multiple users, and if two domains have the same user it does not mean they are the same email account. In order to determine where the mail goes, the home directory part in the passwd file will specify where the email gets saved. passwd files also conveniently provide UID and GID values so the mail can easily be saved with the correct permissions!

In this article we’ll look at how to store passwd information in directories we’ll create at /etc/vmail/ (i.e. /etc/vmail/domain1.com/passwd, /etc/vmail/domain2.tld/passwd) and save emails to mbox style files at ~/mail/domain.tld/user/inbox (i.e. ~/vmail/example.com/joe/inbox).

This makes the assumption that each domain is owned by one of your system users. A single system user could, for example be a specially created account called “vmail” to manage all virtual domains. However, you can allow individual users to administer their own domains since emails are stored in the $HOME directory of the allocated domain owner.

Both Exim and Dovecot will read from the same passwd files for this to work so we hack them both in a similar fashion. By the way, when I say “hack”, these systems have been written with the intention of being hacked ;)

Defining your first virtual domain and user

Create a directory named /etc/vmail.

Within that, create a directory for a domain which has a MX record pointing to your server (make sure it’s all in lowercase).

Now create a passwd file in there containing the username in the address and the uid, gid, home directory of the owner. Don’t worry about the password bit just yet. I’m just setting it to “xxx” here because incmoming mail does not require a password. You’ll see why pete@example.com cannot log in with the password “xxx” until we change this later.

The remainder of the article will make use of this file.

Now create the place where these emails will be stored (in fred’s $HOME directory).

Of course, if you’re going to be doing this regularly you’d write a tool for creating such files since it can be quite tedious. I may post a command line tool myself, but as it stands I still do it by hand.

Setting up Exim

Be very sure that you have installed Exim4, not Exim3. Also make sure that any other SMTP server software has been removed to prevent conflicts; remember to look in inetd or xinetd if you’ve never checked there before.

There are two ways to install Exim4. You can install with a single configuration file exim.conf, or you can install with separate smaller config files in a conf.d style layout. I advise using the latter option in the interest of maintainability, but this article will apply either way. The single config file is simply a glued-together version of the conf.d layout.

The single config file will most likely reside at /etc/exim4/exim.conf. Inside that file there are sections which start with the keyword “begin”; for example “begin transports” and “begin routers”. These are where the conf.d style layout gets broken down. The conf.d style layout places sub-directories in /etc/exim4/conf.d. For example; /etc/exim4/conf.d/transport, /etc/exim4/conf.d/router etc.

Once you have Exim installed, check the daemon actually runs by starting it from /etc/init.d or /etc/rc.d. You should be able to telnet to localhost on port 25, getting a greeting message beginning with “220″. Type “QUIT” to end the session.

If telnet could not connect on port 25, or you get a greeting beginning with anything other than “220″ something has gone wrong with your installation. Unfortunately this article cannot delve into possible causes for the sake of brevity, but needless to say, you should consult the exim documentation. One really obvious thing to check would be the “local_interfaces” line in the configuration ;)

Exim has four major areas in its configuration:

1. General; contains information such as what interface to listen on, what domains belong to the server and who can relay through it. Essentially the general configuration sets up variables which are used in the other areas of the configuration.
2. ACLs; programmed logically to determine what happens at each stage in the SMTP processing. For example you can check if the sender is trying to spoof an address or if relaying should be denied from within the ACLs.
3. Transports; specifies how the emails should be delivered (written to a file on disk, added to a database, relayed to another server etc).
4. Routing; determines which transport should be used.

Apart from the General configuration, Exim is configured almost entirely by a series of expressions and conditions. For programmers this might feel normal, but for non-programmers it can be a bit daunting.

We’ll work backwards here so you can more easily see the chain of how it all ties together.

The transport configuration

mbox files which we’re going to write to use a standard Exim driver called “appendfile”. You can add new transports to Exim by simply adding a new transport declaration. For the most part we can base the virtual domain transport on the mbox local transport. If you use a single exim.conf file, scroll down to the transports section inside it. If you use the conf.d layout, create a new file in /etc/exim4/conf.d/transport/virtual_transport (the name you use is up to you).

Now, add the following transport to the configuration:

I accept that it looks extremely complicated. It is complicated. But lets break it down a bit and suddenly it seems less intimidating. The lines ending with a backslash are just partial lines. The backslash indicates the whatever is on the following line should be appended to it. You can remove the backslashes and place everything on on line if you wanted to but I find it harder to read.

The first line, “virtual_mail_spool:” specifies that you are declaring a new transport method. You can rename this to suit your needs.

The following lines provide settings for the transport. Lets break the rest of it down because it looks pretty scary right? :)

appendfile is the standard mbox driver in Exim. If you used a Maildir (multiple files) instead of mbox then you’d have to include an additional “maildir_format” line too.

Ok, I know, I know. WTF is that?! Overall, the line specifies the user permissions (username or uid) under which to write the file. In this case it pulls out the uid from our passwd file.

The curly braces are used to set the order of precedence and to group expressions together. The opening ${ indicates that what follows needs to be expanded/evaluated.

The variables in there, $local_part and $domain are provided by exim. For an address pete@example.com, $local_part = pete and $domain = example.com.

The first ${extract{2}{:}{ .. stuff … }} tells Exim to split ” … stuff … ” at every “:” character and then pull out the third chunk (indexing starts at zero). For a single line in the passwd file this will directly extract the uid number.

Looking at ” … stuff … ” we’ve actually got the expression ${lookup{$local_part}lsearch{/etc/vmail/$domain/passwd}}. This finds a single line in the passwd file.

${lookup{ … keyword .. }lsearch{ … file … }} is the bit which finds the line in question. Here it’s looking for the file at /etc/vmail/example.com because $domain = exmaple.com. It then looks for the line starting with “pete”, thus giving us the correct line in the file and allowing the extract{}{:}{} to provide the correct uid.

If you understood how “user” was written, then this should hopefully make sense. As menioned earlier we want to save files at ~/mail/domain/user/inbox.

This finds the home directory of the domain owner, then appends “/mail/example.com/pete/inbox” to it. It specifies the location of the mbox file to which the mail will be saved.

This is structurally identical to the “user” line. It pulls out the gid of the domain owner from the passwd file.

Finally, the line “mode = 0700″ provides the permissions mode to write the file in. 0700 gives full access to the owner and no access to anybody else.

Summarising all that in plain English it: checks which system user should own the email, determines what file to write the email to, checks which group the owner is in, specifies the permissions on the file to be 0700 (-rwx——).

This is enough for our transport configuration. However, the transport will never actually be used until a router points to it so we now need to create a router.

The router configuration

Essentially a router is just a set of conditions which, if evaluate true cause Exim to honour the transport it points to. Our router will need to check if the user and domain are valid for our virtual configuration. This is a simple case of looking to see if a directory exists for the domain in /etc/vmail and if the user line can be seen in the passwd file for that domain.

If you use a single exim.conf file, scroll to the top of routers section. If you use a conf.d layout, create a new file at /etc/exim4/router/virtual_user. Exim actually loads files in alphabetical order so you might want to prepend the filename with a number to cause it to be loaded before the other files in a conf.d setup.

Add the following to your configration:

The first line, “virtual_user:” declares that we are creating a new router. You can call this whatever you like, the name is irrelevant provided it’s unique.

The line “driver = accept” specifies that this router can only be used if the email was accepted by the ACLs (we’ll look at this later).

This line specifies which domains this router applies to. You could hard-code a list by writing “domain1.com : domain1.org” etc etc, but that would not be easily extendible. “dsearch;” is an expression which returns all files in the directory following the semi-colon. In our case this line evaluates to all domains we virtual host for because that’s what the directories in /etc/vmail are.

This line must evaluate to “true” (or “yes”) if the router is to be used. It looks for a line for the user in the passwd file. If one is found then the condition returns “yes”. If none is found then the condition returns “no” and this router will not be used.

Finally, this specifies the transport we created previously. It tells Exim that if the conditions are true our new transport should be used. If you used a different name for the transport remember to modify this line accordingly.

Summarising this in plain English it says: Only use this router if the mail was already accepted and the domain is a virtual domain in /etc/vmail. If the user cannot be found in /etc/vmail/example.com/passwd, this router should not be used (unroutable address). The transport this router directs to is “virtual_mail_spool”.

Nearly done! Just one quick test

Start (or restart) the Exim4 daemon running from /etc/init.d or rc.d you should be able to telnet to it on port 25. Issue the following commands:

You should see something like this:

Assuming everything’s working you should get something similar to that above. If you’re not getting this then something has gone wrong.

If it worked, you should see a file at /home/fred/mail/example.com/pete/inbox. If you open this file it will contain the email.

This is great, it works! If you have MX records for example.com pointing to this server the server will happily accept mail for the virtual user pete@example.com. Of course, there’s no way to read these emails remotely as yet, unless of course you SSH to the server and open the inbox file directly.

Wait, there’s something else we need to do. If someone tries to email “no-such-user@example.com” they will get the same result during SMTP, but they’ll later get a bounced email because no router was found for “no-such-user” after it was accepted. This is quite normal and I’m sure we’ve all had lots these emails in our inboxes over time. However, if you’re providing email for a lot of domains this would be wasting valuable bandwidth.

Defining a new ACL

It’s possible to deny a request at the “RCPT TO:” phase in SMTP. In order to do this we create a new ACL (access control list). Our ACL will check if the domain is a vitual domain, and will then check that it can find a user for that domain. If it is a virtual domain but no user exists, the ACL will deny the command, thus giving a 550 response.

ACLs are a series of rules. Each ACL ruleset is evaluated in order until a conclusive result has been decided (accept, or deny). In reality there are other results such as “warn” and “require” but we don’t need to delve into them here.

If you’re using the single exim.conf file scroll to the ACL section. For the conf.d style layout, create a new file at /etc/exim4/conf.d/acl/check_virtual_rcpt. Now add the following to the configuration file:

The first line, “acl_check_virtual_rcpt:” defines that you are creating a new ACL ruleset.

The line “deny” specifies that the conditions which follow are assessing whether to deny the request. If all the following conditions evaluate true the request will be denied (our 550 response in RCPT).

This is simply a message which will be displayed in SMTP. You can change it to something like “Sorry, I don’t know about this user” if you really wanted to. If the request is denied the error will say “550 Unknown Recipient” in our case. I think this is quite sensible ;)

As with our router configuration, this line indicates that the ruleset only applies if the domain is a virtual domain found in /etc/vmail.

This is actually the same line I used in the router, except for the leading “!’ character. It looks to see if the user is found in the passwd file. If the user is in the passwd file the condition returns true. However, the “!” before the “condition” keyword indicates that the response should be negated, so if no such user is found, the line evaluates to “yes” rather than “no” and therefore all conditions were satisfied which concludes that the request should be denied.

The final line “accept” simply indicates that if the request was not denied, our ACL ruleset can accept the email. However, another ruleset somewhere else may still deny it ;)

As it stands, Exim does not know to run our ACL yet. In order to do that we need to specify it with the existing ACL for “acl_smtp_rcpt”. Go to the general configuration section and find the line starting with “acl_smtp_rcpt = “. If no such line exists, create it, but before any “begin” sections in the configuration file. For example, the line might look like this:

This line basically tells Exim that during the RCPT phases in SMTP it should carry out the ACL checks defined in the “acl_check_rcpt” ruleset. If there isn’t a line already there then simply set “acl_smtp_rcpt = acl_check_virtual_rcpt” and nothing more is needed. If there is a line there, look at what is assigned to it (acl_check_rcpt for example), then find that acl ruleset. At the top of the ruleset it points to, add these lines:

That basically gets the other ACL to run the checks in your ACL too.

Restart exim and try running those SMTP commands over telnet again, this time replacing the address in RCPT TO with “nobody-here@example.com” You should get an immediate “550″ response. This is good. It will cut out a lot of wated bandwidth from bounced messages when spammers start sending emails to addresses that don’t really exist.

That’s it for the Exim configuration. Phew! Now we need some way to allow our users to open up their inboxes remotely. Thankfully the Dovecot configuration is far less complicated than the Exim configuration ;)

Setting up Dovecot

Make sure you have uninstalled any other imap servers which may be present on your system. Remember to check in inetd or xinetd if you’ve never checked there before ;)

Unlike Exim which is seriously complicated to configure unless you’re a programmer (like myself), Dovecot is a lot friendlier. It’s still flexible enough for our needs but for the most part, getting it to do what we want is trivial. The main dovecot configuration is stored in a single file at /etc/dovecot/dovecot.conf.

Making dovecot listen for IMAP requests

The first thing you want to do is edit the line starting with “protocols =”:

Now we’ll just run a quick test to make sure it’s working. Start (or restart) dovecot from /etc/init.d or rc.d. The telnet to localhost, port 143. You should get a Dovecot greeting. Type “a01 LOGOUT” to end the session:

If telnet cannot connect, or if you get some sort of error message then your imap installation is not working correctly. You’ll need to consult the dovecot documentation for further help before continuing with the configuration.

Specifying the mail location

Like Exim, Dovecot provides some variables for us to use. Scroll down to the section “Mailbox locations and namespaces” then edit the line starting with “mail_location = “:

This is actually pretty straightforward. “mbox:” defines that we’re using mbox files rather than maildir. If you use maildir you’re change it to “maildir:”. %h is the variable for $HOME of the domain owner. This is /home/fred in our example. %d is the domain name and %n is the local part of the address (i.e. for pete@example.com; %n = pete, %d = example.com).

Make sure Dovecot is going to use the correct file permissions (0700, the same as Exim) by specifying, in the “Mail processes” section:

Configuring the login process

We’ve already got a passwd file for pete@example.com which we created earlier. Dovecot can use this just like Exim can. Dovecot does however need to know what pete’s password is. Up until now we haven’t considered what goes in the password part of the passwd file. The official passwd/shadow format expects a hashed password as returned by crypt() with a salt. Dovecot allows you to use plain text passwords however. I’m not condoning the use of plain text passwords, but for the sake of simplicity in this article I’ll show you how it’s done.

Open up /etc/vmail/example.com/passwd.

Edit the “xxx” part where the password should be to say:

The {PLAIN} part at the start of the password specifies that the password is stored in plain text. In this case, pete can log in with the username “pete@example.com” and the password “petes-password”. If you don’t specify the {PLAIN} part then the password will be assumed to be hashed with crypt(). There are tools available for producing such hashes and in the interest of security it would be advisable to do this.

Now scroll down the the “Authentication processes” section in dovecot.conf. Edit the line starting with “auth_username_format”.

This causes usernames to always be in lowercase.

Inside the block starting with “auth default {” make sure “plain” is in the list of mechanisms.

Without this our {PLAIN} part in the passwd file will not work.

There are two phases in authentication: Password verification, and user lookup. These are called “passdb” and “userdb” in dovecot. Scroll a little further down in the configuration and change the section “passdb passwd-file {”.

This specifies that for verifying passwords, dovecot can look in our passwd file for the virtual domain. Notice the %d variable in there again. “deny = no” specifies that dovecot should grant access if the password matches.

Now scroll a little further and edit the section “userdb passwd-file {”:

This simply allows dovecot to use the same passwd file to find the user information after verifying the password. We should be done now :)

A final test!

Restart dovecot. Now try to telnet to localhost on port 143 again. This time logging in as “pete@example.com” with the password “petes-password”. Then we’ll try selecting pete’s inbox. The command sequence is:

You should see something like this:

Notice the line “* 1 EXISTS”. This is the email we sent when we were testing Exim. This means it worked! If you see “0 EXISTS” or you cannot actually log in then something has gone wrong and Dovecot is looking in the wrong place for the emails and/or login files.

If you were to try setting up your email client such as thunderbird or evolution using your server as an imap server with those credentials you should be able to read your emails successfully. If someone sends an email to that email address, assuming there’s a MX record pointing it to your server then you should be able to access the email over IMAP.

To add new domains simply create new passwd files in /etc/vmail/domain.tld. To change passwords or add users simply edit the contents of the relevant passwd file.

Good luck! :D

The inspiration I was given in this scenario however was to work with two objects. One which holds the connection, runs the quer