Skip to content

Commit

Permalink
Almost completely rewritten documentation. It is updated to reflect t…
Browse files Browse the repository at this point in the history 
…he new JavaScript configuration system.

git-svn-id: http://mireka.googlecode.com/svn/trunk@182 741d60a8-641f-389e-c7ec-093451e00b49
  • Loading branch information
@hontvari
hontvari committed Mar 24, 2013
1 parent dd68a07 commit 37a5860
Show file tree
Hide file tree
Showing 33 changed files with 1,001 additions and 322 deletions.
64 changes: 0 additions & 64 deletions setup/doc/administration.html
View file

This file was deleted.

27 changes: 27 additions & 0 deletions setup/doc/basic-configuration/alias.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<html>
<head>
<title>Adding an alias</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Adding an alias</h1>

<p>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.

<p>Edit <code>local-recipients.js</code> and insert the new alias mapping below the
comment <cite>ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE</cite>.
For example if you have a user account with the name <code>jane</code>, and you want
to define an alternative address, <code>jeannie</code> for her, you shoud insert the following line:
<p class=code>...
<span class="relevant">alias("[email protected]", "[email protected]"),</span>
...</p>

<p>From now, mails sent to <code>[email protected]</code> will be delivered to the
existing maildrop named <code>jane</code>.
<p>Note: both addresses must be local addresses.


</body>
</html>
27 changes: 27 additions & 0 deletions setup/doc/basic-configuration/authenticate-by-ip.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<html>
<head>
<title>Authenticate by IP address</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Authenticate by IP address</h1>

<p>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.
<p>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.

<p>Edit <code>submission/authorized-ip.js</code> 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:
<p class="code">...
<span class="relevant">"192.168.0.0/24",</span>
...</p>

</body>
</html>
39 changes: 39 additions & 0 deletions setup/doc/basic-configuration/configuration.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<html>
<head>
<title>Configuration basics</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Configuration basics</h1>

<h3>How does Mireka store configuration</h3>

<p>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:
<ul>
<li>Sets up Mireka components and wire them together.
<li>Sets up mailing specific informations, like user accounts, forwading lists etc.
</ul>

<h3>Location of configuration files</h3>

The location of the configuration files depends on how you installed Mireka.
<ul>
<li>If you installed it by extracting the zip distribution archive then they are in the <code>conf</code> subdirectory.
<li>If you installed the deb package then they are in <code>/etc/mireka/</code>.
</ul>

<h3>Editing</h3>

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.

<!-- <h3>How does the changes take effect</h3> -->

<p><b>After changing the configuration you have to restart Mireka.</b>


</body>
</html>
29 changes: 29 additions & 0 deletions setup/doc/basic-configuration/domain.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<html>
<head>
<title>Add domain</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Add domain</h1>

<p>If you want Mireka to accept mails from external servers then you have to specify the list of your domain names.
For example, if <code>[email protected]</code> and <code>[email protected]</code>
are mail addresses of your local users, then you have to add <code>example.com</code> and <code>example.net</code> 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.

<p>The list is specified in the <code>domains.js</code> configuration file.
Edit the file and add your domain to the <code>remoteParts</code> list.
For the example above the file should look something like this:
<p class=code>localDomains = setup(InlineDomainRegistry, {
remoteParts: [
<span class="relevant">"example.com",
"example.net"</span>
]
});
</p>
<p>The domain must be double quoted, multiple domains must be separated by commas.


</body>
</html>
45 changes: 45 additions & 0 deletions setup/doc/basic-configuration/first-steps.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<html>
<head>
<title>First steps after installation</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>First steps after installation</h1>

<p>After installating Mireka, you have to configure the following settings, which has no sensible defaults.
<h3>Server name</h3>
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.
<p>Edit <code>mireka.js</code> and change the value of the <code>helo</code> variable.
For example if your server is named <code>mail.example.com</code> the result should look like this:
<p class="code">...
var helo="<span class="relevant">mail.example.com</span>";
...
</p>

<h3>SRS key</h3>
<p>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.
<p>Edit <code>mireka.js</code>, uncomment the <code>secretKey</code> line and edit its value.
For example if you have choosen <code>12AB34CD</code> as the secret, the result should look like this:
<p class="code">...
<span class="relevant">secretKey: "12AB34CD",</span>
...
</p>

