github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity
docker-mailserver/edge/config/security/ssl/index.html
github-actions[bot] 5e1bc23ebd deploy: e7b88d865b
2021-06-08 01:20:52 +00:00

2114 lines
87 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.) using Docker.">
<meta name="author" content="docker-mailserver (Github Organization)">
<link rel="canonical" href="https://docker-mailserver.github.io/docker-mailserver/edge/config/security/ssl/">
<link rel="icon" href="../../../assets/logo/favicon-32x32.png">
<meta name="generator" content="mkdocs-1.1.2, mkdocs-material-7.1.7">
<title>Security | TLS (aka SSL) - Docker Mailserver</title>
<link rel="stylesheet" href="../../../assets/stylesheets/main.ca7ac06f.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/palette.f1a3b89f.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&display=fallback">
<style>:root{--md-text-font-family:"Roboto";--md-code-font-family:"Roboto Mono"}</style>
<link rel="stylesheet" href="../../../assets/css/customizations.css">
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
<script>function __prefix(e){return new URL("../../..",location).pathname+"."+e}function __get(e,t=localStorage){return JSON.parse(t.getItem(__prefix(e)))}</script>
<script>var palette=__get("__palette");if(null!==palette&&"object"==typeof palette.color)for(var key in palette.color)document.body.setAttribute("data-md-color-"+key,palette.color[key])</script>
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#lets-encrypt-recommended" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../../.." title="Docker Mailserver" class="md-header__button md-logo" aria-label="Docker Mailserver" data-md-component="logo">
<img src="../../../assets/logo/dmo-logo-white.min.svg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Docker Mailserver
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Security | TLS (aka SSL)
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3 3.19.09m3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95 2.06.05m-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31z"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_2">
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5c-.84 0-1.65.15-2.39.42L12 2M3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29L3.34 7m.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14L3.36 17M20.65 7l-1.77 3.79a7.023 7.023 0 0 0-2.38-4.15l4.15.36m-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29L20.64 17M12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44L12 22z"/></svg>
</label>
</form>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
</label>
<button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
</button>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/docker-mailserver/docker-mailserver/" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
</div>
<div class="md-source__repository">
docker-mailserver
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-tabs__inner md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href="../../.." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../../../introduction/" class="md-tabs__link">
Introduction
</a>
</li>
<li class="md-tabs__item">
<a href="../../setup.sh/" class="md-tabs__link md-tabs__link--active">
Configuration
</a>
</li>
<li class="md-tabs__item">
<a href="../../../examples/tutorials/basic-installation/" class="md-tabs__link">
Examples
</a>
</li>
<li class="md-tabs__item">
<a href="../../../faq/" class="md-tabs__link">
FAQ
</a>
</li>
<li class="md-tabs__item">
<a href="../../../contributing/issues-and-pull-requests/" class="md-tabs__link">
Contributing
</a>
</li>
<li class="md-tabs__item">
<a href="https://hub.docker.com/repository/docker/mailserver/docker-mailserver" class="md-tabs__link">
DockerHub
</a>
</li>
<li class="md-tabs__item">
<a href="https://github.com/orgs/docker-mailserver/packages/container/package/docker-mailserver" class="md-tabs__link">
GHCR
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../../.." title="Docker Mailserver" class="md-nav__button md-logo" aria-label="Docker Mailserver" data-md-component="logo">
<img src="../../../assets/logo/dmo-logo-white.min.svg" alt="logo">
</a>
Docker Mailserver
</label>
<div class="md-nav__source">
<a href="https://github.com/docker-mailserver/docker-mailserver/" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
</div>
<div class="md-source__repository">
docker-mailserver
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../.." class="md-nav__link">
Home
</a>
</li>
<li class="md-nav__item">
<a href="../../../introduction/" class="md-nav__link">
Introduction
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" checked>
<label class="md-nav__link" for="__nav_3">
Configuration
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Configuration" data-md-level="1">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Configuration
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../setup.sh/" class="md-nav__link">
Your Best Friend setup.sh
</a>
</li>
<li class="md-nav__item">
<a href="../../environment/" class="md-nav__link">
Environment Variables
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_3" data-md-state="indeterminate" type="checkbox" id="__nav_3_3" checked>
<label class="md-nav__link" for="__nav_3_3">
User Management
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="User Management" data-md-level="2">
<label class="md-nav__title" for="__nav_3_3">
<span class="md-nav__icon md-icon"></span>
User Management
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../user-management/accounts/" class="md-nav__link">
Accounts
</a>
</li>
<li class="md-nav__item">
<a href="../../user-management/aliases/" class="md-nav__link">
Aliases
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_4" data-md-state="indeterminate" type="checkbox" id="__nav_3_4" checked>
<label class="md-nav__link" for="__nav_3_4">
Best Practices
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Best Practices" data-md-level="2">
<label class="md-nav__title" for="__nav_3_4">
<span class="md-nav__icon md-icon"></span>
Best Practices
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../best-practices/dkim/" class="md-nav__link">
DKIM
</a>
</li>
<li class="md-nav__item">
<a href="../../best-practices/dmarc/" class="md-nav__link">
DMARC
</a>
</li>
<li class="md-nav__item">
<a href="../../best-practices/spf/" class="md-nav__link">
SPF
</a>
</li>
<li class="md-nav__item">
<a href="../../best-practices/autodiscover/" class="md-nav__link">
Auto-discovery
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_5" type="checkbox" id="__nav_3_5" checked>
<label class="md-nav__link" for="__nav_3_5">
Security
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Security" data-md-level="2">
<label class="md-nav__title" for="__nav_3_5">
<span class="md-nav__icon md-icon"></span>
Security
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../understanding-the-ports/" class="md-nav__link">
Understanding the Ports
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
SSL/TLS
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
SSL/TLS
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#lets-encrypt-recommended" class="md-nav__link">
Let's Encrypt (Recommended)
</a>
<nav class="md-nav" aria-label="Let's Encrypt (Recommended)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#example-using-docker-for-lets-encrypt" class="md-nav__link">
Example using Docker for Let's Encrypt
</a>
</li>
<li class="md-nav__item">
<a href="#example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion" class="md-nav__link">
Example using Docker, nginx-proxy and letsencrypt-nginx-proxy-companion
</a>
</li>
<li class="md-nav__item">
<a href="#example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion-with-docker-compose" class="md-nav__link">
Example using Docker, nginx-proxy and letsencrypt-nginx-proxy-companion with docker-compose
</a>
</li>
<li class="md-nav__item">
<a href="#example-using-the-lets-encrypt-certificates-on-a-synology-nas" class="md-nav__link">
Example using the Let's Encrypt Certificates on a Synology NAS
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#caddy" class="md-nav__link">
Caddy
</a>
</li>
<li class="md-nav__item">
<a href="#traefik-v2" class="md-nav__link">
Traefik v2
</a>
</li>
<li class="md-nav__item">
<a href="#self-signed-certificates" class="md-nav__link">
Self-Signed Certificates
</a>
<nav class="md-nav" aria-label="Self-Signed Certificates">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#generating-a-self-signed-certificate" class="md-nav__link">
Generating a self-signed certificate
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#custom-certificate-files" class="md-nav__link">
Custom Certificate Files
</a>
</li>
<li class="md-nav__item">
<a href="#testing-a-certificate-is-valid" class="md-nav__link">
Testing a Certificate is Valid
</a>
</li>
<li class="md-nav__item">
<a href="#plain-text-access" class="md-nav__link">
Plain-Text Access
</a>
</li>
<li class="md-nav__item">
<a href="#importing-certificates-obtained-via-another-source" class="md-nav__link">
Importing Certificates Obtained via Another Source
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../fail2ban/" class="md-nav__link">
Fail2Ban
</a>
</li>
<li class="md-nav__item">
<a href="../mail_crypt/" class="md-nav__link">
Mail Encryption
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_6" data-md-state="indeterminate" type="checkbox" id="__nav_3_6" checked>
<label class="md-nav__link" for="__nav_3_6">
Troubleshooting
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Troubleshooting" data-md-level="2">
<label class="md-nav__title" for="__nav_3_6">
<span class="md-nav__icon md-icon"></span>
Troubleshooting
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../troubleshooting/debugging/" class="md-nav__link">
Debugging
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../pop3/" class="md-nav__link">
Mail Delivery with POP3
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_8" data-md-state="indeterminate" type="checkbox" id="__nav_3_8" checked>
<label class="md-nav__link" for="__nav_3_8">
Advanced Configuration
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Advanced Configuration" data-md-level="2">
<label class="md-nav__title" for="__nav_3_8">
<span class="md-nav__icon md-icon"></span>
Advanced Configuration
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../advanced/optional-config/" class="md-nav__link">
Optional Configuration
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_8_2" data-md-state="indeterminate" type="checkbox" id="__nav_3_8_2" checked>
<label class="md-nav__link" for="__nav_3_8_2">
Maintenance
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Maintenance" data-md-level="3">
<label class="md-nav__title" for="__nav_3_8_2">
<span class="md-nav__icon md-icon"></span>
Maintenance
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../advanced/maintenance/update-and-cleanup/" class="md-nav__link">
Update and Cleanup
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_8_3" data-md-state="indeterminate" type="checkbox" id="__nav_3_8_3" checked>
<label class="md-nav__link" for="__nav_3_8_3">
Override the Default Configs
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Override the Default Configs" data-md-level="3">
<label class="md-nav__title" for="__nav_3_8_3">
<span class="md-nav__icon md-icon"></span>
Override the Default Configs
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../advanced/override-defaults/dovecot/" class="md-nav__link">
Dovecot
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/override-defaults/postfix/" class="md-nav__link">
Postfix
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/override-defaults/user-patches/" class="md-nav__link">
Modifications via Script
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../advanced/auth-ldap/" class="md-nav__link">
LDAP Authentication
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/mail-sieve/" class="md-nav__link">
Email Filtering with Sieve
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/mail-fetchmail/" class="md-nav__link">
Email Gathering with Fetchmail
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_8_7" data-md-state="indeterminate" type="checkbox" id="__nav_3_8_7" checked>
<label class="md-nav__link" for="__nav_3_8_7">
Email Forwarding
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Email Forwarding" data-md-level="3">
<label class="md-nav__title" for="__nav_3_8_7">
<span class="md-nav__icon md-icon"></span>
Email Forwarding
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../advanced/mail-forwarding/relay-hosts/" class="md-nav__link">
Relay Hosts
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/mail-forwarding/aws-ses/" class="md-nav__link">
AWS SES
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../advanced/full-text-search/" class="md-nav__link">
Full-Text Search
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/kubernetes/" class="md-nav__link">
Kubernetes
</a>
</li>
<li class="md-nav__item">
<a href="../../advanced/ipv6/" class="md-nav__link">
IPv6
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" data-md-state="indeterminate" type="checkbox" id="__nav_4" checked>
<label class="md-nav__link" for="__nav_4">
Examples
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Examples" data-md-level="1">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Examples
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_1" data-md-state="indeterminate" type="checkbox" id="__nav_4_1" checked>
<label class="md-nav__link" for="__nav_4_1">
Tutorials
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Tutorials" data-md-level="2">
<label class="md-nav__title" for="__nav_4_1">
<span class="md-nav__icon md-icon"></span>
Tutorials
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../examples/tutorials/basic-installation/" class="md-nav__link">
Basic Installation
</a>
</li>
<li class="md-nav__item">
<a href="../../../examples/tutorials/mailserver-behind-proxy/" class="md-nav__link">
Mailserver behind Proxy
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_2" data-md-state="indeterminate" type="checkbox" id="__nav_4_2" checked>
<label class="md-nav__link" for="__nav_4_2">
Use Cases
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Use Cases" data-md-level="2">
<label class="md-nav__title" for="__nav_4_2">
<span class="md-nav__icon md-icon"></span>
Use Cases
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../examples/uses-cases/forward-only-mailserver-with-ldap-authentication/" class="md-nav__link">
Forward-Only Mailserver with LDAP
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../../faq/" class="md-nav__link">
FAQ
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" data-md-state="indeterminate" type="checkbox" id="__nav_6" checked>
<label class="md-nav__link" for="__nav_6">
Contributing
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Contributing" data-md-level="1">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Contributing
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../contributing/issues-and-pull-requests/" class="md-nav__link">
Issues and Pull Requests
</a>
</li>
<li class="md-nav__item">
<a href="../../../contributing/coding-style/" class="md-nav__link">
Coding Style
</a>
</li>
<li class="md-nav__item">
<a href="../../../contributing/tests/" class="md-nav__link">
Tests
</a>
</li>
<li class="md-nav__item">
<a href="../../../contributing/documentation/" class="md-nav__link">
Documentation
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="https://hub.docker.com/repository/docker/mailserver/docker-mailserver" class="md-nav__link">
DockerHub
</a>
</li>
<li class="md-nav__item">
<a href="https://github.com/orgs/docker-mailserver/packages/container/package/docker-mailserver" class="md-nav__link">
GHCR
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#lets-encrypt-recommended" class="md-nav__link">
Let's Encrypt (Recommended)
</a>
<nav class="md-nav" aria-label="Let's Encrypt (Recommended)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#example-using-docker-for-lets-encrypt" class="md-nav__link">
Example using Docker for Let's Encrypt
</a>
</li>
<li class="md-nav__item">
<a href="#example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion" class="md-nav__link">
Example using Docker, nginx-proxy and letsencrypt-nginx-proxy-companion
</a>
</li>
<li class="md-nav__item">
<a href="#example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion-with-docker-compose" class="md-nav__link">
Example using Docker, nginx-proxy and letsencrypt-nginx-proxy-companion with docker-compose
</a>
</li>
<li class="md-nav__item">
<a href="#example-using-the-lets-encrypt-certificates-on-a-synology-nas" class="md-nav__link">
Example using the Let's Encrypt Certificates on a Synology NAS
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#caddy" class="md-nav__link">
Caddy
</a>
</li>
<li class="md-nav__item">
<a href="#traefik-v2" class="md-nav__link">
Traefik v2
</a>
</li>
<li class="md-nav__item">
<a href="#self-signed-certificates" class="md-nav__link">
Self-Signed Certificates
</a>
<nav class="md-nav" aria-label="Self-Signed Certificates">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#generating-a-self-signed-certificate" class="md-nav__link">
Generating a self-signed certificate
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#custom-certificate-files" class="md-nav__link">
Custom Certificate Files
</a>
</li>
<li class="md-nav__item">
<a href="#testing-a-certificate-is-valid" class="md-nav__link">
Testing a Certificate is Valid
</a>
</li>
<li class="md-nav__item">
<a href="#plain-text-access" class="md-nav__link">
Plain-Text Access
</a>
</li>
<li class="md-nav__item">
<a href="#importing-certificates-obtained-via-another-source" class="md-nav__link">
Importing Certificates Obtained via Another Source
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<a href="https://github.com/docker-mailserver/docker-mailserver/edit/master/docs/content/config/security/ssl.md" title="Edit this page" class="md-content__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg>
</a>
<h1>SSL/TLS</h1>
<p>There are multiple options to enable SSL:</p>
<ul>
<li>Using <a href="#lets-encrypt-recommended">letsencrypt</a> (recommended)</li>
<li>Using <a href="#caddy">Caddy</a></li>
<li>Using <a href="#traefik">Traefik</a></li>
<li>Using <a href="#self-signed-certificates-testing-only">self-signed certificates</a> with the provided tool</li>
<li>Using <a href="#custom-certificate-files">your own certificates</a></li>
</ul>
<p>After installation, you can test your setup with:</p>
<ul>
<li><a href="https://www.checktls.com/TestReceiver"><code>checktls.com</code></a></li>
<li><a href="https://github.com/drwetter/testssl.sh"><code>testssl.sh</code></a></li>
</ul>
<h2 id="lets-encrypt-recommended"><a class="toclink" href="#lets-encrypt-recommended">Let's Encrypt (Recommended)</a></h2>
<p>To enable Let's Encrypt on your mail server, you have to:</p>
<ul>
<li>Get your certificate using <a href="https://github.com/letsencrypt/letsencrypt">letsencrypt client</a></li>
<li>Add an environment variable <code>SSL_TYPE</code> with value <code>letsencrypt</code> (see <a href="https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml"><code>docker-compose.yml</code></a>)</li>
<li>Mount your whole <code>letsencrypt</code> folder to <code>/etc/letsencrypt</code></li>
<li>
<p>The certs folder name located in <code>letsencrypt/live/</code> must be the <code>fqdn</code> of your container responding to the <code>hostname</code> command. The <code>fqdn</code> (full qualified domain name) inside the docker container is built combining the <code>hostname</code> and <code>domainname</code> values of the <code>docker-compose</code> file, eg:</p>
<div class="highlight"><pre><span></span><code><span class="nt">services</span><span class="p">:</span>
<span class="nt">mailserver</span><span class="p">:</span>
<span class="nt">hostname</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mail</span>
<span class="nt">domainname</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">myserver.tld</span>
<span class="nt">fqdn</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mail.myserver.tld</span>
</code></pre></div>
</li>
</ul>
<p>You don't have anything else to do. Enjoy.</p>
<h3 id="example-using-docker-for-lets-encrypt"><a class="toclink" href="#example-using-docker-for-lets-encrypt">Example using Docker for Let's Encrypt</a></h3>
<ol>
<li>
<p>Make a directory to store your letsencrypt logs and configs. In my case:</p>
<div class="highlight"><pre><span></span><code>mkdir -p /home/ubuntu/docker/letsencrypt
<span class="nb">cd</span> /home/ubuntu/docker/letsencrypt
</code></pre></div>
</li>
<li>
<p>Now get the certificate (modify <code>mail.myserver.tld</code>) and following the certbot instructions.</p>
</li>
<li>
<p>This will need access to port 80 from the internet, adjust your firewall if needed:</p>
<div class="highlight"><pre><span></span><code>docker run --rm -it <span class="se">\</span>
-v <span class="nv">$PWD</span>/log/:/var/log/letsencrypt/ <span class="se">\</span>
-v <span class="nv">$PWD</span>/etc/:/etc/letsencrypt/ <span class="se">\</span>
-p <span class="m">80</span>:80 <span class="se">\</span>
certbot/certbot certonly --standalone -d mail.myserver.tld
</code></pre></div>
</li>
<li>
<p>You can now mount <code>/home/ubuntu/docker/letsencrypt/etc/</code> in <code>/etc/letsencrypt</code> of <code>docker-mailserver</code>.</p>
<p>To renew your certificate just run (this will need access to port 443 from the internet, adjust your firewall if needed):</p>
<div class="highlight"><pre><span></span><code>docker run --rm -it <span class="se">\</span>
-v <span class="nv">$PWD</span>/log/:/var/log/letsencrypt/ <span class="se">\</span>
-v <span class="nv">$PWD</span>/etc/:/etc/letsencrypt/ <span class="se">\</span>
-p <span class="m">80</span>:80 <span class="se">\</span>
-p <span class="m">443</span>:443 <span class="se">\</span>
certbot/certbot renew
</code></pre></div>
</li>
</ol>
<h3 id="example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion"><a class="toclink" href="#example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion">Example using Docker, <code>nginx-proxy</code> and <code>letsencrypt-nginx-proxy-companion</code></a></h3>
<p>If you are running a web server already, it is non-trivial to generate a Let's Encrypt certificate for your mail server using <code>certbot</code>, because port 80 is already occupied. In the following example, we show how <code>docker-mailserver</code> can be run alongside the docker containers <code>nginx-proxy</code> and <code>letsencrypt-nginx-proxy-companion</code>.</p>
<p>There are several ways to start <code>nginx-proxy</code> and <code>letsencrypt-nginx-proxy-companion</code>. Any method should be suitable here.</p>
<p>For example start <code>nginx-proxy</code> as in the <code>letsencrypt-nginx-proxy-companion</code> <a href="https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion">documentation</a>:</p>
<div class="highlight"><pre><span></span><code>docker run --detach <span class="se">\</span>
--name nginx-proxy <span class="se">\</span>
--restart always <span class="se">\</span>
--publish <span class="m">80</span>:80 <span class="se">\</span>
--publish <span class="m">443</span>:443 <span class="se">\</span>
--volume /server/letsencrypt/etc:/etc/nginx/certs:ro <span class="se">\</span>
--volume /etc/nginx/vhost.d <span class="se">\</span>
--volume /usr/share/nginx/html <span class="se">\</span>
--volume /var/run/docker.sock:/tmp/docker.sock:ro <span class="se">\</span>
jwilder/nginx-proxy
</code></pre></div>
<p>Then start <code>nginx-proxy-letsencrypt</code>:</p>
<div class="highlight"><pre><span></span><code>docker run --detach <span class="se">\</span>
--name nginx-proxy-letsencrypt <span class="se">\</span>
--restart always <span class="se">\</span>
--volume /server/letsencrypt/etc:/etc/nginx/certs:rw <span class="se">\</span>
--volumes-from nginx-proxy <span class="se">\</span>
--volume /var/run/docker.sock:/var/run/docker.sock:ro <span class="se">\</span>
jrcs/letsencrypt-nginx-proxy-companion
</code></pre></div>
<p>Start the rest of your web server containers as usual.</p>
<p>Start another container for your <code>mail.myserver.tld</code>. This will generate a Let's Encrypt certificate for your domain, which can be used by <code>docker-mailserver</code>. It will also run a web server on port 80 at that address:</p>
<div class="highlight"><pre><span></span><code>docker run -d <span class="se">\</span>
--name webmail <span class="se">\</span>
-e <span class="s2">&quot;VIRTUAL_HOST=mail.myserver.tld&quot;</span> <span class="se">\</span>
-e <span class="s2">&quot;LETSENCRYPT_HOST=mail.myserver.tld&quot;</span> <span class="se">\</span>
-e <span class="s2">&quot;LETSENCRYPT_EMAIL=foo@bar.com&quot;</span> <span class="se">\</span>
library/nginx
</code></pre></div>
<p>You may want to add <code>-e LETSENCRYPT_TEST=true</code> to the above while testing to avoid the Let's Encrypt certificate generation rate limits.</p>
<p>Finally, start the mailserver with the <code>docker-compose.yml</code>. Make sure your mount path to the letsencrypt certificates is correct.</p>
<p>Inside your <code>/path/to/mailserver/docker-compose.yml</code> (for the mailserver from this repo) make sure volumes look like below example:</p>
<div class="highlight"><pre><span></span><code><span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">maildata:/var/mail</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">mailstate:/var/mail-state</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">./config/:/tmp/docker-mailserver/</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/server/letsencrypt/etc:/etc/letsencrypt/live</span>
</code></pre></div>
<p>Then: <code>/path/to/mailserver/docker-compose up -d mail</code></p>
<h3 id="example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion-with-docker-compose"><a class="toclink" href="#example-using-docker-nginx-proxy-and-letsencrypt-nginx-proxy-companion-with-docker-compose">Example using Docker, <code>nginx-proxy</code> and <code>letsencrypt-nginx-proxy-companion</code> with <code>docker-compose</code></a></h3>
<p>The following <code>docker-compose.yml</code> is the basic setup you need for using <code>letsencrypt-nginx-proxy-companion</code>. It is mainly derived from its own wiki/documenation.</p>
<details class="example" open="open"><summary>Example Code</summary><div class="highlight"><pre><span></span><code><span class="nt">version</span><span class="p">:</span> <span class="s">&quot;2&quot;</span>
<span class="nt">services</span><span class="p">:</span>
<span class="nt">nginx</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx</span>
<span class="nt">container_name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx</span>
<span class="nt">ports</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">80:80</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">443:443</span>
<span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/htpasswd:/etc/nginx/htpasswd</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/conf.d:/etc/nginx/conf.d</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/vhost.d:/etc/nginx/vhost.d</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/html:/usr/share/nginx/html</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/certs:/etc/nginx/certs:ro</span>
<span class="nt">networks</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">proxy-tier</span>
<span class="nt">restart</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">always</span>
<span class="nt">nginx-gen</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">jwilder/docker-gen</span>
<span class="nt">container_name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx-gen</span>
<span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/var/run/docker.sock:/tmp/docker.sock:ro</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/templates/nginx.tmpl:/etc/docker-gen/templates/nginx.tmpl:ro</span>
<span class="nt">volumes_from</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">nginx</span>
<span class="nt">entrypoint</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">/usr/local/bin/docker-gen -notify-sighup nginx -watch -wait 5s:30s /etc/docker-gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf</span>
<span class="nt">restart</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">always</span>
<span class="nt">letsencrypt-nginx-proxy-companion</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">jrcs/letsencrypt-nginx-proxy-companion</span>
<span class="nt">container_name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">letsencrypt-companion</span>
<span class="nt">volumes_from</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">nginx</span>
<span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/var/run/docker.sock:/var/run/docker.sock:ro</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/certs:/etc/nginx/certs:rw</span>
<span class="nt">environment</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">NGINX_DOCKER_GEN_CONTAINER=nginx-gen</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">DEBUG=false</span>
<span class="nt">restart</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">always</span>
<span class="nt">networks</span><span class="p">:</span>
<span class="nt">proxy-tier</span><span class="p">:</span>
<span class="nt">external</span><span class="p">:</span>
<span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx-proxy</span>
</code></pre></div>
</details>
<p>The second part of the setup is the actual mail container. So, in another folder, create another <code>docker-compose.yml</code> with the following content (Removed all ENV variables for this example):</p>
<details class="example" open="open"><summary>Example Code</summary><div class="highlight"><pre><span></span><code><span class="nt">version</span><span class="p">:</span> <span class="s">&#39;2&#39;</span>
<span class="nt">services</span><span class="p">:</span>
<span class="nt">mailserver</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mailserver/docker-mailserver:latest</span>
<span class="nt">hostname</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">&lt;HOSTNAME&gt;</span> <span class="c1"># &lt;-- change this</span>
<span class="nt">domainname</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">&lt;DOMAINNAME&gt;</span> <span class="c1"># &lt;-- change this</span>
<span class="nt">container_name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mailserver</span>
<span class="nt">ports</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;25:25&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;143:143&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;465:465&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;587:587&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;993:993&quot;</span>
<span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">./mail:/var/mail</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">./mail-state:/var/mail-state</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">./config/:/tmp/docker-mailserver/</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/mnt/data/nginx/certs/:/etc/letsencrypt/live/:ro</span>
<span class="nt">cap_add</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">NET_ADMIN</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SYS_PTRACE</span>
<span class="nt">restart</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">always</span>
<span class="nt">cert-companion</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx</span>
<span class="nt">environment</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;VIRTUAL_HOST=&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;VIRTUAL_NETWORK=nginx-proxy&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;LETSENCRYPT_HOST=&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;LETSENCRYPT_EMAIL=&quot;</span>
<span class="nt">networks</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">proxy-tier</span>
<span class="nt">restart</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">always</span>
<span class="nt">networks</span><span class="p">:</span>
<span class="nt">proxy-tier</span><span class="p">:</span>
<span class="nt">external</span><span class="p">:</span>
<span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx-proxy</span>
</code></pre></div>
</details>
<p>The mail container needs to have the letsencrypt certificate folder mounted as a volume. No further changes are needed. The second container is a dummy-sidecar we need, because the mail-container do not expose any web-ports. Set your ENV variables as you need. (<code>VIRTUAL_HOST</code> and <code>LETSENCRYPT_HOST</code> are mandandory, see documentation)</p>
<h3 id="example-using-the-lets-encrypt-certificates-on-a-synology-nas"><a class="toclink" href="#example-using-the-lets-encrypt-certificates-on-a-synology-nas">Example using the Let's Encrypt Certificates on a Synology NAS</a></h3>
<p>Version 6.2 and later of the Synology NAS DSM OS now come with an interface to generate and renew letencrypt certificates. Navigation into your DSM control panel and go to Security, then click on the tab Certificate to generate and manage letsencrypt certificates.</p>
<p>Amongst other things, you can use these to secure your mail server. DSM locates the generated certificates in a folder below <code>/usr/syno/etc/certificate/_archive/</code>.</p>
<p>Navigate to that folder and note the 6 character random folder name of the certificate you'd like to use. Then, add the following to your <code>docker-compose.yml</code> declaration file:</p>
<div class="highlight"><pre><span></span><code><span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/usr/syno/etc/certificate/_archive/&lt;your-folder&gt;/:/tmp/ssl</span>
<span class="nt">environment</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SSL_TYPE=manual</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SSL_CERT_PATH=/tmp/ssl/fullchain.pem</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SSL_KEY_PATH=/tmp/ssl/privkey.pem</span>
</code></pre></div>
<p>DSM-generated letsencrypt certificates get auto-renewed every three months.</p>
<h2 id="caddy"><a class="toclink" href="#caddy">Caddy</a></h2>
<p>If you are using Caddy to renew your certificates, please note that only RSA certificates work. Read <a href="https://github.com/docker-mailserver/docker-mailserver/issues/1440">#1440</a> for details. In short for Caddy v1 the <code>Caddyfile</code> should look something like:</p>
<div class="highlight"><pre><span></span><code>https://mail.domain.com {
tls yourcurrentemail@gmail.com {
key_type rsa2048
}
}
</code></pre></div>
<p>For Caddy v2 you can specify the <code>key_type</code> in your server's global settings, which would end up looking something like this if you're using a <code>Caddyfile</code>:</p>
<div class="highlight"><pre><span></span><code>{
debug
admin localhost:2019
http_port 80
https_port 443
default_sni mywebserver.com
key_type rsa4096
}
</code></pre></div>
<p>If you are instead using a json config for Caddy v2, you can set it in your site's TLS automation policies:</p>
<details class="example" open="open"><summary>Example Code</summary><div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;apps&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;http&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;servers&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;srv0&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;listen&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;:443&quot;</span>
<span class="p">],</span>
<span class="nt">&quot;routes&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;match&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;host&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;mail.domain.com&quot;</span><span class="p">,</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">],</span>
<span class="nt">&quot;handle&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;handler&quot;</span><span class="p">:</span> <span class="s2">&quot;subroute&quot;</span><span class="p">,</span>
<span class="nt">&quot;routes&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;handle&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;body&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;handler&quot;</span><span class="p">:</span> <span class="s2">&quot;static_response&quot;</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">],</span>
<span class="nt">&quot;terminal&quot;</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">},</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="nt">&quot;tls&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;automation&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;policies&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;subjects&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;mail.domain.com&quot;</span><span class="p">,</span>
<span class="p">],</span>
<span class="nt">&quot;key_type&quot;</span><span class="p">:</span> <span class="s2">&quot;rsa2048&quot;</span><span class="p">,</span>
<span class="nt">&quot;issuer&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;email@email.com&quot;</span><span class="p">,</span>
<span class="nt">&quot;module&quot;</span><span class="p">:</span> <span class="s2">&quot;acme&quot;</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;issuer&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;email@email.com&quot;</span><span class="p">,</span>
<span class="nt">&quot;module&quot;</span><span class="p">:</span> <span class="s2">&quot;acme&quot;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div>
</details>
<p>The generated certificates can be mounted:</p>
<div class="highlight"><pre><span></span><code><span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.domain.com/mail.domain.com.crt:/etc/letsencrypt/live/mail.domain.com/fullchain.pem</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.domain.com/mail.domain.com.key:/etc/letsencrypt/live/mail.domain.com/privkey.pem</span>
</code></pre></div>
<p>EC certificates fail in the TLS handshake:</p>
<div class="highlight"><pre><span></span><code><span class="go">CONNECTED(00000003)</span>
<span class="go">140342221178112:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:ssl/record/rec_layer_s3.c:1543:SSL alert number 40</span>
<span class="go">no peer certificate available</span>
<span class="go">No client certificate CA names sent</span>
</code></pre></div>
<h2 id="traefik-v2"><a class="toclink" href="#traefik-v2">Traefik v2</a></h2>
<p><a href="https://github.com/containous/traefik">Traefik</a> is an open-source application proxy using the <a href="https://tools.ietf.org/html/rfc8555">ACME protocol</a>. <a href="https://github.com/containous/traefik">Traefik</a> can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc. We strongly recommend to use <a href="https://github.com/containous/traefik">Traefik</a>'s major version 2.</p>
<p><a href="https://github.com/containous/traefik">Traefik</a>'s storage format is natively supported if the <code>acme.json</code> store is mounted into the container at <code>/etc/letsencrypt/acme.json</code>. The file is also monitored for changes and will trigger a reload of the mail services. Wild card certificates issued for <code>*.domain.tld</code> are supported. You will then want to use <code class="highlight"><span class="nv">SSL_DOMAIN</span><span class="o">=</span>domain.tld</code>. Lookup of the certificate domain happens in the following order:</p>
<ol>
<li><code class="highlight"><span class="si">${</span><span class="nv">SSL_DOMAIN</span><span class="si">}</span></code></li>
<li><code class="highlight"><span class="si">${</span><span class="nv">HOSTNAME</span><span class="si">}</span></code></li>
<li><code class="highlight"><span class="si">${</span><span class="nv">DOMAINNAME</span><span class="si">}</span></code></li>
</ol>
<p>This setup only comes with one caveat: The domain has to be configured on another service for <a href="https://github.com/containous/traefik">Traefik</a> to actually request it from Let'sEncrypt, i.e. <a href="https://github.com/containous/traefik">Traefik</a> will not issue a certificate without a service / router demanding it.</p>
<details class="example" open="open"><summary>Example Code</summary><p>Here is an example setup for <a href="https://docs.docker.com/compose/"><code>docker-compose</code></a>:</p>
<div class="highlight"><pre><span></span><code><span class="nt">version</span><span class="p">:</span> <span class="s">&#39;3.8&#39;</span>
<span class="nt">services</span><span class="p">:</span>
<span class="nt">mailserver</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">docker.io/mailserver/docker-mailserver:latest</span>
<span class="nt">container_name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mailserver</span>
<span class="nt">hostname</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mail</span>
<span class="nt">domainname</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">domain.tld</span>
<span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/traefik/acme.json:/etc/letsencrypt/acme.json:ro</span>
<span class="nt">environment</span><span class="p">:</span>
<span class="nt">SSL_TYPE</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">letsencrypt</span>
<span class="nt">SSL_DOMAIN</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mail.example.com&quot;</span>
<span class="c1"># for a wildcard certificate, use</span>
<span class="c1"># SSL_DOMAIN: example.com</span>
<span class="nt">traefik</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">docker.io/traefik:v2.4.8</span>
<span class="nt">ports</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;80:80&quot;</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;443:443&quot;</span>
<span class="nt">command</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--providers.docker</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--entrypoints.http.address=:80</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--entrypoints.http.http.redirections.entryPoint.to=https</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--entrypoints.http.http.redirections.entryPoint.scheme=https</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--entrypoints.https.address=:443</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--entrypoints.https.http.tls.certResolver=letsencrypt</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--certificatesresolvers.letsencrypt.acme.email=admin@domain.tld</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--certificatesresolvers.letsencrypt.acme.storage=/acme.json</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=http</span>
<span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/traefik/acme.json:/acme.json</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/var/run/docker.sock:/var/run/docker.sock:ro</span>
<span class="nt">whoami</span><span class="p">:</span>
<span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">docker.io/traefik/whoami:latest</span>
<span class="nt">labels</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="s">&quot;traefik.http.routers.whoami.rule=Host(`mail.domain.tld`)&quot;</span>
</code></pre></div>
</details>
<h2 id="self-signed-certificates"><a class="toclink" href="#self-signed-certificates">Self-Signed Certificates</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Use self-signed certificates only for testing purposes!</p>
</div>
<p>This feature requires you to provide the following files into your <a href="../../advanced/optional-config/"><code>config/ssl/</code> directory</a> (internal location: <code>/tmp/docker-mailserver/ssl/</code>):</p>
<ul>
<li><code>${HOSTNAME}-key.pem</code></li>
<li><code>${HOSTNAME}-cert.pem</code></li>
<li><code>demoCA/cacert.pem</code></li>
</ul>
<p>Where <code>${HOSTNAME}</code> is the mailserver <a href="https://en.wikipedia.org/wiki/Fully_qualified_domain_name">FQDN</a> (<code>hostname</code>(<em>mail</em>) + <code>domainname</code>(<em>example.com</em>), eg: <code>mail.example.com</code>).</p>
<p>To use the certificate:</p>
<ul>
<li>Add <code>SSL_TYPE=self-signed</code> to your container environment variables.</li>
<li>If a matching certificate (files listed above) is found in <code>config/ssl</code>, it will be automatically setup in postfix and dovecot. You just have to place them in <code>config/ssl</code> folder.</li>
</ul>
<h4 id="generating-a-self-signed-certificate"><a class="toclink" href="#generating-a-self-signed-certificate">Generating a self-signed certificate</a></h4>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Since v10, support in <code>setup.sh</code> for generating a self-signed SSL certificate internally was removed.</p>
<p>It is now similar to <code>SSL_TYPE=manual</code> (<em>except <code>manual</code> does not support verification for a custom CA</em>), but does not require additional ENV vars for providing the location of cert files.</p>
</div>
<p>One way to generate self-signed certificates is with <a href="https://smallstep.com/docs/step-cli">Smallstep's <code>step</code> CLI</a>. This is exactly what <a href="https://github.com/docker-mailserver/docker-mailserver/tree/master/test/test-files/ssl/example.test"><code>docker-mailserver</code> does for creating test certificates</a>.</p>
<p>For example with the FQDN <code>mail.example.test</code>, you can generate the required files by running:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#! /bin/sh</span>
mkdir -p demoCA
step certificate create <span class="s2">&quot;Smallstep Root CA&quot;</span> <span class="s2">&quot;demoCA/cacert.pem&quot;</span> <span class="s2">&quot;demoCA/cakey.pem&quot;</span> <span class="se">\</span>
--no-password --insecure <span class="se">\</span>
--profile root-ca <span class="se">\</span>
--not-before <span class="s2">&quot;2021-01-01T00:00:00+00:00&quot;</span> <span class="se">\</span>
--not-after <span class="s2">&quot;2031-01-01T00:00:00+00:00&quot;</span> <span class="se">\</span>
--san <span class="s2">&quot;example.test&quot;</span> <span class="se">\</span>
--san <span class="s2">&quot;mail.example.test&quot;</span> <span class="se">\</span>
--kty RSA --size <span class="m">2048</span>
step certificate create <span class="s2">&quot;Smallstep Leaf&quot;</span> mail.example.test-cert.pem mail.example.test-key.pem <span class="se">\</span>
--no-password --insecure <span class="se">\</span>
--profile leaf <span class="se">\</span>
--ca <span class="s2">&quot;demoCA/cacert.pem&quot;</span> <span class="se">\</span>
--ca-key <span class="s2">&quot;demoCA/cakey.pem&quot;</span> <span class="se">\</span>
--not-before <span class="s2">&quot;2021-01-01T00:00:00+00:00&quot;</span> <span class="se">\</span>
--not-after <span class="s2">&quot;2031-01-01T00:00:00+00:00&quot;</span> <span class="se">\</span>
--san <span class="s2">&quot;example.test&quot;</span> <span class="se">\</span>
--san <span class="s2">&quot;mail.example.test&quot;</span> <span class="se">\</span>
--kty RSA --size <span class="m">2048</span>
</code></pre></div>
<p>If you'd rather not install the CLI tool locally to run the <code>step</code> commands above; you can save the script above to a file such as <code>generate-certs.sh</code> (<em>and make it executable <code>chmod +x generate-certs.sh</code></em>) in a directory that you want the certs to be placed, then run that script with docker:</p>
<div class="highlight"><pre><span></span><code><span class="c1"># --user to keep ownership of the files to your user and group ID</span>
docker run --rm -it <span class="se">\</span>
--user <span class="s2">&quot;</span><span class="k">$(</span>id -u<span class="k">)</span><span class="s2">:</span><span class="k">$(</span>id -g<span class="k">)</span><span class="s2">&quot;</span> <span class="se">\</span>
--volume <span class="s2">&quot;</span><span class="si">${</span><span class="nv">PWD</span><span class="si">}</span><span class="s2">:/tmp&quot;</span> <span class="se">\</span>
--workdir <span class="s2">&quot;/tmp&quot;</span> <span class="se">\</span>
--entrypoint <span class="s2">&quot;/tmp/generate-certs.sh&quot;</span> <span class="se">\</span>
smallstep/step-ca
</code></pre></div>
<h2 id="custom-certificate-files"><a class="toclink" href="#custom-certificate-files">Custom Certificate Files</a></h2>
<p>You can also provide your own certificate files. Add these entries to your <code>docker-compose.yml</code>:</p>
<div class="highlight"><pre><span></span><code><span class="nt">volumes</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/etc/ssl:/tmp/ssl:ro</span>
<span class="nt">environment</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SSL_TYPE=manual</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SSL_CERT_PATH=/tmp/ssl/cert/public.crt</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">SSL_KEY_PATH=/tmp/ssl/private/private.key</span>
</code></pre></div>
<p>This will mount the path where your ssl certificates reside as read-only under <code>/tmp/ssl</code>. Then all you have to do is to specify the location of your private key and the certificate.</p>
<div class="admonition info">
<p class="admonition-title">Info</p>
<p>You may have to restart your mailserver once the certificates change.</p>
</div>
<h2 id="testing-a-certificate-is-valid"><a class="toclink" href="#testing-a-certificate-is-valid">Testing a Certificate is Valid</a></h2>
<ul>
<li>
<p>From your host:</p>
<div class="highlight"><pre><span></span><code>docker <span class="nb">exec</span> mail openssl s_client <span class="se">\</span>
-connect <span class="m">0</span>.0.0.0:25 <span class="se">\</span>
-starttls smtp <span class="se">\</span>
-CApath /etc/ssl/certs/
</code></pre></div>
</li>
<li>
<p>Or:</p>
<div class="highlight"><pre><span></span><code>docker <span class="nb">exec</span> mail openssl s_client <span class="se">\</span>
-connect <span class="m">0</span>.0.0.0:143 <span class="se">\</span>
-starttls imap <span class="se">\</span>
-CApath /etc/ssl/certs/
</code></pre></div>
</li>
</ul>
<p>And you should see the certificate chain, the server certificate and: <code>Verify return code: 0 (ok)</code></p>
<p>In addition, to verify certificate dates:</p>
<div class="highlight"><pre><span></span><code>docker <span class="nb">exec</span> mail openssl s_client <span class="se">\</span>
-connect <span class="m">0</span>.0.0.0:25 <span class="se">\</span>
-starttls smtp <span class="se">\</span>
-CApath /etc/ssl/certs/ <span class="se">\</span>
<span class="m">2</span>&gt;/dev/null <span class="p">|</span> openssl x509 -noout -dates
</code></pre></div>
<h2 id="plain-text-access"><a class="toclink" href="#plain-text-access">Plain-Text Access</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Not recommended for purposes other than testing.</p>
</div>
<p>Add this to <code>config/dovecot.cf</code>:</p>
<div class="highlight"><pre><span></span><code><span class="na">ssl</span> <span class="o">=</span> <span class="s">yes</span>
<span class="na">disable_plaintext_auth</span><span class="o">=</span><span class="s">no</span>
</code></pre></div>
<p>These options in conjunction mean:</p>
<ul>
<li>SSL/TLS is offered to the client, but the client isn't required to use it.</li>
<li>The client is allowed to login with plaintext authentication even when SSL/TLS isn't enabled on the connection.</li>
<li><strong>This is insecure</strong>, because the plaintext password is exposed to the internet.</li>
</ul>
<h2 id="importing-certificates-obtained-via-another-source"><a class="toclink" href="#importing-certificates-obtained-via-another-source">Importing Certificates Obtained via Another Source</a></h2>
<p>If you have another source for SSL/TLS certificates you can import them into the server via an external script. The external script can be found here: <a href="https://github.com/hanscees/dockerscripts/blob/master/scripts/tomav-renew-certs">external certificate import script</a>.</p>
<p>The steps to follow are these:</p>
<ol>
<li>Transport the new certificates to <code>./config/ssl</code> (<code>/tmp/ssl</code> in the container)</li>
<li>You should provide <code>fullchain.key</code> and <code>privkey.pem</code></li>
<li>Place the script in <code>./config/</code> (or <code>/tmp/docker-mailserver/</code> inside the container)</li>
<li>Make the script executable (<code>chmod +x tomav-renew-certs.sh</code>)</li>
<li>Run the script: <code>docker exec mail /tmp/docker-mailserver/tomav-renew-certs.sh</code></li>
</ol>
<p>If an error occurs the script will inform you. If not you will see both postfix and dovecot restart.</p>
<p>After the certificates have been loaded you can check the certificate:</p>
<div class="highlight"><pre><span></span><code>openssl s_client <span class="se">\</span>
-servername mail.mydomain.net <span class="se">\</span>
-connect <span class="m">192</span>.168.0.72:465 <span class="se">\</span>
<span class="m">2</span>&gt;/dev/null <span class="p">|</span> openssl x509
<span class="c1"># or</span>
openssl s_client <span class="se">\</span>
-servername mail.mydomain.net <span class="se">\</span>
-connect mail.mydomain.net:465 <span class="se">\</span>
<span class="m">2</span>&gt;/dev/null <span class="p">|</span> openssl x509
</code></pre></div>
<p>Or you can check how long the new certificate is valid with commands like:</p>
<div class="highlight"><pre><span></span><code><span class="nb">export</span> <span class="nv">SITE_URL</span><span class="o">=</span><span class="s2">&quot;mail.mydomain.net&quot;</span>
<span class="nb">export</span> <span class="nv">SITE_IP_URL</span><span class="o">=</span><span class="s2">&quot;192.168.0.72&quot;</span> <span class="c1"># can also be `mail.mydomain.net`</span>
<span class="nb">export</span> <span class="nv">SITE_SSL_PORT</span><span class="o">=</span><span class="s2">&quot;993&quot;</span> <span class="c1"># imap port dovecot</span>
<span class="c1">##works: check if certificate will expire in two weeks </span>
<span class="c1">#2 weeks is 1209600 seconds</span>
<span class="c1">#3 weeks is 1814400</span>
<span class="c1">#12 weeks is 7257600</span>
<span class="c1">#15 weeks is 9072000</span>
<span class="nv">certcheck_2weeks</span><span class="o">=</span><span class="sb">`</span>openssl s_client -connect <span class="si">${</span><span class="nv">SITE_IP_URL</span><span class="si">}</span>:<span class="si">${</span><span class="nv">SITE_SSL_PORT</span><span class="si">}</span> <span class="se">\</span>
-servername <span class="si">${</span><span class="nv">SITE_URL</span><span class="si">}</span> <span class="m">2</span>&gt; /dev/null <span class="p">|</span> openssl x509 -noout -checkend <span class="m">1209600</span><span class="sb">`</span>
<span class="c1">####################################</span>
<span class="c1">#notes: output can be</span>
<span class="c1">#Certificate will not expire</span>
<span class="c1">#Certificate will expire</span>
<span class="c1">####################</span>
</code></pre></div>
<p>What does the script that imports the certificates do:</p>
<ol>
<li>Check if there are new certs in the <code>/tmp/ssl</code> folder.</li>
<li>Check with the ssl cert fingerprint if they differ from the current certificates.</li>
<li>If so it will copy the certs to the right places.</li>
<li>And restart postfix and dovecot.</li>
</ol>
<p>You can of course run the script by cron once a week or something. In that way you could automate cert renewal. If you do so it is probably wise to run an automated check on certificate expiry as well. Such a check could look something like this:</p>
<div class="highlight"><pre><span></span><code><span class="c1">## code below will alert if certificate expires in less than two weeks</span>
<span class="c1">## please adjust varables! </span>
<span class="c1">## make sure the mail -s command works! Test!</span>
<span class="nb">export</span> <span class="nv">SITE_URL</span><span class="o">=</span><span class="s2">&quot;mail.mydomain.net&quot;</span>
<span class="nb">export</span> <span class="nv">SITE_IP_URL</span><span class="o">=</span><span class="s2">&quot;192.168.2.72&quot;</span> <span class="c1"># can also be `mail.mydomain.net`</span>
<span class="nb">export</span> <span class="nv">SITE_SSL_PORT</span><span class="o">=</span><span class="s2">&quot;993&quot;</span> <span class="c1"># imap port dovecot</span>
<span class="nb">export</span> <span class="nv">ALERT_EMAIL_ADDR</span><span class="o">=</span><span class="s2">&quot;bill@gates321boom.com&quot;</span>
<span class="nv">certcheck_2weeks</span><span class="o">=</span><span class="sb">`</span>openssl s_client -connect <span class="si">${</span><span class="nv">SITE_IP_URL</span><span class="si">}</span>:<span class="si">${</span><span class="nv">SITE_SSL_PORT</span><span class="si">}</span> <span class="se">\</span>
-servername <span class="si">${</span><span class="nv">SITE_URL</span><span class="si">}</span> <span class="m">2</span>&gt; /dev/null <span class="p">|</span> openssl x509 -noout -checkend <span class="m">1209600</span><span class="sb">`</span>
<span class="c1">####################################</span>
<span class="c1">#notes: output can be</span>
<span class="c1">#Certificate will not expire</span>
<span class="c1">#Certificate will expire</span>
<span class="c1">####################</span>
<span class="c1">#echo &quot;certcheck 2 weeks gives $certcheck_2weeks&quot;</span>
<span class="c1">##automated check you might run by cron or something</span>
<span class="c1">## does tls/ssl certificate expire within two weeks?</span>
<span class="k">if</span> <span class="o">[</span> <span class="s2">&quot;</span><span class="nv">$certcheck_2weeks</span><span class="s2">&quot;</span> <span class="o">=</span> <span class="s2">&quot;Certificate will not expire&quot;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
<span class="nb">echo</span> <span class="s2">&quot;all is well, certwatch 2 weeks says </span><span class="nv">$certcheck_2weeks</span><span class="s2">&quot;</span>
<span class="k">else</span>
<span class="nb">echo</span> <span class="s2">&quot;Cert seems to be expiring pretty soon, within two weeks: </span><span class="nv">$certcheck_2weeks</span><span class="s2">&quot;</span>
<span class="nb">echo</span> <span class="s2">&quot;we will send an alert email and log as well&quot;</span>
logger Certwatch: cert <span class="nv">$SITE_URL</span> will expire <span class="k">in</span> two weeks
<span class="nb">echo</span> <span class="s2">&quot;Certwatch: cert </span><span class="nv">$SITE_URL</span><span class="s2"> will expire in two weeks&quot;</span> <span class="p">|</span> mail -s <span class="s2">&quot;cert </span><span class="nv">$SITE_URL</span><span class="s2"> expires in two weeks &quot;</span> <span class="nv">$ALERT_EMAIL_ADDR</span>
<span class="k">fi</span>
</code></pre></div>
</article>
</div>
</div>
<a href="#" class="md-top md-icon" title="Back to top" data-md-component="top" data-md-state="hidden">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"/></svg>
</a>
</main>
<footer class="md-footer">
<nav class="md-footer__inner md-grid" aria-label="Footer">
<a href="../understanding-the-ports/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Understanding the Ports" rel="prev">
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
</div>
<div class="md-footer__title">
<div class="md-ellipsis">
<span class="md-footer__direction">
Previous
</span>
Understanding the Ports
</div>
</div>
</a>
<a href="../fail2ban/" class="md-footer__link md-footer__link--next" aria-label="Next: Fail2Ban" rel="next">
<div class="md-footer__title">
<div class="md-ellipsis">
<span class="md-footer__direction">
Next
</span>
Fail2Ban
</div>
</div>
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
</div>
</a>
</nav>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-footer-copyright">
<div class="md-footer-copyright__highlight">
<p>&copy <a href="https://github.com/docker-mailserver"><em>Docker Mailserver Organization</em></a><br/><span>This project is licensed under the MIT license.</span></p>
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "../../..", "features": ["navigation.tabs", "navigation.top", "navigation.expand", "navigation.instant"], "translations": {"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing", "select.version.title": "Select version"}, "search": "../../../assets/javascripts/workers/search.b0710199.min.js", "version": {"provider": "mike"}}</script>
<script src="../../../assets/javascripts/bundle.76f349be.min.js"></script>
</body>
</html>
Reference in a new issue View git blame Copy permalink