Windows¶
Setup program¶
To install E-MailRelay on Windows run emailrelay-setup.exe.
The installation GUI will take you through the installation options and then
install the run-time files from the payload directory into your chosen
locations and also create a startup batch file (emailrelay-start.bat) and
configuration file (emailrelay.cfg).
If you plan to install into Program Files and ProgramData, or if you want
to run E-MailRelay as a Windows service then you will need to allow the
installation program to run as Administrator.
You can also run the main E-MailRelay program emailrelay.exe directly without
going through the installation process but you will need to refer to the
documentation to set the appropriate configuration options.
Running the program¶
After a successful installation you should see E-MailRelay listed in the
Windows Start Menu and/or as an entry in the Windows Services tool.
The Start Menu item will run the startup batch file emailrelay-start.bat.
This is normally in the ProgramData\E-MailRelay folder, together with
the configuration file emailrelay.cfg. Once the E-MailRelay server is running
you should see an icon appear in the Windows System Notification Area (also
known as the System Tray) under the Show hidden icons button.
Or if E-MailRelay runs as a service you should see an entry in the Windows
Services tool with a status of Running. Check the E-MailRelay log file to see
what it is doing.
Configuration¶
E-MailRelay is configured with options like --verbose and --spool-dir in the
emailrelay-startup.bat batch file, or equivalently verbose and spool-dir
lines in the emailrelay.cfg configuration file.
Note that emailrelay-start.bat lives under ProgramData, and although this
might be a hidden directory you can still navigate there by right-clicking on
the E-MailRelay link under Program Files\E-MailRelay and selecting "Open file
location".
You can edit the batch file or configuration file using Notepad: right-click on
the file, then show more options and edit.
Alternatively, use the emailrelay-gui program to make the changes.
All configuration options are documented in the E-MailRelay reference document.
Account user-ids and passwords can be configured by editing the E-MailRelay
secrets file, normally ProgramData\E-MailRelay\emailrelay.auth. Check that
the --client-auth or --server-auth options in the startup batch file or
configuration file refer to this file.
Manual installation¶
The manual installation process for when you cannot run the setup program can be as simple as this:
Create a new program directory
C:\Program Files\E-MailRelay.Create a new spool directory
C:\Program Files\E-MailRelay\spool.Copy the EXE files from
programsin the zip file intoC:\Program Files\E-MailRelay.Create a new text file, e.g.
C:\Program Files\E-MailRelay\auth.txt, to contain account details.Add account details to
auth.txtwith a line likeclient plain myaccount mypassword.Right-drag
emailrelay.exeonto the desktop to create a shortcut for the server.Add configuration options to the server shortcut properties in the
targetbox.
The configuration options should normally include:
--log-file=@app\log-%d.txt--spool-dir=@app\spool--client-auth=@app\auth.txt--forward-to=smtp.example.com:25--poll=60
Copy the shortcut to Start Menu and Startup folders as necessary.
Running as a service¶
E-MailRelay can be set up as a Windows service so that it starts up
automatically at boot-time. This can be enabled on the Server startup page
in the installation program or later using the emailrelay-gui configuration
program.
Alternatively, to set up the service manually you must first have a
configuration file called emailrelay.cfg that contains all the configuration
options for running the E-MailRelay server, and you must have a simple
service-wrapper configuration file called emailrelay-service.cfg that points
to it, and this must be in the same directory as the service wrapper executable
(emailrelay-service.exe).
The contents of the service-wrapper configuration file can be a single line that points to the folder containing the configuration file, like this:
dir-config="C:\ProgramData\E-MailRelay"
Then just run emailrelay-service --install from an Administrator command
prompt to install the service.
If you need to run multiple E-MailRelay services then put a unique service
name and display name on the emailrelay-service --install <name> <display-name>
command-line. The service name you give is used to derive the name of the
configuration file (<name>.cfg) that contains the E-MailRelay server's
configuration options, so you will need to create that first.
Note that a service specific error code when starting the service is the main
emailrelay program's exit code. This will have the value 2 if the listening
socket is already in use, normally indicating that another E-MailRelay program
is running.
Uninstall¶
To uninstall:
Stop the program and/or the service.
Uninstall the service, if installed (
emailrelay-service --remove).Delete the files from the E-MailRelay
program filesfolder (e.g.C:\Program Files\E-MailRelay).Delete the files from the E-MailRelay
program datafolder (e.g.C:\ProgramData\E-MailRelay).Delete any desktop shortcuts (e.g.
%USERPROFILE%\Desktop\E-MailRelay.lnk).Delete any start menu shortcuts (e.g.
%APPDATA%\Microsoft\Windows\Start Menu\Programs\E-MailRelay.lnk).Delete any auto-start shortcuts (e.g.
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\E-MailRelay.lnk).Clean up the registry under
HKLM\System\CurrentControlSet\Services\EventLog\Application\emailrelay.
Diagnostics¶
E-MailRelay logging is sent to the Windows Event Log and/or written to a log
file, and individual failed mail messages will have the failure reason recorded
inside the .bad envelope file.
The Windows Event Log can be accessed by running eventvwr.exe or searching for
Event Viewer; from there look under Windows Logs and Application.
You can increase the verbosity of the logging by adding the --verbose option
to the E-MailRelay options, typically by editing the emailrelay.cfg
configuration file in the C:\ProgramData\E-MailRelay folder.
Testing with telnet¶
The telnet program can be used for testing an E-MailRelay server.
To install the program search for Windows Features and enable the "Telnet
client" checkbox.
Then run telnet from a command prompt, using localhost and the E-MailRelay
port number as command-line parameters:
telnet localhost 25
This should show a greeting from the E-MailRelay server and then you can
start typing SMTP commands like EHLO, MAIL FROM:<..>, RCPT TO:<...>
and DATA. Refer to RFC-821 Appendix F for some examples.