How to safely change the Roundcube Webmail URL

Unsupported Modifications
1

Hi everyone,

I wanted to share a method I discovered for changing the default Roundcube webmail URL (e.g., moving it to the root domain box.yourdomain.com/ or a different subpath like /webmail/) that is “safe” meaning it persists through Mail-in-a-Box updates and doesn’t involve hacking core system files and also secure if configured correctly.

This method builds on the information discussed in the Is atleast being able to toggle PHP planned? thread. As noted there, while hosting PHP sites is not officially supported, we can utilize the nginx_conf_custom_include feature to inject custom Nginx configurations. By adding the necessary FastCGI parameters to these custom files, we can enable the PHP execution required for Roundcube to function at a new location.

The Method

The trick is to place a custom configuration file in the user-data directory. Mail-in-a-Box automatically includes configurations found here into the Nginx server block for your domain.

  1. SSH into your box.
  2. Navigate to /home/user-data/www/.
  3. Create a new configuration file named after your box’s hostname (e.g., box.yourdomain.com.conf).

Depending on what you want to achieve, paste one of the following code snippets into that file.

Option 1: Serve Webmail at Root (box.yourdomain.com/)

This configuration sets Roundcube as the index for the root of your box domain and redirects any requests from the old /mail path to the root.

# Roundcube Webmail configuration - Root Access

# If the request starts with /mail, redirect immediately to root
if ($request_uri ~* "^/mail(.*)") {
    return 301 /$1;
}

location / {
         index index.php;
         alias /usr/local/lib/roundcubemail/;
         client_max_body_size 128M;
}

location ~ /config/.* {
         # A ~-style location is needed to give this precedence over the next block.
         return 403;
}

location ~ ^/(?!\/)[^/]*\.php$ {
         # note: ~ has precedence over a regular location block
         include fastcgi_params;
         fastcgi_split_path_info ^(/.*)()$;
         fastcgi_index index.php;
         fastcgi_param SCRIPT_FILENAME /usr/local/lib/roundcubemail/$fastcgi_script_name;
         fastcgi_param PHP_ADMIN_VALUE "session.cookie_path=/";
         fastcgi_pass php-fpm;

         # Outgoing mail also goes through this endpoint, so increase the maximum
         # file upload limit to match the corresponding Postfix limit.
         client_max_body_size 128M;
}

Option 2: Serve Webmail at a subpath (box.yourdomain.com/webmail/)

This configuration serves Roundcube at /webmail/ and redirects the old /mail path there.

# Roundcube Webmail configuration - /webmail/ path

# If the request starts with /mail, redirect immediately to /webmail
if ($request_uri ~* "^/mail(.*)") {
    return 301 /webmail$1;
}

location /webmail/ {
         index index.php;
         alias /usr/local/lib/roundcubemail/;
         client_max_body_size 128M;
}

location ~ /webmail/config/.* {
         # A ~-style location is needed to give this precedence over the next block.
         return 403;
}

location ~ /webmail/.*\.php {
         # note: ~ has precedence over a regular location block
         include fastcgi_params;
         fastcgi_split_path_info ^/webmail(/.*)()$;
         fastcgi_index index.php;
         fastcgi_param SCRIPT_FILENAME /usr/local/lib/roundcubemail/$fastcgi_script_name;
         fastcgi_param PHP_ADMIN_VALUE "session.cookie_path=/webmail/";
         fastcgi_pass php-fpm;

         # Outgoing mail also goes through this endpoint, so increase the maximum
         # file upload limit to match the corresponding Postfix limit.
         client_max_body_size 128M;
}

Apply Changes

After creating the file, you need to trigger a web update to apply the Nginx changes:

Bash

sudo ~/mailinabox/tools/web_update

This should seamlessly switch your webmail URL while keeping the configuration safe in your user-data directory!