E-MailRelay 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`). 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` which contains all the necessary configuration options, and once the E-MailRelay server is running you should see an icon appear in the Windows system notification area 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` or `--spool-dir` in the `emailrelay-startup.bat` batch 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` and selecting `Open file location`. You can edit the batch file using Notepad: right-click on the E-MailRelay link or on the `emailrelay-start.bat` 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. Check 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 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 `programs` in the zip file into `c:\Program Files\E-MailRelay`. * Create a new text file, eg. `c:\Program Files\E-MailRelay\auth.txt`, to contain account details. * Add account details to `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 configuration options to the server shortcut properties in the `target` box. The configuration options should normally include: * `--log` * `--verbose` * `--log-file=@app\log-%d.txt` * `--spool-dir=@app\spool` * `--client-auth=@app\auth.txt` * `--client-tls` * `--forward-to=smtp.example.com:25` * `--forward-on-disconnect` * `--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 one-line batch file called `emailrelay-start.bat` 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 startup 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 service-wrapper configuration file can be a single line that points to the directory containing the startup batch file, 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 service-wrapper configuration file and the startup batch file in order to run the E-MailRelay program. If you need to run multiple E-MailRelay services then put a unique service name and display name on the `emailrelay-service --install ` command-line. The service name you give is used to derive the name of the `-start.bat` batch file that contains the E-MailRelay server's configuration options, so you will need to create that first. 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 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 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-start.bat` batch script in `C:\ProgramData\E-MailRelay`. 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. [RFC-821]: https://tools.ietf.org/html/rfc821 [SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol _____________________________________ Copyright (C) 2001-2023 Graeme Walker