Installing Roundcube Webmail under IIS on Windows Server 2019

This document discusses how to install the Roundcube PHP webmail application on IIS under Windows Server while retaining some of the functionality lost from the .htaccess file security and configuration changes automatically available to Apache installations.

Applies To

  • Windows Server 2012, 2012 R2, 2016, 2019, 2022
  • Internet Information Services

Prerequisites

  • IIS installed via Server Manager / PowerShell with at least the following enabled:
    • Fast CGI (CGI)
    • ISAPI Extensions
    • ISAPI Filters
    • Default Document
    • HTTP Errors
    • Static Content
    • Request Filtering
    • Static and dynamic content compression (optional but recommended)
  • URL Rewrite
  • MySQL Connector/ODBC 8.0 (or suitable database driver). This document will use MySQL 8.0
  • PHP 5.4.1 or higher (but not PHP 8.0 at the time of writing). PHP 7.4.xx is recommended
    • PHP should be registered in IIS Manager > Handler Mappings as follows:
      • Request path: *.php
      • Module: FastCgiModule
      • Executable (optional): “<drive>:\<path>\php-cgi.exe”
    • Your PHP.ini file should enable the following extensions:
      • php_fileinfo.dll
      • php_intl.dll
      • php_mysqli.dll (if using MySQL/MariaDB)
      • php_pdo_mysql.dll (if using MySQL/MariaDB)
      • php_mbstring.dll
      • php_openssl.dll
      • You may also wish to consider obtaining the (optional) non-bundled Pspell and IconV extensions
    • Be sure to set a value for date.timezone in the PHP.ini file based upon allowed values found at http://php.net/date.timezone
    • In the PHP.ini file, file uploads should be set to on via file_uploads = On and a value set for upload_tmp_dir = <path>
      Note: IUSR and you application pool identity should have read/write/modify permission on this folder. See installation step 12 below for details on how to add permissions for the application pool identity
  • Create a new website in IIS for your Roundcube install. In this document the website will be named webmail.mydomain.com
    • It is recommended that you create a dedicated application pool for your site. In this document the application pool will be named webmail.mydomain.com. Ensure that it has the following settings if the application pool will be used exclusively by your Roundcube installation:
      • .NET CLR Version: No Managed Code
      • Identity: ApplicationPoolIdentity
    • The website should be located on an NTFS volume. In this document the path C:\iisroot\webmail.mydomain.com will be used
    • Setup any host headers and bindings required as per your installation

Installation

Download your preferred build of Roundcube from the Roundcube website. The Roundcube redistributable is available in three packages: ‘dependent’, ‘complete’ and ‘framework’. You should choose the ‘complete’ package for use with IIS. This document will follow the installation of version 1.5.2 Stable.

View: Roundcube

