diff --git a/setup/doc/administration.html b/setup/doc/administration.html deleted file mode 100644 index 2ee0dde..0000000 --- a/setup/doc/administration.html +++ /dev/null @@ -1,64 +0,0 @@ - - -Administration - - - -

Administration

- -

-For the administration of the Resin application server, see the -documentation of Resin. -

- -Log files are located in two places: - - -

${resin.dir>/log/jvm-default.log

-It contains errors and warnings. If everything goes well, it should only contain -startup and shutdown messages. - -

${mirekaHome}/log/access.log

-It contains every SMTP command received or sent and some additional information -from -filters. It contains errors and warnings as well. If you have more then 100 000 -mail transactions per day, then you may want to switch on buffering on this log. - -

${mirekaHome}/log/unknown-user.log

-Every recipients, which are rejected because they are not in the list of -valid recipients, although they are addressed to a local domain, are logged in -this file. This log file is useful on a fresh installation of Mireka, to -make sure that no valid recipients are rejected because of wrong configuration. -It can be switched off later. - -

Traffic statistics

- -The MeasureTraffic -filter publishes statistics in a JMX MBean object under the name -mireka:type=TrafficSummary. -It can be displayed either in the -administration pages of Resin, or using the jconsole application of the JDK. - -

Postmaster mails

- -

-All mails sent to the special Postmaster addresses are saved into the -{mirekaHome}/postmaster directory. They are sent to their assigned -destination as well. There are two types of postmaster addresses. In the -first form, no domain is specified. This is always accepted. In the second form, -domain part is also specified. These are only accepted if the domain is a local -domain. This feature is useful for debugging. The saved file shows the content -of the message before any processing. The mails are saved even if an error -occurs later in the processing chain, e.g. the back-end server cannot be -connected in proxy mode. -

- -

-You may need to clear the directory occasionally. -

- - - \ No newline at end of file diff --git a/setup/doc/basic-configuration/alias.html b/setup/doc/basic-configuration/alias.html new file mode 100644 index 0000000..eb51075 --- /dev/null +++ b/setup/doc/basic-configuration/alias.html @@ -0,0 +1,27 @@ + + + Adding an alias + + + + +

Adding an alias

+ +

Alias is a virtual recipient address which is mapped to another local recipient address. +Mails sent to the alias are handled exactly as if they were sent to the other address. + +

Edit local-recipients.js and insert the new alias mapping below the +comment ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE. +For example if you have a user account with the name jane, and you want +to define an alternative address, jeannie for her, you shoud insert the following line: +

... +alias("jeannie@example.com", "jane@example.com"), +...

+ +

From now, mails sent to jeannie@example.com will be delivered to the +existing maildrop named jane. +

Note: both addresses must be local addresses. + + + + diff --git a/setup/doc/basic-configuration/authenticate-by-ip.html b/setup/doc/basic-configuration/authenticate-by-ip.html new file mode 100644 index 0000000..128b1ad --- /dev/null +++ b/setup/doc/basic-configuration/authenticate-by-ip.html @@ -0,0 +1,27 @@ + + + Authenticate by IP address + + + + +

Authenticate by IP address

+ +

Clients connecting to the Message Submission port must be authenticated. +It must not be allowed that anyone on the internet could send mails through the server, +because spammers quickly find such an open-proxy SMTP server and starts to use it. +

Authentication is based on either the name-password pair of a user account, or on the IP address of the client. +For remote users with dynamic IP addresses the password authentication, +for servers the IP address based authentication is the more useful. + +

Edit submission/authorized-ip.js and insert the IP addresses or address ranges, +from which machines are allowed to send mail without password authentication. +For example if your private network is 192.168.0.0/24 and you allow machines on +your private network to send mail without password authentication, +insert the following line: +

... +"192.168.0.0/24", +...

+ + + diff --git a/setup/doc/basic-configuration/configuration.html b/setup/doc/basic-configuration/configuration.html new file mode 100644 index 0000000..3f1170c --- /dev/null +++ b/setup/doc/basic-configuration/configuration.html @@ -0,0 +1,39 @@ + + + Configuration basics + + + + +

Configuration basics

+ +

How does Mireka store configuration

+ +

Mireka configuration is stored in text files. +The configuration files are written in the JavaScript programming language, +although only the most basic elements of JavaScript is used. The configuration does two things: +

+ +

Location of configuration files

+ +The location of the configuration files depends on how you installed Mireka. + + +

Editing

+ +It is best if you edit the files using an editor capable of syntax highlighting JavaScript files. +For example you can use Vim on the Linux command line, or jEdit on Windows and Linux GUI. + + + +

After changing the configuration you have to restart Mireka. + + + + diff --git a/setup/doc/basic-configuration/domain.html b/setup/doc/basic-configuration/domain.html new file mode 100644 index 0000000..e0abedd --- /dev/null +++ b/setup/doc/basic-configuration/domain.html @@ -0,0 +1,29 @@ + + + Add domain + + + + +

Add domain

+ +

If you want Mireka to accept mails from external servers then you have to specify the list of your domain names. +For example, if john@example.com and john@example.net +are mail addresses of your local users, then you have to add example.com and example.net to the list. +If the domain part of a recipient is not in this list, then the recipient will be rejected by the MX SMTP service. + +

The list is specified in the domains.js configuration file. +Edit the file and add your domain to the remoteParts list. +For the example above the file should look something like this: +

localDomains = setup(InlineDomainRegistry, { + remoteParts: [ + "example.com", + "example.net" + ] +}); +

+

The domain must be double quoted, multiple domains must be separated by commas. + + + + diff --git a/setup/doc/basic-configuration/first-steps.html b/setup/doc/basic-configuration/first-steps.html new file mode 100644 index 0000000..7349ab7 --- /dev/null +++ b/setup/doc/basic-configuration/first-steps.html @@ -0,0 +1,45 @@ + + + First steps after installation + + + + +

First steps after installation

+ +

After installating Mireka, you have to configure the following settings, which has no sensible defaults. +

Server name

+The server identifies itself for others with its domain name. +If this server will send mails to external servers, then it is important to setup this correctly. +In this case always use the fully qualified domain name of the server. +Otherwise you should come up with something meaningful for you. +

Edit mireka.js and change the value of the helo variable. +For example if your server is named mail.example.com the result should look like this: +

... +var helo="mail.example.com"; +... +

+ +

SRS key

+

If Mireka will be configured to sometime forward incoming mail to an external server, than it has to use a mechanism named SRS to successfully deliver the mail. +SRS needs a secret key. Choose a random hexadecimal value which should be about 32 characters long. +

Edit mireka.js, uncomment the secretKey line and edit its value. +For example if you have choosen 12AB34CD as the secret, the result should look like this: +

... + secretKey: "12AB34CD", +... +

+ +

Postmaster

+If your server is not only a proxy, then you have to designate a user as the postmaster. +Do this after you have setup user accounts. +See the page Designate the Postmaster for instructions. +

+ +

Mailer-daemon name and address

+You have to change the mailer daemon address at the top of the submission/queues.js +configuration file, to reflect your own domain. The mailer daemon address is used as the from +address in automatically generated delivery status notification mails. + + + diff --git a/setup/doc/basic-configuration/forward.html b/setup/doc/basic-configuration/forward.html new file mode 100644 index 0000000..22c3652 --- /dev/null +++ b/setup/doc/basic-configuration/forward.html @@ -0,0 +1,27 @@ + + + Specifying forwarding + + + + +

Specifying forwarding

+ +

Forwarding is used to redistribute incoming mail to one or more +other addresses, including remote addresses too. In contrast to a mailing list, +if delivery to any of the destination addresses fails, then the bounce message goes +to the original sender, not to a third person, like a mailing list owner. + +

NOTE: Before first configuring forwarding to a remote address, you must configure the SRS module. +See First steps. + +

Edit local-recipients.js and insert a new forwarding rule below the +comment ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE. +For example if you want that all mails sent to the address project-halo@example.com be +forwarded to john@example.com and customer@example.net, then insert the following line: +

... +forward("project-halo@example.com", "john@example.com", "customer@example.net"), +...

+ + + diff --git a/setup/doc/basic-configuration/mailing-list.html b/setup/doc/basic-configuration/mailing-list.html new file mode 100644 index 0000000..b72c012 --- /dev/null +++ b/setup/doc/basic-configuration/mailing-list.html @@ -0,0 +1,47 @@ + + + Defining a simple mailing list + + + + +

Defining a simple mailing list

+ +

Mireka provides very simple mailing lists. This implementation is +appropriate for small, internal, closed membership lists. There is no +archiving, automatized subscription/unsubscription address, moderation etc. If the +requirements are more complex, then a dedicated list manager software should be used. + +

Edit local-recipients.js and insert a new mailing list definition below the +comment ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE. +For example if you want that all mails sent to the address admin@example.com be +distributed to john@example.com and jane@example.net, then insert the following lines: +

... +mailingList({ + address: "admin@example.com", + subjectPrefix: "[SYS-ADMIN]", // Subject of mails will be prefixed by this text. Default: no prefix. + membersOnly: false, // Only members are allowed to send mails to the list. Default: true + attachmentsAllowed: true, // Default is true. + replyToList: true, + reversePath: "list-owner@example.com", // Bounce messages will go to this address. Required. + membersOnlyMessage: "Only example.com system administrators can post onto this list.", + nonMemberSenderValidator: setup(SubjectRegexpValidator, { + pattern: ".*TICKET-NO.*" + }), + members: listMembers([ + "john@example.com", + "jane@example.net", + ]), +}), +...

+ +

Fields not commented above: +

+ + + diff --git a/setup/doc/basic-configuration/postmaster.html b/setup/doc/basic-configuration/postmaster.html new file mode 100644 index 0000000..40d6968 --- /dev/null +++ b/setup/doc/basic-configuration/postmaster.html @@ -0,0 +1,31 @@ + + + Designating the Postmaster + + + + +

Designating the Postmaster

+ +According to RFC 5321: +Any system that includes an SMTP server +supporting mail relaying or delivery MUST support the reserved mailbox "postmaster" as a +case-insensitive local name. + +

Edit local-recipients.js and change the value of the PostmasterAliasMapper.canonical +attribute. +For example if the local user, john@example.com, should receive mails sent to the postmaster addresses +then the result should look like this: +

... + setup(PostmasterAliasMapper, { + canonical: "john@example.com" + }), +... +

+ +

The designated Postmaster will receive mails sent to the Postmaster of any local +domains (for example Postmaster@example.com) +and also to the special Postmaster (without domain) address. + + + diff --git a/setup/doc/basic-configuration/proxy.html b/setup/doc/basic-configuration/proxy.html new file mode 100644 index 0000000..71a9595 --- /dev/null +++ b/setup/doc/basic-configuration/proxy.html @@ -0,0 +1,76 @@ + + + Using as proxy + + + + +

Using as proxy

+ +

Mireka can relay mails sent to one or more or even any addresses to another SMTP server. +

Mireka relays the SMTP statements received in a mail +session to a backend server step-by-step in real-time. In this way both +this server and the backend server is able to reject a mail within the +SMTP session, before accepting the responsibility of delivering the +mail. This fast-fail behaviour is useful in some situations. + +

First edit mireka.js and configure the value of the backendServer +variable. For example if your backend server is backend.example.com and +listens on port 2525, your configuration should look like this: +

... +backendServer = setup(BackendServer, { + host: "backend.example.com", + port: 2525, + clientFactory: clientFactory +}); +...

+ +

Note: you can freely specify another backend server for a different set of recipient addresses. + +

Next, edit local-recipients.js and insert the proxy mapping below the +comment ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE. +For example if you want to relay everything to the backend server, then insert the following code: +

... +massProxy(backendServer, [ setup(AnyRecipient) ]); +...

+ +

Here is a complex example for selectively relaying specific addresses: +

... + +massProxy(backendServer, [ + + // Fully specified recipients + setup(InlineRecipientRegistry, { + addresses: [ + "john@example.com", + "jack@example.com" + ] + }), + + // A wildcard recipient, only the local part is specified + setup(CaseInsensitiveAnyDomainRecipient, { + localPart: "anonymous" + }), + + // Another wildcard recipient with regular expression + setup(RegexAddressSpecification, { + localPartRegex: ".*-bounces-.*", + remotePart: "lists.example.com" + }), + + // Any postmaster address + setup(AnyPostmaster), + + // Addresses corresponding to local user accounts + setup(GlobalUsersRecipientSpecification, { + users: globalUsers + }), +]), +...

+ +

Tip: Proxy mappings should be placed near the end of +local-recipients.js, so locally handled addresses will not be shadowed +accidentally by proxied addresses specified using wildcards. + + + diff --git a/setup/doc/basic-configuration/sendmail.html b/setup/doc/basic-configuration/sendmail.html new file mode 100644 index 0000000..2a9e32c --- /dev/null +++ b/setup/doc/basic-configuration/sendmail.html @@ -0,0 +1,24 @@ + + + Sendmail command on Linux + + + + +

Sendmail command on Linux

+ +

Many Linux software depends on the sendmail program to send mail. +We have good experience with the sSMTP application. It provides a sendmail +implementation which sends the mail directly to an SMTP server. +

To install sSMTP on Ubuntu: +

sudo apt-get install ssmtp

+

Edit its main configuration file: +

sudoedit /etc/ssmtp/ssmtp.conf

+

Set sSMTP to send mail to the Message Submission port of Mireka. For example: +

mailhub=mail.example.com:587

+

You may also want to set other properties and edit the other configuration file, /etc/ssmtp/revaliases. +

If sSMTP is on a different host than Mireka, then set Mireka to allow message submission from the sSMTP host. +See Authenticate by IP address. + + + diff --git a/setup/doc/basic-configuration/user.html b/setup/doc/basic-configuration/user.html new file mode 100644 index 0000000..e31b02e --- /dev/null +++ b/setup/doc/basic-configuration/user.html @@ -0,0 +1,34 @@ + + + Adding a user account + + + + +

Adding a user account

+ + +

global-users.js contains the list of users who are authorized to +use the Message Submission and POP3 services. It contains username, password pairs. +An email client (MUA) must authenticate using such an account before submitting and +retrieving messages. + +

Note: The users listed here will receive a POP maildrop and become valid recipients +for all local domains listed in domains.js. +For example, you have a user account with the name john, and the local +domains are example.com and example.net. +In this case the Mireka accepts both john@example.com and john@example.org. + +

Edit the global-users.js file and add your user to the users list. +For example if you have two users, John and Jane, the result should look something like this: +

globalUsers = setup(GlobalUsers, { users: [ + + globalUser("john", "changeit"), + globalUser("jane", "changeit"), + +]});

+ +

Do not forget to designate a user as postmaster. + + + diff --git a/setup/doc/configuration.html b/setup/doc/configuration.html index b136a3c..42ce6d2 100644 --- a/setup/doc/configuration.html +++ b/setup/doc/configuration.html @@ -1,6 +1,7 @@ -Configuration +Configuration files + -

How to Configure Mireka

- -

Container: Resin Application Server

-

Mireka is using the Resin application server for configuration and startup. -Therefore it is distibuted in a standard Java Web Application archive, although -currently it has no web interface. In the unlikely event, that some additonal -configuration of Resin is needed, other than what was already done during -installation, you can find more information about Resin on its web site at -http://www.caucho.com/products/resin/. -

+

Configuration files

-

Mail services

-

-Mireka configuration files are located in the ${mirekaHome}/conf/ -directory. -

+Configuration files are located in MIREKA_HOME/conf. +They will be read and processed by Mireka on startup. -

-mireka.xml is the primary configuration file of Mireka. -It is imported by -resin-web.xml in the Mireka web application archive during runtime. -mireka.xml in turn imports most of the other configuration -files. +

mireka.js is the primary configuration file of Mireka. +The JavaScript evaluator starts with this file. This file in turn imports all +other .js files. +It also imports helper functions from a non-configuration file: +MIREKA_HOME/lib/configuration.js. +These helper functions are described in detail in comment blocks within that file.

-

-These configuration files will be read and processed by Resin. -Essentially, they control what objects must be created in runtime. The name of a tag -is a Java class name. An element assigns a value to a property of the object. -It is also possible to specify another objest as a property value, either -defining it inline, or referencing it by an EL expression. -For more information on the syntax, see the Resin documentation. -

+

In addition to the standard EcmaScript objects and Mireka mailing specific Java objects, +the script can access the mireka.startup.ScriptApi object using the configuration variable.

-For more information on the Mireka classes which are referenced in the -configuration, see the javadoc. +Essentially, the JavaScript code in the configuration files create new Mireka objects, which are written in Java, +and assigns values to their properties. +A typical pattern looks like this: +

setup(Member, { + address: "john@example.com", + name: "John Doe", +}),

+As in almost all cases, the setup JavaScript function is used. +It creates a new instance of the mireka.forward.Member class, +and set its properties by calling Member.setAddress with the value "john@example.com", +and Member.setName with "John Doe". +setup does a few other things, see the comment block preceeding it. + +

It is also possible to specify another object as a property value, either +defining it inline, or referencing it by a variable name.

-The import structure of configuration files should be considered as an example. -It is possible to include all data in mireka.xml. It is also possible -to divide the configuration into more files than what is supplied by default. +For more information on Mireka objects, see the Javadoc.

+

List of configuration files

- - + - - - - - + - + - + - - - +
mireka.xmlEnables/disables SMTP, Submission and POP3 +
File nameFunction
mireka.jsEnables/disables SMTP, Message Submission and POP3 services by importing or not importing their respective configuration files. It contains common elements used by more than one services. Some of these are default objects which are referred by other parts of the configuration, but it @@ -69,67 +64,58 @@

Mail services

See the comments in the file for more information.
mxConfiguration files related to the -public SMTP +
mx.jsConfigures the public SMTP service, which receives mails sent to the local domains by any server on the internet. The service, in turn, stores the mail in a POP3 mailbox, relays it in real time to a backend server behaving like a proxy, forwards it, etc.
submissionConfiguration files -related to the Message Submission service, used by local users to send mails either to -other local users, or to other domains on the internet. The service, in turn, stores the mail in a POP3 mailbox, relays it in -real time to a backend server behaving like a proxy, forwards it, etc. +
submission/* +These files configure the Message Submission service, +used by local users to send mails either to +other local users, or to other domains on the internet.
pop/pop.xmlConfigures the POP3 service itself and the POP3 +
pop.jsConfigures the POP3 service itself and the POP3 Importer. POP3 Importer is useful for migration. It retrieves each users' mails from another POP3 server after startup. To use it, it is necessary that the user names and the passwords match on both system.
domains.xmlList of local domain names. +
domains.jsList of local domain names. If the domain part of a recipient is not in this list, then the recipient will be rejected by the MX SMTP service.
global-users.xml
global-users.js Authorized users of the Mail Submission, POP3 services, in addition they are also valid wildcard recipients in the MX SMTP service.
alias.xml
local-recipients.js -List of aliases. An alias maps one or more virtual recipients to a -canonical recipient address. +It tells what to do with mails sent to local domains. +It maps recipient addresses to a destinations, like store the mail in a maildrop for +later retrieval via POP3, forward it to another domain, etc.
forwards.xml
circular.js -Forward lists. Forward lists are used to redistribute incoming mail to multiple -other addresses. +This file exists purely for a technical reason, to break circular dependencies. +If a configuration object named A refers to another object B, but B also refers to A, then +neither A nor B could be created and fully initialized before the other. In such cases +an unitialized A object is created in this file, then it is referenced when object B and other +depending objects are created and initialized. +Finally object A is initialized in the usual configuration file corresponding to its function.
lists.xml -List of (very) simple mailing lists. -
others.xml
logback.xml -Other local recipients not included in the alias.xml, forwards.xml etc. -configuration files. +It configures logging.
-

Logging

-

-${mirekaHome}/conf/logback.xml configures logging. -For more information, see the documentation of -Logback and the -Administration section. -

- \ No newline at end of file diff --git a/setup/doc/development.html b/setup/doc/development.html index ada5adb..d8d25aa 100644 --- a/setup/doc/development.html +++ b/setup/doc/development.html @@ -8,8 +8,8 @@

Developing and installing custom components

Almost anything can be changed in Mireka without modifying Mireka source code, -just by adding new Java classes for example in a jar and configuring them in -the XML configuration files. Particularly useful are the filters, which can +just by adding new Java classes for example in a jar and initializing these new objects in +the configuration files. Particularly useful are the filters, which can alter the processing of a mail immediately within the SMTP transaction.

@@ -20,6 +20,7 @@

Developing and installing custom components

Filters

+

For an overview about the filter mechanism, see the Filters section.

A filter consists of two classes. FilterType @@ -42,10 +43,9 @@

Filters

Installation

-Place your jars and classes into ${mirekaHome}/lib and -${mirekaHome}/classes, -respectively. You can even place Java source files into -${mirekaHome}/classes, Resin will compile it automatically. +Place your jars and compiled classes into MIREKA_HOME/lib and +MIREKA_HOME/classes +respectively.

diff --git a/setup/doc/directory.html b/setup/doc/directory.html new file mode 100644 index 0000000..ddfb049 --- /dev/null +++ b/setup/doc/directory.html @@ -0,0 +1,38 @@ + + +Directory layout + + + +

Directory layout

+ +Mireka has a single home directory, MIREKA_HOME, which contains almost everything related to it: +configuration, mails, log, Java code. The actual data may reside on some other part of +the file hierarcy, but even then, the home directory contains a file system link +to the actual place of the data. +For example in case of the Ubuntu deb installation, MIREKA_HOME is /var/lib/mireka, +which contains a soft link named log, which points to the /var/log/mireka directory, +which in turn contains the log files. +

The place of MIREKA_HOME depends on your system and installation method: +

+See the installation pages for more information. +

Directories within MIREKA_HOME: +

+ + + \ No newline at end of file diff --git a/setup/doc/doc.css b/setup/doc/doc.css new file mode 100644 index 0000000..0c0b839 --- /dev/null +++ b/setup/doc/doc.css @@ -0,0 +1,4 @@ +.code { background: #DDD; padding: 5px; margin: 5px; font-family: monospace; white-space: pre; overflow: auto } +.relevant { color: #B33; font-weight:bold } +.comment { color: #880 } + diff --git a/setup/doc/filters.html b/setup/doc/filters.html index bd55c52..a0e96dd 100644 --- a/setup/doc/filters.html +++ b/setup/doc/filters.html @@ -32,8 +32,8 @@

Filters

-The filter chain is configured in mx/mx.xml and -submission/submission.xml. +The filter chain is configured in mx.js and +submission/submission.js.

diff --git a/setup/doc/global-users.html b/setup/doc/global-users.html deleted file mode 100644 index 87bc0b1..0000000 --- a/setup/doc/global-users.html +++ /dev/null @@ -1,36 +0,0 @@ - - -Global Users Configuration File - - - - -

Global Users Configuration File (global-users.xml)

- -

-global-users.xml contains the list of users who are authorized to -use the mail submission and POP3 services. It contains username, password pairs. -An email client (MUA) -must authenticate in the SMTP session using these accounts before submitting a -message. -

-

-Note: According to the default configuration, if the MX service is -enabled, then the users listed here become valid wildcard recipients in the MX -service too. Because the list contains the local-part of addresses only, they -will be accepted with any local domain on their right side. For example, the -list contains the user john, and example.com and -example.org are both local domains. In this case the MX service -accepts both john@example.com and john@example.org. -

- - - \ No newline at end of file diff --git a/setup/doc/graphite.html b/setup/doc/graphite.html new file mode 100644 index 0000000..ce6f655 --- /dev/null +++ b/setup/doc/graphite.html @@ -0,0 +1,34 @@ + + +Realtime graphing and monitoring with Graphite + + + + +

Realtime graphing and monitoring with Graphite

+ +

Mireka can send traffic and JRE statistics to a Graphite +server which can produce realtime graphs for monitoring. + +

To enable sending data to Graphite, edit mireka.js and uncomment +the GraphiteReporter block. +If your Graphite server host is graphite.example.com, +and the host name of the server running Mireka is mail, +then the result should look like this: +

... +/* + uncomment to send monitoring data to a Graphite server for graphical + viewing +*/ +██ +setup(GraphiteReporter, { + host: "graphite.example.com", + prefix: "mail.mireka" +}); +██ +...

+We have good experience with using HOSTNAME.PROGRAM_NAME +for the prefix property, but you can freely choose any value for it. +Graphite prefixes the name of data elements coming from this Mireka process with the supplied value. + + \ No newline at end of file diff --git a/setup/doc/index.html b/setup/doc/index.html index 33539ca..048f32e 100644 --- a/setup/doc/index.html +++ b/setup/doc/index.html @@ -8,15 +8,44 @@

Mireka documentation

Contents
    -
  1. Installation -
  2. Configuration -
      -
    1. SMTP service -
    2. Message Submission service -
    3. Filters -
    4. Local users -
    -
  3. Administration +
  4. Quick Start - Trying Mireka without installing + +
  5. Installation + +
  6. Basic Configuration + +
  7. Directory layout +
  8. Configuration files +
  9. SMTP service +
  10. Message Submission Service +
  11. Logging +
  12. Realtime graphing and monitoring with Graphite +
  13. Monitoring and management via JMX +
  14. Filters +
  15. Postmaster mail copies
  16. Developing custom components
Appendix diff --git a/setup/doc/install/linux.html b/setup/doc/install/linux.html new file mode 100644 index 0000000..47124ee --- /dev/null +++ b/setup/doc/install/linux.html @@ -0,0 +1,26 @@ + + + Installing on Linux + + + + +

Installing on Linux

+ + +

Ubuntu

+ +

If you want a quick installation which uses the usual directories like +/var/lib, /var/log, /usr/share/lib etc. than follow: +Installing the deb package. + +

If you want Mireka to use only a single folder like /opt/mireka, +for example because you need more than one version parallel, +or you need other customizations, then follow: +Installing binary tarball. + +

Other Linux OS

+Installing binary tarball on other Linux OS + + + diff --git a/setup/doc/install/other-linux.html b/setup/doc/install/other-linux.html new file mode 100644 index 0000000..e8b8eb4 --- /dev/null +++ b/setup/doc/install/other-linux.html @@ -0,0 +1,18 @@ + + + Installing binary tarball on other Linux OS + + + + +

Installing binary tarball on other Linux OS

+ +

The installation procedure should be very similar to the Installing binary tarball on Ubuntu page. +

If your OS uses an init system other than Upstart, then instead of the Upstart job configuration file, use the example SysV init scripts in the examples directory: +

sudo cp doc/examples/daemon/init.sh /etc/init.d/mireka +sudo cp doc/examples/daemon/default.sh /etc/default/mireka +sudo chmod 755 /etc/init.d/mireka

+

Configure your system to autostart the Mireka service at boot time. + + + diff --git a/setup/doc/install/ubuntu-deb.html b/setup/doc/install/ubuntu-deb.html new file mode 100644 index 0000000..31b5dc4 --- /dev/null +++ b/setup/doc/install/ubuntu-deb.html @@ -0,0 +1,21 @@ + + + Installing the deb package on Ubuntu + + + + +

Installing the deb package on Ubuntu

+ +

Download the deb package: +

wget http://mireka.googlecode.com/files/mireka_4.0-1_all.deb +

Install the gdebi tool, which can install local deb packages: +

sudo apt-get install gdebi-core +

Install Mireka: +

sudo gdebi mireka_4.0-1_all.deb

+

You will find the log files in /var/log/mireka, the configuration files in /etc/mireka. +The Mireka home dir is /var/lib/mireka. +

You can start it using sudo start mireka and stop it using sudo stop mireka. + + + diff --git a/setup/doc/install/ubuntu-tarball.html b/setup/doc/install/ubuntu-tarball.html new file mode 100644 index 0000000..78fd982 --- /dev/null +++ b/setup/doc/install/ubuntu-tarball.html @@ -0,0 +1,69 @@ + + + Installing binary tarball on Ubuntu + + + + +

Installing binary tarball on Ubuntu

+ +

Install dependencies +

sudo apt-get install adduser authbind openjdk-7-jre-headless unzip

+ +

Download and extract the binary release into /opt/mireka +

# Mireka version to be installed +VERSION=4.0 +cd ~ + +# Download binary package: +wget http://mireka.googlecode.com/files/mireka-$VERSION.zip + +# Extract it +unzip mireka-$VERSION.zip + +# No more need for the downloaded archive +rm mireka-$VERSION.zip + +# Move the extracted content to /opt/mireka +sudo mv mireka-$VERSION /opt/mireka + +cd /opt/mireka +

+ +

Create a user account named mireka, Mireka will run as that user +

# Create mireka user +sudo adduser --system --home /opt/mireka --no-create-home --group --disabled-password --shell /bin/false mireka

+ +

Setup file ownerships +

# Set the default: owned by root, readable by everybody +sudo chown -R root:root . + +# Logs are writable by mireka, and readable by operators and nobody else. +sudo chown -R mireka:adm log +sudo chmod 2750 log + +# Directories containing mails are writable by mireka and nobody else can see them. +sudo chown -R mireka:mireka maildrops postmaster queues +sudo chmod 750 maildrops postmaster queues + +# The configuration file which contains passwords are writable only to root, +# readable for mireka, others must not see it. +sudo chown root:mireka conf/global-users.js +sudo chmod 640 conf/global-users.js

+ +

Configure authbind to enable Mireka to listen on the standard mail ports while running as non-root. +These ports are lower than 1024, and by default are reserved for root. +

# authbind in Ubuntu 12.10 require ports in the 512-1023 to be included in files starting with ! +MIREKA_UID=$(id -u mireka) +echo -e "0.0.0.0/0:25,25\n0.0.0.0/0:110,110\n0.0.0.0/0:587,587" | sudo tee /etc/authbind/byuid/$MIREKA_UID /etc/authbind/byuid/\!$MIREKA_UID

+ +

Install Upstart job configuration file to run Mireka as a dameon and start it. +

sudo cp doc/examples/daemon/upstart.conf /etc/init/mireka.conf +sudo start mireka

+ +

You will find the log files in /opt/mireka/log, the configuration files in /opt/mireka/conf. +The Mireka home dir is /opt/mireka. +

You can start it using sudo start mireka and stop it using sudo stop mireka. + + + diff --git a/setup/doc/install/windows.html b/setup/doc/install/windows.html new file mode 100644 index 0000000..5f5e681 --- /dev/null +++ b/setup/doc/install/windows.html @@ -0,0 +1,57 @@ + + + Installing on Windows + + + + +

Installing on Windows

+ +

Dependencies

+

Download and install the Java Runtime Environment. JRE 7 or newer is required:
+Oracle Java SE downloads + +

Extract binary archive

+Download and extract the binary archive. +Use a target directory like C:\ProgramData\Mireka. +Mails are stored in subdirectories in the installation directory, +so the protected Program Files directory is not ideal, +unless you replace the affected subdirectories with links to C:\ProgramData\Mireka subdirectories. + +

Permissions

+

Setup permissions if your use case requires it. +The recommended permissions are the same as on Linux. +See the comments in the Setup file ownerships section of the Installing binary tarball on Ubuntu page. + +

Run Mireka as a Service

+

Download the Apache Commons Daemon Windows binary archive from here: +www.apache.org/dist/commons/daemon/binaries/windows/ +

You can find more information about Commons Daemon here: commons.apache.org/proper/commons-daemon/binaries.html +

The archive contains binaries for both 32 and 64 bit systems. +Copy prunmgr.exe and the prunsrv.exe corresponding to your processor architecture into the bin directory of Mireka. +

Start a command shell running it as administrator in the Mireka home directory. +

Rename the two exe files to be more specific: +

rename bin\prunsrv.exe mireka.exe +rename bin\prunmgr.exe mirekaw.exe +

Install the service: +

bin\mireka install mireka --DisplayName="Mireka Mail Server" --Description="Mireka Mail Server and SMTP Proxy" --StartMode=jvm --StopMode=jvm --StartPath="%CD%" --StopPath="%CD%" --Classpath=classes;lib/*;conf ++JvmOptions=-Dlogback.configurationFile=conf/logback.xml ++JvmOptions=-Dmireka.home="%CD%" ++JvmOptions=-Djava.net.preferIPv4Stack=true --Startup=auto --StartClass=mireka.startup.Start --StopClass=mireka.startup.Stop --LogPath=log + +

+

You can start the Mireka service in the Services Management Console GUI, or by issuing the command: +

net start mireka

+ +
Troubleshooting / Maintenance
+

Check the logs, including the daemon utility log in the log subdirectory. +

To remove the service: +

bin\mireka delete

+

GUI to view/change service parameters: +

bin\mirekaw

+

Detailed status information about the service: +

sc query mireka

+ +

Next steps

+

Mireka home directory is the directory where you extracted the Mireka zip file. +You will find the log files in the log, the configuration files in the conf subdirectories. + + + diff --git a/setup/doc/installation.html b/setup/doc/installation.html deleted file mode 100644 index b5aa18b..0000000 --- a/setup/doc/installation.html +++ /dev/null @@ -1,93 +0,0 @@ - - - Installation - - - -

How to Install Mireka

-These instructions describe how to set up a single, standalone instance of Mireka. -You should have have installed JDK 1.6+. -
    -
  1. Download and install - Resin 4.0.10 open source edition - as per the Resin instructions. The Resin install directory is referenced in this document - as ${resin.dir}. You may want to configure a fixed JMX port on - Resin, so you will be able to use jconsole to monitor Mireka. -
    2. -
  2. Download and unzip the Mireka distribution. The installation directory - may be for example "C:\Program Files\Mireka" on Windows or - /var/lib/mireka on Ubuntu. - This directory is referenced in this document as ${mirekaHome} -
  3. On Linux ensure that Resin has the necessary permissions: - - For more information see Permissions on Ubuntu. -
    4. -
  4. Configure the mirekaHome variable in Resin. - To do this, edit ${resin.dir}/conf/resin.xml. After the line:
    - <host id="" root-directory=".">
    - insert this line:
    - <resin:set var="mirekaHome" value="YOUR_DIR" />
    - where YOUR_DIR should be the ${mirekaHome} directory. -
    5. -
  5. Copy mireka.war to ${resin.dir}/webapps/
    6. -
  6. Configure Mireka by editing its configuration files in the - ${mirekaHome}/conf/ directory. For more information, - see Configuration. -
    7. -
  7. Start Resin. For more information on this, see the documentation of Resin.
    8. -
- -

-To verify that everyting is going well, look at the log files in -${resin.dir}/log and ${mirekaHome}/log. -

- - -

Permissions on Ubuntu

-On Ubuntu by default Resin runs as user www-data, -which has no permissions to open ports below 1024. -

The easiest way to have the necessary permissions is to run Resin as root. -Comment out, or delete these lines in ${resin.dir}/conf/resin.xml: -

-	<resin:if test="${resin.userName == 'root'}">
-		<user-name>www-data</user-name>
-		<group-name>www-data</group-name>
-	</resin:if>
-
-

-Another solution is to use the authbind command. -Install the package providing authbind by issuing -the command -
-	sudo apt-get install authbind
-
-Modify /etc/init.d/resin by replacing -
-	JAVA="$JAVA_HOME/bin/java"		
-
-with -
-	JAVA="/usr/bin/authbind --deep $JAVA_HOME/bin/java"		
-
-Replace -
-	ARGS="$RESIN_CONF $RESIN_LOG $RESIN_ROOT $SERVER"
-
-with -
-	ARGS="$RESIN_CONF $RESIN_LOG $RESIN_ROOT $SERVER -Djava.net.preferIPv4Stack=true"
-
-For all required ports, create an empty file named like /etc/authbind/byport/587 -with executable permissions for the user www-data. - - - - diff --git a/setup/doc/jmx.html b/setup/doc/jmx.html new file mode 100644 index 0000000..6526b59 --- /dev/null +++ b/setup/doc/jmx.html @@ -0,0 +1,54 @@ + + +Monitoring and management via JMX + + + + +

Monitoring and management via JMX

+ +

JMX (Java Management Extensions) makes it possible to connect to the running Mireka process and set and view JRE and Mireka management online. +Among others you can change log levels and monitor mail traffic. + +

Enable JMX access

+

JMX access is not enabled by default, because it is insecure without additional measures.

+ +

To enable, some Java command line parameters must be added as detailed below. +JMX will be listening on all interfaces and no authentication will be required. +Therefore it must be firewalled, otherwise anyone can connect to it. +Even then, any local user can connect to it.

+ +

If it is switched on, and firewalled, JMX can be accessed either locally, or remotely via an SSH tunnel. +The port is 4452, but RMI, the default remote access protocol of JMX, also uses a second, random port in the later phases, so it is practically impossible to use it across a firewall.

+ +
Ubuntu
+

Uncomment the line starting with env JMX_OPTIONS in the Upstart job configuration file, /etc/init/mireka.conf. + +

Other Linux
+

Uncomment the JMX options line below the comment Enable JMX in the /etc/default/mireka configuration file. + +

Windows
+

Start Service Manager, bin/mirekaw.exe, go to the Java tab and add the following lines to the Java Options edit box: +

-Dcom.sun.management.jmxremote.port=4452 +-Dcom.sun.management.jmxremote.ssl=false +-Dcom.sun.management.jmxremote.authenticate=false

+ +
On all platforms
+

Restart Mireka so the changes take effect. + +

Remotely connecting to Mireka, using jconsole and Putty

+Configure a socks proxy in Putty, either using the GUI, or in command line: +

putty -D 9999 -load mireka-session

+ +Start jconsole: +

jconsole -J-DsocksProxyHost=localhost -J-DsocksProxyPort=9999 -debug

+ +

Traffic statistics

+ +The MeasureTraffic +filter publishes statistics in a JMX MBean object under the name +mireka:type=TrafficSummary. +It can be displayed for example using the jconsole application of the JDK. + + + \ No newline at end of file diff --git a/setup/doc/logging.html b/setup/doc/logging.html new file mode 100644 index 0000000..1d170a4 --- /dev/null +++ b/setup/doc/logging.html @@ -0,0 +1,36 @@ + + +Logging + + + +

Logging

+ +

Log files

+ +Log files are in the MIREKA_HOME/log directory. + +

error.log

+It contains errors and warnings. If everything goes well, it should only contain +startup and shutdown messages. + +

access.log

+It contains every SMTP command received or sent and some additional information +from +filters. It contains errors and warnings as well. If you have more then 100 000 +mail transactions per day, then you may want to switch on buffering on this log. + +

unknown-user.log

+Every recipients, which are rejected because they are not in the list of +valid recipients, although they are addressed to a local domain, are logged in +this file. This log file is useful on a fresh installation of Mireka, to +make sure that no valid recipients are rejected because of wrong configuration. +By default it is switched off. + +

Configuring logging

+Mireka uses the Logback logging library. +The log configuration file is MIREKA_HOME/conf/logback.xml. +For more information, see the documentation of Logback. + + + \ No newline at end of file diff --git a/setup/doc/mx.html b/setup/doc/mx.html index 495f262..d337d88 100644 --- a/setup/doc/mx.html +++ b/setup/doc/mx.html @@ -1,6 +1,6 @@ -MX Service Configuration +SMTP Service -

How to Configure the Submission Service

+

Message Submission Service

-The Submission service is used by local users to send mails to either +The submission service is used by local users to send mails to either other local users, or to other domains on the internet. The service, in turn, transmits mails to the public SMTP server of the recipient domain, delivers them locally, relays them locally, etc. This service is specified by RFC 4409, Message Submission for Mail. +It is a variant of SMTP.

If the transmission of a mail to a remote domain fails on the first attempt, @@ -37,13 +38,16 @@

How to Configure the Submission Service

record.

+

List of configuration files

+

-Configuration files specific to the Submission service are located in the -${mirekaHome}/conf/submission directory. +Configuration files specific to the Message Submission service are located in the +MIREKA_HOME/conf/submission directory.

- + - - + +
submission.xmlprimary configuration file of the Submission +
File nameFunction
submission.jsThe primary configuration file of the Submission service. It configures the SMTP server, the filter chain, and most filter parameters. In turn, it imports all the other configuration files of the Submission service. @@ -53,16 +57,19 @@

How to Configure the Submission Service

filter chain
  • filter chain: Filters are responsible for the processing of submitted mail transactions. -
  • recipient table: it does not have any interesting role in this service, it -just specifies that all recipients must be transmitted to the mail server of -the recipient's domain. +
  • recipient table: the recipient table used here simply specifies +that the service delivers mail to local recipients according to the local-recipients.js +configuration file, just like the SMTP service. Mails sent to non-local +addresses are transmitted to the mail server of the recipient's domain.
    • authorized-ip.xmllist of ip addresses or address ranges. -Mails can be submitted from these ip addresses without further authentication of -the sender. -

    This file is imported by submission.xml.

    queues.xmlThe submission service uses file system based + +
    authorized-ip.jsList of ip addresses or address ranges. +Mails can be submitted from these ip addresses without any further authentication. + +

    This file is imported by submission.js.

    queues.jsThe submission service uses file system based queues to make sure no mails are lost. Until a mail is confirmed to be received by the recipient domain the mail stays in a queue. The queues are managed by transmitters.