E-MailRelay Windows

Setup program

Installing E-MailRelay on Windows should be straightforward if you have the setup program emailrelay-setup.exe and its associated payload files.

Run emailrelay-setup.exe as an administrator if you are going to be installing into protected directories like Program Files.

The setup GUI will take you through the installation options and then install the run-time files into your chosen locations.

If anything goes wrong with the installation process then you can still just run the main E-MailRelay executable straight out of the distribution zip file. Follow the Manual installation section below for more help.

Running the program

After a successful installation you should see E-MailRelay listed in the Windows Start Menu. This will run the emailrelay-start.bat batch file to start the E-MailRelay server, and you should then see an icon appear in the Windows system tray.

Configuration

E-MailRelay is configured though command-line options like --verbose or --spool-dir=c:/temp in the emailrelay-startup.bat batch file.

These options are all documented in the reference document, although there are some Windows-specific variations:

The --syslog option refers to the Windows Event Viewer's Application log.
The --no-daemon option is used for a normal window rather than an icon in the system tray.
The --minimise option, used with --no-daemon, makes the window start minimised.
The --hidden option with --no-daemon hides all windows and suppresses message boxes.

The Windows-only --show option can be used as a more flexible alternative to --no-daemon and --hidden using --show=popup and --show=hidden respectively, or --show=window for a minimisable window, --show=tray for the default system-tray icon or --show=window,tray for both.

Account information can be configured by editing the E-MailRelay secrets file. Look for the --client-auth or --server-auth options in the startup batch file to find out where this is.

Manual installation

The manual installation process for when you do not have the self-extracting setup program, goes something like this:

Create a new program directory c:\Program Files\E-MailRelay
Copy the packaged files into c:\Program Files\E-MailRelay
Create a new spool directory c:\ProgramData\E-MailRelay\spool
Create a new text file, eg. c:\ProgramData\E-MailRelay\emailrelay-auth.txt, to contain account details
Add your account details to emailrelay-auth.txt with a line like client plain myaccount mypassword
Right-drag emailrelay.exe onto the desktop to create a shortcut for the server.
Add --as-server --verbose to the server shortcut properties in the target box.
Right-drag again to create a shortcut to do the forwarding.
Add --as-client example.com:smtp --client-auth c:\ProgramData\E-MailRelay\emailrelay-auth.txt to the client shortcut.

Copy the shortcuts to Start Menu and Startup folders as necessary.

Running as a service

E-MailRelay can be set up as a service so that it starts up automatically at boot-time. If you are setting this up manually you must first have a one-line batch file called emailrelay-start.bat that contains all the command-line options for running the E-MailRelay server, and you must have a simple configuration file called emailrelay-service.cfg that points to it. The configuration file must be in the same directory as the emailrelay-service.exe executable.

The batch file should contain a single line, something like this:

    start "emailrelay" "C:\Program Files\E-MailRelay\emailrelay.exe" --forward-to smtp.example.com:25 ...

There is no need to use --no-daemon and --hidden; these are added automatically.

The contents of the configuration file can be a single line like this:

    dir-config="C:\ProgramData\E-MailRelay"

Then just run emailrelay-service --install from an Administrator command prompt to install the service.

Every time the service starts it reads the configuration file and the startup batch file in order to run the E-MailRelelay program.

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 <name>-start.bat batch file that contains the E-MailRelay server's command-line options, so you will need to create that first.

Uninstall

To uninstall:

Stop the program and/or the service (ControlPanel->SystemAndSecurity->AdministrativeTools->Services).
Uninstall the service, if installed (emailrelay-service --remove).
Delete the files from the E-MailRelay program files folder (eg. C:\Program Files\E-MailRelay).
Delete the files from the E-MailRelay program data folder (eg. C:\ProgramData\E-MailRelay).
Delete any desktop shortcuts (eg. %USERPROFILE%\Desktop\E-MailRelay.lnk).
Delete any start menu shortcuts (eg. %APPDATA%\Microsoft\Windows\Start Menu\Programs\E-MailRelay.lnk).
Delete any auto-start shortcuts (eg. %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 going to ControlPanel->SystemAndSecurity->AdministrativeTools->EventViewer; 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 command-line, typically by editing the emailrelay-start.bat batch script.

Testing with telnet

The telnet program can be used for testing an E-MailRelay server. You should start by enabling the Windows telnet client using ControlPanel->Programs->TurnWindowsFeaturesOnAndOff.

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.

Building from source

E-MailRelay can be compiled on Windows using Microsoft Visual Studio C++ (MSVC) or mingw-w64. For MSVC builds there is a perl script (winbuild) that creates cmake files from the autotools makefiles, runs cmake to create the MSVC project files and then runs msbuild to compile E-MailRelay. If perl, cmake, MSVC, Qt and mbedTLS source are installed in the right way then the winbuild.bat batch file should be able to do a complete MSVC release build in one go.

7.0 KiB Raw Blame History