MySQL Setup

Before starting the Hedwig IMAP server, you need to create the hedwig database in MySQL. There are two files in the sql/mysql directory: hedwig-schema.sql and hedwig.mwb.

The hedwig-schema.sql file contains all the CREATE statements required to create the structure of the hedwig database including tables and triggers.

The hedwig.mwb file is a MySQL Workbench data model that you can open within MySQL Workbench.

To install the hedwig database, follow these steps:

• Connect to the MySQL server using the mysql command-line client with the following command:

  shell> mysql -u root -p
  

  Enter your password when prompted. A non-root account can be used as long as the account has privileges to create new databases.

• Execute the hedwig-schema.sql script to create the database structure by using the following command:

  mysql> SOURCE D:/hedwig/sql/mysql/hedwig-schema.sql;
  

  Replace D:/hedwig/sql/mysql/hedwig-schema.sql with the path to the hedwig-schema.sql file on your system.

• Confirm that the hedwig database is installed correctly. Execute the following statements. You should see output similiar to that shown here.

  mysql> USE hedwig;
  Database changed
  
  mysql> SHOW TABLES;
  

  +------------------+
  | Tables_in_hedwig |
  +------------------+
  | hw_acl           |
  | hw_alias         |
  | hw_headername    |
  | hw_headervalue   |
  | hw_keyword       |
  | hw_mailbox       |
  | hw_message       |
  | hw_physmessage   |
  | hw_subscription  |
  | hw_user          |
  +------------------+
  10 rows in set (0.00 sec) 
  

Adding an user

INSERT INTO hw_user(loginid,passwd) VALUES ('[user.email.address]','[password]')

Hedwig automatically creates the mailbox for the user on need. So you don't need to create mailboxes for this user manually.

Deleting an user

DELETE FROM hw_user WHERE loginid='[user.email.address]'

Adding an alias

INSERT INTO hw_alias(alias,deliver_to) VALUES ('[user.alias.address]','[user.email.address]')

Deleting an alias

DELETE FROM hw_alias WHERE deliver_to='[user.email.address]' AND alias='[user.alias.address]'

Configuring the IMAP server

Followings are description of all IMAP configuration parameters.

• compress_after (default: empty)

  Message files are automatically compressed after the configured time. The actual compression is done in a nighty cronjob, which you must set up:

  Time units: y(years), m(months), d(days)

       Example:
       compress_after=3m
  

• expunge_after (default: empty)

  Mails are expunged from mailboxes after being there the configurable time. The actual expunging is done in a nightly cronjob, which you must set up:

       Example:
       expunge_after=INBOX 3m Trash 2m
  

• stop_cron_after (default: 2h)

  Stop disk cleanup cron (which is responsible for compression of message file and expunging mails) after the configured time from it started.

  Time units: h(hours), m(minutes)

       Example:
       stop_cron_after=3h
  

• default_quota (default: 0)

  The default quota for uers in mega bytes. Specify 0 when user has no limit in quota.

• imap_timeout (default: 1800)

  The IMAP socket I/O timeout value in seconds, or zero (timeout infinity).

• imap_thread_count (default: 2 * the number of available processors in the machine)

  The maximun number of IMAP worker threads.

• imap_trace_protocol (default: false)

  The IMAP protocol trace mode. If true protocol trace will be printed to the output specified by the imap_protocol_log parameter.

• imap_protocol_log (default: empty)

  The location of file used for debugging output for IMAP protocol. If empty, the standard output will be used.

Configuring the SMTP server

If you decided to use legacy MTA like Postfix, you dont need to read this section. Instead see Configuring_MTA for more information about the legacy MTA configuration.

SMTP configuration parameters are also controlled via the default.properties file. Before starting the server, you need to configure some parameters to your environment.

Followings are description of all SMTP configuration parameters.

• max_retry_count (default: 3)

  The maximal number of times that a spooled message attempts to be re-sent. If a temporary exception has been caught during transmission, the infrastucture automatically retransmits the message. If a permanent exception is caught, a failure message is sent to the original message sender or postmaster. The retransmission algorithm quadruples the delay with every attempt, which result in approximately 42 minutes passing between the first transmission attempt and the last transmission attempt.

