One place for hosting & domains

      How To Connect to a Managed Redis Instance over TLS with Stunnel and redis-cli


      A managed Redis instance can provide benefits like high availability and automated updates. However, any time you make a connection to a remote database server, you run the risk of malicious actors sniffing the sensitive information you send to it.

      redis-cli, the Redis command line interface, doesn’t natively support connections over TLS, a cryptographic protocol that allows for secure communications over a network. This means that without further configuration, redis-cli is not a secure way to connect to a remote Redis server. One way to establish a secure connection to a managed Redis instance is to create a tunnel that uses the TLS protocol.

      Stunnel is an open-source proxy used to create secure tunnels, allowing you to communicate with other machines over TLS. In this guide, we will walk through installing and configuring stunnel so you can connect to a managed Redis instance over TLS with redis-cli.


      To complete this guide, you will need:

      • Access to an Ubuntu 18.04 server. This server should have a non-root user with administrative privileges and a firewall configured with ufw. To set this up, follow our initial server setup guide for Ubuntu 18.04.
      • A managed Redis database instance. The steps outlined in this tutorial were tested on a DigitalOcean Managed Redis Database, though they should generally work for managed databases from any cloud provider. To provision a DigitalOcean Managed Redis Database, follow our Managed Redis product documentation.

      Step 1 — Installing Stunnel and redis-cli

      When you install a Redis server, it usually comes packaged with redis-cli. However, you can install redis-cli without the Redis server by installing the redis-tools package from the default Ubuntu repositories. You can also install stunnel from the default Ubuntu repositories by downloading the stunnel4 package.

      First, update your server’s package index if you’ve not done so recently:

      Then install the redis-tools and stunnel4 packages with APT:

      • sudo apt install redis-tools stunnel4

      When prompted, press ENTER to confirm that you want to install the packages.

      You can check whether stunnel was installed correctly and its systemd service is working by running the following command:

      • sudo systemctl status stunnel4


      ● stunnel4.service - LSB: Start or stop stunnel 4.x (TLS tunnel for network daemons) Loaded: loaded (/etc/init.d/stunnel4; generated) Active: active (exited) since Thu 2019-09-12 14:34:05 UTC; 8s ago Docs: man:systemd-sysv-generator(8) Tasks: 0 (limit: 2362) CGroup: /system.slice/stunnel4.service Sep 12 14:34:05 stunnel systemd[1]: Starting LSB: Start or stop stunnel 4.x (TLS tunnel for network daemons)... Sep 12 14:34:05 stunnel stunnel4[2034]: TLS tunnels disabled, see /etc/default/stunnel4 Sep 12 14:34:05 stunnel systemd[1]: Started LSB: Start or stop stunnel 4.x (TLS tunnel for network daemons).

      Here, you can see that the stunnel service is active, though the process immediately exited. This tells us that stunnel is running, but it isn’t able to actually do anything since we haven’t yet configured it.

      Step 2 — Configuring Stunnel

      Modern Linux systems rely on systemd for initializing and managing services and daemons. However, stunnel uses a SysV-style init script, which is based on the older UNIX System V init system, for startup. You’ll need to modify the /etc/default/stunnel4 file to enable this init script.

      Open this file with your preferred text editor. Here, we’ll use nano:

      • sudo nano /etc/default/stunnel4

      Find the ENABLED option near the top of the file. It will be set to 0 by default, but change this to 1 to enable stunnel to start at boot:


      # /etc/default/stunnel
      # Julien LEMOINE <>
      # September 2003
      # Change to one to enable stunnel automatic startup
      . . .

      Save and close the file. If you used nano to edit the file, do so by pressing CTRL+X, Y, then ENTER.

      Next, you will need to create a configuration file for stunnel which will tell the program where it needs to route traffic.

      Open a new file called stunnel.conf under the /etc/stunnel directory:

      • sudo nano /etc/stunnel/stunnel.conf

      Add the following content to this file:


      fips = no
      setuid = nobody
      setgid = nogroup
      pid =
      debug = 7
        client = yes
        accept =
        connect = managed_redis_hostname_or_ip:managed_redis_port

      The first five lines in the file are global options, meaning they will apply to every service you include in this file:

      • fips: Enables or disables stunnel’s FIPS 140-2 mode. In this mode, stunnel will validate that the connection meets the Federal Information Processing Standard. Setting this to no disables this feature. Note that disabling this is not any less secure, but keeping it enabled (as it is by default) would require some extra configuration.
      • setuid: Defines the Unix user ID under which stunnel will run. By default, the stunnel process is owned by the root user. However, the stunnel documentation recommends that you drop administrative privileges once the tunnel starts, as failing to do so poses a security risk. Setting the setuid parameter to nobody will cause nobody, an unprivileged user, to take ownership over the stunnel process once the tunnel has been established.
      • setgid: Defines the Unix group ID under which stunnel will run. As with setuid, this configuration specifies a group without any special privileges — nogroup — to avoid any potential security issues.
      • pid: Defines a file location where stunnel will create a .pid file, a type of file that contains a process’s PID. .pid files are typically used by other programs to find the PID of a running process. By default, stunnel creates a .pid file in the /var/run/stunnel4/ directory. Because the nobody user doesn’t have permission to access that directory, it will prevent the tunnel from starting correctly. By not providing any argument to the pid parameter in this configuration we’re disabling this behavior, as a .pid file isn’t necessary for the purposes of this tutorial. If you do need a .pid file for your use case, though, be sure to set this to a file that nobody has permission to write to.
      • debug: Sets stunnel’s debugging level, which can range from 0 to 7. In this example we’ll set it to 7, the highest level available, as that will provide the most detailed information if stunnel runs into any issues. You can set it to any level you like, but be aware that the default setting is 5.

      The remaining lines are service-level options, and only apply to the tunnel we’ll create for redis-cli:

      • [redis-cli]: This is a service name and specifies that the following lines represent an individual service configuration for a client program. You can have more than one service in a stunnel configuration file, though each must be associated with an existing client application and you can’t have two services for the same application.
      • client: Setting this to yes tells stunnel to run in client mode, meaning that stunnel will connect to a TLS server (the managed Redis instance) rather than act as a TLS server.
      • accept: Defines the host and port on which stunnel will accept connections from the client. Here, we specify the IP address, which is an IPv4 loopback address used to represent localhost, and port 8000. This means stunnel will listen for connections originating from the Ubuntu server on port 8000 and encrypt them. Note that you can set the port to any port number you like as long as it’s not already in use.
      • connect: Defines the remote address and port to which stunnel will make the connection. Be sure to change this parameter to align with your managed database’s port and hostname or IP address.

      Note: The hostname or IP address and port you should specify in the connect directive will be specific to your own managed Redis database. These can usually be found in your cloud provider’s database management user interface where you provisioned your Redis instance.

      If you’re using a DigitalOcean Managed Redis Database, you can find this information by going to your Control Panel and clicking on Databases in the left-hand sidebar menu. Then, click on the name of the Redis instance you want to connect to and scroll down to the Connection Details section. There, you will find fields describing your database’s host and port.

      This is a fairly minimal configuration that leaves many of stunnel’s default settings in place. The program has many options available for you to create tunnels that suit your particular needs. See the official documentation for more details.

      After adding this content, save and close the file.

      Then, restart the stunnel4 service so stunnel will read the new configuration file:

      • sudo systemctl restart stunnel4

      Following that, you can test whether stunnel has created with netstat, a command line utility used to display network connections. Run the following command, which pipelines the netstat output into a grep command, which then searches it for every instance of stunnel:

      • sudo netstat -plunt | grep stunnel


      tcp 0 0* LISTEN 17868/stunnel

      This output shows that stunnel is listening for connections on local port 8000.

      You can also confirm that the nobody user has taken ownership over the stunnel process with ps, a program that displays all currently-running processes:


      nobody 15674 0.0 0.1 121912 3180 ? Ssl 19:28 0:00 /usr/bin/stunnel4 /etc/stunnel/stunnel.conf . . .

      Here, you can see that nobody has indeed taken over the stunnel process.

      Stunnel is now fully configured and running on your system. You’re ready to connect to your managed Redis instance and test that the tunnel is working as expected.

      Step 3 — Connecting To Your Managed Database over TLS

      Now that you’ve installed redis-cli and configured stunnel on your server, you’re ready to connect to your managed database over TLS.

      Based on the settings defined in the configuration file created in Step 2, you would connect to your managed database with the following command:

      • redis-cli -h localhost -p 8000

      This command includes the -h flag, which tells redis-cli that the next argument will be the host to connect to. In this case, it’s localhost since we’re connecting to a tunnel created locally on the server. After that is the -p flag, which precedes the port of the local tunnel we’re connecting to, which in this case is port 8000.

      After running that command, you will be connected to your managed Redis server. Your prompt will change to reflect that you’ve connected and are in redis-cli’s interactive mode:

      Note: Oftentimes, managed databases are configured to require users to authenticate with a password when they connect. If your managed Redis instance requires a password, you can include the -a flag in your redis-cli command, followed by your password:

      • redis-cli -h localhost -p 8000 -a password

      Alternatively, you can authenticate by running the auth command followed by your password after establishing the connection:

      If you’re using a DigitalOcean Managed Database, you can find your Redis instance’s password in the same place you found its hostname and port. In your Control Panel, click on Databases in the left-hand sidebar menu. Then, click on the name of the Redis instance you’ve connected to. Scroll down to the Connection Details section, and there you’ll find a field labeled password. Click on the show button to reveal the password, then copy and paste it into either of these commands — replacing password — in order to authenticate.

      You can test whether the tunnel is working as expected by running the ping command from Redis’s interactive mode:

      If the connection is alive it will return PONG:



      If, however, stunnel is not tunnelling traffic from your server to your Redis instance correctly, you may see an error message like this before being disconnected from Redis:


      Error: Server closed the connection

      If you receive this or a similar error, double check that you’ve entered your Redis instance’s hostname and port correctly in your stunnel.conf file. Likewise, be sure that you entered the correct port number in your redis-cli command.

      Once you’ve confirmed that the tunnel is working, go ahead and disconnect from your Redis instance:

      If you ever change stunnel’s configuration, you’ll need to reload or restart the stunnel4 service so stunnel will notice the changes:

      • sudo systemctl reload stunnel4

      However, if at any point in the future you want to close the TLS tunnel, you won’t be able to close it with systemctl. Instead, you’ll need to kill the process with the pkill command:

      After the tunnel has ben closed, you can reopen the tunnel by restarting the service:

      • sudo systemctl restart stunnel4

      Now that you’ve successfully configured stunnel, you’re all set to begin adding data to your managed Redis instance with redis-cli.


      Stunnel is a handy tool for creating TLS tunnels and establishing secure connections to remote servers. This is especially useful in cases where the secure transport of information between machines is critical, as with a remote database.

      From here, you can begin exploring Redis and integrating it with your next application. If you’re new to working with Redis, you may find our series on How To Manage a Redis Database useful.

      Source link

      How To Configure MTA-STS and TLS Reporting for Your Domain Using Apache on Ubuntu 18.04

      The author selected Electronic Frontier Foundation Inc to receive a donation as part of the Write for DOnations program.


      Mail Transport Agent Strict Transport Security (MTA-STS) is a new internet standard that allows you to enable strict force-TLS for email sent between supported email providers. It is similar to HTTP Strict Transport Security (HSTS), where a force-TLS policy is set and then cached for a specified amount of time, reducing the risk of man-in-the-middle or downgrade attacks.

      MTA-STS is complemented by SMTP TLS Reporting (TLSRPT), which gives you insight into which emails are successfully delivered over TLS, and which aren’t. TLSRPT is similar to DMARC reporting, but for TLS.

      The primary reason for implementing MTA-STS for your domain is to ensure that confidential email that is sent to you is transmitted securely over TLS. Other methods for requiring TLS for email communications are still susceptible to man-in-the-middle attacks, as the initial connection is unencrypted. MTA-STS ensures that the initial incoming connection is using TLS by default, which greatly reduces the risk of these attacks.

      An example use case for MTA-STS and TLS Reporting is to help create a secure customer service email system for your business. Customers may send support tickets via email that contain confidential personal information, which needs a secure TLS connection. MTA-STS provides that secure connection, and TLSRPT will deliver daily reports identifying any emails that weren’t sent securely—giving crucial insight into any ongoing or previous attacks against your email system.

      In this tutorial, you will learn how to configure MTA-STS and TLSRPT for your domain name, and then interpret your first TLS Report. While this tutorial covers the steps for using Apache on Ubuntu 18.04 with a Let’s Encrypt certificate, the MTA-STS/TLSRPT configuration will also work on alternatives, such as Nginx on Debian.


      Before you begin this guide, you’ll need:

      Once you have these ready, log in to your server as your non-root user to begin.

      Note: Once you have completed the implementation steps for MTA-STS and TLSRPT, you may have to wait up to 24 hours to receive your first TLS Report. This is because most email providers send reports once per day. You may resume the tutorial from Step 5 once you’ve received your first report.

      Step 1 — Creating an MTA-STS Policy File

      MTA-STS is enabled and configured using a plain text configuration file that you host on your website. Supported mail servers will then automatically connect to your website to retrieve the file, which causes MTA-STS to be enabled. In this first step you’ll understand the available options for this file and choose the most appropriate for your file.

      Firstly, open a new text file in your home directory so that you have somewhere to write down your desired configuration:

      We will first go over an example, and then you will write your own configuration file.

      Following is an example of an MTA-STS configuration file:

      Example MTA-STS Configuration File

      version: STSv1
      mode: enforce
      mx: mail1.your-domain
      mx: mail2.your-domain
      max_age: 604800

      This example configuration file specifies that all email delivered to mail1.your-domain and mail2.your-domain from supported providers must be delivered over a valid TLS connection. If a valid TLS connection cannot be established with your mail server (for example, if the certificate has expired or is self-signed), the email will not be delivered.

      This will make it much more challenging for an attacker to intercept and snoop on/modify your email in a situation like a man-in-the-middle attack. This is because having MTA-STS enabled properly only allows email to be transmitted over a valid TLS connection, which requires a valid TLS certificate. It would be hard for an attacker to acquire such a certificate, as doing so usually requires privileged access to your domain name and/or website.

      As shown in the example earlier in this step, the configuration file consists of a number of key/value pairs:

      • version:

        • Purpose: To specify the version of the MTA-STS specification to use.
        • Accepted Values: Currently the only accepted value is STSv1.
        • Example: version: STSv1
      • mode:

        • Purpose: Specify which mode MTA-STS should be enabled in.
        • Accepted Values:
          • enforce: Force all incoming email from supported providers to use valid TLS.
          • testing: Report-only mode. email will not be blocked, but TLSRPT reports are still sent.
          • none: Disable MTA-STS.
        • Example: mode: enforce
      • mx:

        • Purpose: To specify which mail servers are allowed to handle email for your domain. This should match the servers specified in your mx records.
        • Accepted Values: Fully-qualified domain name of a mail server, or a wildcard host. Multiple mx: values must be used to specify multiple mail servers.
        • Example: mx: mail1.your-domain, mx: mail2.your-domain, mx: *
      • max_age:

        • Purpose: To specify the maximum lifetime of the MTA-STS policy, in seconds.
        • Accepted Values: Any positive integer up to 31557600.
        • Example: max_age: 604800 (1 week)

      You can also view the official specification for the key/value pairs in Section 3.2 of the MTA-STS RFC.

      Warning: Enabling MTA-STS in enforce mode could unexpectedly cause some email not to be delivered to you. Instead, it is recommended to use mode: testing and a low max_age: value at first, in order to ensure that everything is working correctly before turning on MTA-STS fully.

      Using the example file earlier in the step, as well as the preceding key/value pair examples, write your desired MTA-STS policy file and save it to the file that you created at the start of the step.

      The following example file is ideal for testing MTA-STS, as it will not cause any emails to be unexpectedly blocked, and has a max_age of only 1 day, meaning that if you decide to disable it, the configuration will expire quickly. Note that some email providers will only send TLSRPT reports if the max_age is greater than 1 day, which is why 86401 seconds is a good choice (1 day and 1 second).

      Example Test MTA-STS Configuration File

      version: STSv1
      mode: testing
      mx: mail1.your-domain
      mx: mail2.your-domain
      max_age: 86401

      In this step you created your desired MTA-STS configuration file and saved it to your home area. In the next step, you will configure an Apache web server to serve the file in the correct format.

      Step 2 — Configuring Apache to Serve Your MTA-STS Policy File

      In this step, you’ll configure an Apache virtual host to serve your MTA-STS configuration file, and then add a DNS record to allow the site to be accessed from a subdomain.

      In order for your MTA-STS configuration file to be automatically discovered by mail servers, it must be served at exactly the right path: https://mta-sts.your-domain/.well-known/mta-sts.txt. You must use the mta-sts subdomain over HTTPS and the /.well-known/mta-sts.txt path, otherwise your configuration will not work.

      This can be achieved by creating a new Apache virtual host for the mta-sts subdomain, which will serve the MTA-STS policy file. This step builds upon the base configuration that you’ll have set up in the prerequisite step How to Install the Apache Web Server on Ubuntu 18.04.

      Firstly, create a directory for your virtual host:

      • sudo mkdir /var/www/mta-sts

      If you’re hosting multiple different domains on your web server, it is recommended to use a different MTA-STS virtual host for each, for example /var/www/mta-sts-site1 and /var/www/mta-sts-site2.

      Next, you need to create the .well-known directory, which is where your MTA-STS configuration file will be stored. .well-known is a standardized directory for ‘well-known’ files, such as TLS certificate validation files, security.txt, and more.

      • sudo mkdir /var/www/mta-sts/.well-known

      Now you can move the MTA-STS policy file that you created in Step 1 into the web server directory that you just created:

      • sudo mv ~/mta-sts.txt /var/www/mta-sts/.well-known/mta-sts.txt

      You can check that the file was copied correctly if you wish:

      • cat /var/www/mta-sts/.well-known/mta-sts.txt

      This will output the contents of the file that you created in Step 1.

      In order for Apache to serve the file, you’ll need to configure the new virtual host and enable it. MTA-STS only works over HTTPS, so you’ll use port 443 (HTTPS) exclusively, rather than using port 80 (HTTP) as well.

      Firstly, create a new virtual host configuration file:

      • sudo nano /etc/apache2/sites-available/mta-sts.conf

      Like with the virtual host directory, if you are hosting multiple different domains on the same web server, it is recommended to use a different virtual host name for each.

      Then, copy the following sample configuration into the file, and populate the variables where required:


      <IfModule mod_ssl.c>
      <VirtualHost your-server-ipv4-address:443 [your-server-ipv6-address]:443>
          ServerName mta-sts.your-domain
          DocumentRoot /var/www/mta-sts
          ErrorDocument 403 "403 Forbidden - This site is used to specify the MTA-STS policy for this domain, please see '/.well-known/mta-sts.txt'. If you were not expecting to see this, please use <a href="https://your-domain" rel="noopener">https://your-domain</a> instead."
          RewriteEngine On
          RewriteOptions IgnoreInherit
          RewriteRule !^/.well-known/mta-sts.txt - [L,R=403]
          SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
          SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
          Include /etc/letsencrypt/options-ssl-apache.conf

      This configuration will create the mta-sts virtual host, which will be served at mta-sts.your-domain. It will also redirect all requests, except for those to the mta-sts.txt file itself, to a custom 403 Forbidden error page, with a friendly explanation of what the subdomain site is for. This is to help ensure that any visitors who accidentally come across your MTA-STS site aren’t inadvertently confused.

      Currently, a self-signed TLS certificate is used. This is not ideal, as a fully valid/trusted certificate is required for MTA-STS to work correctly. In Step 3, you will acquire a TLS certificate using Let’s Encrypt.

      Next, ensure that the required Apache modules are enabled:

      After that, enable the new virtual host:

      Then, run a syntax check of the Apache configuration files, to ensure that there aren’t any unexpected errors:

      • sudo apachectl configtest

      When the test passes with no errors, you can restart Apache to fully enable the new virtual host:

      • sudo service apache2 restart

      Now that the Apache virtual host has been set up and configured, you need to create the required DNS record(s) to allow it to be accessed using the fully-qualified domain name mta-sts.your-domain.

      The way that this is done depends on the DNS hosting provider that you use. However, if you use DigitalOcean as your DNS provider, simply navigate to your project, followed by clicking on your domain.

      Finally, add the required DNS records for the mta-sts subdomain. If your Droplet only uses IPv4, create an A record for mta-sts, pointing to your-server-ipv4-address. If you use IPv6 as well, create an AAAA record pointing to your-server-ipv6-address.

      A screenshot of the DigitalOcean DNS control panel, showing an example DNS record for mta-sts pointing to an IPv4 address.

      In this step, you created and configured a new Apache virtual host for your MTA-STS subdomain, then added the required DNS record(s) to allow it to be accessed easily. In the next step, you will acquire a trusted Let’s Encrypt certificate for your MTA-STS subdomain.

      Step 3 — Acquiring a Let’s Encrypt Certificate for Your MTA-STS Subdomain

      In this step, you’ll acquire a TLS certificate from Let’s Encrypt, to allow your mta-sts.your-domain site to be served correctly over HTTPS.

      In order to do this, you’ll use certbot, which you set up as part of the prerequisite step How To Secure Apache with Let’s Encrypt on Ubuntu 18.04.

      Firstly, run certbot to issue a certificate for your mta-sts subdomain using the Apache plugin verification method:

      • sudo certbot --apache -d mta-sts.your-domain

      This will automatically issue a trusted certificate and install it on your Apache web server. When the Certbot wizard asks about configuring a HTTP -> HTTPS redirect, select 'No’, as this is not required for MTA-STS.

      To finish, test your new virtual host to ensure that it is working correctly. Use a web browser to visit https://mta-sts.your-domain/.well-known/mta-sts.txt, or use a command-line tool such as curl:

      • curl https://mta-sts.your-domain/.well-known/mta-sts.txt

      This will output the MTA-STS policy file that you created in Step 1:


      version: STSv1 mode: testing mx: mail1.your-domain mx: mail2.your-domain max_age: 86401

      If an error occurs, ensure that the virtual host configuration from Step 2 is correct, and that you have added a DNS record for the mta-sts subdomain.

      In this step, you issued a Let’s Encrypt TLS certificate for your mta-sts subdomain, and tested that it’s working. Next, you’ll set some DNS TXT records to fully enable MTA-STS and TLSRPT.

      Step 4 — Configuring the DNS Records Required to Enable MTA-STS and TLSRPT

      In this step, you’ll configure two DNS TXT records, which will fully enable the MTA-STS policy that you have already created, and also enable TLS Reporting (TLSRPT).

      These DNS records can be configured using any DNS hosting provider, but in this example, DigitalOcean is used as the provider.

      Firstly, log on to your DigitalOcean control panel and navigate to your project, followed by clicking on your domain.

      You then need to add the following two TXT records:

      _mta-sts.your-domain IN TXT "v=STSv1; id=id-value"
      _smtp._tls.your-domain IN TXT "v=TLSRPTv1; rua=reporting-address"

      id-value is a string used to identify the version of your MTA-STS policy in place. If you update your policy, you’ll need to also update the id value to ensure that the new version is detected by mail providers. It is recommended to use the current date stamp as the id, for example 20190811231231 (23:12:31 on 11th Aug 2019).

      reporting-address is the address where your TLS reports will be sent to. This can be either an email address prefixed with mailto:, or a web URI, for example for an API that collects reports. The reporting address doesn’t have to be an address on your-domain. You may use a completely different domain if you wish.

      For example, the following two sample records are both valid:

      _mta-sts.your-domain IN TXT "v=STSv1; id=20190811231231"
      _smtp._tls.your-domain IN TXT "v=TLSRPTv1; rua=mailto:tls-reports@your-domain"

      Adjust the variables as required, and set these DNS TXT records in your DigitalOcean control panel (or whichever DNS provider you’re using):

      A screenshot of the DigitalOcean control panel, showing the _mta-sts DNS TXT record being set.

      A screenshot of the DigitalOcean control panel, showing the _smtp._tls DNS TXT record being set.

      Once these DNS records have been set and have propagated, MTA-STS will be enabled with the policy that you created in Step 1, and will begin to receive TLSRPT reports at the address that you specified.

      In this step, you configured the DNS records required for MTA-STS to be enabled. Next, you will receive and then interpret your first TLSRPT report.

      Step 5 — Interpreting Your First TLSRPT Report

      Now that you’ve enabled MTA-STS and TLSRPT (TLS Reporting) for your domain, you will begin to receive reports from supported email providers. These reports will show the number of emails that were or were not successfully delivered over TLS, and the reasons for any errors.

      Different email providers send their reports at different times; for example, Google Mail sends their reports daily at around 10:00 UTC.

      Depending on how you configured the TLSRPT DNS record in Step 5, you will either receive your reports via email, or via a web API. This tutorial focuses on the email method, as that is the most common configuration.

      If you’ve just completed the rest of this tutorial, wait until you receive your first report, then you can resume.

      Your daily TLSRPT report via email will usually have a subject line similar to the following:

      Report Domain: your-domain Submitter: Report-ID: <>

      This email will have an attachment in .gz format, which is a Gzip compressed archive, with a file name similar to the following:!your-domain!1565222400!1565308799!001.json.gz

      For the rest of this tutorial this file will be referred to as report.json.gz.

      Save this file to your local machine, and extract it using whichever tool you prefer.

      If you’re using a Debian-based Linux system, you will be able to run the gzip -d command to decompress the archive:

      This will result in a JSON file called report.json.

      Next, you can view the report either directly as the raw JSON string, or use your favorite JSON prettifier to put it into a more readable format. In this example, jq will be used, but you could also use Python’s json.tool if you wish.

      Note: If you don’t have jq installed, you can install it using apt install jq. Or, for other operating systems use the necessary installation instructions from jq.

      This will output something similar to the following:

      Prettified report.json

      { "organization-name": "Google Inc.", "date-range": { "start-datetime": "2019-08-10T00:00:00Z", "end-datetime": "2019-08-10T23:59:59Z" }, "contact-info": "", "report-id": "2019-08-10T00:00:00Z_your-domain", "policies": [ { "policy": { "policy-type": "sts", "policy-string": [ "version: STSv1", "mode: testing", "mx: mail1.your-domain", "mx: mail2.your-domain", "max_age: 86401" ], "policy-domain": "your-domain" }, "summary": { "total-successful-session-count": 230, "total-failure-session-count": 0 } } ] }

      The report shows the provider that generated the report and the reporting period, as well as the MTA-STS policy that was applied. However, the main section that you’ll be interested in is summary, specifically the successful and failed session counts.

      This sample report shows that 230 emails were successfully delivered over TLS from the mail provider that generated the report, and 0 email deliveries failed to establish a proper TLS connection.

      In the event that there is a failure—for example, if a TLS certificate expires or there is an attacker on the network—the failure mode will be documented in the report. Some examples of failure modes are:

      • starttls-not-supported: If the receiving mail server doesn’t support STARTTLS.
      • certificate-expired: If a certificate has expired.
      • certificate-not-trusted: If a self-signed or other non-trusted certificate is used.

      In this final step, you received and then interpreted your first TLSRPT report.


      In this article you set up and configured MTA-STS and TLS Reporting for your domain, and interpreted your first TLSRPT report.

      Once MTA-STS has been enabled and working stably for a while, it is recommended to adjust the policy, increasing the max_age value, and eventually switching it to enforce mode once you are sure that all email from supported providers is being delivered successfully over TLS.

      Finally, if you’d like to learn more about the MTA-STS and TLSRPT specifications, you can review the RFCs for both of them:

      Source link