MegaBrutal's SMTP Server (MgSMTP) ~~~ BASIC USER'S GUIDE ~~~ I. Foreword II. Features III. Installation/Uninstallation IV. Configuration V. Managing mailboxes VI. Reading your local e-mails VII. Running in user mode VIII. Service-specific exit codes IX. Disclaimer I. Foreword ----------- 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. Common uses of MgSMTP: - As an SMTP relay on a Windows desktop OS to accept e-mails from your applications, other computers, devices on your LAN. - SMTP relay for scan-to-mail printers. - To make the PHP mail function work for your Apache/PHP installation on Windows. 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 . 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. 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. 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. If you use the software, I highly recommend you to subscribe to the project's mailing list here: https://lists.sourceforge.net/lists/listinfo/mgsmtp-general MgSMTP is a one-man project that I do in my free time. Any donations would be highly appreciated. http://sourceforge.net/project/project_donations.php?group_id=371997 II. Features ------------ 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. Supported features: - Mail routing table - Mail forwarding/remailing - User authentication (AUTH LOGIN) - ACLs - Domain-specific mailboxes Unsupported, planned features: - DNSBL check (RBL, RHSBL) - Message piping - Greylisting - Bind to specific interfaces only - IPv6 - SSL/TLS III. Installation/Uninstallation -------------------------------- 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.) To install: 1. Extract the contents of the package to a directory you'd like it. For example: "C:\Program Files\MgSMTP". 2. Make a configuration file ("mgsmtp_server.ini") and create a mailbox for "postmaster". (See below.) 3. Open up a command-line in the target directory. Type: "mgsmtp /INSTALL" to register MgSMTP as a Windows service. 4. Type "net start MgSMTP" to start the service. 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)! To uninstall: 1. Open up a privileged command line, and go to the directory of MgSMTP. 2. Stop the MgSMTP service. (You can do this by issuing the "net stop MgSMTP" command.) 3. Type "mgsmtp /UNINSTALL" to unregister the MgSMTP service. You have successfully uninstalled MgSMTP. You may safely remove its subdirectory if you want. IV. Configuration ----------------- 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. I list some hints and warnings here: - 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. - 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. - 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: net stop MgSMTP net start MgSMTP V. Managing mailboxes --------------------- 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. To add a new mailbox: 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. 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: notepad postmaster 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. 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 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"). 4. Restart MgSMTP, for it won't be aware of the new mailbox until you do so. To remove a mailbox: 1. Stop MgSMTP! 2. Simply delete the mailbox file from the "mail" directory, or move it to another directory. 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.) 4. Start MgSMTP again. To rename a mailbox: 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. NOTE: Instead of renaming the mailbox, you should consider adding an alias for it! To add aliases and setting the quota of a mailbox: See the example configuration file to see how to adjust the settings of existing mailboxes. 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. VI. Reading your local e-mails ------------------------------ 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: inbox-path=C:\Program Files\MgSMTP\mail\postmaster 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. 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!) 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. VII. Running in user mode ------------------------- 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. 1. Ensure that your user profile has administrative rights. 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". 3. Type "mgsmtp /USERMODE" at the command-line. 4. To stop MgSMTP, hit CTRL-C at the command-line. You should get your prompt back. VIII. Service-specific exit codes --------------------------------- 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. Here are the meanings of these service specific exit codes: 1: The configuration file, "mgsmtp_server.ini" is missing, or otherwise inaccessible. 2: You haven't supplied a name for your mail server in the configuration file. You must fill in the "Server\Name" entry. 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. 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. IX. Disclaimer -------------- MegaBrutal's SMTP Server (MgSMTP) Copyright (C) 2010-2012 MegaBrutal 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. 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. You should have received a copy of the GNU Affero General Public License along with this program. If not, see . ~~~ By MegaBrutal ~~~