readme.txt

   1                         MegaBrutal's SMTP Server (MgSMTP)
   2
   3                            ~~~ BASIC USER'S GUIDE ~~~
   4
   5
   6     I. Foreword
   7    II. Features
   8   III. Installation/Uninstallation
   9    IV. Configuration
  10     V. Managing mailboxes
  11    VI. Reading your local e-mails
  12   VII. Running in user mode
  13  VIII. Service-specific exit codes
  14    IX. Disclaimer
  15
  16
  17 I. Foreword
  18 -----------
  19
  20 MgSMTP is a lightweight SMTP server for Windows, with minimal feature support. (However, the list of its features is constantly augmenting.) MgSMTP is suitable for you, if you'd like to run a simple, low-traffic mail server on Windows. You can use it as a relay on your LAN, or a primary or backup MX server for your domain(s). It runs as a Windows service. MgSMTP is a free and open-source software released under the GNU GPL.
  21
  22 Common uses of MgSMTP:
  23 - As an SMTP relay on a Windows desktop OS to accept e-mails from your applications, other computers, devices on your LAN.
  24 - SMTP relay for scan-to-mail printers.
  25 - To make the PHP mail function work for your Apache/PHP installation on Windows.
  26
  27 Thanks for downloading MgSMTP! If you have any comments, questions, feature or support requests, bug reports regarding the software, please send an e-mail to <megabrutal@mgsmtp.eu>. In case of bug reports and support requests, please try to explain your problem in details and (if applicable) include relevant snippets from your smtp.log.
  28
  29 Currently, MgSMTP is in BETA state. I don't recommend to use it for critical purposes. MgSMTP has never been tested under high traffic, and most likely it would provide very poor performance in such conditions. I suggest you to check for new MgSMTP versions frequently, because crucial bugfixes may be released at any day.
  30
  31 Also note, I don't provide any warranty for MgSMTP (and the voluntary support I provide for it). Of course, I'll do my best to make it a good-quality software, but I can't promise anything. See the official disclaimer at the end of this file.
  32
  33 If you use the software, I highly recommend you to subscribe to the project's mailing list here:
  34 https://lists.sourceforge.net/lists/listinfo/mgsmtp-general
  35
  36 MgSMTP is a one-man project that I do in my free time. Any donations would be highly appreciated.
  37 http://sourceforge.net/project/project_donations.php?group_id=371997
  38
  39
  40 II. Features
  41 ------------
  42
  43 As of now, MgSMTP only supports a very basic set of features. Read mgsmtp_server_example.ini for details. Sadly, MgSMTP still lacks some common features those are widely supported by most mail servers. As of yet, MgSMTP doesn't support SSL/TLS, and doesn't utilize any SPAM-prevention techniques.
  44
  45 Supported features:
  46 - Mail routing table
  47 - Mail forwarding/remailing
  48 - User authentication (AUTH LOGIN)
  49 - ACLs
  50 - Domain-specific mailboxes
  51
  52 Unsupported, planned features:
  53 - DNSBL check (RBL, RHSBL)
  54 - Message piping
  55 - Greylisting
  56 - Bind to specific interfaces only
  57 - IPv6
  58 - SSL/TLS
  59
  60
  61 III. Installation/Uninstallation
  62 --------------------------------
  63
  64 Note, some steps of the installation (or uninstallation) may require administrative rights. If UAC is enabled on your system, ensure that you start applications necessary for doing the following steps (such as Total Commander, if you use, and command-line) as administrator. (UAC is only available on Windows Vista and newer systems, you don't need to worry about it if you have an older OS - just log in as an administrator account.)
  65
  66
  67 To install:
  68
  69 1. Extract the contents of the package to a directory you'd like it. For example: "C:\Program Files\MgSMTP".
  70
  71 2. Make a configuration file ("mgsmtp_server.ini") and create a mailbox for "postmaster". (See below.)
  72
  73 3. Open up a command-line in the target directory. Type: "mgsmtp /INSTALL" to register MgSMTP as a Windows service.
  74
  75 4. Type "net start MgSMTP" to start the service.
  76
  77 If you get an error message at the last step, see the service-specific exit codes below. Also don't forget to inspect your log file (smtp.log by default)!
  78
  79
  80 To uninstall:
  81
  82 1. Open up a privileged command line, and go to the directory of MgSMTP.
  83
  84 2. Stop the MgSMTP service. (You can do this by issuing the "net stop MgSMTP" command.)
  85
  86 3. Type "mgsmtp /UNINSTALL" to unregister the MgSMTP service.
  87
  88 You have successfully uninstalled MgSMTP. You may safely remove its subdirectory if you want.
  89
  90
  91 IV. Configuration
  92 -----------------
  93
  94 The configuration file for MgSMTP is actually an INI file that you need to prepare carefully before you use the software. I've presented a sample configuration file ("mgsmtp_server_example.ini") that you should read to get a clue how to configure MgSMTP. You should make your configuration file as "mgsmtp_server.ini" in MgSMTP's directory.
  95
  96 I list some hints and warnings here:
  97
  98 - You must supply the "Server\Name" entry to start the service. This will be the virtual hostname of your server that it'll report in greetings, in HELO commands sent to other servers, in failure notices; and most importantly, it'll accept e-mail addresses with the given hostname as local. You may supply additional hostnames in "Server\Alias" to tell the server to treat those hostnames as local as well.
  99
 100 - If your server is able to accept connections from the Internet, or otherwise untrusted network, ALWAYS enable the "Server\Policies" setting, and set up rights for foreign hosts wisely. If you neglect to do so, you expose your server to the risk of acting as an open relay, and it's pretty unlikely that you'd like that.
 101
 102 - If you make any modifications to the configuration file, you need to restart the service for changes to take effect. To do this, open up a command-line, and issue the following commands:
 103 net stop MgSMTP
 104 net start MgSMTP
 105
 106
 107 V. Managing mailboxes
 108 ---------------------
 109
 110 MgSMTP uses the mbox format to store e-mails in local mailboxes. Such mailboxes are located in the "mail" directory, relative to the executable's path.
 111
 112
 113 To add a new mailbox:
 114
 115 1. Locate the "mail" directory. If you've never run MgSMTP before, you should create that directory. It must be a subdirectory of the directory where mgsmtp.exe is located.
 116
 117 2. Create an empty file with the name of the desired mailbox in the "mail" directory. There are several methods, e.g. you can use the "touch" command (though you need the appropriate GnuWin32 package for that), or Notepad. For example, you'd like to create a mailbox named "postmaster". Open up a command-line, go to the "mail" directory, and type:
 118 notepad postmaster
 119
 120 A Notepad will open, and it'll notify you that the given file doesn't exist, and ask you whether you'd like to create that file. Click Yes, and close the Notepad. A 0-byte file should show up in the directory.
 121
 122 NOTE: If you use Windows Explorer, be sure that the created file doesn't have any extension. The above command-line approaches ensure that, while Windows Explorer may trick you because it hides the file extensions by default. Notepad may automatically add a ".txt" extension if you use the "Save As..." panel. A mailbox file with an extension will still work technically, but it will be addressed like "postmaster.txt@yourdomain.tld". If that's what you want, go ahead! :p
 123
 124 3. If you need to configure special parameters, features for this mailbox (e.g. aliases, quota setting, forwarding), open your configuration file and add a proper "Mailbox\mailboxname" section (see "mgsmtp_server_example.ini").
 125
 126 4. Restart MgSMTP, for it won't be aware of the new mailbox until you do so.
 127
 128
 129 To remove a mailbox:
 130
 131 1. Stop MgSMTP!
 132
 133 2. Simply delete the mailbox file from the "mail" directory, or move it to another directory.
 134
 135 3. Check the configuration file if there are entries concerning the removed mailbox. (E.g. if there are rewriting or forwarding settings those target the removed mailbox, and other references those might cause anomalies. Leaving the "Mailbox\mailboxname" section there is OK, it'll be just ignored by MgSMTP - though it may be still confusing for you, so it's better to at least comment it out.)
 136
 137 4. Start MgSMTP again.
 138
 139
 140 To rename a mailbox:
 141
 142 Follow the steps of "To remove a mailbox", with the difference that you'd rather rename the mailbox file instead of removing it. In the configuration file, you'll need to replace references to the renamed mailbox with its new name.
 143 NOTE: Instead of renaming the mailbox, you should consider adding an alias for it!
 144
 145
 146 To add aliases and setting the quota of a mailbox:
 147
 148 See the example configuration file to see how to adjust the settings of existing mailboxes.
 149 NOTE: It's best to add aliases by editing the configuration file! Avoid creating hardlinks or symlinks for mailboxes (even though theoretically it wouldn't break MgSMTP)! If you need aliases for domain-specific mailboxes those are in a different domain, you can still use the "RewriteTo" feature.
 150
 151
 152 VI. Reading your local e-mails
 153 ------------------------------
 154
 155 Mailboxes stored on your local computer can be read using Pine or Alpine. These e-mail clients are available for Windows. To configure Alpine to read your local mailbox, set the path for that mailbox as "inbox-path". For example:
 156 inbox-path=C:\Program Files\MgSMTP\mail\postmaster
 157
 158 If you'd like to use multiple mailboxes with Alpine on the same computer, under the same Windows user account, you can use multiple configuration files, each can be supplied with the "-p" command-line switch. You may create distinct shortcuts to start Alpine with different configuration files. Alpine also has an option to use alternate sender addresses.
 159
 160 I don't know about any other mail client that is able to read e-mails from mailboxes directly, and runs on Windows. So it really seems Alpine is the only option. (But if you know about such a client, please tell me!)
 161
 162 If you'd like to read your mailboxes on a remote machine, or with other mail clients than Alpine, you need to install a POP3 or IMAP server, and configure it to operate with your mailboxes. Honestly, I don't know about any softwares those may work like that on Windows. Probably later I'll implement a software named "MgPOP3" (or something like that) as MgSMTP's POP3 counterpart service. Though personally I don't need such a software, because I'm fine with Alpine, so I won't be in hurry with a POP3 implementation.
 163
 164
 165 VII. Running in user mode
 166 -------------------------
 167
 168 First, I don't recommend running MgSMTP in user mode, because in that case, you can't shut it down cleanly. However it could be useful to start MgSMTP in user mode, if you'd like to debug it, or you'd just like to get error messages those are hidden when you run MgSMTP in service mode.
 169
 170 1. Ensure that your user profile has administrative rights.
 171
 172 2. Open up a command-line, go to the directory of MgSMTP. If UAC is enabled on your system, right click on the icon of command-line, and select the option to "run as administrator".
 173
 174 3. Type "mgsmtp /USERMODE" at the command-line.
 175
 176 4. To stop MgSMTP, hit CTRL-C at the command-line. You should get your prompt back.
 177
 178
 179 VIII. Service-specific exit codes
 180 ---------------------------------
 181
 182 If MgSMTP fails to start up, you may see service-specific exit codes either on the command-line (if you've tried to start the service with the "net" command) or in the system logs. PowerShell may also show the service-specific exit code when you use the "Start-Service" command, however I'm not sure.
 183
 184 Here are the meanings of these service specific exit codes:
 185
 186 1: The configuration file, "mgsmtp_server.ini" is missing, or otherwise inaccessible.
 187
 188 2: You haven't supplied a name for your mail server in the configuration file. You must fill in the "Server\Name" entry.
 189
 190 3: You don't have a mailbox named "postmaster". Either create a new mailbox with that name, or add "postmaster" as an alias for an existing mailbox.
 191
 192 4: You've attempted to start too many delivery threads. The maximum number of delivery threads is 36. See the explanation in the example configuration file.
 193
 194
 195 IX. Disclaimer
 196 --------------
 197
 198 MegaBrutal's SMTP Server (MgSMTP)
 199 Copyright (C) 2010-2012 MegaBrutal
 200
 201 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 202
 203 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 204
 205 You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <http://www.gnu.org/licenses/>.
 206
 207
 208 ~~~ By MegaBrutal ~~~