• message_size_limit (default: 10240000)

  The maximal size in bytes of a message, including envelope information. Specify 0 when message size has no limit.

• mydomain

  The internet domain name of this mail system. The default is to use $myhostname minus the first component.

       Example:
       mydomain=example.com
  

• myhostname

  The internet hostname of this mail system. The default is to use the fully-qualified domain name from gethostname().

       Example:
       myhostname=host.example.com
  

• mynetworks (default: see hwadmin mynetworks output)

  The list of trusted SMTP clients that have privileges to relay mail through Hedwig. Specify a list of network address, network/netmask or network/netmask bits patterns, separated by commas and/or whitespace.

  Note 1: If you set the mynetworks to 0.0.0.0/0, the Hedwig acts as an open relay server.

       Example:
       mynetworks=127.0.0.0/8 168.100.189.0/24 168.100.170.0/255.255.255.0
  

• postmaster (default: postmaster@mydomain)

  The sender address of delivery status notification message.

       Example:
       postmaster=postmaster@example.com 
  

• smtp_helo_name (default: $myhostname)

  The host name to send in the SMTP EHLO or HELO command. The default value is the machine hostname.

• smtp_gateway

  SMTP server to be used as a gateway for this server. If this value is set, then all messages with remote recipients will be delivered to the gateway server. The port may be specified in the format host:port.

• smtp_gateway_username

  The username to be passed to the SMTP gateway to establish a connection.

• smtp_gateway_password

  The password to be passed to the SMTP gateway to establish a connection.

• smtp_recipient_limit (default: 0)

  The maximum number of recipients that the Hedwig SMTP server accepts per message delivery request. Specify 0 when recipients count has no limit.

• smtp_sasl_auth_enable (default: no)

  Enable SASL authentication in the Hedwig SMTP server. By default, the Hedwig SMTP server does not use authentication.

• smtp_connect_timeout (default: 5000)

  The Hedwig SMTP client socket connection timeout value in milliseconds. When no connection can be made within the deadline, the Hedwig SMTP client tries the next SMTP server associated with target MX record.

• smtp_timeout (default: 5000)

  The Hedwig SMTP client socket I/O timeout value in milliseconds.

• smtp_trace_protocol (default: false)

  The SMTP protocol trace mode. If true protocol trace will be printed to the console.

• smtp_protocol_log (default: empty)

  The location of file used for debugging output for SMTP protocol. If empty, the standard output will be used.

• smtpd_client_restrictions (default: empty)

  Optional restrictions that the Hedwig SMTP server applies in the context of a client request.

  The default is to allow all connection requests.

  The following restrictions are specific to client hostname or client network address information.

  • permit_mynetworks

    Permit the request when the client IP address matches any network or network address listed in mynetworks.

  • reject_rbl_client rbl_domains

    List of servers that provides real-time black list (RBL) and domain name server black lists (DNSBL). Connections are blocked when the reversed client network address is listed with the A record under these domains.

    Specify a list of rbl domains, separated by whitespace.

    Note 1: If you're running a high-traffic mail server, you'd better setup a local DNS server to catch DNS queries, because free RBL service like zen.spamhaus.org may improperly reply if your server exceed the DNS query limit.

  In addition, you can use the following generic restrictions.

  • reject

    Reject the request. This restriction is useful at the end of a restriction list, to make the default policy explicit.

       Example:
       smtpd_client_restrictions=permit_mynetworks, reject_rbl_client zen.spamhaus.org spamlist.or.kr, reject
  

• smtpd_error_sleep_time (default: 1)

  SMTP server response delay in second after a client has made more than smtpd_soft_error_limit errors, and fewer than smtpd_hard_error_limit errors, without delivering mail.

• smtpd_hard_error_limit (default: 20)

  The maximum number of errors a SMTP client is allowed to make without delivering mail. The Hedwig SMTP server disconnects when the limit is exceeded.

• smtpd_recipient_restrictions (default: empty)

  Optional restrictions that the Hedwig SMTP server applies in the context of a client RCPT TO command.

  The default is to permit everything.

  • check_recipient_access table

    Search the specified access table for the resolved RCPT TO address, domain, or localpart@, and execute the corresponding action. If access table is not specified, conf/recipient_access file is used as a default table.

  • reject_unlisted_recipient

    Reject the request when the RCPT TO address does not exist in the local user database.

