--------------------------------------------------------------------------- POPFile SSL Setup wizard for Windows v0.5.0 ReadMe 21 August 2011 --------------------------------------------------------------------------- NOTE: This wizard is NOT compatible with POPFile 1.1.2 or any later release. POPFile 1.1.2 (or later) uses a different SSL support package and all of the necessary files are included in the POPFile installer. --------------------------------------------------------------------------- CONTENTS Introduction POPFile 1.0.0 to 1.1.1 POPFile 0.22.5 POPFile 0.22.0 to 0.22.4 BUILTIN Mode Patch to speed up SSL operations SSL Configuration Do not use concurrent POP3 connections ("forking") in POPFile Troubleshooting Capturing POPFile error messages Capturing POPFile error messages (Win9x Instructions) Finding the POPFile files AddSSL log report --------------------------------------------------------------------------- INTRODUCTION --------------------------------------------------------------------------- This wizard is intended for use with POPFile 0.22.x but it can also be used to add or update SSL support for releases up to and including POPFile 1.1.1. This wizard is NOT compatible with the SSL support used by POPFile 1.1.2 (or later) therefore it will report an error if an attempt is made to use it with POPFile 1.1.2 or any later release. To support SSL connections to mail servers POPFile requires some additional Perl components and OpenSSL DLLs which are not included in the installer. To ensure that POPFile uses the most up-to-date SSL files these additional files are normally downloaded by the Windows installer when the SSL Support option is selected. The Windows installers for POPFile 1.0.0, 1.0.1, 1.1.0 and 1.1.1 create a "Change" option in POPFile's "Add/Remove Programs" entry to make it easy to add (or update) the SSL Support files after POPFile has been installed. Most of the SSL Support files are downloaded from the University of Winnipeg repository but one file is downloaded from another repository (ppm.tcool.org) in order to get a newer version which supports timeouts. POPFile 1.1.0 uses a timeout to cope with mail servers which fail to respond promptly (earlier versions of POPFile would "hang" if the SSL mail server failed to respond). Sometimes some patches need to be applied to make POPFile work with these SSL files. The installers for the 1.0.0 to 1.1.1 releases are able to download and apply any necessary SSL patches. The 0.22.5 installer is able to download the SSL Support files but it cannot download any patches for this old release (because the installer does not use the new POPFile web server address). If any SSL patches become necessary for POPFile 0.22.5 this wizard must be used instead of the 0.22.5 installer. The installers for 0.22.3 and 0.22.4 are unable to handle these SSL patches therefore this SSL Setup wizard must be used to add or upgrade SSL support for these releases (because neither 0.22.3 nor 0.22.4 are compatible with the current SSL files from the University of Winnipeg repository). The installers for POPFile 0.22.0, 022.1 and 0.22.2 do not install the files required to provide SSL support therefore this SSL Setup wizard must be used to add or upgrade SSL support for these old releases. Although this wizard has been provided to make it easy to add all the necessary extra Perl components and OpenSSL DLLs to an existing POPFile 0.22.5 or earlier installation, it can be used with later releases of POPFile as an alternative to using the "Change" option in the "Add/Remove Programs" entry for POPFile (or the installer's "/SSL" mode). --------------------------------------------------------------------------- POPFile 1.0.0 to 1.1.1 --------------------------------------------------------------------------- In addition to downloading and installing the extra SSL support files the installers for the 1.0.0, 1.0.1, 1.1.0 or 1.1.1 releases will download and apply any necessary SSL patches from the POPFile website. The installer also creates a "Change" option in the "Add/Remove Programs" entry for POPFile that can be used to add or upgrade SSL support for an existing POPFile installation. If the installer was unable to download and install SSL support at install time this "Change" option can be used to make further attempts. This utility can be used as an alternative to using the "Add/Remove Programs" entry to add or update SSL support for the 1.0.0 or later releases of POPFile. --------------------------------------------------------------------------- POPFile 0.22.5 --------------------------------------------------------------------------- The installer for the 0.22.5 release is able to download and install the extra SSL support files for POPFile. If there is a problem downloading and installing SSL support then another attempt can be made by re-running the installer with the "/SSL" command-line option: setup.exe /SSL This makes the installer run in a special mode which only adds or upgrades SSL support for the existing installation. At present no SSL patches are required for 0.22.5 but if any are required for this old release then the 0.22.5 installer will be unable to apply them (because it does not use the new address for the POPFile web server). This utility is able to download and install SSL support and any necessary SSL patches for POPFile 0.22.5. If SSL Support is required for POPFile 0.22.5 it is recommended that this utility be used instead of the 0.22.5 installer to ensure that any necessary SSL patches get applied to this old release. --------------------------------------------------------------------------- POPFile 0.22.0 to 0.22.4 --------------------------------------------------------------------------- If SSL support is required for POPFile 0.22.4 or any earlier 0.22.x release then this utility _must_ be used, otherwise POPFile will crash when it tries to use SSL to connect to a mail server. POPFile 0.22.0 and 0.22.1 ship with a minimal Perl based upon Perl 5.8.3 and the 0.22.2 release uses a minimal Perl based upon Perl 5.8.4. Both of these minimal Perl systems will crash when they try to use the current University of Winnipeg SSL files therefore this wizard includes a set of SSL files which are compatible with POPFile 0.22.0, 0.22.1 and 0.22.2 installations. POPFile 0.22.3 and 0.22.4 use Perl 5.8.7 which is no longer compatible with one of the current SSL files (SSL.pm) from the University of Winnipeg. This is why POPFile will crash when trying to use SSL if the 0.22.3 or 0.22.4 installer was used to add SSL support to POPFile. This SSL Setup wizard is able to downgrade the SSL.pm file to version v0.97 to make it work with POPFile 0.22.3 & 0.22.4. The original SSL.pm file will be backed up as SSL.pm.bk1 (in the same folder). Once the installation location has been selected the minimal Perl's version number is used to determine whether to install the built-in SSL files or to download and install the latest SSL files and apply the necessary patches. --------------------------------------------------------------------------- BUILTIN Mode --------------------------------------------------------------------------- If the minimal Perl version cannot the determined, the built-in SSL files are installed in the hope that these will allow POPFile 0.22.0 or any later version up to and including POPFile 1.1.1 to use SSL. Another way to force the installation of the built-in SSL files is to supply the /BUILTIN option on the command-line when running this utility: addssl.exe /BUILTIN This is an easy way to cope with the case where the University of Winnipeg SSL support files are not compatible with the current POPFile release and this utility is unable to make the files compatible with POPFile. --------------------------------------------------------------------------- PATCH TO SPEED UP SSL OPERATIONS --------------------------------------------------------------------------- The Module.pm file distributed with POPFile 0.22.0 results in EXTREMELY SLOW message downloading. This problem was fixed in the 0.22.1 and later releases. If this utility is used to add SSL support to an installation which uses the "slow" version of Module.pm it will automatically patch the module to make it match the version which was distributed with the 0.22.1 release. This patch makes SSL operation work at a similar speed to non-SSL operation. If the file is patched, the original Module.pm file will be backed up as Module.pm.bk1 (in the same folder). --------------------------------------------------------------------------- SSL CONFIGURATION --------------------------------------------------------------------------- This version of the wizard does not attempt to configure any email accounts to use SSL; it simply adds the necessary SSL support files to an existing setup. To change a POPFile-enabled account to use SSL, change the "login" details for this account in the email program from "servername:username" to "servername:995:username:ssl" For POPFile 0.22.3 (or later) the "login" details can simply be changed to "servername:username:ssl" (i.e. all you need to do is add ':ssl' at the end) Please note that the SSL connection is between POPFile and the mail server, so do _not_ configure the email program to use SSL for this account. If you want to reconfigure an account (which uses SSL) to make it work with POPFile, make sure that the "Use secure connection (SSL)" option is NOT selected for this account in your email program, in addition to changing the "login" details as described above. You'll also need to change the POP3 server settings, as described in the on-line POPFile documentation. --------------------------------------------------------------------------- DO NOT USE CONCURRENT POP3 CONNECTIONS ("FORKING") IN POPFILE --------------------------------------------------------------------------- If "Allow concurrent POP3 connections" shows "No" on the Configuration page in the UI then "forking" is disabled (this is the default setting). If you have enabled forking, please disable it (otherwise POPFile will crash when accessing any SSL-enabled accounts). To disable forking, change the "Allow concurrent POP3 connections" setting from "Yes" to "No" on the Configuration page, or change the "pop3_force_fork" parameter on the Advanced page in the UI from "1" to "0", or shutdown POPFile and edit the "pop3_force_fork" setting in the popfile.cfg file (0 = disabled) --------------------------------------------------------------------------- TROUBLESHOOTING --------------------------------------------------------------------------- The SSL files in the University of Winnipeg repository are updated at irregular intervals. At present (21 August 2011) no SSL patches are required for POPFile 0.22.5, 1.0.0, 1.0.1 or 1.1.0 and this utility is able to make the downloaded SSL files compatible with POPFile 0.22.3 or 0.22.4 (by downgrading one file to an earlier version). It is possible that future updates of these SSL files may not work properly with POPFile. As a temporary workaround you can force this wizard to install the old SSL files which are normally only used with POPFile 0.22.0, 0.22.1 and 0.22.2. Just supply the /BUILTIN command-line option when you run the wizard: addssl.exe /BUILTIN The option is not case-sensitive so /builtin can be used instead of /BUILTIN Although these old files are out of date they may still work with POPFile 0.22.3 or later. If you have trouble using POPFile's SSL mode, you are recommended to use POPFile's console mode when you run POPFile so you will be able to see any error messages output by POPFile. There are several ways to select console mode. For further details see the "Capturing POPFile error messages" or "Capturing POPFile error messages (Win9x Instructions)" sections of this document. --------------------------------------------------------------------------- CAPTURING POPFILE ERROR MESSAGES --------------------------------------------------------------------------- An easy way to temporarily run POPFile in console mode without changing any configuration settings is to use the Message Capture Utility to run POPFile instead of the method normally used to run POPFile. The Message Capture Utility (msgcapture.exe) will display the POPFile console messages in a scrollable window and allow you to save them in a text file by right-clicking inside that window - this makes it easy to report any messages which result from problems with the SSL support installed by this wizard. Recent versions of POPFile's installer create a Start Menu shortcut which can be used to run the Message Capture Utility: Start -> Programs -> POPFile -> Support -> Message Capture utility (this shortcut will also work on Win9x systems) The 'msgcapture.exe' program can be found in the same folder as 'runpopfile.exe'. You can run the utility by using the command msgcapture.exe /timeout=0 (that is a zero not a letter O at the end of the command) to ensure the msgcapture.exe program waits for POPFile to shut down or terminate. Note that the '/timeout=0' option can be omitted for msgcapture.exe v0.0.55 (or later). This command will not work on Win9x systems - please see the next section. --------------------------------------------------------------------------- CAPTURING POPFILE ERROR MESSAGES (Win9x INSTRUCTIONS) --------------------------------------------------------------------------- Recent versions of POPFile's installer create a Start Menu shortcut which can be used to run the Message Capture Utility: Start -> Programs -> POPFile -> Support -> Message Capture utility If the installer did not create this "Message Capture utility" shortcut you can use the 'pfi-run.bat' file in the POPFile 'User Data' folder to capture the error messages. This batch file sets up the necessary environment data before running the 'msgcapture.exe /timeout=0' command. An easy way to run this batch file is to double-click its icon. A DOS box should appear briefly, followed by the window for the "POPFile Message Capture Utility". If all you see is a DOS box popping up and instantly disappearing (with no Message Capture Utility window appearing), you will need to allocate some more environment space for the batch file. To do this, right-click the pfi-run.bat icon, select "Properties", select the "Memory" tab and look at the "Initial environment" value (at the top right). If the setting is "Auto", select "512" from the list, click "Apply" then "OK". If the setting is not "Auto" then select a higher value (e.g. if it says "512" then change it to "768"). After increasing the environment space, double-click the pfi-run.bat icon to start the POPFile Message Capture Utility. --------------------------------------------------------------------------- FINDING THE POPFILE FILES --------------------------------------------------------------------------- If you are not sure where the POPFile program files and/or the 'User Data' files are stored, use the following Start Menu shortcut to find out: Start -> Programs -> POPFile -> Support -> PFI Diagnostic utility (simple) --------------------------------------------------------------------------- ADDSSL LOG REPORT --------------------------------------------------------------------------- A timestamped log file (addssl.log) is created in the POPFile program folder listing the actions performed by the POPFile SSL Setup wizard. --------------------------------------------------------------------------- This product installs software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/) --------------------------------------------------------------------------- CHANGE HISTORY: 21-Aug-11 (v0.5.0) Updated to detect POPFile 1.1.2 or later as these releases use a different SSL support package and are therefore not compatible with this wizard. 05-Dec-08 (v0.3.7) Updated now that POPFile 1.1.0 has been released. 17-Sep-08 (v0.3.6) Use ppm.tcool.org repository for IO::Socket:SSL (released as an RC4 version) 13-Aug-08 (v0.3.5) Updated to use the latest version of the Inetc plugin. 24-Jul-08 (v0.3.4) Updated to use a plugin to determine the status of the POPFile service. 04-Mar-08 (v0.3.1) Updated to use the relevant POPFile Patch Control File when the utility is used to add or upgrade SSL Support for POPFile 0.22.5 or a later release. 14-Feb-08 (v0.3.0) Updated to work with the POPFile project's new server structure and the current SSL Support files from the University of Winnipeg repository. 18-Sep-07 (v0.2.11) Further Vista improvements (can now detect if POPFile is running when the utility is run by a "standard" user). Updated the Inetc plugin to the "11 August 2007" version. 08-Feb-07 (v0.2.8) Made the utility work a little better with Windows Vista. 27-Jan-07 (v0.2.7) If the SSL Support files are downloaded the utility now downloads any patches required to make the SSL Support files compatible with POPFile 0.22.x. 02-Jan-07 (v0.2.5) Rebuilt using the new "1 January 2007" version of the Inetc plugin. 05-Dec-06 (v0.2.4) Avoid the need to patch the standard NSIS MUI language file to replace "Japanese" with "Nihongo" in the menu used to select the language used by the utility. 28-Nov-06 (v0.2.3) Rebuilt using the latest NSIS compiler (v2.22). 19-Nov-06 (v0.2.2) Rebuilt using the latest NSIS compiler (v2.21) and the new "12 November 2006" version of the Inetc plugin. When the /BUILTIN option is used the utility no longer tries to patch SSL.pm (because the built-in version is compatible with POPFile). 14-Sep-06 (v0.2.1) The University of Winnipeg repository has been updated to supply IO::Socket::SSL v1.01 which is not compatible with the current version of POPFile. Updated this wizard to downgrade SSL.pm v1.01 to v0.97 which is compatible with POPFile. Now using the latest version of the Inetc plugin. A message is now shown if the SSL.pm patch fails to work. 29-Aug-06 (v0.2.0) Updated the Version Information and the version number. 21-Aug-06 (v0.1.9) Simplified the code by removing the need for duplicated data files (the installer and this utility now use the same SSL patch file and the same 'empty' file). 20-Aug-06 (v0.1.8) The University of Winnipeg repository has been updated to supply IO::Socket::SSL v0.999 which is not compatible with the current version of POPFile. Updated this wizard to downgrade SSL.pm v0.999 to v0.97 which is compatible with POPFile. 20-Aug-06 (v0.1.7) Added a new command-line option (/BUILTIN) to force the installation of the old pre-0.22.3 compatible SSL files. This option has been added to cope with the situation where the University of Winnipeg supplies SSL files which are not compatible with the current release of POPFile. Built using NSIS 2.19 instead of NSIS 2.15. Moved the code which patches SSL.pm to make it work with POPFile (so the patch can now also applied by the installer). 22-Jul-06 (v0.1.6) Built using NSIS 2.15 instead of NSIS 2.0 in order to be able to use the 'Inetc' plugin to download the SSL support files. This plugin has much better proxy support than the standard 'NSISdl' plugin. If the SSL support files are downloaded then SSL.pm will be downgraded from v0.99 to v0.97 to make it compatible with POPFile. 19-Jan-06 (v0.1.5) Updated to use POPFile's revised license terms (now restricted to version 2 of the GNU GPL). 13-Nov-05 (v0.1.2.1)Updated to use latest Brazilian Portuguese translations. 13-Oct-05 (v0.1.2) Updated to use the latest Japanese translations. Source files updated to mention the additional NSIS compiler warnings and provide a cross-reference list for them. 02-Oct-05 (v0.1.1) Updated to use the latest version of getssl.nsh and the latest language strings. This ReadMe updated to mention the forthcoming POPFile 0.22.3 release. 28-Jun-05 (v0.1.0) The files on the University of Winnipeg server are no longer compatible with POPFile 0.22.x so this utility now includes an older set of compatible SSL components. 04-Feb-05 (v0.0.15) The POPFile 0.23.0 installer will be able to download and install the SSL support files, so this wizard now uses an "include" file instead of in-line code for the SSL download and install operations. 21-Dec-04 (v0.0.11) Use latest version of the 'untgz' plugin and revise the notes on Module.pm patching and SSL configuration. 03-Dec-04 (v0.0.10) Suppress the patch status message box when the Module.pm version is neither 1.40 nor 1.41 (to avoid confusion) 29-Oct-04 (v0.0.9) Source code size greatly reduced by making it "include" the main PFI library. The ReadMe now mentions that forking should be disabled. 19-Oct-04 (v0.0.8) Source files (slightly rearranged) are now in CVS. Now using getpopfile.org as the POPFile homepage address. Revised this ReadMe file. 28-Sep-04 (v0.0.7) The wizard now patches Module.pm (if necessary) to upgrade it to v1.41 to solve the extremely slow SSL mail transfer problem. 14-Sep-04 (v0.0.6) Revised these notes (some account configuration information added, mentioned the /timeout=0 option and explained how to increase the Win9x environment space for pfi-run.bat) 08-Sep-04 (v0.0.5) Added build instructions to the header comment. 08-Sep-04 (v0.0.4) Revised ReadMe and WELCOME page text. 08-Sep-04 (v0.0.3) Improved WELCOME page text and progress/log messages. 06-Sep-04 (v0.0.2) Improved reporting of downloads. 06-Sep-04 (v0.0.1) First public release. --------------------------------------------------------------------------- Brian Smith POPFile "Help" Discussion Forum: http://getpopfile.org/discussion/1 --------------------------------------------------------------------------- (end)