<h3>Postmaster</h3>
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 <a href="postmaster.html">Designate the Postmaster</a> for instructions.
<p>

<h3>Mailer-daemon name and address</h3>
You have to change the mailer daemon address at the top of the <code>submission/queues.js</code>
configuration file, to reflect your own domain. The mailer daemon address is used as the <cite>from</cite>
address in automatically generated delivery status notification mails.

</body>
</html>
27 changes: 27 additions & 0 deletions setup/doc/basic-configuration/forward.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<html>
<head>
<title>Specifying forwarding</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Specifying forwarding</h1>

<p>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.

<p>NOTE: Before first configuring forwarding to a remote address, you must configure the SRS module.
See <a href="first-steps.html">First steps</a>.

<p>Edit <code>local-recipients.js</code> and insert a new forwarding rule below the
comment <cite>ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE</cite>.
For example if you want that all mails sent to the address <code>[email protected]</code> be
forwarded to <code>[email protected]</code> and <code>[email protected]</code>, then insert the following line:
<p class=code>...
<span class="relevant">forward("[email protected]", "[email protected]", "[email protected]"),</span>
...</p>

</body>
</html>
47 changes: 47 additions & 0 deletions setup/doc/basic-configuration/mailing-list.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<html>
<head>
<title>Defining a simple mailing list</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Defining a simple mailing list</h1>

<p>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.

<p>Edit <code>local-recipients.js</code> and insert a new mailing list definition below the
comment <cite>ENTER YOUR RECIPIENT-DESTINATION MAPPINGS HERE</cite>.
For example if you want that all mails sent to the address <code>[email protected]</code> be
distributed to <code>[email protected]</code> and <code>[email protected]</code>, then insert the following lines:
<p class="code">...
<span class="relevant">mailingList({
address: "[email protected]",
subjectPrefix: "[SYS-ADMIN]", <span class="comment">// Subject of mails will be prefixed by this text. Default: no prefix.</span>
membersOnly: false, <span class="comment">// Only members are allowed to send mails to the list. Default: true</span>
attachmentsAllowed: true, <span class="comment">// Default is true.</span>
replyToList: true,
reversePath: "[email protected]", <span class="comment">// Bounce messages will go to this address. Required.</span>
membersOnlyMessage: "Only example.com system administrators can post onto this list.",
nonMemberSenderValidator: setup(SubjectRegexpValidator, {
pattern: ".*TICKET-NO.*"
}),
members: listMembers([
"[email protected]",
"[email protected]",
]),
}),</span>
...</p>

<p>Fields not commented above:
<ul>
<li><code>replyToList</code>: If true, pressing the Reply button in a mail client send a mail to the list, and not the original sender. Default: true.
<li><code>membersOnlyMessage</code>: Mails from non-members (if they are disabled) will be bounced with this message. Default:</span>
<q>Only members of the list are allowed to send a message to this list address.</q>
<li><code>nonMemberSenderValidator</code>: Mails from non-members with subjects matching the supplied regular expressions will be always allowed. Optional.
</ul>

</body>
</html>
31 changes: 31 additions & 0 deletions setup/doc/basic-configuration/postmaster.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<html>
<head>
<title>Designating the Postmaster</title>
<link rel="stylesheet" type="text/css" href="../doc.css" />
</head>

<body>
<h1>Designating the Postmaster</h1>

According to <cite>RFC 5321</cite>:
<q cite="http://tools.ietf.org/html/rfc5321">Any system that includes an SMTP server
supporting mail relaying or delivery MUST support the reserved mailbox "postmaster" as a
case-insensitive local name.</q>

<p>Edit <code>local-recipients.js</code> and change the value of the <code>PostmasterAliasMapper.canonical</code>
attribute.
For example if the local user, <code>[email protected]</code>, should receive mails sent to the postmaster addresses
then the result should look like this:
<p class="code">...
setup(PostmasterAliasMapper, {
canonical: "<span class="relevant">[email protected]</span>"
}),
...
</p>

<p>The designated Postmaster will receive mails sent to the Postmaster of any local
domains (for example <code>[email protected]</code>)
and also to the special <code>Postmaster</code> (without domain) address.

</body>
</html>
Loading

0 comments on commit 37a5860

Please sign in to comment.