• smtpd_relay_restrictions (default: permit_mynetworks, permit_sasl_authenticated, reject)

  Access retrictions for mail relay control that the Hedwig SMTP server applies in the context of the RCPT To command. Specify a list of restrictions, separated by commas.

  IMPORTANT: If you do not specify this restrictions Hedwig will acts as an open relay server.

  • permit_sasl_authenticated

    Permit the request when the client is successfully authenticated via the RFC 4954 (AUTH) protocol.

• smtpd_sender_restrictions (default: empty)

  Optional restrictions that the Hedwig SMTP server applies in the context of a client MAIL FROM command.

  The default is to permit everything.

  • check_sender_access table

    Search the specified access table for the MAIL FROM address, domain, or localpart@, and execute the corresponding action. If access table is not specified, conf/sender_access file is used as a default table.

• smtpd_soft_error_limit (default: 10)

  The number of errors a SMTP client is allowed to make without delivering mail before the Hedwig SMTP server slows down all its responses.

• smtpd_timeout (default: 300000)

  The SMTP server socket I/O timeout value in milliseconds, or zero (timeout infinity).

Configuring the POP3 server

POP3 configuration parameters are also controlled via the default.properties file.

Followings are description of all POP3 configuration parameters.

• pop3d_timeout (default: 300000)

  The POP3 server socket I/O timeout value in milliseconds, or zero (timeout infinity).

LDA with Postfix

Hedwig LDA is easy to configure with Postfix virtual domains support. Hedwig supports two delivery methods PIPE and LMTP.

hedwig-pipe unix - n n - - pipe
  flags=DRhu user=hedwig/hedwig argv=/home/hedwig/bin/deliver.sh ${sender} ${recipient}

default_destination_recipient_limit = 50
virtual_mailbox_domains = your.domain.here
virtual_transport = hedwig-pipe

hedwig-lmtp unix - - n - - lmtp

virtual_transport = hedwig-lmtp:<host>:<port>

Configuring MS Outlook 2007

Use the following method to configure Outlook as an IMAP4 client.

1. Start Outlook.
2. On the Tools menu, click Account Settings.
3. Click New.
4. Click Microsoft Exchange, POP3, IMAP, or HTTP, and then click Next.
5. In the Auto Account Setup dialog box, click to select the Manually configure server settings or additional server types check box, and then click Next.
6. Click Internet E-Mail, and then click Next.
7. In the Server Information section, select IMAP for Account Type.
8. In the Your Name box, enter your name exactly as you want it to appear to recipients.
9. In the E-mail Address box, type your e-mail address.
10. In the User Name box, type your your account name. If the server supports multiple domains, then type your e-mail address not your account name.
11. In the Password box, type your password.
12. In the Incoming mail server box, type the name of your IMAP4 server.
13. In the Outgoing mail server (SMTP) box, type the name of your SMTP server.
14. Click Next after you have completed entering this configuration information, and then click Finish.

Configuring Mozilla Thunderbird 3.1

Use the following method to configure Thunderbird as an IMAP4 client.

1. Start Thunderbird
2. On the Tools menu, click Account Settings.
3. Click the Account Actions button and select Add Mail Account.
4. In the Your name box, enter your name exactly as you want it to appear to recipients.
5. In the Email address box, type your e-mail address.
6. In the Password box, type your password.
7. Click Continue. Thunderbird will try to determine your account settings based on the domain portion of your email address (that is, the portion after the "@" symbol). Press the Stop button to abort the lookup, then edit the server names, port and IMAP, and then press Manual Configuration to manually set up the the account. Note that it's important that you set server names, port and IMAP before clicking Manual Config.
8. In the Account Settings dialog, in the left pane, select Server Settings option under your new account.
9. In the right pane, make sure the User Name box contains your account name. If the server supports multiple domains, then type your e-mail address not your account name.

Graphical overview of tables

Tables in Hedwig

This is a more detailed description of the tables in hedwig in alphabetic order.

Target Categories in Disk Cleanup Cron

