1 MegaBrutal's SMTP Server (MgSMTP)
3 ~~~ BASIC USER'S GUIDE ~~~
8 III. Installation/Uninstallation
11 VI. Reading your local e-mails
12 VII. Running in user mode
13 VIII. Running under Wine
14 IX. Service-specific exit codes
21 MgSMTP is a lightweight SMTP server for Windows and Wine. 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.
23 Common uses of MgSMTP:
24 - As an SMTP relay on a Windows desktop OS to accept e-mails from your applications, other computers, devices on your LAN.
25 - SMTP relay for scan-to-mail printers.
26 - To make the PHP mail function work for your Apache/PHP installation on Windows.
28 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.
30 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.
32 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.
34 If you use the software, I highly recommend you to subscribe to the project's mailing list here:
35 https://lists.sourceforge.net/lists/listinfo/mgsmtp-general
37 MgSMTP is a one-man project that I do in my free time. Any donations would be highly appreciated.
38 http://sourceforge.net/project/project_donations.php?group_id=371997
44 As of now, MgSMTP only supports a relatively small 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.
48 - Mail forwarding/remailing
49 - Aliases, plus aliases
50 - User authentication (AUTH LOGIN)
52 - Domain-specific mailboxes
54 Unsupported, planned features:
55 - DNSBL check (RBL, RHSBL)
58 - Bind to specific interfaces only
63 III. Installation/Uninstallation
64 --------------------------------
66 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.)
71 1. Extract the contents of the package to a directory you'd like it. For example: "C:\Program Files\MgSMTP".
73 2. Make a configuration file ("mgsmtp_server.ini") and create a mailbox for "postmaster". (See below.)
75 3. Open up a command-line in the target directory. Type: "mgsmtp /INSTALL" to register MgSMTP as a Windows service. If you have a 64-bit operating system and would prefer to use the 64-bit binary, use "mgsmtp64 /INSTALL".
77 4. Type "net start MgSMTP" to start the service.
79 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)! Additionally, you can check mgsmtp_stdout.log (in %SYSTEMROOT%\System32 or %SYSTEMROOT%\SysWOW64, depending on your architecture).
84 1. Open up a privileged command line, and go to the directory of MgSMTP.
86 2. Stop the MgSMTP service. (You can do this by issuing the "net stop MgSMTP" command.)
88 3. Type "mgsmtp /UNINSTALL" or "mgsmtp64 /UNINSTALL" to unregister the MgSMTP service.
90 You have successfully uninstalled MgSMTP. You may safely remove its subdirectory if you want.
96 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.
98 I list some hints and warnings here:
100 - 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.
102 - 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.
104 - 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:
109 V. Managing mailboxes
110 ---------------------
112 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.
115 To add a new mailbox:
117 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.
119 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:
121 (Don't forget about the dot to indicate you don't want your filename to have any extension!)
123 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.
125 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
127 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").
129 4. Restart MgSMTP, for it won't be aware of the new mailbox until you do so.
136 2. Simply delete the mailbox file from the "mail" directory, or move it to another directory.
138 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.)
140 4. Start MgSMTP again.
145 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.
146 NOTE: Instead of renaming the mailbox, you should consider adding an alias for it!
149 To add aliases and setting the quota of a mailbox:
151 See the example configuration file to see how to adjust the settings of existing mailboxes.
152 NOTE: If possible, add aliases by editing the configuration file, instead of creating hardlinks or symlinks for mailboxes. (Though there were cases when I had to use links, and it worked fine.) If you need aliases for domain-specific mailboxes those are in a different domain, you can still use the "RewriteTo" feature.
155 VI. Reading your local e-mails
156 ------------------------------
158 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:
159 inbox-path=C:\Program Files\MgSMTP\mail\postmaster
161 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.
163 I don't know about any other GUI 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!) On the command-line, you may have some Unix tools ported through Cygwin, GnuWin32, MinGW, but I didn't use any of them extensively.
165 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.
168 VII. Running in user mode
169 -------------------------
171 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.
173 1. Ensure that your user profile has administrative rights.
175 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".
177 3. Type "mgsmtp /USERMODE" at the command-line.
179 4. To stop MgSMTP, hit CTRL-C at the command-line. You should get your prompt back.
182 VIII. Running under Wine
183 -----------------------
185 Since I basically quit using Windows and became a massive Ubuntu user in the last 2 years, I needed to look for a solution to continue running MgSMTP (since it's mine, of course I insist to use it :p). Unfortunately, I didn't have time to port MgSMTP to Linux, thus I use it with Wine. I've even made some modifications to the code to make it more compatible with Wine. Even though you have many mail server alternatives for Linux, if you still insist to use MgSMTP, and accept the resource-overhead that comes with running it under Wine, there's nothing holding you back.
187 Here are some tips for running MgSMTP under Wine:
189 - As you know, in the Unix world, only root processes can bind to ports below 1024. The standard SMTP port (25) is in this range. Still, you are not advised to run MgSMTP or Wine as root. The workaround for this is to create a system account dedicated for MgSMTP (e.g. "mgsmtp", also consider adding it to group "mail"). Set up MgSMTP to listen on a higher port (e.g. 2500), and then forward port 25 to port 2500. You can use iptables:
190 iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 25 -j REDIRECT --to-port 2500
192 The drawback of port forwarding is that it won't apply to the local machine, so applications running on the actual machine have to be configured to connect on port 2500. But other machines on your network will be able to connect your server on port 25.
194 - It is also advised to isolate MgSMTP in a chroot jail, or even better, in a container (e.g. LXC). By using the latter, you will have a dedicated IP for MgSMTP with a separate iptables, thus you'll be able to connect that IP on port 25 from your host.
196 - I personally suggest to install MgSMTP under /opt, e.g. /opt/mgsmtp, and it's also fine to set this directory as the home directory for your "mgsmtp" account. Thus your wineprefix will be /opt/mgsmtp/.wine, and Wine will see your home as Z:\opt\mgsmtp\.
198 - Good idea to symlink or bind mount /var/mail to MgSMTP's mail directory, or link individual mailbox files to/from there, so the system will be aware of your mailboxes.
200 - Wine has an inconvenient feature. It only runs services when other, non-service applications are running under the same wineprefix. When all non-service applications quit, Wine will kill all Windows services, including MgSMTP. I've searched for the reason and I've only found, Wine is not designed to run permanent Windows services. Live with it! The solution is to always keep an application open with Wine. I always open a cmd.exe for this purpose, and a screen is ideal to keep it alive.
202 Example for MgSMTP installation under Wine:
209 Detach from screen. MgSMTP will continue to run in the background. Next time you want to start MgSMTP, you won't need "net start MgSMTP": since MgSMTP registers itself as an auto-start service, Wine will automatically start it when you open a cmd. Just remember to start cmd in a screen, so it is kept alive. Also advised to keep a separate wineprefix for MgSMTP (if you've created a separate Unix account to run it, then this condition is automatically fulfilled).
212 IX. Service-specific exit codes
213 -------------------------------
215 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.
217 Here are the meanings of these service specific exit codes:
219 1: The configuration file, "mgsmtp_server.ini" is missing, or otherwise inaccessible.
221 2: You haven't supplied a name for your mail server in the configuration file. You must fill in the "Server\Name" entry.
223 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.
225 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.
231 MegaBrutal's SMTP Server (MgSMTP)
232 Copyright (C) 2010-2014 MegaBrutal
234 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.
236 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.
238 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/>.
241 ~~~ By MegaBrutal ~~~
projects / mgsmtp.git / blob