Use 7-zip or another archival utility to open the .tar.gz package file

  1. Extract everything from the .tar.gz file in to C:\iisroot\webmail.mydomain.com except for the ‘public_html’ folder.
    The public_html folder contains POSIX symbolic links that 7-zip cannot map onto NTFS. As a substitute we will re-create these using IIS virtual directories.
  2. Create a new, empty folder called public_html in C:\iisroot\webmail.mydomain.com i.e. C:\iisroot\webmail.mydomain.com\public_html
  3. Open IIS Manager and navigate to Sites > webmail.mydomain.com. Expand webmail.mydomain.com in the left-hand navigation panel so that you can see the folder list.
  4. Right click on public_html and choose ‘Add Virtual directory…’ to create a virtual directory. You will need to do this three times to create the following folder maps:
    1. Alias: plugins
      Physical path: C:\iisroot\webmail.mydomain.com\plugins
    2. Alias: program
      Physical path: C:\iisroot\webmail.mydomain.com\program
    3. Alias: skins
      Physical path: C:\iisroot\webmail.mydomain.com\skins
  5. In IIS Manager return to the home screen and select MIME Types (or if you do not want to add it globally, select MIME Types for your webmail.mydomain.com site)
  6. Click ‘Add…’ and fill in the following:
    1. File name extension: .webp
    2. MIME type: image/webp
  7. In Windows Explorer browse to C:\iisroot
  8. Right click on the webmail.mydomain.com folder, go to properties and open the security tab
  9. Click the Advanced button. disable inheritance and copy all of the existing security entries
  10. Delete the ‘Users’ entry
  11. Add IUSR with Modify permissions for ‘This folder, subfolders and files’
  12. Add ‘IIS AppPool\webmail.mydomain.com‘ with Modify access controls for ‘This folder, subfolders and files’
    Note: You must type ‘IIS AppPool\<application pool name>’ manually; you will not be able to locate it in the users and groups lookup. If Windows Explorer cannot locate the user, ensure that you have created the application pool as indicated in the prerequisites section. If you are using the Default application Pool rather than a dedicated one then the username will be ‘IIS AppPool\DefaultAppPool‘.Once you have finished you should at a minimum have permissions set for SYSTEM, IUSR and your IIS application pool.
  13. Click OK until you have closed the folder properties and returned to Windows Explorer
  14. Download the following file and save it in C:\iisroot\webmail.mydomain.com\config:
    http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
    This file provides a list of valid mime types that can be used to validate file upload and downloads. You should periodically refresh this file on your install.
    Note: This file can be placed anywhere, including in a common location that is shared between multiple tenant sites on your server. The application pool identity requires read access to the file.
  15. Open Notepad
  16. Paste in the following lines of XML
    <?xml version="1.0" encoding="UTF-8"?>
    <configuration>
      <system.webServer>
        <security>
          <requestFiltering>
            <!-- Prevent access to the contents of this directory and all sub-directories -->
            <denyUrlSequences>
              <add sequence="/" />
            </denyUrlSequences>
          </requestFiltering>
        </security>
      </system.webServer>
    </configuration>
    This file prevents HTTP connections from accessing content found in a folder
  17. Save a copy of the file with the filename web.config in the following locations:
    1. C:\iisroot\webmail.mydomain.com\bin
    2. C:\iisroot\webmail.mydomain.com\config
    3. C:\iisroot\webmail.mydomain.com\logs
    4. C:\iisroot\webmail.mydomain.com\program\include
    5. C:\iisroot\webmail.mydomain.com\program\lib
    6. C:\iisroot\webmail.mydomain.com\program\localization
    7. C:\iisroot\webmail.mydomain.com\SQL
    8. C:\iisroot\webmail.mydomain.com\temp
  18. In IIS Manager navigate to your webmail.mydomain.com website and select the ‘HTTP Response Headers’ option.
  19. Delete the ‘Powered-By’ entry
  20. Click ‘Add…’ and set the following values:
    1. Name: X-Robots-Tag
      Value: noindex, nofollow
    2. Name: X-Content-Type-Options
      Value: nosniff
    3. Name: X-Frame-Options
      Value: SAMEORIGIN
    4. Name: X-XSS-Protection
      Value: 1; mode=blockNote: You may need to adjust these for your environment. Testing is advised.
  21. Click on ‘Set Common Headers…’ and set the following:
    1. Enable ‘Enable HTTP keep-alive’
    2. Enable ‘Expire Web content’
    3. Select After and set the value to 30 days
  22. Open your web browser and navigate to http(s)://webmail.mydomain.com/installer
  23. You can now follow the installer wizard which will help you to generate a custom config.inc.php file.When specifying paths, for example for the log_dir and temp_dir you must specify a full NTFS path and not attempt to use a relative path i.e. use C:\iisroot\webmail.mydomain.com\temp and C:\iisroot\webmail.mydomain.com\logs not /temp and /logsFor enhanced security, it is recommended that you place your temp folder and logs folder outside of a publically accessible folder.Once you have completed the wizard, download the config.inc.php file generated by the wizard and place it in C:\iisroot\webmail.mydomain.com\config
  24. At the bottom of the config file add the following lines:
    $config['mime_types'] = 'C:\iisroot\webmail.mydomain.com\config\mime.types';
    $config['enable_installer'] = false;
  25. Delete the C:\iisroot\webmail.mydomain.com\installer folder
  26. [Optional if using HTTPS] Go to the webmail.domain.com site in IIS Manager, select the URL Rewrite settings option and click on ‘Add Rule(s)…’
  27. Choose Inbound rules > Blank rule
  28. Configure the new rule as follows:
    Name: Force HTTPS
    Requested URL: Matches the Pattern
    Using: Regular Expressions
    Pattern: (.*)
    Ignore case: Enabled
    Logical grouping: Match AllAdd an input as follows:
    Condition input: {HTTPS}
    Check if input string: Matches the Pattern
    Pattern: ^OFF$
    Ignore case: EnabledThis will disable the use of unencrypted HTTP connections from using your webmail service, forcing all connections to HTTPS

You should now have a working Roundcube installation running on your IIS server.

Troubleshooting

The following represent issues that I have experienced when installing and configuring Roundcube on IIS.

The UI shows an error “Connection error (failed to reach the server)” however e-mail is successfully delivered to the intended recipient and appears in the sent items folder

This is caused by an NTFS permissions issue on the logs directory. If Roundcube cannot write to its log file, an error indicating that the SMTP server could not be contacted is displayed to the user. Review the permissions on your Temp and Logs folder, pay specific attention to ensuring that IUSR and your ‘IIS AppPool\<name>’ have modify permissions on both folders including directory traversal into those folders (i.e. on the parent folder(s) too).

The Roundcube login screen loads, however you cannot log-in using a valid username and password. Error messages including the phrase “Empty startup greeting” are logged in the Roundcube log file

This is caused by a communication error between the HTTPd server and the IMAP server. It could be an invalid IP address or FQDN in your configuration file. It could be caused by a firewall or iy may be caused by anti-SPAM/anti-brute-force security mehanisms on your mail server. If you IMAP server is configured to automatically ban users who present invalid credentials more than # times, then your HTTPd servers IP address may have been added to a ban list. Ensure that your mail server has not been banned and that its IP address is added to a white list.