There are two different types of categories that Disk Cleanup targets when it performs the job.

• Expunge Old Messages and Message Files

  It expunges messages and message files that are stored in specfic mailbox and older than specific period of time from now. You can specify the mailboxes and periods by setting the expunge_after parameter in default.properties. This parameter is consist of pairs of mailbox name and period.

• Compress Old Message Files

  It compresses message files that are older than specific period of time from now. The files are still available, but there will be a slight increase in access times because the files will be decompressed every time they are accessed. You can specify the period by setting the compress_after parameter in default.properties.

Schedule Disk Cleanup

You might want to set the cron to run daily or weekly depending on what works best for you. To schedule Disk Cleanup Cron to run on a regular basis we need to edit the applicationContext.xml from conf directory of your installation. Change the cronExpression to what you want to.

        <bean id="cronTrigger" class="org.springframework.scheduling.quartz.CronTriggerBean">
                <property name="jobDetail" ref="diskCleanupJob" />
                <!-- Run every day at 3 AM -->
                <property name="cronExpression" value="0 0 3 * * ?" />
        </bean>

The cronExpression is a string that is actually made up of seven sub-expressions, that descibe individual details of the schedule. These sub-expression are separated with white-space, and represents:

• Seconds
• Minutes
• Hours
• Day-of-Month
• Month
• Day-of-Week
• Year (optional field)

  See the Quartz Enterprise Job Scheduler Tutorial for more information about cron expression.

Overview

The Hedwig Web Console is a web based administration tool for working with Hedwig Mail server.

Running the Web Console

Download the hedwig-web-version.war file and install the war distribution. Then you can point your web browser at the URL.

• http://localhost:8080/hedwig-web-version/

  And hey presto, you should now have the Web Console running.

Configuring the Web Console

Copy default.properties from Hedwig server's conf directory to WEB-INF. Web Console is used by limited number of users, so change the jdbc.maxActive and jdbc.maxIdle value to smaller value.

To enable access to the Web Console, you must create a new username/password combination and associate the role name manager with it. Web Console defaults to a properties file stored at WEB-INF/users.properties, which can be edited with any text editor. This file might look like this:

admin=s3cret:manager

which defines the username and password used by this individual to log on, and the role names he or she is associated with.

Using the Web Console

Accounts

You can create, update or delete accounts in this menu.

And you can import multiple accounts using Import menu. Accounts are imported using a colon delimited text file. The following fields are required for accounts import.

Import file format

Field	Form
Address	The email address of the account.
Password	The password of the account.
Maximum size	The maximum disk space that the account may use.
Forwarding	The email address you want to forward messages to.

If fields are empty or omitted, default value is used for that field. Following is a sample import file.

joe@domain.com:s3cret:1024:joe@gmail.com
bill@domain.com
jane@domain.com:tiger:
kara@domain.com:::nicole@nate.com

Fetch Account

Hedwig can download messages from POP3 accounts on other servers. Email downloads are delivered to the selected account. You can fetch external account from Fetch menu in the Edit Account page.

• Name

  The name of the external account. The name is in free text and can be anything you like.

• Protocol

  Currently only POP3. Support for other protocols, such as IMAP, may be added in future.

• Server address & TCP Port

  The hostname and TCP/IP port of the server should connect to when downloading messages.

• User name & Password

  The user name and password the server should use when login to the external server. This should be the same information that you normally enter in your email client when login to that account.

• SSL

  If the external server requires an encrypted connection(SSL), check the Use SSL option.

• Settings

  If you select Delete messages immediately, server will delete the messages from the external server right after downloading them. The opposite, Do not delete messages, causes server not to delete messages on the external server.

Aliases

You can create, update or delete aliases in this menu.

Aliases are used to forward email from one specific address to another. Imagine them as addresses without a mailbox; instead of having their own mailbox, they store received messages in another account's mailbox. This can be useful if you want to monitor several email addresses, but only have one real email account on the server. For example, you may want to receive email messages sent to webmaster@domain.com, feedback@domain.com and yourname@domain.com, but you just want to create the webmaster@domain.com account instead of 3 different accounts. Then feedback@domain.com and yourname@domain.com can be made aliases of webmaster@domain.com.