diff --git a/v12.0/assets/css/customizations.css b/v12.0/assets/css/customizations.css new file mode 100644 index 00000000..49ede009 --- /dev/null +++ b/v12.0/assets/css/customizations.css @@ -0,0 +1,100 @@ +/* + This file adds our styling additions / fixes to maintain. + Some of which are overly specific and may break with future updates by upstream. +*/ + +/* ============================================================================================================= */ + +/* External Link icon feature. Rejected from upstreaming to `mkdocs-material`. +Alternative solution using SVG icon here (Broken on Chrome?): https://github.com/squidfunk/mkdocs-material/issues/2318#issuecomment-789461149 +Tab or Nav sidebar with non-relative links will prepend an icon (font glyph) +If you want to append instead, switch `::before` to `::after`. +*/ +/* reference the icon font to use */ +@font-face { + font-family: 'external-link'; + src: url('../fonts/external-link.woff') format('woff'); +} + +/* Matches the two nav link classes that start with `http` `href` values, regular docs pages use relative URLs instead. */ +.md-tabs__link[href^="http"]::before, .md-nav__link[href^="http"]::before { + display: inline-block; /* treat similar to text */ + font-family: 'external-link'; + content:'\0041'; /* represents "A" which our font renders as an icon instead of the "A" glyph */ + font-size: 80%; /* icon is a little too big by default, scale it down */ +} + +/* ============================================================================================================= */ + +/* UI Improvement: Header bar (top of page) adjustments - Increase scale of logo and adjust white-space */ +/* Make the logo larger without impacting other header components */ +.md-header__button.md-logo > img { transform: scale(180%); margin-left: 0.4rem; } +/* Reduce the white-space between the Logo and Title components */ +.md-header__title { margin-left: 0.3rem; } + +/* ============================================================================================================= */ + +/* UI Improvement: Add light colour bg for the version selector, with some rounded corners */ +.md-version__current { + background-color: rgb(255,255,255,0.18); /* white with 18% opacity */ + padding: 5px; + border-radius: 3px; +} + +/* ============================================================================================================= */ + +/* + UX Bugfix for left navbar visibility on top-level (tabbed) pages with no nested sub-pages. + Upstream will not fix: https://github.com/squidfunk/mkdocs-material/issues/3109 +*/ + +@media screen and (min-width: 76.25em) { + .md-nav--lifted>.md-nav__list>.md-nav__item--active>.md-nav__link { + display: none; + } +} + +/* ============================================================================================================= */ + +/* + UX Bugfix for permalink affecting typography in headings. + Upstream will not fix: https://github.com/squidfunk/mkdocs-material/issues/2369 +*/ + +/* Headings are configured to be links (instead of only the permalink symbol), removes the link colour */ +div.md-content article.md-content__inner a.toclink { + color: currentColor; +} + +/* Instead of a permalink symbol at the end of heading text, use a border line on the left spanning height of heading */ +/* Includes optional background fill with rounded right-side corners, and restores inline code style */ +/* NOTE: Headings with markdown links embedded disrupt the bg fill style, as they're not children of `a.toclink` element */ +div.md-content article.md-content__inner a.toclink { + display: inline-block; /* Enables multi-line support for both border and bg color */ + border-left: .2rem solid transparent; /* transparent placeholder to avoid heading shift during reveal transition */ + margin-left: -0.6rem; /* Offset heading to the left */ + padding-left: 0.4rem; /* Push heading back to original position, margin-left - border-left widths */ + transition: background-color 200ms,border-left 200ms; + + /* Only relevant if using background highlight style */ + border-radius: 0 0.25rem 0.25rem 0; + padding-right: 0.4rem; +} + +div.md-content article.md-content__inner a.toclink:hover, +div.md-content article.md-content__inner :target > a.toclink { + border-left: .2rem solid #448aff; /* highlight line on the left */ + background-color: #b3dbff6e; /* background highlight fill */ + transition: background-color 200ms,border-left 200ms; +} + +/* Upstream overrides some of the `code` element styles for headings, restore them */ +div.md-content article.md-content__inner a.toclink code { + padding: 0 0.3em; /* padding to the left and right, not top and bottom */ + border-radius: 0.2rem; /* 0.1rem of original style bit too small */ + background-color: var(--md-code-bg-color); +} + +.highlight.no-copy .md-clipboard { display: none; } + +/* ============================================================================================================= */ diff --git a/v12.0/assets/fonts/external-link.woff b/v12.0/assets/fonts/external-link.woff new file mode 100644 index 00000000..6e888e08 Binary files /dev/null and b/v12.0/assets/fonts/external-link.woff differ diff --git a/v12.0/assets/img/bg-water.webp b/v12.0/assets/img/bg-water.webp new file mode 100644 index 00000000..5eb84897 Binary files /dev/null and b/v12.0/assets/img/bg-water.webp differ diff --git a/v12.0/assets/javascripts/bundle.407015b8.min.js b/v12.0/assets/javascripts/bundle.407015b8.min.js new file mode 100644 index 00000000..4361bb78 --- /dev/null +++ b/v12.0/assets/javascripts/bundle.407015b8.min.js @@ -0,0 +1,29 @@ +"use strict";(()=>{var Ri=Object.create;var gr=Object.defineProperty;var ki=Object.getOwnPropertyDescriptor;var Hi=Object.getOwnPropertyNames,Ht=Object.getOwnPropertySymbols,Pi=Object.getPrototypeOf,yr=Object.prototype.hasOwnProperty,on=Object.prototype.propertyIsEnumerable;var nn=(e,t,r)=>t in e?gr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,P=(e,t)=>{for(var r in t||(t={}))yr.call(t,r)&&nn(e,r,t[r]);if(Ht)for(var r of Ht(t))on.call(t,r)&&nn(e,r,t[r]);return e};var an=(e,t)=>{var r={};for(var n in e)yr.call(e,n)&&t.indexOf(n)<0&&(r[n]=e[n]);if(e!=null&&Ht)for(var n of Ht(e))t.indexOf(n)<0&&on.call(e,n)&&(r[n]=e[n]);return r};var Pt=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var $i=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of Hi(t))!yr.call(e,o)&&o!==r&&gr(e,o,{get:()=>t[o],enumerable:!(n=ki(t,o))||n.enumerable});return e};var yt=(e,t,r)=>(r=e!=null?Ri(Pi(e)):{},$i(t||!e||!e.__esModule?gr(r,"default",{value:e,enumerable:!0}):r,e));var cn=Pt((xr,sn)=>{(function(e,t){typeof xr=="object"&&typeof sn!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(xr,function(){"use strict";function e(r){var n=!0,o=!1,i=null,s={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function a(T){return!!(T&&T!==document&&T.nodeName!=="HTML"&&T.nodeName!=="BODY"&&"classList"in T&&"contains"in T.classList)}function c(T){var Qe=T.type,De=T.tagName;return!!(De==="INPUT"&&s[Qe]&&!T.readOnly||De==="TEXTAREA"&&!T.readOnly||T.isContentEditable)}function f(T){T.classList.contains("focus-visible")||(T.classList.add("focus-visible"),T.setAttribute("data-focus-visible-added",""))}function u(T){T.hasAttribute("data-focus-visible-added")&&(T.classList.remove("focus-visible"),T.removeAttribute("data-focus-visible-added"))}function p(T){T.metaKey||T.altKey||T.ctrlKey||(a(r.activeElement)&&f(r.activeElement),n=!0)}function m(T){n=!1}function d(T){a(T.target)&&(n||c(T.target))&&f(T.target)}function h(T){a(T.target)&&(T.target.classList.contains("focus-visible")||T.target.hasAttribute("data-focus-visible-added"))&&(o=!0,window.clearTimeout(i),i=window.setTimeout(function(){o=!1},100),u(T.target))}function v(T){document.visibilityState==="hidden"&&(o&&(n=!0),G())}function G(){document.addEventListener("mousemove",N),document.addEventListener("mousedown",N),document.addEventListener("mouseup",N),document.addEventListener("pointermove",N),document.addEventListener("pointerdown",N),document.addEventListener("pointerup",N),document.addEventListener("touchmove",N),document.addEventListener("touchstart",N),document.addEventListener("touchend",N)}function oe(){document.removeEventListener("mousemove",N),document.removeEventListener("mousedown",N),document.removeEventListener("mouseup",N),document.removeEventListener("pointermove",N),document.removeEventListener("pointerdown",N),document.removeEventListener("pointerup",N),document.removeEventListener("touchmove",N),document.removeEventListener("touchstart",N),document.removeEventListener("touchend",N)}function N(T){T.target.nodeName&&T.target.nodeName.toLowerCase()==="html"||(n=!1,oe())}document.addEventListener("keydown",p,!0),document.addEventListener("mousedown",m,!0),document.addEventListener("pointerdown",m,!0),document.addEventListener("touchstart",m,!0),document.addEventListener("visibilitychange",v,!0),G(),r.addEventListener("focus",d,!0),r.addEventListener("blur",h,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var fn=Pt(Er=>{(function(e){var t=function(){try{return!!Symbol.iterator}catch(f){return!1}},r=t(),n=function(f){var u={next:function(){var p=f.shift();return{done:p===void 0,value:p}}};return r&&(u[Symbol.iterator]=function(){return u}),u},o=function(f){return encodeURIComponent(f).replace(/%20/g,"+")},i=function(f){return decodeURIComponent(String(f).replace(/\+/g," "))},s=function(){var f=function(p){Object.defineProperty(this,"_entries",{writable:!0,value:{}});var m=typeof p;if(m!=="undefined")if(m==="string")p!==""&&this._fromString(p);else if(p instanceof f){var d=this;p.forEach(function(oe,N){d.append(N,oe)})}else if(p!==null&&m==="object")if(Object.prototype.toString.call(p)==="[object Array]")for(var h=0;hd[0]?1:0}),f._entries&&(f._entries={});for(var p=0;p1?i(d[1]):"")}})})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Er);(function(e){var t=function(){try{var o=new e.URL("b","http://a");return o.pathname="c d",o.href==="http://a/c%20d"&&o.searchParams}catch(i){return!1}},r=function(){var o=e.URL,i=function(c,f){typeof c!="string"&&(c=String(c)),f&&typeof f!="string"&&(f=String(f));var u=document,p;if(f&&(e.location===void 0||f!==e.location.href)){f=f.toLowerCase(),u=document.implementation.createHTMLDocument(""),p=u.createElement("base"),p.href=f,u.head.appendChild(p);try{if(p.href.indexOf(f)!==0)throw new Error(p.href)}catch(T){throw new Error("URL unable to set base "+f+" due to "+T)}}var m=u.createElement("a");m.href=c,p&&(u.body.appendChild(m),m.href=m.href);var d=u.createElement("input");if(d.type="url",d.value=c,m.protocol===":"||!/:/.test(m.href)||!d.checkValidity()&&!f)throw new TypeError("Invalid URL");Object.defineProperty(this,"_anchorElement",{value:m});var h=new e.URLSearchParams(this.search),v=!0,G=!0,oe=this;["append","delete","set"].forEach(function(T){var Qe=h[T];h[T]=function(){Qe.apply(h,arguments),v&&(G=!1,oe.search=h.toString(),G=!0)}}),Object.defineProperty(this,"searchParams",{value:h,enumerable:!0});var N=void 0;Object.defineProperty(this,"_updateSearchParams",{enumerable:!1,configurable:!1,writable:!1,value:function(){this.search!==N&&(N=this.search,G&&(v=!1,this.searchParams._fromString(this.search),v=!0))}})},s=i.prototype,a=function(c){Object.defineProperty(s,c,{get:function(){return this._anchorElement[c]},set:function(f){this._anchorElement[c]=f},enumerable:!0})};["hash","host","hostname","port","protocol"].forEach(function(c){a(c)}),Object.defineProperty(s,"search",{get:function(){return this._anchorElement.search},set:function(c){this._anchorElement.search=c,this._updateSearchParams()},enumerable:!0}),Object.defineProperties(s,{toString:{get:function(){var c=this;return function(){return c.href}}},href:{get:function(){return this._anchorElement.href.replace(/\?$/,"")},set:function(c){this._anchorElement.href=c,this._updateSearchParams()},enumerable:!0},pathname:{get:function(){return this._anchorElement.pathname.replace(/(^\/?)/,"/")},set:function(c){this._anchorElement.pathname=c},enumerable:!0},origin:{get:function(){var c={"http:":80,"https:":443,"ftp:":21}[this._anchorElement.protocol],f=this._anchorElement.port!=c&&this._anchorElement.port!=="";return this._anchorElement.protocol+"//"+this._anchorElement.hostname+(f?":"+this._anchorElement.port:"")},enumerable:!0},password:{get:function(){return""},set:function(c){},enumerable:!0},username:{get:function(){return""},set:function(c){},enumerable:!0}}),i.createObjectURL=function(c){return o.createObjectURL.apply(o,arguments)},i.revokeObjectURL=function(c){return o.revokeObjectURL.apply(o,arguments)},e.URL=i};if(t()||r(),e.location!==void 0&&!("origin"in e.location)){var n=function(){return e.location.protocol+"//"+e.location.hostname+(e.location.port?":"+e.location.port:"")};try{Object.defineProperty(e.location,"origin",{get:n,enumerable:!0})}catch(o){setInterval(function(){e.location.origin=n()},100)}}})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Er)});var Kr=Pt((Mt,qr)=>{/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */(function(t,r){typeof Mt=="object"&&typeof qr=="object"?qr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Mt=="object"?Mt.ClipboardJS=r():t.ClipboardJS=r()})(Mt,function(){return function(){var e={686:function(n,o,i){"use strict";i.d(o,{default:function(){return Ci}});var s=i(279),a=i.n(s),c=i(370),f=i.n(c),u=i(817),p=i.n(u);function m(j){try{return document.execCommand(j)}catch(O){return!1}}var d=function(O){var E=p()(O);return m("cut"),E},h=d;function v(j){var O=document.documentElement.getAttribute("dir")==="rtl",E=document.createElement("textarea");E.style.fontSize="12pt",E.style.border="0",E.style.padding="0",E.style.margin="0",E.style.position="absolute",E.style[O?"right":"left"]="-9999px";var H=window.pageYOffset||document.documentElement.scrollTop;return E.style.top="".concat(H,"px"),E.setAttribute("readonly",""),E.value=j,E}var G=function(O,E){var H=v(O);E.container.appendChild(H);var I=p()(H);return m("copy"),H.remove(),I},oe=function(O){var E=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},H="";return typeof O=="string"?H=G(O,E):O instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(O==null?void 0:O.type)?H=G(O.value,E):(H=p()(O),m("copy")),H},N=oe;function T(j){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?T=function(E){return typeof E}:T=function(E){return E&&typeof Symbol=="function"&&E.constructor===Symbol&&E!==Symbol.prototype?"symbol":typeof E},T(j)}var Qe=function(){var O=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},E=O.action,H=E===void 0?"copy":E,I=O.container,q=O.target,Me=O.text;if(H!=="copy"&&H!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(q!==void 0)if(q&&T(q)==="object"&&q.nodeType===1){if(H==="copy"&&q.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(H==="cut"&&(q.hasAttribute("readonly")||q.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(Me)return N(Me,{container:I});if(q)return H==="cut"?h(q):N(q,{container:I})},De=Qe;function $e(j){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?$e=function(E){return typeof E}:$e=function(E){return E&&typeof Symbol=="function"&&E.constructor===Symbol&&E!==Symbol.prototype?"symbol":typeof E},$e(j)}function wi(j,O){if(!(j instanceof O))throw new TypeError("Cannot call a class as a function")}function rn(j,O){for(var E=0;E0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof I.action=="function"?I.action:this.defaultAction,this.target=typeof I.target=="function"?I.target:this.defaultTarget,this.text=typeof I.text=="function"?I.text:this.defaultText,this.container=$e(I.container)==="object"?I.container:document.body}},{key:"listenClick",value:function(I){var q=this;this.listener=f()(I,"click",function(Me){return q.onClick(Me)})}},{key:"onClick",value:function(I){var q=I.delegateTarget||I.currentTarget,Me=this.action(q)||"copy",kt=De({action:Me,container:this.container,target:this.target(q),text:this.text(q)});this.emit(kt?"success":"error",{action:Me,text:kt,trigger:q,clearSelection:function(){q&&q.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(I){return vr("action",I)}},{key:"defaultTarget",value:function(I){var q=vr("target",I);if(q)return document.querySelector(q)}},{key:"defaultText",value:function(I){return vr("text",I)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(I){var q=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return N(I,q)}},{key:"cut",value:function(I){return h(I)}},{key:"isSupported",value:function(){var I=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],q=typeof I=="string"?[I]:I,Me=!!document.queryCommandSupported;return q.forEach(function(kt){Me=Me&&!!document.queryCommandSupported(kt)}),Me}}]),E}(a()),Ci=Ai},828:function(n){var o=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function s(a,c){for(;a&&a.nodeType!==o;){if(typeof a.matches=="function"&&a.matches(c))return a;a=a.parentNode}}n.exports=s},438:function(n,o,i){var s=i(828);function a(u,p,m,d,h){var v=f.apply(this,arguments);return u.addEventListener(m,v,h),{destroy:function(){u.removeEventListener(m,v,h)}}}function c(u,p,m,d,h){return typeof u.addEventListener=="function"?a.apply(null,arguments):typeof m=="function"?a.bind(null,document).apply(null,arguments):(typeof u=="string"&&(u=document.querySelectorAll(u)),Array.prototype.map.call(u,function(v){return a(v,p,m,d,h)}))}function f(u,p,m,d){return function(h){h.delegateTarget=s(h.target,p),h.delegateTarget&&d.call(u,h)}}n.exports=c},879:function(n,o){o.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},o.nodeList=function(i){var s=Object.prototype.toString.call(i);return i!==void 0&&(s==="[object NodeList]"||s==="[object HTMLCollection]")&&"length"in i&&(i.length===0||o.node(i[0]))},o.string=function(i){return typeof i=="string"||i instanceof String},o.fn=function(i){var s=Object.prototype.toString.call(i);return s==="[object Function]"}},370:function(n,o,i){var s=i(879),a=i(438);function c(m,d,h){if(!m&&!d&&!h)throw new Error("Missing required arguments");if(!s.string(d))throw new TypeError("Second argument must be a String");if(!s.fn(h))throw new TypeError("Third argument must be a Function");if(s.node(m))return f(m,d,h);if(s.nodeList(m))return u(m,d,h);if(s.string(m))return p(m,d,h);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function f(m,d,h){return m.addEventListener(d,h),{destroy:function(){m.removeEventListener(d,h)}}}function u(m,d,h){return Array.prototype.forEach.call(m,function(v){v.addEventListener(d,h)}),{destroy:function(){Array.prototype.forEach.call(m,function(v){v.removeEventListener(d,h)})}}}function p(m,d,h){return a(document.body,m,d,h)}n.exports=c},817:function(n){function o(i){var s;if(i.nodeName==="SELECT")i.focus(),s=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var a=i.hasAttribute("readonly");a||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),a||i.removeAttribute("readonly"),s=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var c=window.getSelection(),f=document.createRange();f.selectNodeContents(i),c.removeAllRanges(),c.addRange(f),s=c.toString()}return s}n.exports=o},279:function(n){function o(){}o.prototype={on:function(i,s,a){var c=this.e||(this.e={});return(c[i]||(c[i]=[])).push({fn:s,ctx:a}),this},once:function(i,s,a){var c=this;function f(){c.off(i,f),s.apply(a,arguments)}return f._=s,this.on(i,f,a)},emit:function(i){var s=[].slice.call(arguments,1),a=((this.e||(this.e={}))[i]||[]).slice(),c=0,f=a.length;for(c;c{"use strict";/*! + * escape-html + * Copyright(c) 2012-2013 TJ Holowaychuk + * Copyright(c) 2015 Andreas Lubbe + * Copyright(c) 2015 Tiancheng "Timothy" Gu + * MIT Licensed + */var ns=/["'&<>]/;Go.exports=os;function os(e){var t=""+e,r=ns.exec(t);if(!r)return t;var n,o="",i=0,s=0;for(i=r.index;i0&&i[i.length-1])&&(f[0]===6||f[0]===2)){r=0;continue}if(f[0]===3&&(!i||f[1]>i[0]&&f[1]=e.length&&(e=void 0),{value:e&&e[n++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function W(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var n=r.call(e),o,i=[],s;try{for(;(t===void 0||t-- >0)&&!(o=n.next()).done;)i.push(o.value)}catch(a){s={error:a}}finally{try{o&&!o.done&&(r=n.return)&&r.call(n)}finally{if(s)throw s.error}}return i}function D(e,t,r){if(r||arguments.length===2)for(var n=0,o=t.length,i;n1||a(m,d)})})}function a(m,d){try{c(n[m](d))}catch(h){p(i[0][3],h)}}function c(m){m.value instanceof et?Promise.resolve(m.value.v).then(f,u):p(i[0][2],m)}function f(m){a("next",m)}function u(m){a("throw",m)}function p(m,d){m(d),i.shift(),i.length&&a(i[0][0],i[0][1])}}function ln(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof Ee=="function"?Ee(e):e[Symbol.iterator](),r={},n("next"),n("throw"),n("return"),r[Symbol.asyncIterator]=function(){return this},r);function n(i){r[i]=e[i]&&function(s){return new Promise(function(a,c){s=e[i](s),o(a,c,s.done,s.value)})}}function o(i,s,a,c){Promise.resolve(c).then(function(f){i({value:f,done:a})},s)}}function C(e){return typeof e=="function"}function at(e){var t=function(n){Error.call(n),n.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var It=at(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: +`+r.map(function(n,o){return o+1+") "+n.toString()}).join(` + `):"",this.name="UnsubscriptionError",this.errors=r}});function Ve(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Ie=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,n,o,i;if(!this.closed){this.closed=!0;var s=this._parentage;if(s)if(this._parentage=null,Array.isArray(s))try{for(var a=Ee(s),c=a.next();!c.done;c=a.next()){var f=c.value;f.remove(this)}}catch(v){t={error:v}}finally{try{c&&!c.done&&(r=a.return)&&r.call(a)}finally{if(t)throw t.error}}else s.remove(this);var u=this.initialTeardown;if(C(u))try{u()}catch(v){i=v instanceof It?v.errors:[v]}var p=this._finalizers;if(p){this._finalizers=null;try{for(var m=Ee(p),d=m.next();!d.done;d=m.next()){var h=d.value;try{mn(h)}catch(v){i=i!=null?i:[],v instanceof It?i=D(D([],W(i)),W(v.errors)):i.push(v)}}}catch(v){n={error:v}}finally{try{d&&!d.done&&(o=m.return)&&o.call(m)}finally{if(n)throw n.error}}}if(i)throw new It(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)mn(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&Ve(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&Ve(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Sr=Ie.EMPTY;function jt(e){return e instanceof Ie||e&&"closed"in e&&C(e.remove)&&C(e.add)&&C(e.unsubscribe)}function mn(e){C(e)?e():e.unsubscribe()}var Le={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var st={setTimeout:function(e,t){for(var r=[],n=2;n0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var n=this,o=this,i=o.hasError,s=o.isStopped,a=o.observers;return i||s?Sr:(this.currentObservers=null,a.push(r),new Ie(function(){n.currentObservers=null,Ve(a,r)}))},t.prototype._checkFinalizedStatuses=function(r){var n=this,o=n.hasError,i=n.thrownError,s=n.isStopped;o?r.error(i):s&&r.complete()},t.prototype.asObservable=function(){var r=new F;return r.source=this,r},t.create=function(r,n){return new En(r,n)},t}(F);var En=function(e){ie(t,e);function t(r,n){var o=e.call(this)||this;return o.destination=r,o.source=n,o}return t.prototype.next=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.next)===null||o===void 0||o.call(n,r)},t.prototype.error=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.error)===null||o===void 0||o.call(n,r)},t.prototype.complete=function(){var r,n;(n=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||n===void 0||n.call(r)},t.prototype._subscribe=function(r){var n,o;return(o=(n=this.source)===null||n===void 0?void 0:n.subscribe(r))!==null&&o!==void 0?o:Sr},t}(x);var Et={now:function(){return(Et.delegate||Date).now()},delegate:void 0};var wt=function(e){ie(t,e);function t(r,n,o){r===void 0&&(r=1/0),n===void 0&&(n=1/0),o===void 0&&(o=Et);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=n,i._timestampProvider=o,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=n===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,n),i}return t.prototype.next=function(r){var n=this,o=n.isStopped,i=n._buffer,s=n._infiniteTimeWindow,a=n._timestampProvider,c=n._windowTime;o||(i.push(r),!s&&i.push(a.now()+c)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var n=this._innerSubscribe(r),o=this,i=o._infiniteTimeWindow,s=o._buffer,a=s.slice(),c=0;c0?e.prototype.requestAsyncId.call(this,r,n,o):(r.actions.push(this),r._scheduled||(r._scheduled=ut.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,n,o){var i;if(o===void 0&&(o=0),o!=null?o>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,n,o);var s=r.actions;n!=null&&((i=s[s.length-1])===null||i===void 0?void 0:i.id)!==n&&(ut.cancelAnimationFrame(n),r._scheduled=void 0)},t}(Wt);var Tn=function(e){ie(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var n=this._scheduled;this._scheduled=void 0;var o=this.actions,i;r=r||o.shift();do if(i=r.execute(r.state,r.delay))break;while((r=o[0])&&r.id===n&&o.shift());if(this._active=!1,i){for(;(r=o[0])&&r.id===n&&o.shift();)r.unsubscribe();throw i}},t}(Dt);var Te=new Tn(Sn);var _=new F(function(e){return e.complete()});function Vt(e){return e&&C(e.schedule)}function Cr(e){return e[e.length-1]}function Ye(e){return C(Cr(e))?e.pop():void 0}function Oe(e){return Vt(Cr(e))?e.pop():void 0}function zt(e,t){return typeof Cr(e)=="number"?e.pop():t}var pt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function Nt(e){return C(e==null?void 0:e.then)}function qt(e){return C(e[ft])}function Kt(e){return Symbol.asyncIterator&&C(e==null?void 0:e[Symbol.asyncIterator])}function Qt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function Ni(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var Yt=Ni();function Gt(e){return C(e==null?void 0:e[Yt])}function Bt(e){return pn(this,arguments,function(){var r,n,o,i;return $t(this,function(s){switch(s.label){case 0:r=e.getReader(),s.label=1;case 1:s.trys.push([1,,9,10]),s.label=2;case 2:return[4,et(r.read())];case 3:return n=s.sent(),o=n.value,i=n.done,i?[4,et(void 0)]:[3,5];case 4:return[2,s.sent()];case 5:return[4,et(o)];case 6:return[4,s.sent()];case 7:return s.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function Jt(e){return C(e==null?void 0:e.getReader)}function U(e){if(e instanceof F)return e;if(e!=null){if(qt(e))return qi(e);if(pt(e))return Ki(e);if(Nt(e))return Qi(e);if(Kt(e))return On(e);if(Gt(e))return Yi(e);if(Jt(e))return Gi(e)}throw Qt(e)}function qi(e){return new F(function(t){var r=e[ft]();if(C(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function Ki(e){return new F(function(t){for(var r=0;r=2;return function(n){return n.pipe(e?A(function(o,i){return e(o,i,n)}):de,ge(1),r?He(t):Vn(function(){return new Zt}))}}function zn(){for(var e=[],t=0;t=2,!0))}function pe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new x}:t,n=e.resetOnError,o=n===void 0?!0:n,i=e.resetOnComplete,s=i===void 0?!0:i,a=e.resetOnRefCountZero,c=a===void 0?!0:a;return function(f){var u,p,m,d=0,h=!1,v=!1,G=function(){p==null||p.unsubscribe(),p=void 0},oe=function(){G(),u=m=void 0,h=v=!1},N=function(){var T=u;oe(),T==null||T.unsubscribe()};return y(function(T,Qe){d++,!v&&!h&&G();var De=m=m!=null?m:r();Qe.add(function(){d--,d===0&&!v&&!h&&(p=$r(N,c))}),De.subscribe(Qe),!u&&d>0&&(u=new rt({next:function($e){return De.next($e)},error:function($e){v=!0,G(),p=$r(oe,o,$e),De.error($e)},complete:function(){h=!0,G(),p=$r(oe,s),De.complete()}}),U(T).subscribe(u))})(f)}}function $r(e,t){for(var r=[],n=2;ne.next(document)),e}function K(e,t=document){return Array.from(t.querySelectorAll(e))}function z(e,t=document){let r=ce(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function ce(e,t=document){return t.querySelector(e)||void 0}function _e(){return document.activeElement instanceof HTMLElement&&document.activeElement||void 0}function tr(e){return L(b(document.body,"focusin"),b(document.body,"focusout")).pipe(ke(1),l(()=>{let t=_e();return typeof t!="undefined"?e.contains(t):!1}),V(e===_e()),B())}function Xe(e){return{x:e.offsetLeft,y:e.offsetTop}}function Qn(e){return L(b(window,"load"),b(window,"resize")).pipe(Ce(0,Te),l(()=>Xe(e)),V(Xe(e)))}function rr(e){return{x:e.scrollLeft,y:e.scrollTop}}function dt(e){return L(b(e,"scroll"),b(window,"resize")).pipe(Ce(0,Te),l(()=>rr(e)),V(rr(e)))}var Gn=function(){if(typeof Map!="undefined")return Map;function e(t,r){var n=-1;return t.some(function(o,i){return o[0]===r?(n=i,!0):!1}),n}return function(){function t(){this.__entries__=[]}return Object.defineProperty(t.prototype,"size",{get:function(){return this.__entries__.length},enumerable:!0,configurable:!0}),t.prototype.get=function(r){var n=e(this.__entries__,r),o=this.__entries__[n];return o&&o[1]},t.prototype.set=function(r,n){var o=e(this.__entries__,r);~o?this.__entries__[o][1]=n:this.__entries__.push([r,n])},t.prototype.delete=function(r){var n=this.__entries__,o=e(n,r);~o&&n.splice(o,1)},t.prototype.has=function(r){return!!~e(this.__entries__,r)},t.prototype.clear=function(){this.__entries__.splice(0)},t.prototype.forEach=function(r,n){n===void 0&&(n=null);for(var o=0,i=this.__entries__;o0},e.prototype.connect_=function(){!Dr||this.connected_||(document.addEventListener("transitionend",this.onTransitionEnd_),window.addEventListener("resize",this.refresh),ga?(this.mutationsObserver_=new MutationObserver(this.refresh),this.mutationsObserver_.observe(document,{attributes:!0,childList:!0,characterData:!0,subtree:!0})):(document.addEventListener("DOMSubtreeModified",this.refresh),this.mutationEventsAdded_=!0),this.connected_=!0)},e.prototype.disconnect_=function(){!Dr||!this.connected_||(document.removeEventListener("transitionend",this.onTransitionEnd_),window.removeEventListener("resize",this.refresh),this.mutationsObserver_&&this.mutationsObserver_.disconnect(),this.mutationEventsAdded_&&document.removeEventListener("DOMSubtreeModified",this.refresh),this.mutationsObserver_=null,this.mutationEventsAdded_=!1,this.connected_=!1)},e.prototype.onTransitionEnd_=function(t){var r=t.propertyName,n=r===void 0?"":r,o=va.some(function(i){return!!~n.indexOf(i)});o&&this.refresh()},e.getInstance=function(){return this.instance_||(this.instance_=new e),this.instance_},e.instance_=null,e}(),Bn=function(e,t){for(var r=0,n=Object.keys(t);r0},e}(),Xn=typeof WeakMap!="undefined"?new WeakMap:new Gn,Zn=function(){function e(t){if(!(this instanceof e))throw new TypeError("Cannot call a class as a function.");if(!arguments.length)throw new TypeError("1 argument required, but only 0 present.");var r=ya.getInstance(),n=new Aa(t,r,this);Xn.set(this,n)}return e}();["observe","unobserve","disconnect"].forEach(function(e){Zn.prototype[e]=function(){var t;return(t=Xn.get(this))[e].apply(t,arguments)}});var Ca=function(){return typeof nr.ResizeObserver!="undefined"?nr.ResizeObserver:Zn}(),eo=Ca;var to=new x,Ra=$(()=>k(new eo(e=>{for(let t of e)to.next(t)}))).pipe(g(e=>L(ze,k(e)).pipe(R(()=>e.disconnect()))),J(1));function he(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ye(e){return Ra.pipe(S(t=>t.observe(e)),g(t=>to.pipe(A(({target:r})=>r===e),R(()=>t.unobserve(e)),l(()=>he(e)))),V(he(e)))}function bt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function ar(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}var ro=new x,ka=$(()=>k(new IntersectionObserver(e=>{for(let t of e)ro.next(t)},{threshold:0}))).pipe(g(e=>L(ze,k(e)).pipe(R(()=>e.disconnect()))),J(1));function sr(e){return ka.pipe(S(t=>t.observe(e)),g(t=>ro.pipe(A(({target:r})=>r===e),R(()=>t.unobserve(e)),l(({isIntersecting:r})=>r))))}function no(e,t=16){return dt(e).pipe(l(({y:r})=>{let n=he(e),o=bt(e);return r>=o.height-n.height-t}),B())}var cr={drawer:z("[data-md-toggle=drawer]"),search:z("[data-md-toggle=search]")};function oo(e){return cr[e].checked}function Ke(e,t){cr[e].checked!==t&&cr[e].click()}function Ue(e){let t=cr[e];return b(t,"change").pipe(l(()=>t.checked),V(t.checked))}function Ha(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Pa(){return L(b(window,"compositionstart").pipe(l(()=>!0)),b(window,"compositionend").pipe(l(()=>!1))).pipe(V(!1))}function io(){let e=b(window,"keydown").pipe(A(t=>!(t.metaKey||t.ctrlKey)),l(t=>({mode:oo("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),A(({mode:t,type:r})=>{if(t==="global"){let n=_e();if(typeof n!="undefined")return!Ha(n,r)}return!0}),pe());return Pa().pipe(g(t=>t?_:e))}function le(){return new URL(location.href)}function ot(e){location.href=e.href}function ao(){return new x}function so(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)so(e,r)}function M(e,t,...r){let n=document.createElement(e);if(t)for(let o of Object.keys(t))typeof t[o]!="undefined"&&(typeof t[o]!="boolean"?n.setAttribute(o,t[o]):n.setAttribute(o,""));for(let o of r)so(n,o);return n}function fr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function co(){return location.hash.substring(1)}function Vr(e){let t=M("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function $a(e){return L(b(window,"hashchange"),e).pipe(l(co),V(co()),A(t=>t.length>0),J(1))}function fo(e){return $a(e).pipe(l(t=>ce(`[id="${t}"]`)),A(t=>typeof t!="undefined"))}function zr(e){let t=matchMedia(e);return er(r=>t.addListener(()=>r(t.matches))).pipe(V(t.matches))}function uo(){let e=matchMedia("print");return L(b(window,"beforeprint").pipe(l(()=>!0)),b(window,"afterprint").pipe(l(()=>!1))).pipe(V(e.matches))}function Nr(e,t){return e.pipe(g(r=>r?t():_))}function ur(e,t={credentials:"same-origin"}){return ue(fetch(`${e}`,t)).pipe(fe(()=>_),g(r=>r.status!==200?Tt(()=>new Error(r.statusText)):k(r)))}function We(e,t){return ur(e,t).pipe(g(r=>r.json()),J(1))}function po(e,t){let r=new DOMParser;return ur(e,t).pipe(g(n=>n.text()),l(n=>r.parseFromString(n,"text/xml")),J(1))}function pr(e){let t=M("script",{src:e});return $(()=>(document.head.appendChild(t),L(b(t,"load"),b(t,"error").pipe(g(()=>Tt(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(l(()=>{}),R(()=>document.head.removeChild(t)),ge(1))))}function lo(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function mo(){return L(b(window,"scroll",{passive:!0}),b(window,"resize",{passive:!0})).pipe(l(lo),V(lo()))}function ho(){return{width:innerWidth,height:innerHeight}}function bo(){return b(window,"resize",{passive:!0}).pipe(l(ho),V(ho()))}function vo(){return Q([mo(),bo()]).pipe(l(([e,t])=>({offset:e,size:t})),J(1))}function lr(e,{viewport$:t,header$:r}){let n=t.pipe(Z("size")),o=Q([n,r]).pipe(l(()=>Xe(e)));return Q([r,t,o]).pipe(l(([{height:i},{offset:s,size:a},{x:c,y:f}])=>({offset:{x:s.x-c,y:s.y-f+i},size:a})))}(()=>{function e(n,o){parent.postMessage(n,o||"*")}function t(...n){return n.reduce((o,i)=>o.then(()=>new Promise(s=>{let a=document.createElement("script");a.src=i,a.onload=s,document.body.appendChild(a)})),Promise.resolve())}var r=class extends EventTarget{constructor(n){super(),this.url=n,this.m=i=>{i.source===this.w&&(this.dispatchEvent(new MessageEvent("message",{data:i.data})),this.onmessage&&this.onmessage(i))},this.e=(i,s,a,c,f)=>{if(s===`${this.url}`){let u=new ErrorEvent("error",{message:i,filename:s,lineno:a,colno:c,error:f});this.dispatchEvent(u),this.onerror&&this.onerror(u)}};let o=document.createElement("iframe");o.hidden=!0,document.body.appendChild(this.iframe=o),this.w.document.open(),this.w.document.write(` + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

LDAP Authentication

+ +

Introduction

+

Getting started with ldap and docker-mailserver we need to take 3 parts in account:

+
    +
  • postfix for incoming & outgoing email
    • +
  • dovecot for accessing mailboxes
    • +
  • saslauthd for SMTP authentication (this can also be delegated to dovecot)
    • +
+

Variables to Control Provisioning by the Container

+

Have a look at the ENV page for information on the default values.

+

LDAP_QUERY_FILTER_*

+

Those variables contain the LDAP lookup filters for postfix, using %s as the placeholder for the domain or email address in question. This means that...

+
    +
  • ...for incoming email, the domain must return an entry for the DOMAIN filter (see virtual_alias_domains).
    • +
  • ...for incoming email, the inboxes which receive the email are chosen by the USER, ALIAS and GROUP filters.
      +
    • The USER filter specifies personal mailboxes, for which only one should exist per address, for example (mail=%s) (also see virtual_mailbox_maps)
      • +
    • The ALIAS filter specifies aliases for mailboxes, using virtual_alias_maps, for example (mailAlias=%s)
      • +
    • The GROUP filter specifies the personal mailboxes in a group (for emails that multiple people shall receive), using virtual_alias_maps, for example (mailGroupMember=%s).
      • +
    • Technically, there is no difference between ALIAS and GROUP, but ideally you should use ALIAS for personal aliases for a singular person (like ceo@example.org) and GROUP for multiple people (like hr@example.org).
      • +
    +
    • +
  • ...for outgoing email, the sender address is put through the SENDERS filter, and only if the authenticated user is one of the returned entries, the email can be sent.
      +
    • This only applies if SPOOF_PROTECTION=1.
      • +
    • If the SENDERS filter is missing, the USER, ALIAS and GROUP filters will be used in in a disjunction (OR).
      • +
    • To for example allow users from the admin group to spoof any sender email address, and to force everyone else to only use their personal mailbox address for outgoing email, you can use something like this: (|(memberOf=cn=admin,*)(mail=%s))
      • +
    +
    • +
+
+Example +

A really simple LDAP_QUERY_FILTER configuration, using only the user filter and allowing only admin@* to spoof any sender addresses.

+
- ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+- LDAP_START_TLS=yes
+- ACCOUNT_PROVISIONER=LDAP
+- LDAP_SERVER_HOST=ldap.example.org
+- LDAP_SEARCH_BASE=dc=example,dc=org"
+- LDAP_BIND_DN=cn=admin,dc=example,dc=org
+- LDAP_BIND_PW=mypassword
+- SPOOF_PROTECTION=1
+
+- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)
+- LDAP_QUERY_FILTER_USER=(mail=%s)
+- LDAP_QUERY_FILTER_ALIAS=(|) # doesn't match anything
+- LDAP_QUERY_FILTER_GROUP=(|) # doesn't match anything
+- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(mail=admin@*))
+
+
+

DOVECOT_*_FILTER & DOVECOT_*_ATTRS

+

These variables specify the LDAP filters that dovecot uses to determine if a user can log in to their IMAP account, and which mailbox is responsible to receive email for a specific postfix user.

+

This is split into the following two lookups, both using %u as the placeholder for the full login name (see dovecot documentation for a full list of placeholders). Usually you only need to set DOVECOT_USER_FILTER, in which case it will be used for both filters.

+
    +
  • DOVECOT_USER_FILTER is used to get the account details (uid, gid, home directory, quota, ...) of a user.
    • +
  • DOVECOT_PASS_FILTER is used to get the password information of the user, and is in pretty much all cases identical to DOVECOT_USER_FILTER (which is the default behaviour if left away).
    • +
+

If your directory doesn't have the postfix-book schema installed, then you must change the internal attribute handling for dovecot. For this you have to change the pass_attr and the user_attr mapping, as shown in the example below:

+
- DOVECOT_PASS_ATTRS=<YOUR_USER_IDENTIFIER_ATTRIBUTE>=user,<YOUR_USER_PASSWORD_ATTRIBUTE>=password
+- DOVECOT_USER_ATTRS=<YOUR_USER_HOME_DIRECTORY_ATTRIBUTE>=home,<YOUR_USER_MAILSTORE_ATTRIBUTE>=mail,<YOUR_USER_MAIL_UID_ATTRIBUTE>=uid,<YOUR_USER_MAIL_GID_ATTRIBUTE>=gid
+
+
+

Note

+

For DOVECOT_*_ATTRS, you can replace ldapAttr=dovecotAttr with =dovecotAttr=%{ldap:ldapAttr} for more flexibility, like for example =home=/var/mail/%{ldap:uid} or just =uid=5000.

+

A list of dovecot attributes can be found in the dovecot documentation.

+
+
+Defaults +
- DOVECOT_USER_ATTRS=mailHomeDirectory=home,mailUidNumber=uid,mailGidNumber=gid,mailStorageDirectory=mail
+- DOVECOT_PASS_ATTRS=uniqueIdentifier=user,userPassword=password
+- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
+
+
+
+Example +

Setup for a directory that has the qmail-schema installed and uses uid:

+
- DOVECOT_PASS_ATTRS=uid=user,userPassword=password
+- DOVECOT_USER_ATTRS=homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail
+- DOVECOT_USER_FILTER=(&(objectClass=qmailUser)(uid=%u)(accountStatus=active))
+
+
+

The LDAP server configuration for dovecot will be taken mostly from postfix, other options can be found in the environment section in the docs.

+

DOVECOT_AUTH_BIND

+

Set this to yes to enable authentication binds (more details in the dovecot documentation). Currently, only DN lookup is supported without further changes to the configuration files, so this is only useful when you want to bind as a readonly user without the permission to read passwords.

+

SASLAUTHD_LDAP_FILTER

+

This filter is used for saslauthd, which is called by postfix when someone is authenticating through SMTP (assuming that SASLAUTHD_MECHANISMS=ldap is being used). Note that you'll need to set up the LDAP server for saslauthd separately from postfix.

+

The filter variables are explained in detail in the LDAP_SASLAUTHD file, but unfortunately, this method doesn't really support domains right now - that means that %U is the only token that makes sense in this variable.

+
+

When to use this and how to avoid it

+

Using a separate filter for SMTP authentication allows you to for example allow noreply@example.org to send email, but not log in to IMAP or receive email: (&(mail=%U@example.org)(|(memberOf=cn=email,*)(mail=noreply@example.org)))

+

If you don't want to use a separate filter for SMTP authentication, you can set SASLAUTHD_MECHANISMS=rimap and SASLAUTHD_MECH_OPTIONS=127.0.0.1 to authenticate against dovecot instead - this means that the DOVECOT_USER_FILTER and DOVECOT_PASS_FILTER will be used for SMTP authentication as well.

+
+
+Configure LDAP with saslauthd +
- ENABLE_SASLAUTHD=1
+- SASLAUTHD_MECHANISMS=ldap
+- SASLAUTHD_LDAP_FILTER=(mail=%U@example.org)
+
+
+

Secure Connection with LDAPS or StartTLS

+

To enable LDAPS, all you need to do is to add the protocol to LDAP_SERVER_HOST, for example ldaps://example.org:636.

+

To enable LDAP over StartTLS (on port 389), you need to set the following environment variables instead (the protocol must not be ldaps:// in this case!):

+
- LDAP_START_TLS=yes
+- DOVECOT_TLS=yes
+- SASLAUTHD_LDAP_START_TLS=yes
+
+

Active Directory Configurations (Tested with Samba4 AD Implementation)

+

In addition to LDAP explanation above, when Docker Mailserver is intended to be used with Active Directory (or the equivalent implementations like Samba4 AD DC) the following points should be taken into consideration:

+
    +
  • Samba4 Active Directory requires a secure connection to the domain controller (DC), either via SSL/TLS (LDAPS) or via StartTLS.
    • +
  • The username equivalent in Active Directory is: sAMAccountName.
    • +
  • proxyAddresses can be used to store email aliases of single users. The convention is to prefix the email aliases with smtp: (e.g: smtp:some.name@example.com).
    • +
  • Active Directory is used typically not only as LDAP Directory storage, but also as a domain controller, i.e., it will do many things including authenticating users. Mixing Linux and Windows clients requires the usage of RFC2307 attributes, namely uidNumber, gidNumber instead of the typical uid. Assigning different owner to email folders can also be done in this approach, nevertheless there is a bug at the moment in Docker Mailserver that overwrites all permissions when starting the container. Either a manual fix is necessary now, or a temporary workaround to use a hard-coded ldap:uidNumber that equals to 5000 until this issue is fixed.
    • +
  • To deliver the emails to different members of Active Directory Security Group or Distribution Group (similar to mailing lists), use a user-patches.sh script to modify ldap-groups.cf so that it includes leaf_result_attribute = mail and special_result_attribute = member. This can be achieved simply by:
    • +
+

The configuration shown to get the Group to work is from here and here.

+
# user-patches.sh
+
+...
+grep -q '^leaf_result_attribute = mail$' /etc/postfix/ldap-groups.cf || echo "leaf_result_attribute = mail" >> /etc/postfix/ldap-groups.cf
+grep -q '^special_result_attribute = member$' /etc/postfix/ldap-groups.cf || echo "special_result_attribute = member" >> /etc/postfix/ldap-groups.cf
+...
+
+
    +
  • In /etc/ldap/ldap.conf, if the TLS_REQCERT is demand / hard (default), the CA certificate used to verify the LDAP server certificate must be recognized as a trusted CA. This can be done by volume mounting the ca.crt file and updating the trust store via a user-patches.sh script:
    • +
+
# user-patches.sh
+
+...
+cp /MOUNTED_FOLDER/ca.crt /usr/local/share/ca-certificates/
+update-ca-certificates
+...
+
+

The changes on the configurations necessary to work with Active Directory (only changes are listed, the rest of the LDAP configuration can be taken from the other examples shown in this documentation):

+
# If StartTLS is the chosen method to establish a secure connection with Active Directory.
+- LDAP_START_TLS=yes
+- SASLAUTHD_LDAP_START_TLS=yes
+- DOVECOT_TLS=yes
+
+- LDAP_QUERY_FILTER_USER=(&(objectclass=person)(mail=%s))
+- LDAP_QUERY_FILTER_ALIAS=(&(objectclass=person)(proxyAddresses=smtp:%s))
+# Filters Active Directory groups (mail lists). Additional changes on ldap-groups.cf are also required as shown above.
+- LDAP_QUERY_FILTER_GROUP=(&(objectClass=group)(mail=%s))
+- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)
+# Allows only Domain admins to send any sender email address, otherwise the sender address must match the LDAP attribute `mail`.
+- SPOOF_PROTECTION=1
+- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(proxyAddresses=smtp:%s)(memberOf=cn=Domain Admins,cn=Users,dc=*))
+
+- DOVECOT_USER_FILTER=(&(objectclass=person)(sAMAccountName=%n))
+# At the moment to be able to use %{ldap:uidNumber}, a manual bug fix as described above must be used. Otherwise %{ldap:uidNumber} %{ldap:uidNumber} must be replaced by the hard-coded value 5000.
+- DOVECOT_USER_ATTRS==uid=%{ldap:uidNumber},=gid=5000,=home=/var/mail/%Ln,=mail=maildir:~/Maildir
+- DOVECOT_PASS_ATTRS=sAMAccountName=user,userPassword=password
+- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))
+
+

LDAP Setup Examples

+
+Basic Setup +
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    container_name: mailserver
+    hostname: mail.example.com
+
+    ports:
+      - "25:25"
+      - "143:143"
+      - "587:587"
+      - "993:993"
+
+    volumes:
+      - ./docker-data/dms/mail-data/:/var/mail/
+      - ./docker-data/dms/mail-state/:/var/mail-state/
+      - ./docker-data/dms/mail-logs/:/var/log/mail/
+      - ./docker-data/dms/config/:/tmp/docker-mailserver/
+      - /etc/localtime:/etc/localtime:ro
+
+    environment:
+      - ENABLE_SPAMASSASSIN=1
+      - ENABLE_CLAMAV=1
+      - ENABLE_FAIL2BAN=1
+      - ENABLE_POSTGREY=1
+
+      # >>> Postfix LDAP Integration
+      - ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+      - ACCOUNT_PROVISIONER=LDAP
+      - LDAP_SERVER_HOST=ldap.example.org
+      - LDAP_BIND_DN=cn=admin,ou=users,dc=example,dc=org
+      - LDAP_BIND_PW=mypassword
+      - LDAP_SEARCH_BASE=dc=example,dc=org
+      - LDAP_QUERY_FILTER_DOMAIN=(|(mail=*@%s)(mailAlias=*@%s)(mailGroupMember=*@%s))
+      - LDAP_QUERY_FILTER_USER=(&(objectClass=inetOrgPerson)(mail=%s))
+      - LDAP_QUERY_FILTER_ALIAS=(&(objectClass=inetOrgPerson)(mailAlias=%s))
+      - LDAP_QUERY_FILTER_GROUP=(&(objectClass=inetOrgPerson)(mailGroupMember=%s))
+      - LDAP_QUERY_FILTER_SENDERS=(&(objectClass=inetOrgPerson)(|(mail=%s)(mailAlias=%s)(mailGroupMember=%s)))
+      - SPOOF_PROTECTION=1
+      # <<< Postfix LDAP Integration
+
+      # >>> Dovecot LDAP Integration
+      - DOVECOT_USER_FILTER=(&(objectClass=inetOrgPerson)(mail=%u))
+      - DOVECOT_PASS_ATTRS=uid=user,userPassword=password
+      - DOVECOT_USER_ATTRS==home=/var/mail/%{ldap:uid},=mail=maildir:~/Maildir,uidNumber=uid,gidNumber=gid
+      # <<< Dovecot LDAP Integration
+
+      # >>> SASL LDAP Authentication
+      - ENABLE_SASLAUTHD=1
+      - SASLAUTHD_MECHANISMS=ldap
+      - SASLAUTHD_LDAP_FILTER=(&(mail=%U@example.org)(objectClass=inetOrgPerson))
+      # <<< SASL LDAP Authentication
+
+      - SSL_TYPE=letsencrypt
+      - PERMIT_DOCKER=host
+
+    cap_add:
+      - NET_ADMIN
+
+
+
+Kopano / Zarafa +
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    container_name: mailserver
+    hostname: mail.example.com
+
+    ports:
+      - "25:25"
+      - "143:143"
+      - "587:587"
+      - "993:993"
+
+    volumes:
+      - ./docker-data/dms/mail-data/:/var/mail/
+      - ./docker-data/dms/mail-state/:/var/mail-state/
+      - ./docker-data/dms/config/:/tmp/docker-mailserver/
+
+    environment:
+      # We are not using dovecot here
+      - SMTP_ONLY=1
+      - ENABLE_SPAMASSASSIN=1
+      - ENABLE_CLAMAV=1
+      - ENABLE_FAIL2BAN=1
+      - ENABLE_POSTGREY=1
+      - SASLAUTHD_PASSWD=
+
+      # >>> SASL Authentication
+      - ENABLE_SASLAUTHD=1
+      - SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))
+      - SASLAUTHD_MECHANISMS=ldap
+      # <<< SASL Authentication
+
+      # >>> Postfix Ldap Integration
+      - ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+      - ACCOUNT_PROVISIONER=LDAP
+      - LDAP_SERVER_HOST=<yourLdapContainer/yourLdapServer>
+      - LDAP_SEARCH_BASE=dc=mydomain,dc=loc
+      - LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=loc
+      - LDAP_BIND_PW=mypassword
+      - LDAP_QUERY_FILTER_USER=(&(objectClass=user)(mail=%s))
+      - LDAP_QUERY_FILTER_GROUP=(&(objectclass=group)(mail=%s))
+      - LDAP_QUERY_FILTER_ALIAS=(&(objectClass=user)(otherMailbox=%s))
+      - LDAP_QUERY_FILTER_DOMAIN=(&(|(mail=*@%s)(mailalias=*@%s)(mailGroupMember=*@%s))(mailEnabled=TRUE))
+      # <<< Postfix Ldap Integration
+
+      # >>> Kopano Integration
+      - POSTFIX_DAGENT=lmtp:kopano:2003
+      # <<< Kopano Integration
+
+      - SSL_TYPE=letsencrypt
+      - PERMIT_DOCKER=host
+
+    cap_add:
+      - NET_ADMIN
+
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/dovecot-master-accounts/index.html b/v12.0/config/advanced/dovecot-master-accounts/index.html new file mode 100644 index 00000000..0ffaa428 --- /dev/null +++ b/v12.0/config/advanced/dovecot-master-accounts/index.html @@ -0,0 +1,1578 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Dovecot master accounts - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Dovecot Master Accounts

+ +

Introduction

+

A dovecot master account is able to login as any configured user. This is useful for administrative tasks like hot backups.

+

Configuration

+

It is possible to create, update, delete and list dovecot master accounts using setup.sh. See setup.sh help for usage.

+

This feature is presently not supported with LDAP.

+

Logging in

+

Once a master account is configured, it is possible to connect to any users mailbox using this account. Log in over POP3/IMAP using the following credential scheme:

+

Username: <EMAIL ADDRESS>*<MASTER ACCOUNT NAME>

+

Password: <MASTER ACCOUNT PASSWORD>

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/full-text-search/index.html b/v12.0/config/advanced/full-text-search/index.html new file mode 100644 index 00000000..24209e55 --- /dev/null +++ b/v12.0/config/advanced/full-text-search/index.html @@ -0,0 +1,1806 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Full-Text Search - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Full-Text Search

+ +

Overview

+

Full-text search allows all messages to be indexed, so that mail clients can quickly and efficiently search messages by their full text content. Dovecot supports a variety of community supported FTS indexing backends.

+

docker-mailserver comes pre-installed with two plugins that can be enabled with a dovecot config file.

+

Please be aware that indexing consumes memory and takes up additional disk space.

+

Xapian

+

The dovecot-fts-xapian plugin makes use of Xapian. Xapian enables embedding an FTS engine without the need for additional backends.

+

The indexes will be stored as a subfolder named xapian-indexes inside your local mail-data folder (/var/mail internally). With the default settings, 10GB of email data may generate around 4GB of indexed data.

+

While indexing is memory intensive, you can configure the plugin to limit the amount of memory consumed by the index workers. With Xapian being small and fast, this plugin is a good choice for low memory environments (2GB) as compared to Solr.

+

Setup

+
    +
  1. +

    To configure fts-xapian as a dovecot plugin, create a file at docker-data/dms/config/dovecot/fts-xapian-plugin.conf and place the following in it:

    +
    mail_plugins = $mail_plugins fts fts_xapian
+
+plugin {
+    fts = xapian
+    fts_xapian = partial=3 full=20 verbose=0
+
+    fts_autoindex = yes
+    fts_enforced = yes
+
+    # disable indexing of folders
+    # fts_autoindex_exclude = \Trash
+
+    # Index attachements
+    # fts_decoder = decode2text
+}
+
+service indexer-worker {
+    # limit size of indexer-worker RAM usage, ex: 512MB, 1GB, 2GB
+    vsz_limit = 1GB
+}
+
+# service decode2text {
+#     executable = script /usr/libexec/dovecot/decode2text.sh
+#     user = dovecot
+#     unix_listener decode2text {
+#         mode = 0666
+#     }
+# }
+
    +

    adjust the settings to tune for your desired memory limits, exclude folders and enable searching text inside of attachments

    +
    2. +
  2. +

    Update docker-compose.yml to load the previously created dovecot plugin config file:

    +
      services:
+    mailserver:
+      image: ghcr.io/docker-mailserver/docker-mailserver:latest
+      container_name: mailserver
+      hostname: mail.example.com
+      env_file: mailserver.env
+      ports:
+        - "25:25"    # SMTP  (explicit TLS => STARTTLS)
+        - "143:143"  # IMAP4 (explicit TLS => STARTTLS)
+        - "465:465"  # ESMTP (implicit TLS)
+        - "587:587"  # ESMTP (explicit TLS => STARTTLS)
+        - "993:993"  # IMAP4 (implicit TLS)
+      volumes:
+        - ./docker-data/dms/mail-data/:/var/mail/
+        - ./docker-data/dms/mail-state/:/var/mail-state/
+        - ./docker-data/dms/mail-logs/:/var/log/mail/
+        - ./docker-data/dms/config/:/tmp/docker-mailserver/
+        - ./docker-data/dms/config/dovecot/fts-xapian-plugin.conf:/etc/dovecot/conf.d/10-plugin.conf:ro
+        - /etc/localtime:/etc/localtime:ro
+      restart: always
+      stop_grace_period: 1m
+      cap_add:
+        - NET_ADMIN
+
    +
    3. +
  3. +

    Recreate containers:

    +
    docker-compose down
+docker-compose up -d
+
    +
    4. +
  4. +

    Initialize indexing on all users for all mail:

    +
    docker-compose exec mailserver doveadm index -A -q \*
+
    +
    5. +
  5. +

    Run the following command in a daily cron job:

    +

    docker-compose exec mailserver doveadm fts optimize -A
+
    +Or like the Spamassassin example shows, you can instead use cron from within docker-mailserver to avoid potential errors if the mail-server is not running:

    +
    6. +
+
+Example +

Create a system cron file:

+
# in the docker-compose.yml root directory
+mkdir -p ./docker-data/dms/cron # if you didn't have this folder before
+touch ./docker-data/dms/cron/fts_xapian
+chown root:root ./docker-data/dms/cron/fts_xapian
+chmod 0644 ./docker-data/dms/cron/fts_xapian
+
+

Edit the system cron file nano ./docker-data/dms/cron/fts_xapian, and set an appropriate configuration:

+
# Adding `MAILTO=""` prevents cron emailing notifications of the task outcome each run
+MAILTO=""
+#
+# m h dom mon dow user command
+#
+# Everyday 4:00AM, optimize index files
+0  4 * * * root  doveadm fts optimize -A
+
+

Then with docker-compose.yml:

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    volumes:
+      - ./docker-data/dms/cron/fts_xapian:/etc/cron.d/fts_xapian
+
+
+

Solr

+

The dovecot-solr Plugin is used in conjunction with Apache Solr running in a separate container. This is quite straightforward to setup using the following instructions.

+

Solr is a mature and fast indexing backend that runs on the JVM. The indexes are relatively compact compared to the size of your total email.

+

However, Solr also requires a fair bit of RAM. While Solr is highly tuneable, it may require a bit of testing to get it right.

+

Setup

+
    +
  1. +

    docker-compose.yml:

    +
      solr:
+    image: lmmdock/dovecot-solr:latest
+    volumes:
+      - ./docker-data/dms/config/dovecot/solr-dovecot:/opt/solr/server/solr/dovecot
+    restart: always
+
+  mailserver:
+    depends_on:
+      - solr
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    ...
+    volumes:
+      ...
+      - ./docker-data/dms/config/dovecot/10-plugin.conf:/etc/dovecot/conf.d/10-plugin.conf:ro
+    ...
+
    +
    2. +
  2. +

    ./docker-data/dms/config/dovecot/10-plugin.conf:

    +
    mail_plugins = $mail_plugins fts fts_solr
+
+plugin {
+  fts = solr
+  fts_autoindex = yes
+  fts_solr = url=http://solr:8983/solr/dovecot/
+}
+
    +
    3. +
  3. +

    Recreate containers: docker-compose down ; docker-compose up -d

    +
    4. +
  4. +

    Flag all user mailbox FTS indexes as invalid, so they are rescanned on demand when they are next searched: docker-compose exec mailserver doveadm fts rescan -A

    +
    5. +
+

Further Discussion

+

See #905

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/ipv6/index.html b/v12.0/config/advanced/ipv6/index.html new file mode 100644 index 00000000..dfa85ad0 --- /dev/null +++ b/v12.0/config/advanced/ipv6/index.html @@ -0,0 +1,1600 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | IPv6 - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

IPv6

+ +

Background

+

If your container host supports IPv6, then docker-mailserver will automatically accept IPv6 connections by way of the docker host's IPv6. However, incoming mail will fail SPF checks because they will appear to come from the IPv4 gateway that docker is using to proxy the IPv6 connection (172.20.0.1 is the gateway).

+

This can be solved by supporting IPv6 connections all the way to the docker-mailserver container.

+

Setup steps

+
+++ b/serv/docker-compose.yml
+@@ ... @@ services:
+
++  ipv6nat:
++    image: robbertkl/ipv6nat
++    restart: always
++    network_mode: "host"
++    cap_add:
++      - NET_ADMIN
++      - SYS_MODULE
++    volumes:
++      - /var/run/docker.sock:/var/run/docker.sock:ro
++      - /lib/modules:/lib/modules:ro
+
+@@ ... @@ networks:
+
++  default:
++    driver: bridge
++    enable_ipv6: true
++    ipam:
++      driver: default
++      config:
++        - subnet: fd00:0123:4567::/48
++          gateway: fd00:0123:4567::1
+
+

Further Discussion

+

See #1438

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/kubernetes/index.html b/v12.0/config/advanced/kubernetes/index.html new file mode 100644 index 00000000..637fe2fc --- /dev/null +++ b/v12.0/config/advanced/kubernetes/index.html @@ -0,0 +1,2221 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Kubernetes - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Kubernetes

+ +

Introduction

+

This article describes how to deploy docker-mailserver to Kubernetes. Please note that there is also a Helm chart available.

+
+

Requirements

+

We assume basic knowledge about Kubernetes from the reader. Moreover, we assume the reader to have a basic understanding of mail servers. Ideally, the reader has deployed docker-mailserver before in an easier setup with Docker (Compose).

+
+
+

About Support for Kubernetes

+

Please note that Kubernetes is not officially supported and we do not build images specifically designed for it. When opening an issue, please remember that only Docker & Docker Compose are officially supported.

+

This content is entirely community-supported. If you find errors, please open an issue and provide a PR.

+
+

Manifests

+

Configuration

+

We want to provide the basic configuration in the form of environment variables with a ConfigMap. Note that this is just an example configuration; tune the ConfigMap to your needs.

+
---
+apiVersion: v1
+kind: ConfigMap
+
+metadata:
+  name: mailserver.environment
+
+immutable: false
+
+data:
+  TLS_LEVEL: modern
+  POSTSCREEN_ACTION: drop
+  OVERRIDE_HOSTNAME: mail.example.com
+  FAIL2BAN_BLOCKTYPE: drop
+  POSTMASTER_ADDRESS: postmaster@example.com
+  UPDATE_CHECK_INTERVAL: 10d
+  POSTFIX_INET_PROTOCOLS: ipv4
+  ONE_DIR: '1'
+  ENABLE_CLAMAV: '1'
+  ENABLE_POSTGREY: '0'
+  ENABLE_FAIL2BAN: '1'
+  AMAVIS_LOGLEVEL: '-1'
+  SPOOF_PROTECTION: '1'
+  MOVE_SPAM_TO_JUNK: '1'
+  ENABLE_UPDATE_CHECK: '1'
+  ENABLE_SPAMASSASSIN: '1'
+  SUPERVISOR_LOGLEVEL: warn
+  SPAMASSASSIN_SPAM_TO_INBOX: '1'
+
+  # here, we provide an example for the SSL configuration
+  SSL_TYPE: manual
+  SSL_CERT_PATH: /secrets/ssl/rsa/tls.crt
+  SSL_KEY_PATH: /secrets/ssl/rsa/tls.key
+
+

We can also make use of user-provided configuration files, e.g. user-patches.sh, postfix-accounts.cf and more, to adjust docker-mailserver to our likings. We encourage you to have a look at Kustomize for creating ConfigMaps from multiple files, but for now, we will provide a simple, hand-written example. This example is absolutely minimal and only goes to show what can be done.

+
---
+apiVersion: v1
+kind: ConfigMap
+
+metadata:
+  name: mailserver.files
+
+data:
+  postfix-accounts.cf: |
+    test@example.com|{SHA512-CRYPT}$6$someHashValueHere
+    other@example.com|{SHA512-CRYPT}$6$someOtherHashValueHere
+
+
+

Static Configuration

+

With the configuration shown above, you can not dynamically add accounts as the configuration file mounted into the mail server can not be written to.

+

Use persistent volumes for production deployments.

+
+

Persistence

+

Thereafter, we need persistence for our data. Make sure you have a storage provisioner and that you choose the correct storageClassName.

+
---
+apiVersion: v1
+kind: PersistentVolumeClaim
+
+metadata:
+  name: data
+
+spec:
+  storageClassName: local-path
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 25Gi
+
+

Service

+

A Service is required for getting the traffic to the pod itself. The service is somewhat crucial. Its configuration determines whether the original IP from the sender will be kept. More about this further down below.

+

The configuration you're seeing does keep the original IP, but you will not be able to scale this way. We have chosen to go this route in this case because we think most Kubernetes users will only want to have one instance.

+
---
+apiVersion: v1
+kind: Service
+
+metadata:
+  name: mailserver
+  labels:
+    app: mailserver
+
+spec:
+  type: LoadBalancer
+
+  selector:
+    app: mailserver
+
+  ports:
+    # Transfer
+    - name: transfer
+      port: 25
+      targetPort: transfer
+      protocol: TCP
+    # ESMTP with implicit TLS
+    - name: esmtp-implicit
+      port: 465
+      targetPort: esmtp-implicit
+      protocol: TCP
+    # ESMTP with explicit TLS (STARTTLS)
+    - name: esmtp-explicit
+      port: 587
+      targetPort: esmtp-explicit
+      protocol: TCP
+    # IMAPS with implicit TLS
+    - name: imap-implicit
+      port: 993
+      targetPort: imap-implicit
+      protocol: TCP
+
+

Deployments

+

Last but not least, the Deployment becomes the most complex component. It instructs Kubernetes how to run the docker-mailserver container and how to apply your ConfigMaps, persisted storage, etc. Additionally, we can set options to enforce runtime security here.

+
---
+apiVersion: apps/v1
+kind: Deployment
+
+metadata:
+  name: mailserver
+
+  annotations:
+    ignore-check.kube-linter.io/run-as-non-root: >-
+      'mailserver' needs to run as root
+    ignore-check.kube-linter.io/privileged-ports: >-
+      'mailserver' needs privilegdes ports
+    ignore-check.kube-linter.io/no-read-only-root-fs: >-
+      There are too many files written to make The
+      root FS read-only
+
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: mailserver
+
+  template:
+    metadata:
+      labels:
+        app: mailserver
+
+      annotations:
+        container.apparmor.security.beta.kubernetes.io/mailserver: runtime/default
+
+    spec:
+      hostname: mail
+      containers:
+        - name: mailserver
+          image: ghcr.io/docker-mailserver/docker-mailserver:latest
+          imagePullPolicy: IfNotPresent
+
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: false
+            runAsUser: 0
+            runAsGroup: 0
+            runAsNonRoot: false
+            privileged: false
+            capabilities:
+              add:
+                # file permission capabilities
+                - CHOWN
+                - FOWNER
+                - MKNOD
+                - SETGID
+                - SETUID
+                - DAC_OVERRIDE
+                # network capabilities
+                - NET_ADMIN  # needed for F2B
+                - NET_RAW    # needed for F2B
+                - NET_BIND_SERVICE
+                # miscellaneous  capabilities
+                - SYS_CHROOT
+                - KILL
+              drop: [ALL]
+            seccompProfile:
+              type: RuntimeDefault
+
+          # You want to tune this to your needs. If you disable ClamAV,
+          #   you can use less RAM and CPU. This becomes important in
+          #   case you're low on resources and Kubernetes refuses to
+          #   schedule new pods.
+          resources:
+            limits:
+              memory: 4Gi
+              cpu: 1500m
+            requests:
+              memory: 2Gi
+              cpu: 600m
+
+          volumeMounts:
+            - name: files
+              subPath: postfix-accounts.cf
+              mountPath: /tmp/docker-mailserver/postfix-accounts.cf
+              readOnly: true
+
+            # PVCs
+            - name: data
+              mountPath: /var/mail
+              subPath: data
+              readOnly: false
+            - name: data
+              mountPath: /var/mail-state
+              subPath: state
+              readOnly: false
+            - name: data
+              mountPath: /var/log/mail
+              subPath: log
+              readOnly: false
+
+            # certificates
+            - name: certificates-rsa
+              mountPath: /secrets/ssl/rsa/
+              readOnly: true
+
+            # other
+            - name: tmp-files
+              mountPath: /tmp
+              readOnly: false
+
+          ports:
+            - name: transfer
+              containerPort: 25
+              protocol: TCP
+            - name: esmtp-implicit
+              containerPort: 465
+              protocol: TCP
+            - name: esmtp-explicit
+              containerPort: 587
+            - name: imap-implicit
+              containerPort: 993
+              protocol: TCP
+
+          envFrom:
+            - configMapRef:
+                name: mailserver.environment
+
+      restartPolicy: Always
+
+      volumes:
+        # configuration files
+        - name: files
+          configMap:
+            name: mailserver.files
+
+        # PVCs
+        - name: data
+          persistentVolumeClaim:
+            claimName: data
+
+        # certificates
+        - name: certificates-rsa
+          secret:
+            secretName: mail-tls-certificate-rsa
+            items:
+              - key: tls.key
+                path: tls.key
+              - key: tls.crt
+                path: tls.crt
+
+        # other
+        - name: tmp-files
+          emptyDir: {}
+
+

Certificates - An Example

+

In this example, we use cert-manager to supply RSA certificates. You can also supply RSA certificates as fallback certificates, which docker-mailserver supports out of the box with SSL_ALT_CERT_PATH and SSL_ALT_KEY_PATH, and provide ECDSA as the proper certificates.

+
---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+
+metadata:
+  name: mail-tls-certificate-rsa
+
+spec:
+  secretName: mail-tls-certificate-rsa
+  isCA: false
+  privateKey:
+    algorithm: RSA
+    encoding: PKCS1
+    size: 2048
+  dnsNames: [mail.example.com]
+  issuerRef:
+    name: mail-issuer
+    kind: Issuer
+
+
+

Attention

+

You will need to have cert-manager configured. Especially the issue will need to be configured. Since we do not know how you want or need your certificates to be supplied, we do not provide more configuration here. The documentation for cert-manager is excellent.

+
+

Sensitive Data

+
+

Sensitive Data

+

For storing OpenDKIM keys, TLS certificates or any sort of sensitive data, you should be using Secrets. You can mount secrets like ConfigMaps and use them the same way.

+
+

The TLS docs page provides guidance when it comes to certificates and transport layer security. Always provide sensitive information vai Secrets.

+

Exposing your Mail-Server to the Outside World

+

The more difficult part with Kubernetes is to expose a deployed docker-mailserver to the outside world. Kubernetes provides multiple ways for doing that; each has downsides and complexity. The major problem with exposing docker-mailserver to outside world in Kubernetes is to preserve the real client IP. The real client IP is required by docker-mailserver for performing IP-based SPF checks and spam checks. If you do not require SPF checks for incoming mails, you may disable them in your Postfix configuration by dropping the line that states: check_policy_service unix:private/policyd-spf.

+

The easiest approach was covered above, using externalTrafficPolicy: Local, which disables the service proxy, but makes the service local as well (which does not scale). This approach only works when you are given the correct (that is, a public and routable) IP address by a load balancer (like MetalLB). In this sense, the approach above is similar to the next example below. We want to provide you with a few alternatives too. But we also want to communicate the idea of another simple method: you could use a load-balancer without an external IP and DNAT the network traffic to the mail-server. After all, this does not interfere with SPF checks because it keeps the origin IP address. If no dedicated external IP address is available, you could try the latter approach, if one is available, use the former.

+

External IPs Service

+

The simplest way is to expose docker-mailserver as a Service with external IPs. This is very similar to the approach taken above. Here, an external IP is given to the service directly by you. With the approach above, you tell your load-balancer to do this.

+
---
+apiVersion: v1
+kind: Service
+
+metadata:
+  name: mailserver
+  labels:
+    app: mailserver
+
+spec:
+  selector:
+    app: mailserver
+  ports:
+    - name: smtp
+      port: 25
+      targetPort: smtp
+    # ...
+
+  externalIPs:
+    - 80.11.12.10
+
+

This approach

+
    +
  • does not preserve the real client IP, so SPF check of incoming mail will fail.
    • +
  • requires you to specify the exposed IPs explicitly.
    • +
+

Proxy port to Service

+

The proxy pod helps to avoid the necessity of specifying external IPs explicitly. This comes at the cost of complexity; you must deploy a proxy pod on each Node you want to expose docker-mailserver on.

+

This approach

+
    +
  • does not preserve the real client IP, so SPF check of incoming mail will fail.
    • +
+

Bind to concrete Node and use host network

+

One way to preserve the real client IP is to use hostPort and hostNetwork: true. This comes at the cost of availability; you can reach docker-mailserver from the outside world only via IPs of Node where docker-mailserver is deployed.

+
---
+apiVersion: extensions/v1beta1
+kind: Deployment
+
+metadata:
+  name: mailserver
+
+# ...
+    spec:
+      hostNetwork: true
+
+    # ...
+      containers:
+        # ...
+          ports:
+            - name: smtp
+              containerPort: 25
+              hostPort: 25
+            - name: smtp-auth
+              containerPort: 587
+              hostPort: 587
+            - name: imap-secure
+              containerPort: 993
+              hostPort: 993
+        #  ...
+
+

With this approach,

+
    +
  • it is not possible to access docker-mailserver via other cluster Nodes, only via the Node docker-mailserver was deployed at.
    • +
  • every Port within the Container is exposed on the Host side.
    • +
+

Proxy Port to Service via PROXY Protocol

+

This way is ideologically the same as using a proxy pod, but instead of a separate proxy pod, you configure your ingress to proxy TCP traffic to the docker-mailserver pod using the PROXY protocol, which preserves the real client IP.

+

Configure your Ingress

+

With an NGINX ingress controller, set externalTrafficPolicy: Local for its service, and add the following to the TCP services config map (as described here):

+
25:  "mailserver/mailserver:25::PROXY"
+465: "mailserver/mailserver:465::PROXY"
+587: "mailserver/mailserver:587::PROXY"
+993: "mailserver/mailserver:993::PROXY"
+
+
+

HAProxy

+

With HAProxy, the configuration should look similar to the above. If you know what it actually looks like, add an example here. 😃

+
+

Configure the Mailserver

+

Then, configure both Postfix and Dovecot to expect the PROXY protocol:

+
+HAProxy Example +
kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: mailserver.config
+  labels:
+    app: mailserver
+data:
+  postfix-main.cf: |
+    postscreen_upstream_proxy_protocol = haproxy
+  postfix-master.cf: |
+    smtp/inet/postscreen_upstream_proxy_protocol=haproxy
+    submission/inet/smtpd_upstream_proxy_protocol=haproxy
+    smtps/inet/smtpd_upstream_proxy_protocol=haproxy
+  dovecot.cf: |
+    # Assuming your ingress controller is bound to 10.0.0.0/8
+    haproxy_trusted_networks = 10.0.0.0/8, 127.0.0.0/8
+    service imap-login {
+      inet_listener imap {
+        haproxy = yes
+      }
+      inet_listener imaps {
+        haproxy = yes
+      }
+    }
+# ...
+---
+
+kind: Deployment
+apiVersion: extensions/v1beta1
+metadata:
+  name: mailserver
+spec:
+  template:
+    spec:
+      containers:
+        - name: docker-mailserver
+          volumeMounts:
+            - name: config
+              subPath: postfix-main.cf
+              mountPath: /tmp/docker-mailserver/postfix-main.cf
+              readOnly: true
+            - name: config
+              subPath: postfix-master.cf
+              mountPath: /tmp/docker-mailserver/postfix-master.cf
+              readOnly: true
+            - name: config
+              subPath: dovecot.cf
+              mountPath: /tmp/docker-mailserver/dovecot.cf
+              readOnly: true
+
+
+

With this approach,

+
    +
  • it is not possible to access docker-mailserver via cluster-DNS, as the PROXY protocol is required for incoming connections.
    • +
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/mail-fetchmail/index.html b/v12.0/config/advanced/mail-fetchmail/index.html new file mode 100644 index 00000000..cf957a87 --- /dev/null +++ b/v12.0/config/advanced/mail-fetchmail/index.html @@ -0,0 +1,1700 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Email Gathering with Fetchmail - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Email Gathering with Fetchmail

+ +

To enable the fetchmail service to retrieve e-mails set the environment variable ENABLE_FETCHMAIL to 1. Your docker-compose.yml file should look like following snippet:

+
environment:
+  - ENABLE_FETCHMAIL=1
+  - FETCHMAIL_POLL=300
+
+

Generate a file called fetchmail.cf and place it in the docker-data/dms/config/ folder. Your docker-mailserver folder should look like this example:

+
├── docker-data/dms/config
+│   ├── dovecot.cf
+│   ├── fetchmail.cf
+│   ├── postfix-accounts.cf
+│   └── postfix-virtual.cf
+├── docker-compose.yml
+└── README.md
+
+

Configuration

+

A detailed description of the configuration options can be found in the online version of the manual page.

+

IMAP Configuration

+
+

Example

+
poll 'imap.gmail.com' proto imap
+  user 'username'
+  pass 'secret'
+  is 'user1@example.com'
+  ssl
+
+
+

POP3 Configuration

+
+

Example

+
poll 'pop3.gmail.com' proto pop3
+  user 'username'
+  pass 'secret'
+  is 'user2@example.com'
+  ssl
+
+
+
+

Caution

+

Don’t forget the last line! (eg: is 'user1@example.com'). After is, you have to specify an email address from the configuration file: docker-data/dms/config/postfix-accounts.cf.

+
+

More details how to configure fetchmail can be found in the fetchmail man page in the chapter “The run control file”.

+

Polling Interval

+

By default the fetchmail service searches every 5 minutes for new mails on your external mail accounts. You can override this default value by changing the ENV variable FETCHMAIL_POLL:

+
environment:
+  - FETCHMAIL_POLL=60
+
+

You must specify a numeric argument which is a polling interval in seconds. The example above polls every minute for new mails.

+

Debugging

+

To debug your fetchmail.cf configuration run this command:

+
./setup.sh debug fetchmail
+
+

For more informations about the configuration script setup.sh read the corresponding docs.

+

Here a sample output of ./setup.sh debug fetchmail:

+
fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:09 2016: poll started
+Trying to connect to 132.245.48.18/995...connected.
+fetchmail: Server certificate:
+fetchmail: Issuer Organization: Microsoft Corporation
+fetchmail: Issuer CommonName: Microsoft IT SSL SHA2
+fetchmail: Subject CommonName: outlook.com
+fetchmail: Subject Alternative Name: outlook.com
+fetchmail: Subject Alternative Name: *.outlook.com
+fetchmail: Subject Alternative Name: office365.com
+fetchmail: Subject Alternative Name: *.office365.com
+fetchmail: Subject Alternative Name: *.live.com
+fetchmail: Subject Alternative Name: *.internal.outlook.com
+fetchmail: Subject Alternative Name: *.outlook.office365.com
+fetchmail: Subject Alternative Name: outlook.office.com
+fetchmail: Subject Alternative Name: attachment.outlook.office.net
+fetchmail: Subject Alternative Name: attachment.outlook.officeppe.net
+fetchmail: Subject Alternative Name: *.office.com
+fetchmail: outlook.office365.com key fingerprint: 3A:A4:58:42:56:CD:BD:11:19:5B:CF:1E:85:16:8E:4D
+fetchmail: POP3< +OK The Microsoft Exchange POP3 service is ready. [SABFADEAUABSADAAMQBDAEEAMAAwADAANwAuAGUAdQByAHAAcgBkADAAMQAuAHAAcgBvAGQALgBlAHgAYwBoAGEAbgBnAGUAbABhAGIAcwAuAGMAbwBtAA==]
+fetchmail: POP3> CAPA
+fetchmail: POP3< +OK
+fetchmail: POP3< TOP
+fetchmail: POP3< UIDL
+fetchmail: POP3< SASL PLAIN
+fetchmail: POP3< USER
+fetchmail: POP3< .
+fetchmail: POP3> USER user1@outlook.com
+fetchmail: POP3< +OK
+fetchmail: POP3> PASS *
+fetchmail: POP3< +OK User successfully logged on.
+fetchmail: POP3> STAT
+fetchmail: POP3< +OK 0 0
+fetchmail: No mail for user1@outlook.com at outlook.office365.com
+fetchmail: POP3> QUIT
+fetchmail: POP3< +OK Microsoft Exchange Server 2016 POP3 server signing off.
+fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:11 2016: poll completed
+fetchmail: normal termination, status 1
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/mail-forwarding/aws-ses/index.html b/v12.0/config/advanced/mail-forwarding/aws-ses/index.html new file mode 100644 index 00000000..1b0a4f7c --- /dev/null +++ b/v12.0/config/advanced/mail-forwarding/aws-ses/index.html @@ -0,0 +1,1509 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mail Forwarding | AWS SES - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

AWS SES

+ +

Amazon SES (Simple Email Service) is intended to provide a simple way for cloud based applications to send email and receive email. For the purposes of this project only sending email via SES is supported. Older versions of docker-mailserver used AWS_SES_HOST and AWS_SES_USERPASS to configure sending, this has changed and the setup is mananged through Configure Relay Hosts.

+

You will need to create some Amazon SES SMTP credentials. The SMTP credentials you create will be used to populate the RELAY_USER and RELAY_PASSWORD environment variables.

+

The RELAY_HOST should match your AWS SES region, the RELAY_PORT will be 587.

+

If all of your email is being forwarded through AWS SES, DEFAULT_RELAY_HOST should be set accordingly.

+

Example: +

DEFAULT_RELAY_HOST=[email-smtp.us-west-2.amazonaws.com]:587
+

+
+

Note

+

If you set up AWS Easy DKIM you can safely skip setting up DKIM as the AWS SES will take care of signing your outgoing email.

+
+

To verify proper operation, send an email to some external account of yours and inspect the mail headers. You will also see the connection to SES in the mail logs. For example:

+
May 23 07:09:36 mail postfix/smtp[692]: Trusted TLS connection established to email-smtp.us-east-1.amazonaws.com[107.20.142.169]:25:
+TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)
+May 23 07:09:36 mail postfix/smtp[692]: 8C82A7E7: to=<someone@example.com>, relay=email-smtp.us-east-1.amazonaws.com[107.20.142.169]:25,
+delay=0.35, delays=0/0.02/0.13/0.2, dsn=2.0.0, status=sent (250 Ok 01000154dc729264-93fdd7ea-f039-43d6-91ed-653e8547867c-000000)
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/mail-forwarding/relay-hosts/index.html b/v12.0/config/advanced/mail-forwarding/relay-hosts/index.html new file mode 100644 index 00000000..85015527 --- /dev/null +++ b/v12.0/config/advanced/mail-forwarding/relay-hosts/index.html @@ -0,0 +1,1676 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mail Forwarding | Relay Hosts - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Relay Hosts

+ +

Introduction

+

Rather than having Postfix deliver mail directly, you can configure Postfix to send mail via another mail relay (smarthost). Examples include Mailgun, Sendgrid and AWS SES.

+

Depending on the domain of the sender, you may want to send via a different relay, or authenticate in a different way.

+

Basic Configuration

+

Basic configuration is done via environment variables:

+
    +
  • RELAY_HOST: default host to relay mail through, empty (aka '', or no ENV set) will disable this feature
    • +
  • RELAY_PORT: port on default relay, defaults to port 25
    • +
  • RELAY_USER: username for the default relay
    • +
  • RELAY_PASSWORD: password for the default user
    • +
+

Setting these environment variables will cause mail for all sender domains to be routed via the specified host, authenticating with the user/password combination.

+
+

Warning

+

For users of the previous AWS_SES_* variables: please update your configuration to use these new variables, no other configuration is required.

+
+

Advanced Configuration

+

Sender-dependent Authentication

+

Sender dependent authentication is done in docker-data/dms/config/postfix-sasl-password.cf. You can create this file manually, or use:

+
setup.sh relay add-auth <domain> <username> [<password>]
+
+

An example configuration file looks like this:

+
@domain1.com           relay_user_1:password_1
+@domain2.com           relay_user_2:password_2
+
+

If there is no other configuration, this will cause Postfix to deliver email through the relay specified in RELAY_HOST env variable, authenticating as relay_user_1 when sent from domain1.com and authenticating as relay_user_2 when sending from domain2.com.

+
+

Note

+

To activate the configuration you must either restart the container, or you can also trigger an update by modifying a mail account.

+
+

Sender-dependent Relay Host

+

Sender dependent relay hosts are configured in docker-data/dms/config/postfix-relaymap.cf. You can create this file manually, or use:

+
setup.sh relay add-domain <domain> <host> [<port>]
+
+

An example configuration file looks like this:

+
@domain1.com        [relay1.org]:587
+@domain2.com        [relay2.org]:2525
+
+

Combined with the previous configuration in docker-data/dms/config/postfix-sasl-password.cf, this will cause Postfix to deliver mail sent from domain1.com via relay1.org:587, authenticating as relay_user_1, and mail sent from domain2.com via relay2.org:2525 authenticating as relay_user_2.

+
+

Note

+

You still have to define RELAY_HOST to activate the feature

+
+

Excluding Sender Domains

+

If you want mail sent from some domains to be delivered directly, you can exclude them from being delivered via the default relay by adding them to docker-data/dms/config/postfix-relaymap.cf with no destination. You can also do this via:

+
setup.sh relay exclude-domain <domain>
+
+

Extending the configuration file from above:

+
@domain1.com        [relay1.org]:587
+@domain2.com        [relay2.org]:2525
+@domain3.com
+
+

This will cause email sent from domain3.com to be delivered directly.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/mail-sieve/index.html b/v12.0/config/advanced/mail-sieve/index.html new file mode 100644 index 00000000..218efeff --- /dev/null +++ b/v12.0/config/advanced/mail-sieve/index.html @@ -0,0 +1,1649 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Email Filtering with Sieve - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Email Filtering with Sieve

+ +

User-Defined Sieve Filters

+

Sieve allows to specify filtering rules for incoming emails that allow for example sorting mails into different folders depending on the title of an email. +There are global and user specific filters which are filtering the incoming emails in the following order:

+
    +
  • Global-before -> User specific -> Global-after
    • +
+

Global filters are applied to EVERY incoming mail for EVERY email address. +To specify a global Sieve filter provide a docker-data/dms/config/before.dovecot.sieve or a docker-data/dms/config/after.dovecot.sieve file with your filter rules. +If any filter in this filtering chain discards an incoming mail, the delivery process will stop as well and the mail will not reach any following filters(e.g. global-before stops an incoming spam mail: The mail will get discarded and a user-specific filter won't get applied.)

+

To specify a user-defined Sieve filter place a .dovecot.sieve file into a virtual user's mail folder e.g. /var/mail/example.com/user1/.dovecot.sieve. If this file exists dovecot will apply the filtering rules.

+

It's even possible to install a user provided Sieve filter at startup during users setup: simply include a Sieve file in the docker-data/dms/config/ path for each user login that needs a filter. The file name provided should be in the form <user_login>.dovecot.sieve, so for example for user1@example.com you should provide a Sieve file named docker-data/dms/config/user1@example.com.dovecot.sieve.

+

An example of a sieve filter that moves mails to a folder INBOX/spam depending on the sender address:

+
+

Example

+
require ["fileinto", "reject"];
+
+if address :contains ["From"] "spam@spam.com" {
+  fileinto "INBOX.spam";
+} else {
+  keep;
+}
+
+
+
+

Warning

+

That folders have to exist beforehand if sieve should move them.

+
+

Another example of a sieve filter that forward mails to a different address:

+
+

Example

+
require ["copy"];
+
+redirect :copy "user2@not-example.com";
+
+
+

Just forward all incoming emails and do not save them locally:

+
+

Example

+
redirect "user2@not-example.com";
+
+
+

You can also use external programs to filter or pipe (process) messages by adding executable scripts in docker-data/dms/config/sieve-pipe or docker-data/dms/config/sieve-filter. This can be used in lieu of a local alias file, for instance to forward an email to a webservice. These programs can then be referenced by filename, by all users. Note that the process running the scripts run as a privileged user. For further information see Dovecot's wiki.

+
require ["vnd.dovecot.pipe"];
+pipe "external-program";
+
+

For more examples or a detailed description of the Sieve language have a look at the official site. Other resources are available on the internet where you can find several examples.

+

Automatic Sorting Based on Subaddresses

+

It is possible to sort subaddresses such as user+mailing-lists@example.com into a corresponding folder (here: INBOX/Mailing-lists) automatically.

+
require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
+
+if envelope :detail :matches "to" "*" {
+    set :lower :upperfirst "tag" "${1}";
+    if mailboxexists "INBOX.${1}" {
+        fileinto "INBOX.${1}";
+    } else {
+        fileinto :create "INBOX.${tag}";
+    }
+}
+
+

Manage Sieve

+

The Manage Sieve extension allows users to modify their Sieve script by themselves. The authentication mechanisms are the same as for the main dovecot service. ManageSieve runs on port 4190 and needs to be enabled using the ENABLE_MANAGESIEVE=1 environment variable.

+
+

Example

+
# docker-compose.yml
+ports:
+  - "4190:4190"
+environment:
+  - ENABLE_MANAGESIEVE=1
+
+
+

All user defined sieve scripts that are managed by ManageSieve are stored in the user's home folder in /var/mail/example.com/user1/sieve. Just one sieve script might be active for a user and is sym-linked to /var/mail/example.com/user1/.dovecot.sieve automatically.

+
+

Note

+

ManageSieve makes sure to not overwrite an existing .dovecot.sieve file. If a user activates a new sieve script the old one is backuped and moved to the sieve folder.

+
+

The extension is known to work with the following ManageSieve clients:

+
    +
  • Sieve Editor a portable standalone application based on the former Thunderbird plugin.
    • +
  • Kmail the mail client of KDE's Kontact Suite.
    • +
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/maintenance/update-and-cleanup/index.html b/v12.0/config/advanced/maintenance/update-and-cleanup/index.html new file mode 100644 index 00000000..a895ff14 --- /dev/null +++ b/v12.0/config/advanced/maintenance/update-and-cleanup/index.html @@ -0,0 +1,1579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Maintenance | Update and Cleanup - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Update and Cleanup

+ +

Automatic Update

+

Docker images are handy but it can become a hassle to keep them updated. Also when a repository is automated you want to get these images when they get out.

+

One could setup a complex action/hook-based workflow using probes, but there is a nice, easy to use docker image that solves this issue and could prove useful: watchtower.

+

A docker-compose example:

+
services:
+  watchtower:
+    restart: always
+    image: containrrr/watchtower:latest
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+
+

For more details, see the manual

+

Automatic Cleanup

+

When you are pulling new images in automatically, it would be nice to have them cleaned up as well. There is also a docker image for this: spotify/docker-gc.

+

A docker-compose example:

+
services:
+  docker-gc:
+    restart: always
+    image: spotify/docker-gc:latest
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+
+

For more details, see the manual

+

Or you can just use the --cleanup option provided by containrrr/watchtower.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/optional-config/index.html b/v12.0/config/advanced/optional-config/index.html new file mode 100644 index 00000000..8a18bde6 --- /dev/null +++ b/v12.0/config/advanced/optional-config/index.html @@ -0,0 +1,1597 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Optional Configuration - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Optional Configuration

+ +

This is a list of all configuration files and directories which are optional or automatically generated in your docker-data/dms/config/ directory.

+

Directories

+
    +
  • sieve-filter: directory for sieve filter scripts. (Docs: Sieve)
    • +
  • sieve-pipe: directory for sieve pipe scripts. (Docs: Sieve)
    • +
  • opendkim: DKIM directory. Auto-configurable via setup.sh config dkim. (Docs: DKIM)
    • +
  • ssl: SSL Certificate directory if SSL_TYPE is set to self-signed or custom. (Docs: SSL)
    • +
+

Files

+
    +
  • {user_email_address}.dovecot.sieve: User specific Sieve filter file. (Docs: Sieve)
    • +
  • before.dovecot.sieve: Global Sieve filter file, applied prior to the ${login}.dovecot.sieve filter. (Docs: Sieve)
    • +
  • after.dovecot.sieve: Global Sieve filter file, applied after the ${login}.dovecot.sieve filter. (Docs: Sieve)
    • +
  • postfix-main.cf: Every line will be added to the postfix main configuration. (Docs: Override Postfix Defaults)
    • +
  • postfix-master.cf: Every line will be added to the postfix master configuration. (Docs: Override Postfix Defaults)
    • +
  • postfix-accounts.cf: User accounts file. Modify via the setup.sh email script.
    • +
  • postfix-send-access.cf: List of users denied sending. Modify via setup.sh email restrict.
    • +
  • postfix-receive-access.cf: List of users denied receiving. Modify via setup.sh email restrict.
    • +
  • postfix-virtual.cf: Alias configuration file. Modify via setup.sh alias.
    • +
  • postfix-sasl-password.cf: listing of relayed domains with their respective <username>:<password>. Modify via setup.sh relay add-auth <domain> <username> [<password>]. (Docs: Relay-Hosts Auth)
    • +
  • postfix-relaymap.cf: domain-specific relays and exclusions. Modify via setup.sh relay add-domain and setup.sh relay exclude-domain. (Docs: Relay-Hosts Senders)
    • +
  • postfix-regexp.cf: Regular expression alias file. (Docs: Aliases)
    • +
  • ldap-users.cf: Configuration for the virtual user mapping virtual_mailbox_maps. See the setup-stack.sh script.
    • +
  • ldap-groups.cf: Configuration for the virtual alias mapping virtual_alias_maps. See the setup-stack.sh script.
    • +
  • ldap-aliases.cf: Configuration for the virtual alias mapping virtual_alias_maps. See the setup-stack.sh script.
    • +
  • ldap-domains.cf: Configuration for the virtual domain mapping virtual_mailbox_domains. See the setup-stack.sh script.
    • +
  • whitelist_clients.local: Whitelisted domains, not considered by postgrey. Enter one host or domain per line.
    • +
  • spamassassin-rules.cf: Antispam rules for Spamassassin. (Docs: FAQ - SpamAssassin Rules)
    • +
  • fail2ban-fail2ban.cf: Additional config options for fail2ban.cf. (Docs: Fail2Ban)
    • +
  • fail2ban-jail.cf: Additional config options for fail2ban's jail behaviour. (Docs: Fail2Ban)
    • +
  • amavis.cf: replaces the /etc/amavis/conf.d/50-user file
    • +
  • dovecot.cf: replaces /etc/dovecot/local.conf. (Docs: Override Dovecot Defaults)
    • +
  • dovecot-quotas.cf: list of custom quotas per mailbox. (Docs: Accounts)
    • +
  • user-patches.sh: this file will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started. (Docs: FAQ - How to adjust settings with the user-patches.sh script)
    • +
  • rspamd-commands: list of simple commands to adjust Rspamd modules in an easy way (Docs: Rspamd)
    • +
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/override-defaults/dovecot/index.html b/v12.0/config/advanced/override-defaults/dovecot/index.html new file mode 100644 index 00000000..de23bed8 --- /dev/null +++ b/v12.0/config/advanced/override-defaults/dovecot/index.html @@ -0,0 +1,1610 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Override the Default Configs | Dovecot - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Dovecot

+ +

Add Configuration

+

The Dovecot default configuration can easily be extended providing a docker-data/dms/config/dovecot.cf file. +Dovecot documentation remains the best place to find configuration options.

+

Your docker-mailserver folder should look like this example:

+
├── docker-data/dms/config
+│   ├── dovecot.cf
+│   ├── postfix-accounts.cf
+│   └── postfix-virtual.cf
+├── docker-compose.yml
+└── README.md
+
+

One common option to change is the maximum number of connections per user:

+
mail_max_userip_connections = 100
+
+

Another important option is the default_process_limit (defaults to 100). If high-security mode is enabled you'll need to make sure this count is higher than the maximum number of users that can be logged in simultaneously.

+

This limit is quickly reached if users connect to the docker-mailserver with multiple end devices.

+

Override Configuration

+

For major configuration changes it’s best to override the dovecot configuration files. For each configuration file you want to override, add a list entry under the volumes key.

+
services:
+  mailserver:
+    volumes:
+      - ./docker-data/dms/mail-data/:/var/mail/
+      - ./docker-data/dms/config/dovecot/10-master.conf:/etc/dovecot/conf.d/10-master.conf
+
+

You will first need to obtain the configuration from the running container (where mailserver is the container name):

+
mkdir -p ./docker-data/dms/config/dovecot
+docker cp mailserver:/etc/dovecot/conf.d/10-master.conf ./docker-data/dms/config/dovecot/10-master.conf
+
+

Debugging

+

To debug your dovecot configuration you can use:

+
    +
  • This command: ./setup.sh debug login doveconf | grep <some-keyword>
    • +
  • Or: docker exec -it mailserver doveconf | grep <some-keyword>
    • +
+
+

Note

+

setup.sh is included in the docker-mailserver repository. Make sure to use the one matching your image version release.

+
+

The file docker-data/dms/config/dovecot.cf is copied internally to /etc/dovecot/local.conf. To verify the file content, run:

+
docker exec -it mailserver cat /etc/dovecot/local.conf
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/override-defaults/postfix/index.html b/v12.0/config/advanced/override-defaults/postfix/index.html new file mode 100644 index 00000000..b4301c49 --- /dev/null +++ b/v12.0/config/advanced/override-defaults/postfix/index.html @@ -0,0 +1,1516 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Override the Default Configs | Postfix - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Postfix

+ +

Our default Postfix configuration can easily be extended to add parameters or modify existing ones by providing a docker-data/dms/config/postfix-main.cf. This file uses the same format as Postfix main.cf does (See official docs for all parameters and syntax rules).

+
+

Example

+

One can easily increase the backwards-compatibility level and set new Postscreen options:

+
# increase the compatibility level from 2 (default) to 3
+compatibility_level = 3
+# set a threshold value for Spam detection
+postscreen_dnsbl_threshold = 4
+
+
+
+

How are your changes applied?

+

The custom configuration you supply is appended to the default configuration located at /etc/postfix/main.cf, and then postconf -nf is run to remove earlier duplicate entries that have since been replaced. This happens early during container startup before Postfix is started.

+
+
+

Similarly, it is possible to add a custom docker-data/dms/config/postfix-master.cf file that will override the standard master.cf. Note: Each line in this file will be passed to postconf -P, i.e. the file is not appended as a whole to /etc/postfix/master.cf like docker-data/dms/config/postfix-main.cf! The expected format is <service_name>/<type>/<parameter>, for example:

+
# adjust the submission "reject_unlisted_recipient" option
+submission/inet/smtpd_reject_unlisted_recipient=no
+
+
+

Attention

+

There should be no space between the parameter and the value.

+
+

Run postconf -Mf in the container without arguments to see the active master options.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/override-defaults/user-patches/index.html b/v12.0/config/advanced/override-defaults/user-patches/index.html new file mode 100644 index 00000000..ac7f5c71 --- /dev/null +++ b/v12.0/config/advanced/override-defaults/user-patches/index.html @@ -0,0 +1,1521 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Custom User Changes & Patches | Scripting - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Modifications via Script

+ +

If you'd like to change, patch or alter files or behavior of docker-mailserver, you can use a script.

+

In case you cloned this repository, you can copy the file user-patches.sh.dist (under config/) with cp config/user-patches.sh.dist docker-data/dms/config/user-patches.sh in order to create the user-patches.sh script.

+

If you are managing your directory structure yourself, create a docker-data/dms/config/ directory and add the user-patches.sh file yourself.

+
# 1. Either create the docker-data/dms/config/ directory yourself
+#    or let docker-mailserver create it on initial startup
+/tmp $ mkdir -p docker-data/dms/config/ && cd docker-data/dms/config/
+
+# 2. Create the user-patches.sh file and edit it
+/tmp/docker-data/dms/config $ touch user-patches.sh
+/tmp/docker-data/dms/config $ nano user-patches.sh
+
+

The contents could look like this:

+
#!/bin/bash
+
+cat >/etc/amavis/conf.d/50-user << "END"
+use strict;
+
+$undecipherable_subject_tag = undef;
+$admin_maps_by_ccat{+CC_UNCHECKED} =  undef;
+
+#------------ Do not modify anything below this line -------------
+1;  # ensure a defined return
+END
+
+

And you're done. The user patches script runs right before starting daemons. That means, all the other configuration is in place, so the script can make final adjustments.

+
+

Note

+

Many "patches" can already be done with the Docker Compose-/Stack-file. Adding hostnames to /etc/hosts is done with the extra_hosts: section, sysctl commands can be managed with the sysctls: section, etc.

+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/advanced/podman/index.html b/v12.0/config/advanced/podman/index.html new file mode 100644 index 00000000..3339ffb9 --- /dev/null +++ b/v12.0/config/advanced/podman/index.html @@ -0,0 +1,1804 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Advanced | Podman - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Podman

+ +

Introduction

+

Podman is a daemonless container engine for developing, managing, and running OCI Containers on your Linux System.

+
+

About Support for Podman

+

Please note that Podman is not officially supported as docker-mailserver is built and verified on top of the Docker Engine. This content is entirely community supported. If you find errors, please open an issue and provide a PR.

+
+
+

About this Guide

+

This guide was tested with Fedora 34 using systemd and firewalld. Moreover, it requires Podman version >= 3.2. You may be able to substitute dnf - Fedora's package manager - with others such as apt.

+
+
+

About Security

+

Running podman in rootless mode requires additional modifications in order to keep your mailserver secure. +Make sure to read the related documentation.

+
+

Installation in Rootfull Mode

+

While using Podman, you can just manage docker-mailserver as what you did with Docker. Your best friend setup.sh includes the minimum code in order to support Podman since it's 100% compatible with the Docker CLI.

+

The installation is basically the same. Podman v3.2 introduced a RESTful API that is 100% compatible with the Docker API, so you can use docker-compose with Podman easily. Install Podman and docker-compose with your package manager first.

+
sudo dnf install podman docker-compose
+
+

Then enable podman.socket using systemctl.

+
systemctl enable --now podman.socket
+
+

This will create a unix socket locate under /run/podman/podman.sock, which is the entrypoint of Podman's API. Now, configure docker-mailserver and start it.

+
export DOCKER_HOST="unix:///run/podman/podman.sock"
+docker-compose up -d mailserver
+docker-compose ps
+
+

You should see that docker-mailserver is running now.

+

Self-start in Rootfull Mode

+

Podman is daemonless, that means if you want docker-mailserver self-start while boot up the system, you have to generate a systemd file with Podman CLI.

+
podman generate systemd mailserver > /etc/systemd/system/mailserver.service
+systemctl daemon-reload
+systemctl enable --now mailserver.service
+
+

Installation in Rootless Mode

+

Running rootless containers is one of Podman's major features. But due to some restrictions, deploying docker-mailserver in rootless mode is not as easy compared to rootfull mode.

+
    +
  • a rootless container is running in a user namespace so you cannot bind ports lower than 1024
    • +
  • a rootless container's systemd file can only be placed in folder under ~/.config
    • +
  • a rootless container can result in an open relay, make sure to read the security section.
    • +
+

Also notice that Podman's rootless mode is not about running as a non-root user inside the container, but about the mapping of (normal, non-root) host users to root inside the container.

+
+

Warning

+

In order to make rootless docker-mailserver work we must modify some settings in the Linux system, it requires some basic linux server knowledge so don't follow this guide if you not sure what this guide is talking about. Podman rootfull mode and Docker are still good and security enough for normal daily usage.

+
+

First, enable podman.socket in systemd's userspace with a non-root user.

+
systemctl enable --now --user podman.socket
+
+

The socket file should be located at /var/run/user/$(id -u)/podman/podman.sock. Then, modify docker-compose.yml to make sure all ports are bindings are on non-privileged ports.

+
services:
+  mailserver:
+    ports:
+      - "10025:25"   # SMTP  (explicit TLS => STARTTLS)
+      - "10143:143"  # IMAP4 (explicit TLS => STARTTLS)
+      - "10465:465"  # ESMTP (implicit TLS)
+      - "10587:587"  # ESMTP (explicit TLS => STARTTLS)
+      - "10993:993"  # IMAP4 (implicit TLS)
+
+

Then, setup your mailserver.env file follow the documentation and use docker-compose to start the container.

+
export DOCKER_HOST="unix:///var/run/user/$(id -u)/podman/podman.sock"
+docker-compose up -d mailserver
+docker-compose ps
+
+

Security in Rootless Mode

+

In rootless mode, podman resolves all incoming IPs as localhost, which results in an open gateway in the default configuration. There are two workarounds to fix this problem, both of which have their own drawbacks.

+

Enforce authentication from localhost

+

The PERMIT_DOCKER variable in the mailserver.env file allows to specify trusted networks that do not need to authenticate. If the variable is left empty, only requests from localhost and the container IP are allowed, but in the case of rootless podman any IP will be resolved as localhost. Setting PERMIT_DOCKER=none enforces authentication also from localhost, which prevents sending unauthenticated emails.

+

Use the slip4netns network driver

+

The second workaround is slightly more complicated because the docker-compose.yml has to be modified. +As shown in the fail2ban section the slirp4netns network driver has to be enabled. +This network driver enables podman to correctly resolve IP addresses but it is not compatible with +user defined networks which might be a problem depending on your setup.

+

Rootless Podman requires adding the value slirp4netns:port_handler=slirp4netns to the --network CLI option, or network_mode setting in your docker-compose.yml.

+

You must also add the ENV NETWORK_INTERFACE=tap0, because Podman uses a hard-coded interface name for slirp4netns.

+
+

Example

+
services:
+  mailserver:
+    network_mode: "slirp4netns:port_handler=slirp4netns"
+    environment:
+      - NETWORK_INTERFACE=tap0
+      ...
+
+
+
+

Note

+

podman-compose is not compatible with this configuration.

+
+

Self-start in Rootless Mode

+

Generate a systemd file with the Podman CLI.

+
podman generate systemd mailserver > ~/.config/systemd/user/mailserver.service
+systemctl --user daemon-reload
+systemctl enable --user --now mailserver.service
+
+

Systemd's user space service is only started when a specific user logs in and stops when you log out. In order to make it to start with the system, we need to enable linger with loginctl

+
loginctl enable-linger <username>
+
+

Remember to run this command as root user.

+

Port Forwarding

+

When it comes to forwarding ports using firewalld, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/securing_networks/using-and-configuring-firewalld_securing-networks#port-forwarding_using-and-configuring-firewalld for more information.

+
firewall-cmd --permanent --add-forward-port=port=<25|143|465|587|993>:proto=<tcp>:toport=<10025|10143|10465|10587|10993>
+...
+
+# After you set all ports up.
+firewall-cmd --reload
+
+

Notice that this will only open the access to the external client. If you want to access privileges port in your server, do this:

+
firewall-cmd --permanent --direct --add-rule <ipv4|ipv6> nat OUTPUT 0 -p <tcp|udp> -o lo --dport <25|143|465|587|993> -j REDIRECT --to-ports <10025|10143|10465|10587|10993>
+...
+# After you set all ports up.
+firewall-cmd --reload
+
+

Just map all the privilege port with non-privilege port you set in docker-compose.yml before as root user.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/best-practices/autodiscover/index.html b/v12.0/config/best-practices/autodiscover/index.html new file mode 100644 index 00000000..54ff4117 --- /dev/null +++ b/v12.0/config/best-practices/autodiscover/index.html @@ -0,0 +1,1501 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Best Practices | Auto-discovery - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Auto-discovery

+ +

Email auto-discovery means a client email is able to automagically find out about what ports and security options to use, based on the mail-server URI. It can help simplify the tedious / confusing task of adding own's email account for non-tech savvy users.

+

Email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address ❤

+

There exists autodiscover-email-settings on which provides IMAP/POP/SMTP/LDAP autodiscover capabilities on Microsoft Outlook/Apple Mail, autoconfig capabilities for Thunderbird or kmail and configuration profiles for iOS/Apple Mail.

+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/best-practices/dkim/index.html b/v12.0/config/best-practices/dkim/index.html new file mode 100644 index 00000000..e1d18107 --- /dev/null +++ b/v12.0/config/best-practices/dkim/index.html @@ -0,0 +1,1689 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Best Practices | DKIM - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

DKIM

+ +

DKIM is a security measure targeting email spoofing. It is greatly recommended one activates it.

+
+

Note

+

See the Wikipedia page for more details on DKIM.

+
+

Enabling DKIM Signature

+

To enable DKIM signature, you must have created at least one email account. Once its done, just run the following command to generate the signature:

+
./setup.sh config dkim
+
+

After generating DKIM keys, you should restart docker-mailserver. DNS edits may take a few minutes to hours to propagate.

+

The script should ideally be run with a volume for config attached (eg: ./docker-data/dms/config/:/tmp/docker-mailserver/), otherwise by default it will mount ./config/:/tmp/docker-mailserver/.

+

The default keysize when generating the signature is 4096 bits for now. If you need to change it (e.g. your DNS provider limits the size), then provide the size as the first parameter of the command:

+
./setup.sh config dkim keysize <keysize>
+
+

For LDAP systems that do not have any directly created user account you can run the following command (since 8.0.0) to generate the signature by additionally providing the desired domain name (if you have multiple domains use the command multiple times or provide a comma-separated list of domains):

+
./setup.sh config dkim keysize <key-size> domain <example.com>[,<not-example.com>]
+
+

Now the keys are generated, you can configure your DNS server with DKIM signature, simply by adding a TXT record. If you have direct access to your DNS zone file, then it's only a matter of pasting the content of docker-data/dms/config/opendkim/keys/example.com/mail.txt in your example.com.hosts zone.

+
$ dig mail._domainkey.example.com TXT
+---
+;; ANSWER SECTION
+mail._domainkey.<DOMAIN> 300 IN TXT    "v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN"
+
+

Configuration using a Web Interface

+
    +
  1. Generate a new record of the type TXT.
    2. +
  2. Paste mail._domainkey the Name txt field.
    3. +
  3. In the Target or Value field fill in v=DKIM1; k=rsa; p=AZERTYUGHJKLMWX....
    4. +
  4. In TTL (time to live): Time span in seconds. How long the DNS server should cache the TXT record.
    5. +
  5. Save.
    6. +
+
+

Note

+

Sometimes the key in docker-data/dms/config/opendkim/keys/example.com/mail.txt can be on multiple lines. If so then you need to concatenate the values in the TXT record:

+
+
$ dig mail._domainkey.example.com TXT
+---
+;; ANSWER SECTION
+mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; "
+    "p=AZERTYUIOPQSDF..."
+    "asdfQWERTYUIOPQSDF..."
+
+

The target (or value) field must then have all the parts together: v=DKIM1; k=rsa; p=AZERTYUIOPQSDF...asdfQWERTYUIOPQSDF...

+

Verify-Only

+

If you want DKIM to only verify incoming emails, the following version of /etc/opendkim.conf may be useful (right now there is no easy mechanism for installing it other than forking the repo):

+
# This is a simple config file verifying messages only
+
+#LogWhy                 yes
+Syslog                  yes
+SyslogSuccess           yes
+
+Socket                  inet:12301@localhost
+PidFile                 /var/run/opendkim/opendkim.pid
+
+ReportAddress           postmaster@example.com
+SendReports             yes
+
+Mode                    v
+
+

Switch Off DKIM

+

Simply remove the DKIM key by recreating (not just relaunching) the docker-mailserver container.

+

Debugging

+
    +
  • DKIM-verifer: A add-on for the mail client Thunderbird.
    • +
  • You can debug your TXT records with the dig tool.
    • +
+
$ dig TXT mail._domainkey.example.com
+---
+; <<>> DiG 9.10.3-P4-Debian <<>> TXT mail._domainkey.example.com
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 39669
+;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
+
+;; OPT PSEUDOSECTION:
+; EDNS: version: 0, flags:; udp: 512
+;; QUESTION SECTION:
+;mail._domainkey.example.com. IN TXT
+
+;; ANSWER SECTION:
+mail._domainkey.example.com. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxBSjG6RnWAdU3oOlqsdf2WC0FOUmU8uHVrzxPLW2R3yRBPGLrGO1++yy3tv6kMieWZwEBHVOdefM6uQOQsZ4brahu9lhG8sFLPX4MaKYN/NR6RK4gdjrZu+MYSdfk3THgSbNwIDAQAB"
+
+;; Query time: 50 msec
+;; SERVER: 127.0.1.1#53(127.0.1.1)
+;; WHEN: Wed Sep 07 18:22:57 CEST 2016
+;; MSG SIZE  rcvd: 310
+
+
+
+

Key sizes >=4096-bit

+

Keys of 4096 bits could de denied by some mail-servers. According to https://tools.ietf.org/html/rfc6376 keys are preferably between 512 and 2048 bits. See issue #1854.

+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/best-practices/dmarc/index.html b/v12.0/config/best-practices/dmarc/index.html new file mode 100644 index 00000000..665dec3f --- /dev/null +++ b/v12.0/config/best-practices/dmarc/index.html @@ -0,0 +1,1559 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Best Practices | DMARC - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

DMARC

+ +

More information at DMARC Guide.

+

Enabling DMARC

+

In docker-mailserver, DMARC is pre-configured out of the box. The only thing you need to do in order to enable it, is to add new TXT entry to your DNS.

+

In contrast with DKIM, the DMARC DNS entry does not require any keys, but merely setting the configuration values. You can either handcraft the entry by yourself or use one of available generators (like this one).

+

Typically something like this should be good to start with (don't forget to replace @example.com to your actual domain):

+
_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; sp=none; ri=86400"
+
+

Or a bit more strict policies (mind p=quarantine and sp=quarantine):

+
_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; sp=quarantine"
+
+

DMARC status is not being displayed instantly in Gmail for instance. If you want to check it directly after DNS entries, you can use some services around the Internet such as from Global Cyber Alliance or RedSift. In other cases, email clients will show "DMARC: PASS" in ~1 day or so.

+

Reference: #1511

+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/best-practices/spf/index.html b/v12.0/config/best-practices/spf/index.html new file mode 100644 index 00000000..b81383d3 --- /dev/null +++ b/v12.0/config/best-practices/spf/index.html @@ -0,0 +1,1599 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Best Practices | SPF - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

SPF

+ +

From Wikipedia:

+
+

Quote

+

Sender Policy Framework (SPF) is a simple email-validation system designed to detect email spoofing by providing a mechanism to allow receiving mail exchangers to check that incoming mail from a domain comes from a host authorized by that domain's administrators. The list of authorized sending hosts for a domain is published in the Domain Name System (DNS) records for that domain in the form of a specially formatted TXT record. Email spam and phishing often use forged "from" addresses, so publishing and checking SPF records can be considered anti-spam techniques.

+
+
+

Note

+

For a more technical review: https://github.com/internetstandards/toolbox-wiki/blob/master/SPF-how-to.md

+
+

Add a SPF Record

+

To add a SPF record in your DNS, insert the following line in your DNS zone:

+
; MX record must be declared for SPF to work
+example.com. IN  MX 1 mail.example.com.
+
+; SPF record
+example.com. IN TXT "v=spf1 mx ~all"
+
+

This enables the Softfail mode for SPF. You could first add this SPF record with a very low TTL.

+

SoftFail is a good setting for getting started and testing, as it lets all email through, with spams tagged as such in the mailbox.

+

After verification, you might want to change your SPF record to v=spf1 mx -all so as to enforce the HardFail policy. See http://www.open-spf.org/SPF_Record_Syntax for more details about SPF policies.

+

In any case, increment the SPF record's TTL to its final value.

+

Backup MX, Secondary MX

+

For whitelisting an IP Address from the SPF test, you can create a config file (see policyd-spf.conf) and mount that file into /etc/postfix-policyd-spf-python/policyd-spf.conf.

+

Example:

+

Create and edit a policyd-spf.conf file at docker-data/dms/config/postfix-policyd-spf.conf:

+
debugLevel = 1
+#0(only errors)-4(complete data received)
+
+skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
+
+# Preferably use IP-Addresses for whitelist lookups:
+Whitelist = 192.168.0.0/31,192.168.1.0/30
+# Domain_Whitelist = mx1.not-example.com,mx2.not-example.com
+
+

Then add this line to docker-compose.yml:

+
volumes:
+  - ./docker-data/dms/config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
+
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/debugging/index.html b/v12.0/config/debugging/index.html new file mode 100644 index 00000000..7bcc4f77 --- /dev/null +++ b/v12.0/config/debugging/index.html @@ -0,0 +1,1644 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Debugging - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Debugging

+ +

This page contains valuable information when it comes to resolving issues you encounter.

+
+

Contributions Welcome!

+

Please consider contributing solutions to the FAQ ❤

+
+

Preliminary Information

+

Mail sent from DMS does not arrive at destination

+

Some service providers block outbound traffic on port 25. Common hosting providers known to have this issue:

+ +

These links may advise how the provider can unblock the port through additional services offered, or via a support ticket request.

+

Steps for Debugging DMS

+
    +
  1. Increase log verbosity: Very helpful for troubleshooting problems during container startup. Set the environment variable LOG_LEVEL to debug or trace.
    2. +
  2. Use error logs as a search query: Try finding an existing issue or search engine result from any errors in your container log output. Often you'll find answers or more insights. If you still need to open an issue, sharing links from your search may help us assist you. The mail server log can be acquired by running docker log <CONTAINER NAME> (or docker logs -f <CONTAINER NAME> if you want to follow the log).
    3. +
  3. Understand the basics of mail servers: Especially for beginners, make sure you read our Introduction and Usage articles.
    4. +
  4. Search the whole FAQ: Our FAQ contains answers for common problems. Make sure you go through the list.
    5. +
  5. Reduce the scope: Ensure that you can run a basic setup of DMS first. Then incrementally restore parts of your original configuration until the problem is reproduced again. If you're new to DMS, it is common to find the cause is misunderstanding how to configure a minimal setup.
    6. +
+

Debug a running container

+

To get a shell inside the container run: docker exec -it <CONTAINER NAME> bash.

+

If you need more flexibility than docker logs offers, within the container /var/log/mail/mail.log and /var/log/supervisor/ are the most useful locations to get relevant DMS logs. Use the tail or cat commands to view their contents.

+

To install additional software:

+
    +
  • apt-get update is needed to update repository metadata.
    • +
  • apt-get install <PACKAGE>
    • +
  • For example if you need a text editor, nano is a good package choice for beginners.
    • +
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/environment/index.html b/v12.0/config/environment/index.html new file mode 100644 index 00000000..6f8adec7 --- /dev/null +++ b/v12.0/config/environment/index.html @@ -0,0 +1,4146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Environment Variables - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Environment Variables

+ +
+

Info

+

Values in bold are the default values. If an option doesn't work as documented here, check if you are running the latest image. The current master branch corresponds to the image ghcr.io/docker-mailserver/docker-mailserver:edge.

+
+

General

+
OVERRIDE_HOSTNAME
+

If you can't set your hostname (eg: you're in a container platform that doesn't let you) specify it via this environment variable. It will have priority over docker run --hostname, or the equivalent hostname: field in docker-compose.yml.

+
    +
  • empty => Uses the hostname -f command to get canonical hostname for docker-mailserver to use.
    • +
  • => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for docker-mailserver to function correctly.
    • +
+
LOG_LEVEL
+

Set the log level for DMS. This is mostly relevant for container startup scripts and change detection event feedback.

+

Valid values (in order of increasing verbosity) are: error, warn, info, debug and trace. The default log level is info.

+
SUPERVISOR_LOGLEVEL
+

Here you can adjust the log-level for Supervisor. Possible values are

+
    +
  • critical => Only show critical messages
    • +
  • error => Only show erroneous output
    • +
  • warn => Show warnings
    • +
  • info => Normal informational output
    • +
  • debug => Also show debug messages
    • +
+

The log-level will show everything in its class and above.

+
ONE_DIR
+
    +
  • 0 => state in default directories.
    • +
  • 1 => consolidate all states into a single directory (/var/mail-state) to allow persistence using docker volumes. See the related FAQ entry for more information.
    • +
+
ACCOUNT_PROVISIONER
+

Configures the provisioning source of user accounts (including aliases) for user queries and authentication by services managed by DMS (Postfix and Dovecot).

+

User provisioning via OIDC is planned for the future, see this tracking issue.

+
    +
  • empty => use FILE
    • +
  • LDAP => use LDAP authentication
    • +
  • OIDC => use OIDC authentication (not yet implemented)
    • +
  • FILE => use local files (this is used as the default)
    • +
+

A second container for the ldap service is necessary (e.g. docker-openldap)

+
PERMIT_DOCKER
+

Set different options for mynetworks option (can be overwrite in postfix-main.cf) WARNING: Adding the docker network's gateway to the list of trusted hosts, e.g. using the network or connected-networks option, can create an open relay, for instance if IPv6 is enabled on the host machine but not in Docker.

+
    +
  • none => Explicitly force authentication
    • +
  • container => Container IP address only.
    • +
  • host => Add docker host (ipv4 only).
    • +
  • network => Add the docker default bridge network (172.16.0.0/12); WARNING: docker-compose might use others (e.g. 192.168.0.0/16) use PERMIT_DOCKER=connected-networks in this case.
    • +
  • connected-networks => Add all connected docker networks (ipv4 only).
    • +
+

Note: you probably want to set POSTFIX_INET_PROTOCOLS=ipv4 to make it work fine with Docker.

+
TZ
+

Set the timezone. If this variable is unset, the container runtime will try to detect the time using /etc/localtime, which you can alternatively mount into the container. The value of this variable must follow the pattern AREA/ZONE, i.e. of you want to use Germany's time zone, use Europe/Berlin. You can lookup all available timezones here.

+
ENABLE_AMAVIS
+

Amavis content filter (used for ClamAV & SpamAssassin)

+
    +
  • 0 => Amavis is disabled
    • +
  • 1 => Amavis is enabled
    • +
+
AMAVIS_LOGLEVEL
+

This page provides information on Amavis' logging statistics.

+
    +
  • -1/-2/-3 => Only show errors
    • +
  • 0 => Show warnings
    • +
  • 1/2 => Show default informational output
    • +
  • 3/4/5 => log debug information (very verbose)
    • +
+
ENABLE_DNSBL
+

This enables DNS block lists in Postscreen. If you want to know which lists we are using, have a look at the default main.cf for Postfix we provide and search for postscreen_dnsbl_sites.

+
+

A Warning On DNS Block Lists

+

Make sure your DNS queries are properly resolved, i.e. you will most likely not want to use a public DNS resolver as these queries do not return meaningful results. We try our best to only evaluate proper return codes - this is not a guarantee that all codes are handled fine though.

+

Note that emails will be rejected if they don't pass the block list checks!

+
+
    +
  • 0 => DNS block lists are disabled
    • +
  • 1 => DNS block lists are enabled
    • +
+
ENABLE_OPENDKIM
+

Enables the OpenDKIM service.

+
    +
  • 1 => Enabled
    • +
  • 0 => Disabled
    • +
+
ENABLE_OPENDMARC
+

Enables the OpenDMARC service.

+
    +
  • 1 => Enabled
    • +
  • 0 => Disabled
    • +
+
ENABLE_POP3
+
    +
  • empty => POP3 service disabled
    • +
  • 1 => Enables POP3 service
    • +
+
ENABLE_CLAMAV
+
    +
  • 0 => ClamAV is disabled
    • +
  • 1 => ClamAV is enabled
    • +
+
ENABLE_FAIL2BAN
+
    +
  • 0 => fail2ban service disabled
    • +
  • 1 => Enables fail2ban service
    • +
+

If you enable Fail2Ban, don't forget to add the following lines to your docker-compose.yml:

+
cap_add:
+  - NET_ADMIN
+
+

Otherwise, nftables won't be able to ban IPs.

+
FAIL2BAN_BLOCKTYPE
+
    +
  • drop => drop packet (send NO reply)
    • +
  • reject => reject packet (send ICMP unreachable) +FAIL2BAN_BLOCKTYPE=drop
    • +
+
SMTP_ONLY
+
    +
  • empty => all daemons start
    • +
  • 1 => only launch postfix smtp
    • +
+
SSL_TYPE
+

In the majority of cases, you want letsencrypt or manual.

+

self-signed can be used for testing SSL until you provide a valid certificate, note that third-parties cannot trust self-signed certificates, do not use this type in production. custom is a temporary workaround that is not officially supported.

+
    +
  • empty => SSL disabled.
    • +
  • letsencrypt => Support for using certificates with Let's Encrypt provisioners. (Docs: Let's Encrypt Setup)
    • +
  • manual => Provide your own certificate via separate key and cert files. (Docs: Bring Your Own Certificates)
      +
    • Requires: SSL_CERT_PATH and SSL_KEY_PATH ENV vars to be set to the location of the files within the container.
      • +
    • Optional: SSL_ALT_CERT_PATH and SSL_ALT_KEY_PATH allow providing a 2nd certificate as a fallback for dual (aka hybrid) certificate support. Useful for ECDSA with an RSA fallback. Presently only manual mode supports this feature.
      • +
    +
    • +
  • custom => Provide your own certificate as a single file containing both the private key and full certificate chain. (Docs: None)
    • +
  • self-signed => Provide your own self-signed certificate files. Expects a self-signed CA cert for verification. Use only for local testing of your setup. (Docs: Self-Signed Certificates)
    • +
+

Please read the SSL page in the documentation for more information.

+
TLS_LEVEL
+
    +
  • empty => modern
    • +
  • modern => Enables TLSv1.2 and modern ciphers only. (default)
    • +
  • intermediate => Enables TLSv1, TLSv1.1 and TLSv1.2 and broad compatibility ciphers.
    • +
+
SPOOF_PROTECTION
+

Configures the handling of creating mails with forged sender addresses.

+
    +
  • 0 => (not recommended) Mail address spoofing allowed. Any logged in user may create email messages with a forged sender address.
    • +
  • 1 => Mail spoofing denied. Each user may only send with his own or his alias addresses. Addresses with extension delimiters are not able to send messages.
    • +
+
ENABLE_SRS
+

Enables the Sender Rewriting Scheme. SRS is needed if docker-mailserver acts as forwarder. See postsrsd for further explanation.

+
    +
  • 0 => Disabled
    • +
  • 1 => Enabled
    • +
+
NETWORK_INTERFACE
+

In case your network interface differs from eth0, e.g. when you are using HostNetworking in Kubernetes, you can set this to whatever interface you want. This interface will then be used.

+
    +
  • empty => eth0
    • +
+
VIRUSMAILS_DELETE_DELAY
+

Set how many days a virusmail will stay on the server before being deleted

+
    +
  • empty => 7 days
    • +
+
POSTFIX_DAGENT
+

Configure Postfix virtual_transport to deliver mail to a different LMTP client (default is a unix socket to dovecot).

+

Provide any valid URI. Examples:

+
    +
  • empty => lmtp:unix:/var/run/dovecot/lmtp (default, configured in Postfix main.cf)
    • +
  • lmtp:unix:private/dovecot-lmtp (use socket)
    • +
  • lmtps:inet:<host>:<port> (secure lmtp with starttls)
    • +
  • lmtp:<kopano-host>:2003 (use kopano as mailstore)
    • +
+
POSTFIX_MAILBOX_SIZE_LIMIT
+

Set the mailbox size limit for all users. If set to zero, the size will be unlimited (default).

+
    +
  • empty => 0 (no limit)
    • +
+
ENABLE_QUOTAS
+
    +
  • 1 => Dovecot quota is enabled
    • +
  • 0 => Dovecot quota is disabled
    • +
+

See mailbox quota.

+
POSTFIX_MESSAGE_SIZE_LIMIT
+

Set the message size limit for all users. If set to zero, the size will be unlimited (not recommended!)

+
    +
  • empty => 10240000 (~10 MB)
    • +
+
CLAMAV_MESSAGE_SIZE_LIMIT
+

Mails larger than this limit won't be scanned. +ClamAV must be enabled (ENABLE_CLAMAV=1) for this.

+
    +
  • empty => 25M (25 MB)
    • +
+
ENABLE_MANAGESIEVE
+
    +
  • empty => Managesieve service disabled
    • +
  • 1 => Enables Managesieve on port 4190
    • +
+
POSTMASTER_ADDRESS
+ +
ENABLE_UPDATE_CHECK
+

Check for updates on container start and then once a day. If an update is available, a mail is send to POSTMASTER_ADDRESS.

+
    +
  • 0 => Update check disabled
    • +
  • 1 => Update check enabled
    • +
+
UPDATE_CHECK_INTERVAL
+

Customize the update check interval. Number + Suffix. Suffix must be 's' for seconds, 'm' for minutes, 'h' for hours or 'd' for days.

+
    +
  • 1d => Check for updates once a day
    • +
+
POSTSCREEN_ACTION
+
    +
  • enforce => Allow other tests to complete. Reject attempts to deliver mail with a 550 SMTP reply, and log the helo/sender/recipient information. Repeat this test the next time the client connects.
    • +
  • drop => Drop the connection immediately with a 521 SMTP reply. Repeat this test the next time the client connects.
    • +
  • ignore => Ignore the failure of this test. Allow other tests to complete. Repeat this test the next time the client connects. This option is useful for testing and collecting statistics without blocking mail.
    • +
+
DOVECOT_MAILBOX_FORMAT
+
    +
  • maildir => uses very common Maildir format, one file contains one message
    • +
  • sdbox => (experimental) uses Dovecot high-performance mailbox format, one file contains one message
    • +
  • mdbox ==> (experimental) uses Dovecot high-performance mailbox format, multiple messages per file and multiple files per box
    • +
+

This option has been added in November 2019. Using other format than Maildir is considered as experimental in docker-mailserver and should only be used for testing purpose. For more details, please refer to Dovecot Documentation.

+
POSTFIX_INET_PROTOCOLS
+
    +
  • all => Listen on all interfaces.
    • +
  • ipv4 => Listen only on IPv4 interfaces. Most likely you want this behind Docker.
    • +
  • ipv6 => Listen only on IPv6 interfaces.
    • +
+

Note: More details at http://www.postfix.org/postconf.5.html#inet_protocols

+
DOVECOT_INET_PROTOCOLS
+
    +
  • all => Listen on all interfaces
    • +
  • ipv4 => Listen only on IPv4 interfaces. Most likely you want this behind Docker.
    • +
  • ipv6 => Listen only on IPv6 interfaces.
    • +
+

Note: More information at https://dovecot.org/doc/dovecot-example.conf

+
MOVE_SPAM_TO_JUNK
+

When enabled, e-mails marked with the

+
    +
  1. X-Spam: Yes header added by Rspamd
    2. +
  2. X-Spam-Flag: YES header added by SpamAssassin (requires SPAMASSASSIN_SPAM_TO_INBOX=1)
    3. +
+

will be automatically moved to the Junk folder (with the help of a Sieve script).

+
    +
  • 0 => Spam messages will be delivered in the mailbox.
    • +
  • 1 => Spam messages will be delivered in the Junk folder.
    • +
+

Rspamd

+
ENABLE_RSPAMD
+

Enable or disable Rspamd.

+
+

Current State

+

Rspamd-support is under active development. Be aware that breaking changes can happen at any time. To get more information, see the detailed documentation page for Rspamd.

+
+
    +
  • 0 => disabled
    • +
  • 1 => enabled
    • +
+
ENABLE_RSPAMD_REDIS
+

Explicit control over running a Redis instance within the container. By default, this value will match what is set for ENABLE_RSPAMD.

+

The purpose of this setting is to opt-out of starting an internal Redis instance when enabling Rspamd, replacing it with your own external instance.

+
+Configuring Rspamd for an external Redis instance +

You will need to provide configuration at /etc/rspamd/local.d/redis.conf similar to:

+
servers = "redis.example.test:6379";
+expand_keys = true;
+
+
+
    +
  • 0 => Disabled
    • +
  • 1 => Enabled
    • +
+
RSPAMD_LEARN
+

When enabled,

+
    +
  1. the "autolearning" feature is turned on;
    2. +
  2. the Bayes classifier will be trained when moving mails from or to the Junk folder (with the help of Sieve scripts).
    3. +
+
+

Attention

+

As of now, the spam learning database is global (i.e. available to all users). If one user deliberately trains it with malicious data, then it will ruin your detection rate.

+

This feature is suitably only for users who can tell ham from spam and users that can be trusted.

+
+
    +
  • 0 => Disabled
    • +
  • 1 => Enabled
    • +
+

Reports

+
PFLOGSUMM_TRIGGER
+

Enables regular Postfix log summary ("pflogsumm") mail reports.

+
    +
  • not set => No report
    • +
  • daily_cron => Daily report for the previous day
    • +
  • logrotate => Full report based on the mail log when it is rotated
    • +
+

This is a new option. The old REPORT options are still supported for backwards compatibility. +If this is not set and reports are enabled with the old options, logrotate will be used.

+
PFLOGSUMM_RECIPIENT
+

Recipient address for Postfix log summary reports.

+
    +
  • not set => Use POSTMASTER_ADDRESS
    • +
  • => Specify the recipient address(es)
    • +
+
PFLOGSUMM_SENDER
+

Sender address (FROM) for pflogsumm reports (if Postfix log summary reports are enabled).

+
    +
  • not set => Use REPORT_SENDER
    • +
  • => Specify the sender address
    • +
+
LOGWATCH_INTERVAL
+

Interval for logwatch report.

+
    +
  • none => No report is generated
    • +
  • daily => Send a daily report
    • +
  • weekly => Send a report every week
    • +
+
LOGWATCH_RECIPIENT
+

Recipient address for logwatch reports if they are enabled.

+
    +
  • not set => Use REPORT_RECIPIENT or POSTMASTER_ADDRESS
    • +
  • => Specify the recipient address(es)
    • +
+
LOGWATCH_SENDER
+

Sender address (FROM) for logwatch reports if logwatch reports are enabled.

+
    +
  • not set => Use REPORT_SENDER
    • +
  • => Specify the sender address
    • +
+
REPORT_RECIPIENT
+

Defines who receives reports (if they are enabled).

+
    +
  • empty => Use POSTMASTER_ADDRESS
    • +
  • => Specify the recipient address
    • +
+
REPORT_SENDER
+

Defines who sends reports (if they are enabled).

+
    +
  • empty => mailserver-report@<YOUR DOMAIN>
    • +
  • => Specify the sender address
    • +
+
LOGROTATE_INTERVAL
+

Changes the interval in which log files are rotated.

+
    +
  • weekly => Rotate log files weekly
    • +
  • daily => Rotate log files daily
    • +
  • monthly => Rotate log files monthly
    • +
+
+

Note

+

LOGROTATE_INTERVAL only manages logrotate within the container for services we manage internally.

+

The entire log output for the container is still available via docker logs mailserver (or your respective container name). If you want to configure external log rotation for that container output as well, : Docker Logging Drivers.

+

By default, the logs are lost when the container is destroyed (eg: re-creating via docker-compose down && docker-compose up -d). To keep the logs, mount a volume (to /var/log/mail/).

+
+
+

Note

+

This variable can also determine the interval for Postfix's log summary reports, see PFLOGSUMM_TRIGGER.

+
+

SpamAssassin

+
ENABLE_SPAMASSASSIN
+
    +
  • 0 => SpamAssassin is disabled
    • +
  • 1 => SpamAssassin is enabled
    • +
+
SPAMASSASSIN_SPAM_TO_INBOX
+
    +
  • 0 => Spam messages will be bounced (rejected) without any notification (dangerous).
    • +
  • 1 => Spam messages will be delivered to the inbox and tagged as spam using SA_SPAM_SUBJECT.
    • +
+
ENABLE_SPAMASSASSIN_KAM
+

KAM is a 3rd party SpamAssassin ruleset, provided by the McGrail Foundation. If SpamAssassin is enabled, KAM can be used in addition to the default ruleset.

+
    +
  • 0 => KAM disabled
    • +
  • 1 => KAM enabled
    • +
+
SA_TAG
+
    +
  • 2.0 => add spam info headers if at, or above that level
    • +
+

Note: this SpamAssassin setting needs ENABLE_SPAMASSASSIN=1

+
SA_TAG2
+
    +
  • 6.31 => add 'spam detected' headers at that level
    • +
+

Note: this SpamAssassin setting needs ENABLE_SPAMASSASSIN=1

+
SA_KILL
+
    +
  • 10.0 => triggers spam evasive actions
    • +
+
+

This SpamAssassin setting needs ENABLE_SPAMASSASSIN=1

+

By default, docker-mailserver is configured to quarantine spam emails.

+

If emails are quarantined, they are compressed and stored in a location dependent on the ONE_DIR setting above. To inhibit this behaviour and deliver spam emails, set this to a very high value e.g. 100.0.

+

If ONE_DIR=1 (default) the location is /var/mail-state/lib-amavis/virusmails/, or if ONE_DIR=0: /var/lib/amavis/virusmails/. These paths are inside the docker container.

+
+
SA_SPAM_SUBJECT
+
    +
  • ***SPAM*** => add tag to subject if spam detected
    • +
+

Note: this SpamAssassin setting needs ENABLE_SPAMASSASSIN=1. Add the SpamAssassin score to the subject line by inserting the keyword _SCORE_: ***SPAM(_SCORE_)***.

+
SA_SHORTCIRCUIT_BAYES_SPAM
+
    +
  • 1 => will activate SpamAssassin short circuiting for bayes spam detection.
    • +
+

This will uncomment the respective line in /etc/spamassasin/local.cf

+

Note: activate this only if you are confident in your bayes database for identifying spam.

+
SA_SHORTCIRCUIT_BAYES_HAM
+
    +
  • 1 => will activate SpamAssassin short circuiting for bayes ham detection
    • +
+

This will uncomment the respective line in /etc/spamassasin/local.cf

+

Note: activate this only if you are confident in your bayes database for identifying ham.

+

Fetchmail

+
ENABLE_FETCHMAIL
+
    +
  • 0 => fetchmail disabled
    • +
  • 1 => fetchmail enabled
    • +
+
FETCHMAIL_POLL
+
    +
  • 300 => fetchmail The number of seconds for the interval
    • +
+
FETCHMAIL_PARALLEL
+

0 => fetchmail runs with a single config file /etc/fetchmailrc + 1 => /etc/fetchmailrc is split per poll entry. For every poll entry a separate fetchmail instance is started to allow having multiple imap idle configurations defined.

+

Note: The defaults of your fetchmailrc file need to be at the top of the file. Otherwise it won't be added correctly to all separate fetchmail instances.

+

LDAP

+
ENABLE_LDAP
+

Deprecated. See ACCOUNT_PROVISIONER.

+
LDAP_START_TLS
+
    +
  • empty => no
    • +
  • yes => LDAP over TLS enabled for Postfix
    • +
+
LDAP_SERVER_HOST
+
    +
  • empty => mail.example.com
    • +
  • => Specify the dns-name/ip-address where the ldap-server is listening, or an URI like ldaps://mail.example.com
    • +
  • NOTE: If you going to use docker-mailserver in combination with docker-compose.yml you can set the service name here
    • +
+
LDAP_SEARCH_BASE
+
    +
  • empty => ou=people,dc=domain,dc=com
    • +
  • => e.g. LDAP_SEARCH_BASE=dc=mydomain,dc=local
    • +
+
LDAP_BIND_DN
+
    +
  • empty => cn=admin,dc=domain,dc=com
    • +
  • => take a look at examples of SASL_LDAP_BIND_DN
    • +
+
LDAP_BIND_PW
+
    +
  • empty => admin
    • +
  • => Specify the password to bind against ldap
    • +
+
LDAP_QUERY_FILTER_USER
+
    +
  • e.g. (&(mail=%s)(mailEnabled=TRUE))
    • +
  • => Specify how ldap should be asked for users
    • +
+
LDAP_QUERY_FILTER_GROUP
+
    +
  • e.g. (&(mailGroupMember=%s)(mailEnabled=TRUE))
    • +
  • => Specify how ldap should be asked for groups
    • +
+
LDAP_QUERY_FILTER_ALIAS
+
    +
  • e.g. (&(mailAlias=%s)(mailEnabled=TRUE))
    • +
  • => Specify how ldap should be asked for aliases
    • +
+
LDAP_QUERY_FILTER_DOMAIN
+
    +
  • e.g. (&(|(mail=*@%s)(mailalias=*@%s)(mailGroupMember=*@%s))(mailEnabled=TRUE))
    • +
  • => Specify how ldap should be asked for domains
    • +
+
LDAP_QUERY_FILTER_SENDERS
+
    +
  • empty => use user/alias/group maps directly, equivalent to (|($LDAP_QUERY_FILTER_USER)($LDAP_QUERY_FILTER_ALIAS)($LDAP_QUERY_FILTER_GROUP))
    • +
  • => Override how ldap should be asked if a sender address is allowed for a user
    • +
+
DOVECOT_TLS
+
    +
  • empty => no
    • +
  • yes => LDAP over TLS enabled for Dovecot
    • +
+

Dovecot

+

The following variables overwrite the default values for /etc/dovecot/dovecot-ldap.conf.ext.

+
DOVECOT_BASE
+
    +
  • empty => same as LDAP_SEARCH_BASE
    • +
  • => Tell Dovecot to search only below this base entry. (e.g. ou=people,dc=domain,dc=com)
    • +
+
DOVECOT_DEFAULT_PASS_SCHEME
+
    +
  • empty => SSHA
    • +
  • => Select one crypt scheme for password hashing from this list of password schemes.
    • +
+
DOVECOT_DN
+
    +
  • empty => same as LDAP_BIND_DN
    • +
  • => Bind dn for LDAP connection. (e.g. cn=admin,dc=domain,dc=com)
    • +
+
DOVECOT_DNPASS
+
    +
  • empty => same as LDAP_BIND_PW
    • +
  • => Password for LDAP dn sepecifified in DOVECOT_DN.
    • +
+
DOVECOT_URIS
+
    +
  • empty => same as LDAP_SERVER_HOST
    • +
  • => Specify a space separated list of LDAP uris.
    • +
  • Note: If the protocol is missing, ldap:// will be used.
    • +
  • Note: This deprecates DOVECOT_HOSTS (as it didn't allow to use LDAPS), which is currently still supported for backwards compatibility.
    • +
+
DOVECOT_LDAP_VERSION
+
    +
  • empty => 3
    • +
  • 2 => LDAP version 2 is used
    • +
  • 3 => LDAP version 3 is used
    • +
+
DOVECOT_AUTH_BIND
+ +
DOVECOT_USER_FILTER
+
    +
  • e.g. (&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
    • +
+
DOVECOT_USER_ATTRS
+
    +
  • e.g. homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail
    • +
  • => Specify the directory to dovecot attribute mapping that fits your directory structure.
    • +
  • Note: This is necessary for directories that do not use the Postfix Book Schema.
    • +
  • Note: The left-hand value is the directory attribute, the right hand value is the dovecot variable.
    • +
  • More details on the Dovecot Wiki
    • +
+
DOVECOT_PASS_FILTER
+
    +
  • e.g. (&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
    • +
  • empty => same as DOVECOT_USER_FILTER
    • +
+
DOVECOT_PASS_ATTRS
+
    +
  • e.g. uid=user,userPassword=password
    • +
  • => Specify the directory to dovecot variable mapping that fits your directory structure.
    • +
  • Note: This is necessary for directories that do not use the Postfix Book Schema.
    • +
  • Note: The left-hand value is the directory attribute, the right hand value is the dovecot variable.
    • +
  • More details on the Dovecot Wiki
    • +
+

Postgrey

+
ENABLE_POSTGREY
+
    +
  • 0 => postgrey is disabled
    • +
  • 1 => postgrey is enabled
    • +
+
POSTGREY_DELAY
+
    +
  • 300 => greylist for N seconds
    • +
+

Note: This postgrey setting needs ENABLE_POSTGREY=1

+
POSTGREY_MAX_AGE
+
    +
  • 35 => delete entries older than N days since the last time that they have been seen
    • +
+

Note: This postgrey setting needs ENABLE_POSTGREY=1

+
POSTGREY_AUTO_WHITELIST_CLIENTS
+
    +
  • 5 => whitelist host after N successful deliveries (N=0 to disable whitelisting)
    • +
+

Note: This postgrey setting needs ENABLE_POSTGREY=1

+
POSTGREY_TEXT
+
    +
  • Delayed by Postgrey => response when a mail is greylisted
    • +
+

Note: This postgrey setting needs ENABLE_POSTGREY=1

+

SASL Auth

+
ENABLE_SASLAUTHD
+
    +
  • 0 => saslauthd is disabled
    • +
  • 1 => saslauthd is enabled
    • +
+
SASLAUTHD_MECHANISMS
+
    +
  • empty => pam
    • +
  • ldap => authenticate against ldap server
    • +
  • shadow => authenticate against local user db
    • +
  • mysql => authenticate against mysql db
    • +
  • rimap => authenticate against imap server
    • +
  • NOTE: can be a list of mechanisms like pam ldap shadow
    • +
+
SASLAUTHD_MECH_OPTIONS
+
    +
  • empty => None
    • +
  • e.g. with SASLAUTHD_MECHANISMS rimap you need to specify the ip-address/servername of the imap server ==> xxx.xxx.xxx.xxx
    • +
+
SASLAUTHD_LDAP_SERVER
+
    +
  • empty => same as LDAP_SERVER_HOST
    • +
  • Note: since version 10.0.0, you can specify a protocol here (like ldaps://); this deprecates SASLAUTHD_LDAP_SSL.
    • +
+
SASLAUTHD_LDAP_START_TLS
+
    +
  • empty => no
    • +
  • yes => Enable ldap_start_tls option
    • +
+
SASLAUTHD_LDAP_TLS_CHECK_PEER
+
    +
  • empty => no
    • +
  • yes => Enable ldap_tls_check_peer option
    • +
+
SASLAUTHD_LDAP_TLS_CACERT_DIR
+

Path to directory with CA (Certificate Authority) certificates.

+
    +
  • empty => Nothing is added to the configuration
    • +
  • Any value => Fills the ldap_tls_cacert_dir option
    • +
+
SASLAUTHD_LDAP_TLS_CACERT_FILE
+

File containing CA (Certificate Authority) certificate(s).

+
    +
  • empty => Nothing is added to the configuration
    • +
  • Any value => Fills the ldap_tls_cacert_file option
    • +
+
SASLAUTHD_LDAP_BIND_DN
+
    +
  • empty => same as LDAP_BIND_DN
    • +
  • specify an object with privileges to search the directory tree
    • +
  • e.g. active directory: SASLAUTHD_LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=net
    • +
  • e.g. openldap: SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=mydomain,dc=net
    • +
+
SASLAUTHD_LDAP_PASSWORD
+
    +
  • empty => same as LDAP_BIND_PW
    • +
+
SASLAUTHD_LDAP_SEARCH_BASE
+
    +
  • empty => same as LDAP_SEARCH_BASE
    • +
  • specify the search base
    • +
+
SASLAUTHD_LDAP_FILTER
+
    +
  • empty => default filter (&(uniqueIdentifier=%u)(mailEnabled=TRUE))
    • +
  • e.g. for active directory: (&(sAMAccountName=%U)(objectClass=person))
    • +
  • e.g. for openldap: (&(uid=%U)(objectClass=person))
    • +
+
SASLAUTHD_LDAP_PASSWORD_ATTR
+

Specify what password attribute to use for password verification.

+
    +
  • empty => Nothing is added to the configuration but the documentation says it is userPassword by default.
    • +
  • Any value => Fills the ldap_password_attr option
    • +
+
SASLAUTHD_LDAP_AUTH_METHOD
+
    +
  • empty => bind will be used as a default value
    • +
  • fastbind => The fastbind method is used
    • +
  • custom => The custom method uses userPassword attribute to verify the password
    • +
+
SASLAUTHD_LDAP_MECH
+

Specify the authentication mechanism for SASL bind.

+
    +
  • empty => Nothing is added to the configuration
    • +
  • Any value => Fills the ldap_mech option
    • +
+

SRS (Sender Rewriting Scheme)

+
SRS_SENDER_CLASSES
+

An email has an "envelope" sender (indicating the sending server) and a +"header" sender (indicating who sent it). More strict SPF policies may require +you to replace both instead of just the envelope sender.

+

More info.

+
    +
  • envelope_sender => Rewrite only envelope sender address
    • +
  • header_sender => Rewrite only header sender (not recommended)
    • +
  • envelope_sender,header_sender => Rewrite both senders
    • +
+
SRS_EXCLUDE_DOMAINS
+
    +
  • empty => Envelope sender will be rewritten for all domains
    • +
  • provide comma separated list of domains to exclude from rewriting
    • +
+
SRS_SECRET
+
    +
  • empty => generated when the container is started for the first time
    • +
  • provide a secret to use in base64
    • +
  • you may specify multiple keys, comma separated. the first one is used for signing and the remaining will be used for verification. this is how you rotate and expire keys
    • +
  • if you have a cluster/swarm make sure the same keys are on all nodes
    • +
  • example command to generate a key: dd if=/dev/urandom bs=24 count=1 2>/dev/null | base64
    • +
+
SRS_DOMAINNAME
+
    +
  • empty => Derived from OVERRIDE_HOSTNAME, $DOMAINNAME (internal), or the container's hostname
    • +
  • Set this if auto-detection fails, isn't what you want, or you wish to have a separate container handle DSNs
    • +
+

Default Relay Host

+
DEFAULT_RELAY_HOST
+
    +
  • empty => don't set default relayhost setting in main.cf
    • +
  • default host and port to relay all mail through. + Format: [example.com]:587 (don't forget the brackets if you need this to + be compatible with $RELAY_USER and $RELAY_PASSWORD, explained below).
    • +
+

Multi-domain Relay Hosts

+
RELAY_HOST
+
    +
  • empty => don't configure relay host
    • +
  • default host to relay mail through
    • +
+
RELAY_PORT
+
    +
  • empty => 25
    • +
  • default port to relay mail through
    • +
+
RELAY_USER
+
    +
  • empty => no default
    • +
  • default relay username (if no specific entry exists in postfix-sasl-password.cf)
    • +
+
RELAY_PASSWORD
+
    +
  • empty => no default
    • +
  • password for default relay user
    • +
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/pop3/index.html b/v12.0/config/pop3/index.html new file mode 100644 index 00000000..41ba5740 --- /dev/null +++ b/v12.0/config/pop3/index.html @@ -0,0 +1,1511 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mail Delivery with POP3 - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Mail Delivery with POP3

+ +

If you want to use POP3(S), you have to add the ports 110 and/or 995 (TLS secured) and the environment variable ENABLE_POP3 to your docker-compose.yml:

+
mailserver:
+  ports:
+    - "25:25"    # SMTP  (explicit TLS => STARTTLS)
+    - "143:143"  # IMAP4 (explicit TLS => STARTTLS)
+    - "465:465"  # ESMTP (implicit TLS)
+    - "587:587"  # ESMTP (explicit TLS => STARTTLS)
+    - "993:993"  # IMAP4 (implicit TLS)
+    - "110:110"  # POP3
+    - "995:995"  # POP3 (with TLS)
+  environment:
+    - ENABLE_POP3=1
+
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/security/fail2ban/index.html b/v12.0/config/security/fail2ban/index.html new file mode 100644 index 00000000..2627b2cb --- /dev/null +++ b/v12.0/config/security/fail2ban/index.html @@ -0,0 +1,1748 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Security | Fail2Ban - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Fail2Ban

+ +

Fail2Ban is installed automatically and bans IP addresses for 3 hours after 3 failed attempts in 10 minutes by default.

+

Configuration files

+

If you want to change this, you can easily edit our github example file: config-examples/fail2ban-jail.cf.

+

You can do the same with the values from fail2ban.conf, e.g dbpurgeage. In that case you need to edit: config-examples/fail2ban-fail2ban.cf.

+

The configuration files need to be located at the root of the /tmp/docker-mailserver/ volume bind (usually ./docker-data/dms/config/:/tmp/docker-mailserver/).

+

This following configuration files from /tmp/docker-mailserver/ will be copied during container startup.

+
    +
  • fail2ban-jail.cf -> /etc/fail2ban/jail.d/user-jail.local
    • +
  • fail2ban-fail2ban.cf -> /etc/fail2ban/fail2ban.local
    • +
+

Docker-compose config

+

Example configuration volume bind:

+
    volumes:
+      - ./docker-data/dms/config/:/tmp/docker-mailserver/
+
+
+

Attention

+

docker-mailserver must be launched with the NET_ADMIN capability in order to be able to install the nftables rules that actually ban IP addresses.

+

Thus either include --cap-add=NET_ADMIN in the docker run command, or the equivalent in docker-compose.yml:

+
cap_add:
+  - NET_ADMIN
+
+
+

Running fail2ban in a rootless container

+

RootlessKit is the fakeroot implementation for supporting rootless mode in Docker and Podman. By default RootlessKit uses the builtin port forwarding driver, which does not propagate source IP addresses.

+

It is necessary for fail2ban to have access to the real source IP addresses in order to correctly identify clients. This is achieved by changing the port forwarding driver to slirp4netns, which is slower than builtin but does preserve the real source IPs.

+

Docker with slirp4netns port driver

+

For rootless mode in Docker, create ~/.config/systemd/user/docker.service.d/override.conf with the following content:

+
[Service]
+Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"
+
+

And then restart the daemon:

+
$ systemctl --user daemon-reload
+$ systemctl --user restart docker
+
+
+

Note

+

This changes the port driver for all rootless containers managed by Docker.

+

Per container configuration is not supported, if you need that consider Podman instead.

+
+

Podman with slirp4netns port driver

+

Rootless Podman requires adding the value slirp4netns:port_handler=slirp4netns to the --network CLI option, or network_mode setting in your docker-compose.yml.

+

You must also add the ENV NETWORK_INTERFACE=tap0, because Podman uses a hard-coded interface name for slirp4netns.

+
+

Example

+
services:
+  mailserver:
+    network_mode: "slirp4netns:port_handler=slirp4netns"
+    environment:
+      - ENABLE_FAIL2BAN=1
+      - NETWORK_INTERFACE=tap0
+      ...
+
+
+
+

Note

+

slirp4netns is not compatible with user-defined networks.

+
+

Manage bans

+

You can also manage and list the banned IPs with the setup.sh script.

+

List bans

+
./setup.sh fail2ban
+
+

Un-ban

+

Here 192.168.1.15 is our banned IP.

+
./setup.sh fail2ban unban 192.168.1.15
+
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/security/mail_crypt/index.html b/v12.0/config/security/mail_crypt/index.html new file mode 100644 index 00000000..1daec571 --- /dev/null +++ b/v12.0/config/security/mail_crypt/index.html @@ -0,0 +1,1599 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Security | mail_crypt (email/storage encryption) - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Mail Encryption

+ +
+

Info

+

The Mail crypt plugin is used to secure email messages stored in a Dovecot system. Messages are encrypted before written to storage and decrypted after reading. Both operations are transparent to the user.

+

In case of unauthorized access to the storage backend, the messages will, without access to the decryption keys, be unreadable to the offending party.

+

There can be a single encryption key for the whole system or each user can have a key of their own. The used cryptographical methods are widely used standards and keys are stored in portable formats, when possible.

+
+

Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/

+
+

Single Encryption Key / Global Method

+
    +
  1. +

    Create 10-custom.conf and populate it with the following:

    +
    # Enables mail_crypt for all services (imap, pop3, etc)
+mail_plugins = $mail_plugins mail_crypt
+plugin {
+  mail_crypt_global_private_key = </certs/ecprivkey.pem
+  mail_crypt_global_public_key = </certs/ecpubkey.pem
+  mail_crypt_save_version = 2
+}
+
    +
    2. +
  2. +

    Shutdown your mailserver (docker-compose down)

    +
    3. +
  3. +

    You then need to generate your global EC key. We named them /certs/ecprivkey.pem and /certs/ecpubkey.pem in step #1.

    +
    4. +
  4. +

    The EC key needs to be available in the container. I prefer to mount a /certs directory into the container: + 

    services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    volumes:
+    . . .
+      - ./certs/:/certs
+    . . .
+

    +
    5. +
  5. +

    While you're editing the docker-compose.yml, add the configuration file: + 

    services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    volumes:
+    . . .
+      - ./config/dovecot/10-custom.conf:/etc/dovecot/conf.d/10-custom.conf
+      - ./certs/:/certs
+    . . .
+

    +
    6. +
  6. +

    Start the container, monitor the logs for any errors, send yourself a message, and then confirm the file on disk is encrypted: + 

    [root@ip-XXXXXXXXXX ~]# cat -A /mnt/efs-us-west-2/maildata/awesomesite.com/me/cur/1623989305.M6v�z�@�� m}��,��9����B*�247.us-west-2.compute.inE��\Ck*�@7795,W=7947:2,
+T�9�8t�6�� t���e�W��S   `�H��C�ڤ �yeY��XZ��^�d�/��+�A
+

    +
    7. +
+

This should be the minimum required for encryption of the mail while in storage.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/security/rspamd/index.html b/v12.0/config/security/rspamd/index.html new file mode 100644 index 00000000..854c56ac --- /dev/null +++ b/v12.0/config/security/rspamd/index.html @@ -0,0 +1,1974 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Security | Rspamd - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Rspamd

+ +
+

The current state of Rspamd integration into DMS

+

Recent pull requests have stabilized integration of Rspamd to a point that we encourage users to test the feature. We are confident that there are no major bugs in our integration that make using Rspamd infeasible. Please note that there may still be (breaking) changes ahead as integration is still work in progress!

+

We expect to stabilize this feature with version v12.1.0.

+
+

About

+

Rspamd is a "fast, free and open-source spam filtering system". DMS integrates Rspamd like any other service. We provide a very simple but easy to maintain setup of Rspamd.

+

If you want to have a look at the default configuration files for Rspamd that DMS packs, navigate to target/rspamd/ inside the repository. Please consult the section "The Default Configuration" section down below for a written overview.

+
+

AMD64 vs ARM64

+

We are currently doing a best-effort installation of Rspamd for ARM64 (from the Debian backports repository for Debian 11). The current version difference is two minor versions (AMD64 is at version 3.4, ARM64 at 3.2 [13th Feb 2023]).

+

Maintainers noticed only few differences, some of them with a big impact though. For those running Rspamd on ARM64, we recommend disabling the DKIM signing module if you don't use it.

+
+

The following environment variables are related to Rspamd:

+
    +
  1. ENABLE_RSPAMD
    2. +
  2. ENABLE_RSPAMD_REDIS
    3. +
  3. RSPAMD_LEARN
    4. +
  4. MOVE_SPAM_TO_JUNK
    5. +
+

The Default Configuration

+

Mode of Operation

+

The proxy worker operates in self-scan mode. This simplifies the setup as we do not require a normal worker. You can easily change this though by overriding the configuration by DMS.

+

DMS does not set a default password for the controller worker. You may want to do that yourself. In setups where you already have an authentication provider in front of the Rspamd webpage, you may want to set the secure_ip option to "0.0.0.0/0" for the controller worker to disable password authentication inside Rspamd completely.

+

Persistence with Redis

+

When Rspamd is enabled, we implicitly also start an instance of Redis in the container. Redis is configured to persist it's data via RDB snapshots to disk in the directory /var/lib/redis (which is a symbolic link to /var/mail-state/lib-redis/ when ONE_DIR=1 and a volume is mounted to /var/mail-state/). With the volume mount the snapshot will restore the Redis data across container restarts, and provide a way to keep backup.

+

Redis uses /etc/redis/redis.conf for configuration. We adjust this file when enabling the internal Redis service. If you have an external instance of Redis to use, the internal Redis service can be opt-out via setting the ENV ENABLE_RSPAMD_REDIS=0 (link also details required changes to the DMS rspamd config).

+

Modules

+

You can find a list of all Rspamd modules on their website.

+

Disabled By Default

+

DMS disables certain modules (clickhouse, elastic, greylist, neural, reputation, spamassassin, url_redirector, metric_exporter) by default. We believe these are not required in a standard setup, and they would otherwise needlessly use system resources.

+

Anti-Virus (ClamAV)

+

You can choose to enable ClamAV, and Rspamd will then use it to check for viruses. Just set the environment variable ENABLE_CLAMAV=1.

+

RBLs (Realtime Blacklists) / DNSBLs (DNS-based Blacklists)

+

The RBL module is enabled by default. As a consequence, Rspamd will perform DNS lookups to a variety of blacklists. Whether an RBL or a DNSBL is queried depends on where the domain name was obtained: RBL servers are queried with IP addresses extracted from message headers, DNSBL server are queried with domains and IP addresses extracted from the message body [source].

+
+

Rspamd and DNS Block Lists

+

When the RBL module is enabled, Rspamd will do a variety of DNS requests to (amongst other things) DNSBLs. There are a variety of issues involved when using DNSBLs. Rspamd will try to mitigate some of them by properly evaluating all return codes. This evaluation is a best effort though, so if the DNSBL operators change or add return codes, it may take a while for Rspamd to adjust as well.

+

If you want to use DNSBLs, try to use your own DNS resolver and make sure it is set up correctly, i.e. it should be a non-public & recursive resolver. Otherwise, you might not be able (see this Spamhaus post) to make use of the block lists.

+
+

Providing Custom Settings & Overriding Settings

+

Manually

+

DMS brings sane default settings for Rspamd. They are located at /etc/rspamd/local.d/ inside the container (or target/rspamd/local.d/ in the repository). If you want to change these settings and / or provide your own settings, you can

+
    +
  1. place files at /etc/rspamd/override.d/ which will override Rspamd settings and DMS settings
    2. +
  2. (re-)place files at /etc/rspamd/local.d/ to override DMS settings and merge them with Rspamd settings
    3. +
+
+

Clashing Overrides

+

Note that when also using the rspamd-commands file, files in override.d may be overwritten in case you adjust them manually and with the help of the file.

+
+

With the Help of a Custom File

+

DMS provides the ability to do simple adjustments to Rspamd modules with the help of a single file. Just place a file called rspamd-modules.conf into the directory docker-data/dms/config/ (which translates to /tmp/docker-mailserver/ in the container). If this file is present, DMS will evaluate it. The structure is very simple. Each line in the file looks like this:

+
COMMAND ARGUMENT1 ARGUMENT2 ARGUMENT3
+
+

where COMMAND can be:

+
    +
  1. disable-module: disables the module with name ARGUMENT1
    2. +
  2. enable-module: explicitly enables the module with name ARGUMENT1
    3. +
  3. set-option-for-module: sets the value for option ARGUMENT2 to ARGUMENT3 inside module ARGUMENT1
    4. +
  4. set-option-for-controller: set the value of option ARGUMENT1 to ARGUMENT2 for the controller worker
    5. +
  5. set-option-for-proxy: set the value of option ARGUMENT1 to ARGUMENT2 for the proxy worker
    6. +
  6. set-common-option: set the option ARGUMENT1 that defines basic Rspamd behaviour to value ARGUMENT2
    7. +
  7. add-line: this will add the complete line after ARGUMENT1 (with all characters) to the file /etc/rspamd/override.d/<ARGUMENT1>
    8. +
+
+

An Example Is Shown Down Below

+
+
+

File Names & Extensions

+

For command 1 - 3, we append the .conf suffix to the module name to get the correct file name automatically. For commands 4 - 6, the file name is fixed (you don't even need to provide it). For command 7, you will need to provide the whole file name (including the suffix) yourself!

+
+

You can also have comments (the line starts with #) and blank lines in rspamd-modules.conf - they are properly handled and not evaluated.

+
+

Adjusting Modules This Way

+

These simple commands are meant to give users the ability to easily alter modules and their options. As a consequence, they are not powerful enough to enable multi-line adjustments. If you need to do something more complex, we advise to do that manually!

+
+

Examples & Advanced Configuration

+

A Very Basic Configuration

+

You want to start using Rspamd? Rspamd is disabled by default, so you need to set the following environment variables:

+
ENABLE_RSPAMD=1
+ENABLE_OPENDKIM=0
+ENABLE_OPENDMARC=0
+ENABLE_AMAVIS=0
+ENABLE_SPAMASSASSIN=0
+
+

This will enable Rspamd and disable services you don't need when using Rspamd. Note that with this setup, the default DKIM signing that DMS provides does not work (as it is disabled)! To solve this issue, look at this subsection.

+

Adjusting and Extending The Very Basic Configuration

+

Rspamd is running, but you want or need to adjust it?

+
    +
  1. Say you want to be able to easily look at the frontend Rspamd provides on port 11334 (default) without the need to enter a password (maybe because you already provide authorization and authentication). You will need to adjust the controller worker: create a file called rspamd-modules.conf and add the line set-option-for-controller secure_ip "0.0.0.0/0". Place the file rspamd-modules.conf inside the directory on the host you mount to /tmp/docker-mailserver/ inside the container (in our documentation, we use docker-data/dms/config on the host for this purpose). And you're done! Note: this disables authentication on the website - make sure you know what you're doing!
    2. +
  2. You additionally want to enable the auto-spam-learning for the Bayes module? No problem, just add another line to rspamd-modules.conf that looks like this: set-option-for-module classifier-bayes autolearn true.
    3. +
  3. But the chartable module gets on your nerves? Just disable it by adding another line: disable-module chartable.
    4. +
+

DKIM Signing

+

By default, DMS offers no option to generate and configure signing e-mails with DKIM. This is because the parsing would be difficult. But don't worry: the process is relatively straightforward nevertheless. The official Rspamd documentation for the DKIM signing module is pretty good. Basically, you need to

+
    +
  1. exec into the container
    2. +
  2. Run a command similar to rspamadm dkim_keygen -s 'woosh' -b 2048 -d example.com -k example.private > example.txt, adjusted to your needs
    3. +
  3. Make sure to then persists the files example.private and example.txt (created in step 2) in the container (for example with a Docker bind mount)
    4. +
  4. Create a configuration for the DKIM signing module, i.e. a file called dkim_signing.conf that you mount to /etc/rspamd/local.d/ or /etc/rspamd/override.d/. We provide example configurations down below. We recommend mounting this file into the container as well (as described here); do not use rspamd-modules.conf for this purpose.
    5. +
+
+DKIM Signing Module Configuration Examples +

A simple configuration could look like this:

+
# documentation: https://rspamd.com/doc/modules/dkim_signing.html
+
+enabled = true;
+
+sign_authenticated = true;
+sign_local = true;
+
+use_domain = "header";
+use_redis = false; # don't change unless Redis also provides the DKIM keys
+use_esld = true;
+check_pubkey = true;
+
+domain {
+    example.com {
+        path = "/path/to/example.private";
+        selector = "woosh";
+    }
+}
+
+

If you have multiple domains and you want to sign with the modern ED25519 elliptic curve but also with RSA (you will likely want to have RSA as a fallback!):

+
# documentation: https://rspamd.com/doc/modules/dkim_signing.html
+
+enabled = true;
+
+sign_authenticated = true;
+sign_local = true;
+
+use_domain = "header";
+use_redis = false; # don't change unless Redis also provides the DKIM keys
+use_esld = true;
+check_pubkey = true;
+
+domain {
+    example.com {
+        selectors [
+            {
+                path = "/path/to/com.example.rsa.private";
+                selector = "dkim-rsa";
+            },
+            {
+              path = /path/to/com.example.ed25519.private";
+              selector = "dkim-ed25519";
+            }
+      ]
+    }
+    example.org {
+        selectors [
+            {
+                path = "/path/to/org.example.rsa.private";
+                selector = "dkim-rsa";
+            },
+            {
+              path = "/path/to/org.example.ed25519.private";
+              selector = "dkim-ed25519";
+            }
+        ]
+    }
+}
+
+
+

Abusix Integration

+

This subsection gives information about the integration of Abusix, "a set of blocklists that work as an additional email security layer for your existing mail environment". The setup is straight-forward and well documented:

+
    +
  1. Create an account
    2. +
  2. Retrieve your API key
    3. +
  3. Navigate to the "Getting Started" documentation for Rspamd and follow the steps described there
    4. +
  4. Make sure to change <APIKEY> to your private API key
    5. +
+

We recommend mounting the files directly into the container, as they are rather big and not manageable with the modules script. If mounted to the correct location, Rspamd will automatically pick them up.

+

While Abusix can be integrated into Postfix, Postscreen and a multitude of other software, we recommend integrating Abusix only into a single piece of software running in your mail server - everything else would be excessive and wasting queries. Moreover, we recommend the integration into suitable filtering software and not Postfix itself, as software like Postscreen or Rspamd can properly evaluate the return codes and other configuration.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/security/ssl/index.html b/v12.0/config/security/ssl/index.html new file mode 100644 index 00000000..5e59fdd6 --- /dev/null +++ b/v12.0/config/security/ssl/index.html @@ -0,0 +1,2559 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Security | TLS (aka SSL) - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

SSL/TLS

+ +

There are multiple options to enable SSL (via SSL_TYPE):

+ +

After installation, you can test your setup with:

+ +
+

Exposure of DNS labels through Certificate Transparency

+

All public Certificate Authorities (CAs) are required to log certificates they issue publicly via Certificate Transparency. This helps to better establish trust.

+

When using a public CA for certificates used in private networks, be aware that the associated DNS labels in the certificate are logged publicly and easily searchable. These logs are append only, you cannot redact this information.

+

You could use a wildcard certificate. This avoids accidentally leaking information to the internet, but keep in mind the potential security risks of wildcard certs.

+
+

The FQDN

+

An FQDN (Fully Qualified Domain Name) such as mail.example.com is required for docker-mailserver to function correctly, especially for looking up the correct SSL certificate to use.

+
    +
  • mail.example.com will still use user@example.com as the mail address. You do not need a bare domain for that.
    • +
  • We usually discourage assigning a bare domain (When your DNS MX record does not point to a subdomain) to represent docker-mailserver. However, an FQDN of just example.com is also supported.
    • +
  • Internally, hostname -f will be used to retrieve the FQDN as configured in the below examples.
    • +
  • Wildcard certificates (eg: *.example.com) are supported for SSL_TYPE=letsencrypt. Your configured FQDN below may be mail.example.com, and your wildcard certificate provisioned to /etc/letsencrypt/live/example.com which will be checked as a fallback FQDN by docker-mailserver.
    • +
+
+

Setting the hostname correctly

+

Change mail.example.com below to your own FQDN.

+
# CLI:
+docker run --hostname mail.example.com
+
+

or

+
# docker-compose.yml
+services:
+  mailserver:
+    hostname: mail.example.com
+
+
+

Provisioning methods

+ +

To enable Let's Encrypt for docker-mailserver, you have to:

+
    +
  1. Get your certificate using the Let's Encrypt client Certbot.
    2. +
  2. +

    For your docker-mailserver container:

    + +
    3. +
+

You don't have to do anything else. Enjoy!

+
+

Note

+

/etc/letsencrypt/live stores provisioned certificates in individual folders named by their FQDN.

+

Make sure that the entire folder is mounted to docker-mailserver as there are typically symlinks from /etc/letsencrypt/live/mail.example.com to /etc/letsencrypt/archive.

+
+
+

Example

+

Add these additions to the mailserver service in your docker-compose.yml:

+
services:
+  mailserver:
+    hostname: mail.example.com
+    environment:
+      - SSL_TYPE=letsencrypt
+    volumes:
+      - /etc/letsencrypt:/etc/letsencrypt
+
+
+

Example using Docker for Let's Encrypt

+

Certbot provisions certificates to /etc/letsencrypt. Add a volume to store these, so that they can later be accessed by docker-mailserver container. You may also want to persist Certbot logs, just in case you need to troubleshoot.

+
    +
  1. +

    Getting a certificate is this simple! (Referencing: Certbot docker instructions and certonly --standalone mode):

    +
    # Requires access to port 80 from the internet, adjust your firewall if needed.
+docker run --rm -it \
+  -v "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
+  -v "${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/" \
+  -p 80:80 \
+  certbot/certbot certonly --standalone -d mail.example.com
+
    +
    2. +
  2. +

    Add a volume for docker-mailserver that maps the local certbot/certs/ folder to the container path /etc/letsencrypt/.

    +
    +

    Example

    +

    Add these additions to the mailserver service in your docker-compose.yml:

    +
    services:
+  mailserver:
+    hostname: mail.example.com
+    environment:
+      - SSL_TYPE=letsencrypt
+    volumes:
+      - ./docker-data/certbot/certs/:/etc/letsencrypt
+
    +
    +
    3. +
  3. +

    The certificate setup is complete, but remember it will expire. Consider automating renewals.

    +
    4. +
+
+

Renewing Certificates

+

When running the above certonly --standalone snippet again, the existing certificate is renewed if it would expire within 30 days.

+

Alternatively, Certbot can look at all the certificates it manages, and only renew those nearing their expiry via the renew command:

+
# This will need access to port 443 from the internet, adjust your firewall if needed.
+docker run --rm -it \
+  -v "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
+  -v "${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/" \
+  -p 80:80 \
+  -p 443:443 \
+  certbot/certbot renew
+
+

This process can also be automated via cron or systemd timers.

+
+
+

Using a different ACME CA

+

Certbot does support alternative certificate providers via the --server option. In most cases you'll want to use the default Let's Encrypt.

+
+

Example using certbot-dns-cloudflare with Docker

+

If you are unable get a certificate via the HTTP-01 (port 80) or TLS-ALPN-01 (port 443) challenge types, the DNS-01 challenge can be useful (this challenge can additionally issue wildcard certificates). This guide shows how to use the DNS-01 challenge with Cloudflare as your DNS provider.

+

Obtain a Cloudflare API token:

+
    +
  1. Login into your Cloudflare dashboard.
    2. +
  2. Navigate to the API Tokens page.
    3. +
  3. +

    Click "Create Token", and choose the Edit zone DNS template (Certbot requires the ZONE:DNS:Edit permission).

    +
    +

    Only include the necessary Zone resource configuration

    +

    Be sure to configure "Zone Resources" section on this page to Include -> Specific zone -> <your zone here>.

    +

    This restricts the API token to only this zone (domain) which is an important security measure.

    +
    +
    4. +
  4. +

    Store the API token you received in a file cloudflare.ini with content:

    +
    dns_cloudflare_api_token = YOUR_CLOUDFLARE_TOKEN_HERE
+
    +
    5. +
  5. +

    As this is sensitive data, you should restrict access to it with chmod 600 and chown 0:0.

    +
    6. +
  6. Store the file in a folder if you like, such as docker-data/certbot/secrets/.
    7. +
  7. +

    Your docker-compose.yml should include the following:

    +
    services:
+  mailserver:
+    environments:
+      # Set SSL certificate type.
+      - SSL_TYPE=letsencrypt
+    volumes:
+      # Mount the cert folder generated by Certbot into mail-server:
+      - ./docker-data/certbot/certs/:/etc/letsencrypt/:ro
+
+  certbot-cloudflare:
+    image: certbot/dns-cloudflare:latest
+    command: certonly --dns-cloudflare --dns-cloudflare-credentials /run/secrets/cloudflare-api-token -d mail.example.com
+    volumes:
+      - ./docker-data/certbot/certs/:/etc/letsencrypt/
+      - ./docker-data/certbot/logs/:/var/log/letsencrypt/
+    secrets:
+      - cloudflare-api-token
+
+# Docs: https://docs.docker.com/engine/swarm/secrets/#use-secrets-in-compose
+# WARNING: In compose configs without swarm, the long syntax options have no effect,
+# Ensure that you properly `chmod 600` and `chown 0:0` the file on disk. Effectively treated as a bind mount.
+secrets:
+  cloudflare-api-token:
+    file: ./docker-data/certbot/secrets/cloudflare.ini
+
    +

    Alternative using the docker run command (secrets feature is not available):

    +
    docker run \
+  --volume "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
+  --volume "${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/" \
+  --volume "${PWD}/docker-data/certbot/secrets/:/tmp/secrets/certbot/"
+  certbot/dns-cloudflare \
+  certonly --dns-cloudflare --dns-cloudflare-credentials /tmp/secrets/certbot/cloudflare.ini -d mail.example.com
+
    +
    8. +
  8. +

    Run the service to provision a certificate:

    +
    docker-compose run certbot-cloudflare
+
    +
    9. +
  9. +

    You should see the following log output:

    +
    Saving debug log to /var/log/letsencrypt/letsencrypt. log | Requesting a certificate for mail.example.com
+Waiting 10 seconds for DNS changes to propagate
+Successfully received certificate.
+Certificate is saved at: /etc/letsencrypt/live/mail.example.com/fullchain.pem
+Key is saved at: /etc/letsencrypt/live/mail.example.com/privkey.pem
+This certificate expires on YYYY-MM-DD.
+These files will be updated when the certificate renews.
+NEXT STEPS:
+- The certificate will need to be renewed before it expires. Certbot can automatically renew the certificate in background, but you may need to take steps to enable that functionality. See https://certbot.org/renewal structions.
+
    +
    10. +
+

After completing the steps above, your certificate should be ready to use.

+
+Renewing a certificate (Optional) +

We've only demonstrated how to provision a certificate, but it will expire in 90 days and need to be renewed before then.

+

In the following example, add a new service (certbot-cloudflare-renew) into docker-compose.yml that will handle certificate renewals:

+
services:
+  certbot-cloudflare-renew:
+    image: certbot/dns-cloudflare:latest
+    command: renew --dns-cloudflare --dns-cloudflare-credentials /run/secrets/cloudflare-api-token
+    volumes:
+      - ./docker-data/certbot/certs/:/etc/letsencrtypt/
+      - ./docker-data/certbot/logs/:/var/log/letsencrypt/
+    secrets:
+      - cloudflare-api-token
+
+

You can manually run this service to renew the cert within 90 days:

+
docker-compose run certbot-cloudflare-renew
+
+

You should see the following output +(The following log was generated with --dry-run options)

+
Saving debug log to /var/log/letsencrypt/letsencrypt.log
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+Processing /etc/letsencrypt/renewal/mail.example.com.conf
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+Account registered.
+Simulating renewal of an existing certificate for mail.example.com
+Waiting 10 seconds for DNS changes to propagate
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+Congratulations, all simulated renewals succeeded:
+  /etc/letsencrypt/live/mail.example.com/fullchain.pem (success)
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+

It is recommended to automate this renewal via a task scheduler like a systemd timer or in crontab +(crontab example: Checks every day if the certificate should be renewed)

+
0 0 * * * docker-compose -f PATH_TO_YOUR_DOCKER_COMPOSE_YML up certbot-cloudflare-renew
+
+
+

Example using nginx-proxy and acme-companion with Docker

+

If you are running a web server already, port 80 will be in use which Certbot requires. You could use the Certbot --webroot feature, but it is more common to leverage a reverse proxy that manages the provisioning and renewal of certificates for your services automatically.

+

In the following example, we show how docker-mailserver can be run alongside the docker containers nginx-proxy and acme-companion (Referencing: acme-companion documentation):

+
    +
  1. +

    Start the reverse proxy (nginx-proxy):

    +
    docker run --detach \
+  --name nginx-proxy \
+  --restart always \
+  --publish 80:80 \
+  --publish 443:443 \
+  --volume "${PWD}/docker-data/nginx-proxy/html/:/usr/share/nginx/html/" \
+  --volume "${PWD}/docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/" \
+  --volume "${PWD}/docker-data/acme-companion/certs/:/etc/nginx/certs/:ro" \
+  --volume '/var/run/docker.sock:/tmp/docker.sock:ro' \
+  nginxproxy/nginx-proxy
+
    +
    2. +
  2. +

    Then start the certificate provisioner (acme-companion), which will provide certificates to nginx-proxy:

    +
    # Inherit `nginx-proxy` volumes via `--volumes-from`, but make `certs/` writeable:
+docker run --detach \
+  --name nginx-proxy-acme \
+  --restart always \
+  --volumes-from nginx-proxy \
+  --volume "${PWD}/docker-data/acme-companion/certs/:/etc/nginx/certs/:rw" \
+  --volume "${PWD}/docker-data/acme-companion/acme-state/:/etc/acme.sh/" \
+  --volume '/var/run/docker.sock:/var/run/docker.sock:ro' \
+  --env 'DEFAULT_EMAIL=admin@example.com' \
+  nginxproxy/acme-companion
+
    +
    3. +
  3. +

    Start the rest of your web server containers as usual.

    +
    4. +
  4. +

    Start a dummy container to provision certificates for your FQDN (eg: mail.example.com). acme-companion will detect the container and generate a Let's Encrypt certificate for your domain, which can be used by docker-mailserver:

    +
    docker run --detach \
+  --name webmail \
+  --env 'VIRTUAL_HOST=mail.example.com' \
+  --env 'LETSENCRYPT_HOST=mail.example.com' \
+  --env 'LETSENCRYPT_EMAIL=admin@example.com' \
+  nginx
+
    +

    You may want to add --env LETSENCRYPT_TEST=true to the above while testing, to avoid the Let's Encrypt certificate generation rate limits.

    +
    5. +
  5. +

    Make sure your mount path to the letsencrypt certificates directory is correct. Edit your docker-compose.yml for the mailserver service to have volumes added like below:

    +
    volumes:
+  - ./docker-data/dms/mail-data/:/var/mail/
+  - ./docker-data/dms/mail-state/:/var/mail-state/
+  - ./docker-data/dms/config/:/tmp/docker-mailserver/
+  - ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro
+
    +
    6. +
  6. +

    Then from the docker-compose.yml project directory, run: docker-compose up -d mailserver.

    +
    7. +
+

Example using nginx-proxy and acme-companion with docker-compose

+

The following example is the basic setup you need for using nginx-proxy and acme-companion with docker-mailserver (Referencing: acme-companion documentation):

+
+Example: docker-compose.yml +

You should have an existing docker-compose.yml with a mailserver service. Below are the modifications to add for integrating with nginx-proxy and acme-companion services:

+
services:
+  # Add the following `environment` and `volumes` to your existing `mailserver` service:
+  mailserver:
+    environment:
+      # SSL_TYPE:         Uses the `letsencrypt` method to find mounted certificates.
+      # VIRTUAL_HOST:     The FQDN that `nginx-proxy` will configure itself to handle for HTTP[S] connections.
+      # LETSENCRYPT_HOST: The FQDN for a certificate that `acme-companion` will provision and renew.
+      - SSL_TYPE=letsencrypt
+      - VIRTUAL_HOST=mail.example.com
+      - LETSENCRYPT_HOST=mail.example.com
+    volumes:
+      - ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro
+
+  # If you don't yet have your own `nginx-proxy` and `acme-companion` setup,
+  # here is an example you can use:
+  reverse-proxy:
+    image: nginxproxy/nginx-proxy
+    container_name: nginx-proxy
+    restart: always
+    ports:
+      # Port  80: Required for HTTP-01 challenges to `acme-companion`.
+      # Port 443: Only required for containers that need access over HTTPS. TLS-ALPN-01 challenge not supported.
+      - "80:80"
+      - "443:443"
+    volumes:
+      # `certs/`:      Managed by the `acme-companion` container (_read-only_).
+      # `docker.sock`: Required to interact with containers via the Docker API.
+      - ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
+      - ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
+      - ./docker-data/acme-companion/certs/:/etc/nginx/certs/:ro
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+
+  acme-companion:
+    image: nginxproxy/acme-companion
+    container_name: nginx-proxy-acme
+    restart: always
+    environment:
+      # Only docker-compose v2 supports: `volumes_from: [nginx-proxy]`,
+      # reference the _reverse-proxy_ `container_name` here:
+      - NGINX_PROXY_CONTAINER=nginx-proxy
+    volumes:
+      # `html/`:       Write ACME HTTP-01 challenge files that `nginx-proxy` will serve.
+      # `vhost.d/`:    To enable web access via `nginx-proxy` to HTTP-01 challenge files.
+      # `certs/`:      To store certificates and private keys.
+      # `acme-state/`: To persist config and state for the ACME provisioner (`acme.sh`).
+      # `docker.sock`: Required to interact with containers via the Docker API.
+      - ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
+      - ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
+      - ./docker-data/acme-companion/certs/:/etc/nginx/certs/:rw
+      - ./docker-data/acme-companion/acme-state/:/etc/acme.sh/
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+
+
+

Optional ENV vars worth knowing about

+

Per container ENV that acme-companion will detect to override default provisioning settings:

+
    +
  • LETSENCRYPT_TEST=true: Recommended during initial setup. Otherwise the default production endpoint has a rate limit of 5 duplicate certificates per week. Overrides ACME_CA_URI to use the Let's Encrypt staging endpoint.
    • +
  • LETSENCRYPT_EMAIL: For when you don't use DEFAULT_EMAIL on acme-companion, or want to assign a different email contact for this container.
    • +
  • LETSENCRYPT_KEYSIZE: Allows you to configure the type (RSA or ECDSA) and size of the private key for your certificate. Default is RSA 4096.
    • +
  • LETSENCRYPT_RESTART_CONTAINER=true: When the certificate is renewed, the entire container will be restarted to ensure the new certificate is used.
    • +
+

acme-companion ENV for default settings that apply to all containers using LETSENCRYPT_HOST:

+
    +
  • DEFAULT_EMAIL: An email address that the CA (eg: Let's Encrypt) can contact you about expiring certificates, failed renewals, or for account recovery. You may want to use an email address not handled by your mail-server to ensure deliverability in the event your mail-server breaks.
    • +
  • CERTS_UPDATE_INTERVAL: If you need to adjust the frequency to check for renewals. 3600 seconds (1 hour) by default.
    • +
  • DEBUG=1: Should be helpful when troubleshooting provisioning issues from acme-companion logs.
    • +
  • ACME_CA_URI: Useful in combination with CA_BUNDLE to use a private CA. To change the default Let's Encrypt endpoint to the staging endpoint, use https://acme-staging-v02.api.letsencrypt.org/directory.
    • +
  • CA_BUNDLE: If you want to use a private CA instead of Let's Encrypt.
    • +
+
+
+

Alternative to required ENV on mailserver service

+

While you will still need both nginx-proxy and acme-companion containers, you can manage certificates without adding ENV vars to containers. Instead the ENV is moved into a file and uses the acme-companion feature Standalone certificates.

+

This requires adding another shared volume between nginx-proxy and acme-companion:

+
services:
+  reverse-proxy:
+    volumes:
+      - ./docker-data/nginx-proxy/conf.d/:/etc/nginx/conf.d/
+
+  acme-companion:
+    volumes:
+      - ./docker-data/nginx-proxy/conf.d/:/etc/nginx/conf.d/
+      - ./docker-data/acme-companion/standalone.sh:/app/letsencrypt_user_data:ro
+
+

acme-companion mounts a shell script (standalone.sh), which defines variables to customize certificate provisioning:

+
# A list IDs for certificates to provision:
+LETSENCRYPT_STANDALONE_CERTS=('mail')
+
+# Each ID inserts itself into the standard `acme-companion` supported container ENV vars below.
+# The LETSENCRYPT_<ID>_HOST var is a list of FQDNs to provision a certificate for as the SAN field:
+LETSENCRYPT_mail_HOST=('mail.example.com')
+
+# Optional variables:
+LETSENCRYPT_mail_TEST=true
+LETSENCRYPT_mail_EMAIL='admin@example.com'
+# RSA-4096 => `4096`, ECDSA-256 => `ec-256`:
+LETSENCRYPT_mail_KEYSIZE=4096
+
+

Unlike with the equivalent ENV for containers, changes to this file will not be detected automatically. You would need to wait until the next renewal check by acme-companion (every hour by default), restart acme-companion, or manually invoke the service loop:

+

docker exec nginx-proxy-acme /app/signal_le_service

+
+

Example using Let's Encrypt Certificates with a Synology NAS

+

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.

+

Amongst other things, you can use these to secure your mail-server. DSM locates the generated certificates in a folder below /usr/syno/etc/certificate/_archive/.

+

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 docker-compose.yml declaration file:

+
volumes:
+  - /usr/syno/etc/certificate/_archive/<your-folder>/:/tmp/dms/custom-certs/
+environment:
+  - SSL_TYPE=manual
+  - SSL_CERT_PATH=/tmp/dms/custom-certs/fullchain.pem
+  - SSL_KEY_PATH=/tmp/dms/custom-certs/privkey.pem
+
+

DSM-generated letsencrypt certificates get auto-renewed every three months.

+

Caddy

+

For Caddy v2 you can specify the key_type in your server's global settings, which would end up looking something like this if you're using a Caddyfile:

+
{
+  debug
+  admin localhost:2019
+  http_port 80
+  https_port 443
+  default_sni example.com
+  key_type rsa4096
+}
+
+

If you are instead using a json config for Caddy v2, you can set it in your site's TLS automation policies:

+
+Caddy v2 JSON example snippet +
{
+  "apps": {
+    "http": {
+      "servers": {
+        "srv0": {
+          "listen": [
+            ":443"
+          ],
+          "routes": [
+            {
+              "match": [
+                {
+                  "host": [
+                    "mail.example.com",
+                  ]
+                }
+              ],
+              "handle": [
+                {
+                  "handler": "subroute",
+                  "routes": [
+                    {
+                      "handle": [
+                        {
+                          "body": "",
+                          "handler": "static_response"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ],
+              "terminal": true
+            },
+          ]
+        }
+      }
+    },
+    "tls": {
+      "automation": {
+        "policies": [
+          {
+            "subjects": [
+              "mail.example.com",
+            ],
+            "key_type": "rsa2048",
+            "issuer": {
+              "email": "admin@example.com",
+              "module": "acme"
+            }
+          },
+          {
+            "issuer": {
+              "email": "admin@example.com",
+              "module": "acme"
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+
+
+

The generated certificates can then be mounted:

+
volumes:
+  - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem
+  - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
+
+

Traefik v2

+

Traefik is an open-source application proxy using the ACME protocol. Traefik can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc. We strongly recommend to use Traefik's major version 2.

+

Traefik's storage format is natively supported if the acme.json store is mounted into the container at /etc/letsencrypt/acme.json. The file is also monitored for changes and will trigger a reload of the mail services (Postfix and Dovecot).

+

Wildcard certificates are supported. If your FQDN is mail.example.com and your wildcard certificate is *.example.com, add the ENV: SSL_DOMAIN=example.com.

+

The mail-server will select it's certificate from acme.json checking these ENV for a matching FQDN (in order of priority):

+
    +
  1. ${SSL_DOMAIN}
    2. +
  2. ${HOSTNAME}
    3. +
  3. ${DOMAINNAME}
    4. +
+

This setup only comes with one caveat: The domain has to be configured on another service for Traefik to actually request it from Let's Encrypt, i.e. Traefik will not issue a certificate without a service / router demanding it.

+
+Example Code +

Here is an example setup for docker-compose:

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    container_name: mailserver
+    hostname: mail.example.com
+    volumes:
+       - ./docker-data/traefik/acme.json:/etc/letsencrypt/acme.json:ro
+    environment:
+      SSL_TYPE: letsencrypt
+      SSL_DOMAIN: mail.example.com
+      # for a wildcard certificate, use
+      # SSL_DOMAIN: example.com
+
+  reverse-proxy:
+    image: docker.io/traefik:latest #v2.5
+    container_name: docker-traefik
+    ports:
+       - "80:80"
+       - "443:443"
+    command:
+       - --providers.docker
+       - --entrypoints.http.address=:80
+       - --entrypoints.http.http.redirections.entryPoint.to=https
+       - --entrypoints.http.http.redirections.entryPoint.scheme=https
+       - --entrypoints.https.address=:443
+       - --entrypoints.https.http.tls.certResolver=letsencrypt
+       - --certificatesresolvers.letsencrypt.acme.email=admin@example.com
+       - --certificatesresolvers.letsencrypt.acme.storage=/acme.json
+       - --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=http
+    volumes:
+       - ./docker-data/traefik/acme.json:/acme.json
+       - /var/run/docker.sock:/var/run/docker.sock:ro
+
+  whoami:
+    image: docker.io/traefik/whoami:latest
+    labels:
+       - "traefik.http.routers.whoami.rule=Host(`mail.example.com`)"
+
+
+

Self-Signed Certificates

+
+

Warning

+

Use self-signed certificates only for testing purposes!

+
+

This feature requires you to provide the following files into your docker-data/dms/config/ssl/ directory (internal location: /tmp/docker-mailserver/ssl/):

+
    +
  • <FQDN>-key.pem
    • +
  • <FQDN>-cert.pem
    • +
  • demoCA/cacert.pem
    • +
+

Where <FQDN> is the FQDN you've configured for your docker-mailserver container.

+

Add SSL_TYPE=self-signed to your docker-mailserver environment variables. Postfix and Dovecot will be configured to use the provided certificate (.pem files above) during container startup.

+

Generating a self-signed certificate

+

One way to generate self-signed certificates is with Smallstep's step CLI. This is exactly what docker-mailserver does for creating test certificates.

+

For example with the FQDN mail.example.test, you can generate the required files by running:

+
#! /bin/sh
+mkdir -p demoCA
+
+step certificate create "Smallstep Root CA" "demoCA/cacert.pem" "demoCA/cakey.pem" \
+  --no-password --insecure \
+  --profile root-ca \
+  --not-before "2021-01-01T00:00:00+00:00" \
+  --not-after "2031-01-01T00:00:00+00:00" \
+  --san "example.test" \
+  --san "mail.example.test" \
+  --kty RSA --size 2048
+
+step certificate create "Smallstep Leaf" mail.example.test-cert.pem mail.example.test-key.pem \
+  --no-password --insecure \
+  --profile leaf \
+  --ca "demoCA/cacert.pem" \
+  --ca-key "demoCA/cakey.pem" \
+  --not-before "2021-01-01T00:00:00+00:00" \
+  --not-after "2031-01-01T00:00:00+00:00" \
+  --san "example.test" \
+  --san "mail.example.test" \
+  --kty RSA --size 2048
+
+

If you'd rather not install the CLI tool locally to run the step commands above; you can save the script above to a file such as generate-certs.sh (and make it executable chmod +x generate-certs.sh) in a directory that you want the certs to be placed (eg: docker-data/dms/custom-certs/), then use docker to run that script in a container:

+
# '--user' is to keep ownership of the files written to
+# the local volume to use your systems User and Group ID values.
+docker run --rm -it \
+  --user "$(id -u):$(id -g)" \
+  --volume "${PWD}/docker-data/dms/custom-certs/:/tmp/step-ca/" \
+  --workdir "/tmp/step-ca/" \
+  --entrypoint "/tmp/step-ca/generate-certs.sh" \
+  smallstep/step-ca
+
+

Bring Your Own Certificates

+

You can also provide your own certificate files. Add these entries to your docker-compose.yml:

+
volumes:
+  - ./docker-data/dms/custom-certs/:/tmp/dms/custom-certs/:ro
+environment:
+  - SSL_TYPE=manual
+  # Values should match the file paths inside the container:
+  - SSL_CERT_PATH=/tmp/dms/custom-certs/public.crt
+  - SSL_KEY_PATH=/tmp/dms/custom-certs/private.key
+
+

This will mount the path where your certificate files reside locally into the read-only container folder: /tmp/dms/custom-certs.

+

The local and internal paths may be whatever you prefer, so long as both SSL_CERT_PATH and SSL_KEY_PATH point to the correct internal file paths. The certificate files may also be named to your preference, but should be PEM encoded.

+

SSL_ALT_CERT_PATH and SSL_ALT_KEY_PATH are additional ENV vars to support a 2nd certificate as a fallback. Commonly known as hybrid or dual certificate support. This is useful for using a modern ECDSA as your primary certificate, and RSA as your fallback for older connections. They work in the same manner as the non-ALT versions.

+
+

Info

+

You may have to restart docker-mailserver once the certificates change.

+
+

Testing a Certificate is Valid

+
    +
  • +

    From your host:

    +
    docker exec mailserver openssl s_client \
+  -connect 0.0.0.0:25 \
+  -starttls smtp \
+  -CApath /etc/ssl/certs/
+
    +
    • +
  • +

    Or:

    +
    docker exec mailserver openssl s_client \
+  -connect 0.0.0.0:143 \
+  -starttls imap \
+  -CApath /etc/ssl/certs/
+
    +
    • +
+

And you should see the certificate chain, the server certificate and: Verify return code: 0 (ok)

+

In addition, to verify certificate dates:

+
docker exec mailserver openssl s_client \
+  -connect 0.0.0.0:25 \
+  -starttls smtp \
+  -CApath /etc/ssl/certs/ \
+  2>/dev/null | openssl x509 -noout -dates
+
+

Plain-Text Access

+
+

Warning

+

Not recommended for purposes other than testing.

+
+

Add this to docker-data/dms/config/dovecot.cf:

+
ssl = yes
+disable_plaintext_auth=no
+
+

These options in conjunction mean:

+
    +
  • SSL/TLS is offered to the client, but the client isn't required to use it.
    • +
  • The client is allowed to login with plaintext authentication even when SSL/TLS isn't enabled on the connection.
    • +
  • This is insecure, because the plaintext password is exposed to the internet.
    • +
+

Importing Certificates Obtained via Another Source

+

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: external certificate import script.

+

This is a community contributed script, and in most cases you will have better support via our Change Detection service (automatic for SSL_TYPE of manual and letsencrypt) - Unless you're using LDAP which disables the service.

+
+

Script Compatibility

+
    +
  • Relies on private filepaths /etc/dms/tls/cert and /etc/dms/tls/key intended for internal use only.
    • +
  • Only supports hard-coded fullchain.key + privkey.pem as your mounted file names. That may not align with your provisioning method.
    • +
  • No support for ALT fallback certificates (for supporting dual/hybrid, RSA + ECDSA).
    • +
+
+

The steps to follow are these:

+
    +
  1. Transfer the new certificates to ./docker-data/dms/custom-certs/ (volume mounted to: /tmp/ssl/)
    2. +
  2. You should provide fullchain.key and privkey.pem
    3. +
  3. Place the script in ./docker-data/dms/config/ (volume mounted to: /tmp/docker-mailserver/)
    4. +
  4. Make the script executable (chmod +x tomav-renew-certs.sh)
    5. +
  5. Run the script: docker exec mailserver /tmp/docker-mailserver/tomav-renew-certs.sh
    6. +
+

If an error occurs the script will inform you. If not you will see both postfix and dovecot restart.

+

After the certificates have been loaded you can check the certificate:

+
openssl s_client \
+  -servername mail.example.com \
+  -connect 192.168.0.72:465 \
+  2>/dev/null | openssl x509
+
+# or
+
+openssl s_client \
+  -servername mail.example.com \
+  -connect mail.example.com:465 \
+  2>/dev/null | openssl x509
+
+

Or you can check how long the new certificate is valid with commands like:

+
export SITE_URL="mail.example.com"
+export SITE_IP_URL="192.168.0.72" # can also use `mail.example.com`
+export SITE_SSL_PORT="993" # imap port dovecot
+
+##works: check if certificate will expire in two weeks
+#2 weeks is 1209600 seconds
+#3 weeks is 1814400
+#12 weeks is 7257600
+#15 weeks is 9072000
+
+certcheck_2weeks=`openssl s_client -connect ${SITE_IP_URL}:${SITE_SSL_PORT} \
+  -servername ${SITE_URL} 2> /dev/null | openssl x509 -noout -checkend 1209600`
+
+####################################
+#notes: output could be either:
+#Certificate will not expire
+#Certificate will expire
+####################
+
+

What does the script that imports the certificates do:

+
    +
  1. Check if there are new certs in the internal container folder: /tmp/ssl.
    2. +
  2. Check with the ssl cert fingerprint if they differ from the current certificates.
    3. +
  3. If so it will copy the certs to the right places.
    4. +
  4. And restart postfix and dovecot.
    5. +
+

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:

+
# This script is run inside docker-mailserver via 'docker exec ...', using the 'mail' command to send alerts.
+## code below will alert if certificate expires in less than two weeks
+## please adjust varables!
+## make sure the 'mail -s' command works! Test!
+
+export SITE_URL="mail.example.com"
+export SITE_IP_URL="192.168.2.72" # can also use `mail.example.com`
+export SITE_SSL_PORT="993" # imap port dovecot
+# Below can be from a different domain; like your personal email, not handled by this docker-mailserver:
+export ALERT_EMAIL_ADDR="external-account@gmail.com"
+
+certcheck_2weeks=`openssl s_client -connect ${SITE_IP_URL}:${SITE_SSL_PORT} \
+  -servername ${SITE_URL} 2> /dev/null | openssl x509 -noout -checkend 1209600`
+
+####################################
+#notes: output can be
+#Certificate will not expire
+#Certificate will expire
+####################
+
+#echo "certcheck 2 weeks gives $certcheck_2weeks"
+
+##automated check you might run by cron or something
+## does the certificate expire within two weeks?
+
+if [ "$certcheck_2weeks" = "Certificate will not expire" ]; then
+  echo "all is well, certwatch 2 weeks says $certcheck_2weeks"
+  else
+    echo "Cert seems to be expiring pretty soon, within two weeks: $certcheck_2weeks"
+    echo "we will send an alert email and log as well"
+    logger Certwatch: cert $SITE_URL will expire in two weeks
+    echo "Certwatch: cert $SITE_URL will expire in two weeks" | mail -s "cert $SITE_URL expires in two weeks " $ALERT_EMAIL_ADDR
+fi
+
+

Custom DH Parameters

+

By default docker-mailserver uses ffdhe4096 from IETF RFC 7919. These are standardized pre-defined DH groups and the only available DH groups for TLS 1.3. It is discouraged to generate your own DH parameters as it is often less secure.

+

Despite this, if you must use non-standard DH parameters or you would like to swap ffdhe4096 for a different group (eg ffdhe2048); Add your own PEM encoded DH params file via a volume to /tmp/docker-mailserver/dhparams.pem. This will replace DH params for both Dovecot and Postfix services during container startup.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/security/understanding-the-ports/index.html b/v12.0/config/security/understanding-the-ports/index.html new file mode 100644 index 00000000..a34b75eb --- /dev/null +++ b/v12.0/config/security/understanding-the-ports/index.html @@ -0,0 +1,1874 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Security | Understanding the Ports - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Understanding the Ports

+ +

Quick Reference

+

Prefer ports with Implicit TLS ports, they're more secure than ports using Explicit TLS, and if you use a Reverse Proxy should be less hassle.

+

Overview of Email Ports

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProtocolExplicit TLS1Implicit TLSPurposeEnabled by Default
ESMTP25N/ATransfer2Yes
ESMTP5874653SubmissionYes
POP3110995RetrievalNo
IMAP4143993RetrievalYes
+
    +
  1. A connection may be secured over TLS when both ends support STARTTLS. On ports 110, 143 and 587, docker-mailserver will reject a connection that cannot be secured. Port 25 is required to support insecure connections.
    2. +
  2. Receives email, docker-mailserver additionally filters for spam and viruses. For submitting email to the server to be sent to third-parties, you should prefer the submission ports (465, 587) - which require authentication. Unless a relay host is configured (eg: SendGrid), outgoing email will leave the server via port 25 (thus outbound traffic must not be blocked by your provider or firewall).
    3. +
  3. A submission port since 2018 (RFC 8314).
    4. +
+
+Beware of outdated advice on port 465 +

There is a common misconception of this port due to it's history detailed by various communities and blogs articles on the topic (including by popular mail relay services).

+

Port 465 was briefly assigned the role of SMTPS in 1997 as an secure alternative to Port 25 between MTA exchanges. Then RFC 2487 (STARTTLS) while still in a draft status in late 1998 had IANA revoke the SMTPS assignment. The draft history was modified to exclude all mention of port 465 and SMTPS.

+

In 2018 RFC 8314 was published which revives Port 465 as an Implicit TLS alternative to Port 587 for mail submission. It details very clearly that gaining adoption of 465 as the preferred port will take time. IANA reassigned port 465 as the submissions service. Any unofficial usage as SMTPS is legacy and has been for over two decades.

+

Understand that port 587 is more broadly supported due to this history and that lots of software in that time has been built or configured with that port in mind. STARTTLS is known to have various CVEs discovered even in recent years, do not be misled by any advice implying it should be preferred over implicit TLS. Trust in more official sources, such as the config Postfix has which acknowledges the submissions port (465).

+
+

What Ports Should I Use? (SMTP)

+
flowchart LR
+    subgraph your-server ["Your Server"]
+        in_25(25) --> server
+        in_465(465) --> server
+        server(("docker-mailserver<br/>hello@world.com"))
+        server --- out_25(25)
+        server --- out_465(465)
+    end
+
+    third-party("Third-party<br/>(sending you email)") ---|"Receive email for<br/>hello@world.com"| in_25
+
+    subgraph clients ["Clients (MUA)"]
+        mua-client(Thunderbird,<br/>Webmail,<br/>Mutt,<br/>etc)
+        mua-service(Backend software<br/>on another server)
+    end
+    clients ---|"Send email as<br/>hello@world.com"| in_465
+
+    out_25(25) -->|"Direct<br/>Delivery"| tin_25
+    out_465(465) --> relay("MTA<br/>Relay Server") --> tin_25(25)
+
+    subgraph third-party-server["Third-party Server"]
+        third-party-mta("MTA<br/>friend@example.com")
+        tin_25(25) --> third-party-mta
+    end
+
+

Inbound Traffic (On the left)

+

Mail arriving at your server will be processed and stored in a mailbox, or sent outbound to another mail server.

+
    +
  • Port 25:
      +
    • Think of this like a physical mailbox, anyone can deliver mail to you here. Typically most mail is delivered to you on this port. +-docker-mailserver will actively filter email delivered on this port for spam or viruses, and refuse mail from known bad sources.
      • +
    • Connections to this port may be secure through STARTTLS, but is not mandatory as mail is allowed to arrive via an unencrypted connection.
      • +
    • It is possible for internal clients to submit mail to be sent outbound (without requiring authentication), but that is discouraged. Prefer the submission ports.
      • +
    +
    • +
  • Port 465 and 587:
      +
    • This is the equivalent of a post office box where you would send email to be delivered on your behalf (docker-mailserver is that metaphorical post office, aka the MTA).
      • +
    • These two ports are known as the submission ports, they enable mail to be sent outbound to another MTA (eg: Outlook or Gmail) but require authentication via a mail account.
      • +
    • For inbound traffic, this is relevant when you send mail from your MUA (eg: ThunderBird). It's also used when docker-mailserver is configured as a mail relay, or when you have a service sending transactional mail (eg: order confirmations, password resets, notifications) through docker-mailserver.
      • +
    • Prefer port 465 over port 587, as 465 provides Implicit TLS.
      • +
    +
    • +
+
+

Note

+

When submitting mail (inbound) to be sent (outbound), this involves two separate connections to negotiate and secure. There may be additional intermediary connections which docker-mailserver is not involved in, and thus unable to ensure encrypted transit throughout delivery.

+
+

Outbound Traffic (On the Right)

+

Mail being sent from your server is either being relayed through another MTA (eg: SendGrid), or direct to an MTA responsible for an email address (eg: Gmail).

+
    +
  • Port 25:
      +
    • As most MTA use port 25 to receive inbound mail, when no authenticated relay is involved this is the outbound port used.
      • +
    • Outbound traffic on this port is often blocked by service providers (eg: VPS, ISP) to prevent abuse by spammers. If the port cannot be unblocked, you will need to relay outbound mail through a service to send on your behalf.
      • +
    +
    • +
  • Port 465 and 587:
      +
    • Submission ports for outbound traffic establish trust to forward mail through a third-party relay service. This requires authenticating to an account on the relay service. The relay will then deliver the mail through port 25 on your behalf.
      • +
    • These are the two typical ports used, but smart hosts like SendGrid often document support for additional non-standard ports as alternatives if necessary.
      • +
    • Usually you'll only use these outbound ports for relaying. It is possible to deliver directly to the relevant MTA for email address, but requires having credentials for each MTA.
      • +
    +
    • +
+
+

Tip

+

docker-mailserver can function as a relay too, but professional relay services have a trusted reputation (which increases success of delivery).

+

An MTA with low reputation can affect if mail is treated as junk, or even rejected.

+
+
+

Note

+

At best, you can only ensure a secure connection between the MTA you directly connect to. The receiving MTA may relay that mail to another MTA (and so forth), each connection may not be enforcing TLS.

+
+

Explicit vs Implicit TLS

+

Explicit TLS (aka Opportunistic TLS) - Opt-in Encryption

+

Communication on these ports begin in cleartext. Upgrading to an encrypted connection must be requested explicitly through the STARTTLS protocol and successfully negotiated.

+

Sometimes a reverse-proxy is involved, but is misconfigured or lacks support for the STARTTLS negotiation to succeed.

+
+

Note

+
    +
  • By default, docker-mailserver is configured to reject connections that fail to establish a secure connection (when authentication is required), rather than allow an insecure connection.
    • +
  • Port 25 does not require authentication. If STARTTLS is unsuccessful, mail can be received over an unencrypted connection. You can better secure this port between trusted parties with the addition of MTA-STS, STARTTLS Policy List, DNSSEC and DANE.
    • +
+
+
+

Warning

+

STARTTLS continues to have vulnerabilities found (Nov 2021 article), as per RFC 8314 (Section 4.1) you are encouraged to prefer Implicit TLS where possible.

+

Support for STARTTLS is not always implemented correctly, which can lead to leaking credentials (like a client sending too early) prior to a TLS connection being established. Third-parties such as some ISPs have also been known to intercept the STARTTLS exchange, modifying network traffic to prevent establishing a secure connection.

+
+

Implicit TLS - Enforced Encryption

+

Communication on these ports are always encrypted (enforced, thus implicit), avoiding the potential risks with STARTTLS (Explicit TLS).

+

While Explicit TLS can provide the same benefit (when STARTTLS is successfully negotiated), Implicit TLS more reliably avoids concerns with connection manipulation and compatibility.

+

Security

+
+

Todo

+

This section should provide any related configuration advice, and probably expand on and link to resources about DANE, DNSSEC, MTA-STS and STARTTLS Policy list, with advice on how to configure/setup these added security layers.

+
+
+

Todo

+

A related section or page on ciphers used may be useful, although less important for users to be concerned about.

+
+

TLS connections for a Mail-Server, compared to web browsers

+

Unlike with HTTP where a web browser client communicates directly with the server providing a website, a secure TLS connection as discussed below does not provide the equivalent safety that HTTPS does when the transit of email (receiving or sending) is sent through third-parties, as the secure connection is only between two machines, any additional machines (MTAs) between the MUA and the MDA depends on them establishing secure connections between one another successfully.

+

Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a cleartext connection through interception.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/setup.sh/index.html b/v12.0/config/setup.sh/index.html new file mode 100644 index 00000000..65b075f1 --- /dev/null +++ b/v12.0/config/setup.sh/index.html @@ -0,0 +1,1654 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Your best friend setup.sh - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Your Friend setup.sh

+ +

setup.sh is an administration script that helps with the most common tasks, including initial configuration. It is intended to be run from the host machine, not from inside your running container.

+

The latest version of the script is included in the docker-mailserver repository. You may retrieve it at any time by running this command in your console:

+
wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh
+chmod a+x ./setup.sh
+
+

Usage

+

Run ./setup.sh help and you'll get all you have ever wanted some usage information:

+
SETUP(1)
+
+NAME
+    setup.sh - docker-mailserver administration script
+
+SYNOPSIS
+    ./setup.sh [ OPTIONS... ] COMMAND [ help | ARGUMENTS... ]
+
+    COMMAND := { email | alias | quota | config | relay | debug } SUBCOMMAND
+
+DESCRIPTION
+    This is the main administration script that you use for all your interactions with
+    'docker-mailserver'. Setup, configuration and much more is done with this script.
+
+    Please note that the script executes most of the commands inside the container itself.
+    If the image was not found, this script will pull the ':latest' tag of
+    'docker.io/mailserver/docker-mailserver'. This tag refers to the latest release,
+    see the tagging convention in the README under
+    https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
+
+    You will be able to see detailed information about the script you're invoking and
+    its arguments by appending help after your command. Currently, this
+    does not work with all scripts.
+
+[SUB]COMMANDS
+    COMMAND email :=
+        ./setup.sh email add <EMAIL ADDRESS> [<PASSWORD>]
+        ./setup.sh email update <EMAIL ADDRESS> [<PASSWORD>]
+        ./setup.sh email del [ OPTIONS... ] <EMAIL ADDRESS> [ <EMAIL ADDRESS>... ]
+        ./setup.sh email restrict <add|del|list> <send|receive> [<EMAIL ADDRESS>]
+        ./setup.sh email list
+
+    COMMAND alias :=
+        ./setup.sh alias add <EMAIL ADDRESS> <RECIPIENT>
+        ./setup.sh alias del <EMAIL ADDRESS> <RECIPIENT>
+        ./setup.sh alias list
+
+    COMMAND quota :=
+        ./setup.sh quota set <EMAIL ADDRESS> [<QUOTA>]
+        ./setup.sh quota del <EMAIL ADDRESS>
+
+    COMMAND config :=
+        ./setup.sh config dkim [ ARGUMENTS... ]
+
+    COMMAND relay :=
+        ./setup.sh relay add-auth <DOMAIN> <USERNAME> [<PASSWORD>]
+        ./setup.sh relay add-domain <DOMAIN> <HOST> [<PORT>]
+        ./setup.sh relay exclude-domain <DOMAIN>
+
+    COMMAND fail2ban =
+        ./setup.sh fail2ban
+        ./setup.sh fail2ban ban <IP>
+        ./setup.sh fail2ban unban <IP>
+
+    COMMAND debug :=
+        ./setup.sh debug fetchmail
+        ./setup.sh debug login <COMMANDS>
+        ./setup.sh debug show-mail-logs
+
+EXAMPLES
+    ./setup.sh email add test@example.com [password]
+        Add the email account test@example.com. You will be prompted
+        to input a password afterwards if no password was supplied.
+        When supplying `[password]`, it should be in plaintext.
+
+    ./setup.sh config dkim keysize 2048 domain 'example.com,not-example.com'
+        Creates keys of length 2048 but in an LDAP setup where domains are not known to
+        Postfix by default, so you need to provide them yourself in a comma-separated list.
+
+    ./setup.sh config dkim help
+        This will provide you with a detailed explanation on how to use the
+        config dkim command, showing what arguments can be passed and what they do.
+
+OPTIONS
+    Config path, container or image adjustments
+        -i IMAGE_NAME
+            Provides the name of the 'docker-mailserver' image. The default value is
+            'docker.io/mailserver/docker-mailserver:latest'
+
+        -c CONTAINER_NAME
+            Provides the name of the running container.
+
+        -p PATH
+            Provides the config folder path to the temporary container
+            (does not work if a 'docker-mailserver' container already exists).
+
+    SELinux
+        -z
+            Allows container access to the bind mount content that is shared among
+            multiple containers on a SELinux-enabled host.
+
+        -Z
+            Allows container access to the bind mount content that is private and
+            unshared with other containers on a SELinux-enabled host.
+
+EXIT STATUS
+    Exit status is 0 if the command was successful. If there was an unexpected error, an error
+    message is shown describing the error. In case of an error, the script will exit with exit
+    status 1.
+
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/config/user-management/index.html b/v12.0/config/user-management/index.html new file mode 100644 index 00000000..4da16b99 --- /dev/null +++ b/v12.0/config/user-management/index.html @@ -0,0 +1,1749 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + User Management - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

User Management

+

Accounts

+

Users (email accounts) are managed in /tmp/docker-mailserver/postfix-accounts.cf. The best way to manage accounts is to use the reliable setup command inside the container. Just run docker exec <CONTAINER NAME> setup help and have a look at the section about subcommands, specifically the email subcommand.

+

Adding a new Account

+

Via setup inside the container

+

You can add an account by running docker exec -ti <CONTAINER NAME> setup email add <NEW ADDRESS>. This method is strongly preferred.

+

Manually

+
+

Warning

+

This method is discouraged!

+
+

Alternatively, you may directly add the full email address and its encrypted password, separated by a pipe. To generate a new mail account data, directly from your host, you could for example run the following:

+
docker run --rm -it                                      \
+  --env MAIL_USER=user1@example.com                      \
+  --env MAIL_PASS=mypassword                             \
+  ghcr.io/docker-mailserver/docker-mailserver:latest     \
+  /bin/bash -c \
+    'echo "${MAIL_USER}|$(doveadm pw -s SHA512-CRYPT -u ${MAIL_USER} -p ${MAIL_PASS})" >>docker-data/dms/config/postfix-accounts.cf'
+
+

You will then be asked for a password, and be given back the data for a new account entry, as text. To actually add this new account, just copy all the output text in docker-data/dms/config/postfix-accounts.cf file of your running container.

+

The result could look like this:

+
user1@example.com|{SHA512-CRYPT}$6$2YpW1nYtPBs2yLYS$z.5PGH1OEzsHHNhl3gJrc3D.YMZkvKw/vp.r5WIiwya6z7P/CQ9GDEJDr2G2V0cAfjDFeAQPUoopsuWPXLk3u1
+
+

Quotas

+
    +
  • imap-quota is enabled and allow clients to query their mailbox usage.
    • +
  • When the mailbox is deleted, the quota directive is deleted as well.
    • +
  • Dovecot quotas support LDAP, but it's not implemented (PRs are welcome!).
    • +
+

Aliases

+

The best way to manage aliases is to use the reliable setup script inside the container. Just run docker exec <CONTAINER NAME> setup help and have a look at the section about subcommands, specifically the alias-subcommand.

+

About

+

You may read Postfix's documentation on virtual aliases first. Aliases are managed in /tmp/docker-mailserver/postfix-virtual.cf. An alias is a full email address that will either be:

+
    +
  • delivered to an existing account registered in /tmp/docker-mailserver/postfix-accounts.cf
    • +
  • redirected to one or more other email addresses
    • +
+

Alias and target are space separated. An example on a server with example.com as its domain:

+
# Alias delivered to an existing account
+alias1@example.com user1@example.com
+
+# Alias forwarded to an external email address
+alias2@example.com external-account@gmail.com
+
+

Configuring RegExp Aliases

+

Additional regexp aliases can be configured by placing them into docker-data/dms/config/postfix-regexp.cf. The regexp aliases get evaluated after the virtual aliases (container path: /tmp/docker-mailserver/postfix-virtual.cf). For example, the following docker-data/dms/config/postfix-regexp.cf causes all email sent to "test" users to be delivered to qa@example.com instead:

+
/^test[0-9][0-9]*@example.com/ qa@example.com
+
+

Address Tags (Extension Delimiters) as an alternative to Aliases

+

Postfix supports so-called address tags, in the form of plus (+) tags - i.e. address+tag@example.com will end up at address@example.com. This is configured by default and the (configurable!) separator is set to +. For more info, see Postfix's official documentation.

+
+

Note

+

If you do decide to change the configurable separator, you must add the same line to both docker-data/dms/config/postfix-main.cf and docker-data/dms/config/dovecot.cf, because Dovecot is acting as the delivery agent. For example, to switch to -, add:

+
recipient_delimiter = -
+
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/contributing/general/index.html b/v12.0/contributing/general/index.html new file mode 100644 index 00000000..f1994f41 --- /dev/null +++ b/v12.0/contributing/general/index.html @@ -0,0 +1,1568 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Contributing | General Information - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

General Information

+ +

Coding Style

+

When refactoring, writing or altering scripts or other files, adhere to these rules:

+
    +
  1. Adjust your style of coding to the style that is already present! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all scripts consistent.
    2. +
  2. Use shellcheck to check your scripts! Your contributions are checked by GitHub Actions too, so you will need to do this. You can lint your work with make lint to check against all targets.
    3. +
  3. Use the provided .editorconfig file.
    4. +
  4. Use /bin/bash instead of /bin/sh in scripts
    5. +
+

Documentation

+

You will need to have Docker installed. Navigate into the docs/ directory. Then run:

+
docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material
+
+

This serves the documentation on your local machine on port 8000. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/contributing/issues-and-pull-requests/index.html b/v12.0/contributing/issues-and-pull-requests/index.html new file mode 100644 index 00000000..dd90770b --- /dev/null +++ b/v12.0/contributing/issues-and-pull-requests/index.html @@ -0,0 +1,1608 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Contributing | Issues and Pull Requests - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Issues and Pull Requests

+ +

This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation.

+

Opening an Issue

+
+

Attention

+

Before opening an issue, read the README carefully, study the docs for your version (maybe latest), the Postfix/Dovecot documentation and your search engine you trust. The issue tracker is not meant to be used for unrelated questions!

+
+

When opening an issue, please provide details use case to let the community reproduce your problem. Please start docker-mailserver with the environment variable LOG_LEVEL set to debug or trace and paste the output into the issue.

+
+

Attention

+

Use the issue templates to provide the necessary information. Issues which do not use these templates are not worked on and closed.

+
+

By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution.

+

Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and comply with the rules.

+

Pull Requests

+
+

Motivation

+

You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results.

+
+

Submit a Pull-Request

+

The development workflow is the following:

+
    +
  1. Fork the project and clone your fork with git clone --recurse-submodules ... or run git submodule update --init --recursive after you cloned your fork
    2. +
  2. Write the code that is needed :D
    3. +
  3. Add integration tests if necessary
    4. +
  4. Prepare your environment and run linting and tests
    5. +
  5. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the ENV documentation) and add your changes the changelog under the "Unreleased" section
    6. +
  6. Commit (and sign your commit), push and create a pull-request to merge into master. Please use the pull-request template to provide a minimum of contextual information and make sure to meet the requirements of the checklist.
    7. +
+

Pull requests are automatically tested against the CI and will be reviewed when tests pass. When your changes are validated, your branch is merged. CI builds the new :edge image immediately and your changes will be includes in the next version release.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/contributing/tests/index.html b/v12.0/contributing/tests/index.html new file mode 100644 index 00000000..17596a94 --- /dev/null +++ b/v12.0/contributing/tests/index.html @@ -0,0 +1,1776 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tests - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Tests

+ +
+

Program testing can be used to show the presence of bugs, but never to show their absence!

+

– Edsger Wybe Dijkstra

+
+

Introduction

+

DMS employs a variety of unit and integration tests. All tests and associated configuration is stored in the test/ directory. If you want to change existing functionality or integrate a new feature into DMS, you will probably need to work with our test suite.

+
+

Can I use macOS?

+

We do not support running linting, tests, etc. on macOS at this time. Please use a Linux VM, Debian/Ubuntu is recommended.

+
+

About

+

We use BATS (Bash Automated Testing System) and additional support libraries. BATS is very similar to Bash, and one can easily and quickly get an understanding of how tests in a single file are run. A test file template provides a minimal working example for newcomers to look at.

+

Structure

+

The test/ directory contains multiple directories. Among them is the bats/ directory (which is the BATS git submodule) and the helper/ directory. The latter is especially interesting because it contains common support functionality used in almost every test. Actual tests are located in test/tests/.

+
+

Test suite undergoing refactoring

+

We are currently in the process of restructuring all of our tests. Tests will be moved into test/tests/parallel/ and new tests should be placed there as well.

+
+

Using Our Helper Functions

+

There are many functions that aid in writing tests. We urge you to use them! They will not only ease writing a test but they will also do their best to ensure there are no race conditions or other unwanted side effects. To learn about the functions we provide, you can:

+
    +
  1. look into existing tests for helper functions we already used
    2. +
  2. look into the test/helper/ directory which contains all files that can (and will) be loaded in test files
    3. +
+

We encourage you to try both of the approaches mentioned above. To make understanding and using the helper functions easy, every function contains detailed documentation comments. Read them carefully!

+

How Are Tests Run?

+

Tests are split into two categories:

+
    +
  • test/tests/parallel/: Multiple test files are run concurrently to reduce the required time to complete the test suite. A test file will presently run it's own defined test-cases in a sequential order.
    • +
  • test/tests/serial/: Each test file is queued up to run sequentially. Tests that are unable to support running concurrently belong here.
    • +
+

Parallel tests are further partitioned into smaller sets. If your system has the resources to support running more than one of those sets at a time this is perfectly ok (our CI runs tests by distributing the sets across multiple test runners). Care must be taken not to mix running the serial tests while a parallel set is also running; this is handled for you when using make tests.

+

Running Tests

+

Prerequisites

+

To run the test suite, you will need to:

+
    +
  1. Install Docker
    2. +
  2. Install jq and (GNU) parallel (under Ubuntu, use sudo apt-get -y install jq parallel)
    3. +
  3. Execute git submodule update --init --recursive if you haven't already initialized the git submodules
    4. +
+

Executing Test(s)

+

We use make to run commands.

+
    +
  1. Run make build to create or update the local mailserver-testing:ci Docker image (using the projects Dockerfile)
    2. +
  2. Run all tests: make clean tests
    3. +
  3. Run a single test: make clean generate-accounts test/<TEST NAME WITHOUT .bats SUFFIX>
    4. +
  4. Run multiple unrelated tests: make clean generate-accounts test/<TEST NAME WITHOUT .bats SUFFIX>,<TEST NAME WITHOUT .bats SUFFIX> (just add a , and then immediately write the new test name)
    5. +
  5. Run a whole set or all serial tests: make clean generate-accounts tests/parallel/setX where X is the number of the set or make clean generate-accounts tests/serial
    6. +
+
+Setting the Degree of Parallelization for Tests +

If your machine is capable, you can increase the amount of tests that are run simultaneously by prepending the make clean all command with BATS_PARALLEL_JOBS=X (i.e. BATS_PARALLEL_JOBS=X make clean all). This wil speed up the test procedure. You can also run all tests in serial by setting BATS_PARALLEL_JOBS=1 this way.

+

The default value of BATS_PARALLEL_JOBS is 2. This can be increased if your system has the resources spare to support running more jobs at once to complete the test suite sooner.

+
+
+

Test Output when Running in Parallel

+

When running tests in parallel (with make clean generate-accounts tests/parallel/setX), BATS will delay outputting the results until completing all test cases within a file.

+

This likewise delays the reporting of test-case failures. When troubleshooting parallel set tests, you may prefer to run specific tests you're working on serially (as demonstrated in the example below).

+

When writing tests, ensure that parallel set tests still pass when run in parallel. You need to account for other tests running in parallel that may interfere with your own tests logic.

+
+

An Example

+

In this example, you've made a change to the Rspamd feature support (or adjusted it's tests). First verify no regressions have been introduced by running it's specific test file:

+
$ make clean generate-accounts test/rspamd
+rspamd.bats
+ ✓ [Rspamd] Postfix's main.cf was adjusted [12]
+ ✓ [Rspamd] normal mail passes fine [44]
+ ✓ [Rspamd] detects and rejects spam [122]
+ ✓ [Rspamd] detects and rejects virus [189]
+
+

As your feature work progresses your change for Rspamd also affects ClamAV. As your change now spans more than just the Rspamd test file, you could run multiple test files serially:

+
$ make clean generate-accounts test/rspamd,clamav
+rspamd.bats
+ ✓ [Rspamd] Postfix's main.cf was adjusted [12]
+ ✓ [Rspamd] normal mail passes fine [44]
+ ✓ [Rspamd] detects and rejects spam [122]
+ ✓ [Rspamd] detects and rejects virus [189]
+clamav.bats
+ ✓ [ClamAV] log files exist at /var/log/mail directory [68]
+ ✓ [ClamAV] should be identified by Amavis [67]
+ ✓ [ClamAV] freshclam cron is enabled [76]
+ ✓ [ClamAV] env CLAMAV_MESSAGE_SIZE_LIMIT is set correctly [63]
+ ✓ [ClamAV] rejects virus [60]
+
+

You're almost finished with your change before submitting it as a PR. It's a good idea to run the full parallel set those individual tests belong to (especially if you've modified any tests):

+
$ make clean generate-accounts tests/parallel/set1
+default_relay_host.bats
+ ✓ [Relay] (ENV) 'DEFAULT_RELAY_HOST' should configure 'main.cf:relayhost' [88]
+spam_virus/amavis.bats
+ ✓ [Amavis] SpamAssassin integration should be active [1165]
+spam_virus/clamav.bats
+ ✓ [ClamAV] log files exist at /var/log/mail directory [73]
+ ✓ [ClamAV] should be identified by Amavis [67]
+ ✓ [ClamAV] freshclam cron is enabled [76]
+...
+
+

Even better, before opening a PR run the full test suite:

+
$ make clean tests
+...
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/examples/tutorials/basic-installation/index.html b/v12.0/examples/tutorials/basic-installation/index.html new file mode 100644 index 00000000..851d6fec --- /dev/null +++ b/v12.0/examples/tutorials/basic-installation/index.html @@ -0,0 +1,1764 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tutorials | Basic Installation - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Basic Installation

+ +

A Basic Example With Relevant Environmental Variables

+

This example provides you only with a basic example of what a minimal setup could look like. We strongly recommend that you go through the configuration file yourself and adjust everything to your needs. The default docker-compose.yml can be used for the purpose out-of-the-box, see the Usage chapter.

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    container_name: mailserver
+    # Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
+    hostname: mail.example.com
+    ports:
+      - "25:25"
+      - "465:465"
+      - "587:587"
+      - "993:993"
+    volumes:
+      - ./docker-data/dms/mail-data/:/var/mail/
+      - ./docker-data/dms/mail-state/:/var/mail-state/
+      - ./docker-data/dms/mail-logs/:/var/log/mail/
+      - ./docker-data/dms/config/:/tmp/docker-mailserver/
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      - ENABLE_RSPAMD=1
+      - ENABLE_CLAMAV=1
+      - ENABLE_FAIL2BAN=1
+    cap_add:
+      - NET_ADMIN # For Fail2Ban to work
+    restart: always
+
+

A Basic LDAP Setup

+

Note There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    container_name: mailserver
+    # Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
+    hostname: mail.example.com
+    ports:
+      - "25:25"
+      - "465:465"
+      - "587:587"
+      - "993:993"
+    volumes:
+      - ./docker-data/dms/mail-data/:/var/mail/
+      - ./docker-data/dms/mail-state/:/var/mail-state/
+      - ./docker-data/dms/mail-logs/:/var/log/mail/
+      - ./docker-data/dms/config/:/tmp/docker-mailserver/
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      - ACCOUNT_PROVISIONER=LDAP
+      - LDAP_SERVER_HOST=ldap # your ldap container/IP/ServerName
+      - LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
+      - LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
+      - LDAP_BIND_PW=admin
+      - LDAP_QUERY_FILTER_USER=(&(mail=%s)(mailEnabled=TRUE))
+      - LDAP_QUERY_FILTER_GROUP=(&(mailGroupMember=%s)(mailEnabled=TRUE))
+      - LDAP_QUERY_FILTER_ALIAS=(|(&(mailAlias=%s)(objectClass=PostfixBookMailForward))(&(mailAlias=%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE)))
+      - LDAP_QUERY_FILTER_DOMAIN=(|(&(mail=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailGroupMember=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailalias=*@%s)(objectClass=PostfixBookMailForward)))
+      - DOVECOT_PASS_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
+      - DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
+      - ENABLE_SASLAUTHD=1
+      - SASLAUTHD_MECHANISMS=ldap
+      - SASLAUTHD_LDAP_SERVER=ldap
+      - SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
+      - SASLAUTHD_LDAP_PASSWORD=admin
+      - SASLAUTHD_LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
+      - SASLAUTHD_LDAP_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%U))
+      - POSTMASTER_ADDRESS=postmaster@localhost.localdomain
+    restart: always
+
+

Using DMS as a local mail relay for containers

+
+

Info

+

This was originally a community contributed guide. Please let us know via a Github Issue if you're having any difficulty following the guide so that we can update it.

+
+

This guide is focused on only using SMTP ports (not POP3 and IMAP) with the intent to relay mail received from another service to an external email address (eg: user@gmail.com). It is not intended for mailbox storage of real users.

+

In this setup docker-mailserver is not intended to receive email from the outside world, so no anti-spam or anti-virus software is needed, making the service lighter to run.

+
+

setup

+

The setup command used below is to be run inside the container.

+
+
+

Open Relays

+

Adding the docker network's gateway to the list of trusted hosts (eg: using the network or connected-networks option), can create an open relay. For instance if IPv6 is enabled on the host machine, but not in Docker.

+
+
    +
  1. +

    Create the file docker-compose.yml with a content like this:

    +
    +

    Example

    +
    services:
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+    container_name: mailserver
+    # Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
+    hostname: mail.example.com
+    ports:
+      - "25:25"
+      - "587:587"
+      - "465:465"
+    volumes:
+      - ./docker-data/dms/mail-data/:/var/mail/
+      - ./docker-data/dms/mail-state/:/var/mail-state/
+      - ./docker-data/dms/mail-logs/:/var/log/mail/
+      - ./docker-data/dms/config/:/tmp/docker-mailserver/
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      - ENABLE_FAIL2BAN=1
+      # Using letsencrypt for SSL/TLS certificates:
+      - SSL_TYPE=letsencrypt
+      # Allow sending emails from other docker containers:
+      # Beware creating an Open Relay: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#permit_docker
+      - PERMIT_DOCKER=network
+      # You may want to enable this: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#spoof_protection
+      # See step 6 below, which demonstrates setup with enabled/disabled SPOOF_PROTECTION:
+      - SPOOF_PROTECTION=0
+    cap_add:
+      - NET_ADMIN # For Fail2Ban to work
+    restart: always
+
    +
    +

    The docs have a detailed page on Environment Variables for reference.

    +
    +Firewalled ports +

    If you have a firewall running, you may need to open ports 25, 587 and 465.

    +

    For example, with the firewall ufw, run:

    +
    ufw allow 25
+ufw allow 587
+ufw allow 465
+
    +

    Caution: This may not be sound advice.

    +
    +
    2. +
  2. +

    Configure your DNS service to use an MX record for the hostname (eg: mail) you configured in the previous step and add the SPF TXT record.

    +
    +

    If you manually manage the DNS zone file for the domain

    +

    It would look something like this:

    +
    $ORIGIN example.com
+@     IN  A      10.11.12.13
+mail  IN  A      10.11.12.13
+
+; mail-server for example.com
+@     IN  MX  10 mail.example.com.
+
+; Add SPF record
+@     IN  TXT    "v=spf1 mx -all"
+
    +

    Then don't forget to change the SOA serial number, and to restart the service.

    +
    +
    3. +
  3. +

    Generate DKIM keys for your domain via setup config dkim.

    +

    Copy the content of the file docker-data/dms/config/opendkim/keys/example.com/mail.txt and add it to your DNS records as a TXT like SPF was handled above.

    +

    I use bind9 for managing my domains, so I just paste it on example.com.db:

    +
    mail._domainkey IN      TXT     ( "v=DKIM1; h=sha256; k=rsa; "
+        "p=MIIBIjANBgkqhkiG9w0BAQEFACAQ8AMIIBCgKCAQEAaH5KuPYPSF3Ppkt466BDMAFGOA4mgqn4oPjZ5BbFlYA9l5jU3bgzRj3l6/Q1n5a9lQs5fNZ7A/HtY0aMvs3nGE4oi+LTejt1jblMhV/OfJyRCunQBIGp0s8G9kIUBzyKJpDayk2+KJSJt/lxL9Iiy0DE5hIv62ZPP6AaTdHBAsJosLFeAzuLFHQ6USyQRojefqFQtgYqWQ2JiZQ3"
+        "iqq3bD/BVlwKRp5gH6TEYEmx8EBJUuDxrJhkWRUk2VDl1fqhVBy8A9O7Ah+85nMrlOHIFsTaYo9o6+cDJ6t1i6G1gu+bZD0d3/3bqGLPBQV9LyEL1Rona5V7TJBGg099NQkTz1IwIDAQAB" )  ; ----- DKIM key mail for example.com
+
    +
    4. +
  4. +

    Get an SSL certificate, we have a guide for you here (Let's Encrypt is a popular service to get free SSL certificates).

    +
    5. +
  5. +

    Start docker-mailserver and check the terminal output for any errors: docker-compose up.

    +
    6. +
  6. +

    Create email accounts and aliases:

    +
    +

    With SPOOF_PROTECTION=0

    +
    setup email add admin@example.com passwd123
+setup email add info@example.com passwd123
+setup alias add admin@example.com external-account@gmail.com
+setup alias add info@example.com external-account@gmail.com
+setup email list
+setup alias list
+
    +

    Aliases make sure that any email that comes to these accounts is forwarded to your third-party email address (external-account@gmail.com), where they are retrieved (eg: via third-party web or mobile app), instead of connecting directly to docker-mailserer with POP3 / IMAP.

    +
    +
    +

    With SPOOF_PROTECTION=1

    +
    setup email add admin.gmail@example.com passwd123
+setup email add info.gmail@example.com passwd123
+setup alias add admin@example.com admin.gmail@example.com
+setup alias add info@example.com info.gmail@example.com
+setup alias add admin.gmail@example.com external-account@gmail.com
+setup alias add info.gmail@example.com external-account@gmail.com
+setup email list
+setup alias list
+
    +

    This extra step is required to avoid the 553 5.7.1 Sender address rejected: not owned by user error (the accounts used for submitting mail to Gmail are admin.gmail@example.com and info.gmail@example.com)

    +
    +
    7. +
  7. +

    Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with ctrl+c and start it again as a daemon: docker-compose up -d.

    +
    8. +
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/examples/tutorials/blog-posts/index.html b/v12.0/examples/tutorials/blog-posts/index.html new file mode 100644 index 00000000..93e9200a --- /dev/null +++ b/v12.0/examples/tutorials/blog-posts/index.html @@ -0,0 +1,1498 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tutorials | Blog Posts - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/examples/tutorials/docker-build/index.html b/v12.0/examples/tutorials/docker-build/index.html new file mode 100644 index 00000000..c97c476e --- /dev/null +++ b/v12.0/examples/tutorials/docker-build/index.html @@ -0,0 +1,1656 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tutorials | Docker Build - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Building your own Docker image

+ +

Building your own Docker image

+

Submodules

+

You'll need to retrieve the git submodules prior to building your own Docker image. From within your copy of the git repo run the following to retrieve the submodules and build the Docker image:

+
git submodule update --init --recursive
+docker build -t <YOUR CUSTOM IMAGE NAME> .
+
+

Or, you can clone and retrieve the submodules in one command:

+
git clone --recurse-submodules https://github.com/docker-mailserver/docker-mailserver
+
+

About Docker

+

Version

+

We make use of build-features that require a recent version of Docker. Depending on your distribution, please have a look at the official installation documentation for Docker to get the latest version. Otherwise, you may encounter issues, for example with the --link flag for a COPY command.

+

Environment

+

If you are not using make to build the image, note that you will need to provide DOCKER_BUILDKIT=1 to the docker build command for the build to succeed.

+

Build Arguments

+

The Dockerfile takes additional, so-called build arguments. These are

+
    +
  1. VCS_VERSION: the image version (default = edge)
    2. +
  2. VCS_REVISION: the image revision (default = unknown)
    3. +
+

When using make to build the image, these are filled with proper values. You can build the image without supplying these arguments just fine though.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/examples/tutorials/mailserver-behind-proxy/index.html b/v12.0/examples/tutorials/mailserver-behind-proxy/index.html new file mode 100644 index 00000000..216ef1a6 --- /dev/null +++ b/v12.0/examples/tutorials/mailserver-behind-proxy/index.html @@ -0,0 +1,1694 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tutorials | Mail-Server behind a Proxy - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Mailserver behind Proxy

+ +

Using docker-mailserver behind a Proxy

+

Information

+

If you are hiding your container behind a proxy service you might have discovered that the proxied requests from now on contain the proxy IP as the request origin. Whilst this behavior is technical correct it produces certain problems on the containers behind the proxy as they cannot distinguish the real origin of the requests anymore.

+

To solve this problem on TCP connections we can make use of the proxy protocol. Compared to other workarounds that exist (X-Forwarded-For which only works for HTTP requests or Tproxy that requires you to recompile your kernel) the proxy protocol:

+
    +
  • It is protocol agnostic (can work with any layer 7 protocols, even when encrypted).
    • +
  • It does not require any infrastructure changes.
    • +
  • NAT-ing firewalls have no impact it.
    • +
  • It is scalable.
    • +
+

There is only one condition: both endpoints of the connection MUST be compatible with proxy protocol.

+

Luckily dovecot and postfix are both Proxy-Protocol ready softwares so it depends only on your used reverse-proxy / loadbalancer.

+

Configuration of the used Proxy Software

+

The configuration depends on the used proxy system. I will provide the configuration examples of traefik v2 using IMAP and SMTP with implicit TLS.

+

Feel free to add your configuration if you achieved the same goal using different proxy software below:

+
+Traefik v2 +

Truncated configuration of traefik itself:

+
services:
+  reverse-proxy:
+    image: docker.io/traefik:latest # v2.5
+    container_name: docker-traefik
+    restart: always
+    command:
+      - "--providers.docker"
+      - "--providers.docker.exposedbydefault=false"
+      - "--providers.docker.network=proxy"
+      - "--entrypoints.web.address=:80"
+      - "--entryPoints.websecure.address=:443"
+      - "--entryPoints.smtp.address=:25"
+      - "--entryPoints.smtp-ssl.address=:465"
+      - "--entryPoints.imap-ssl.address=:993"
+      - "--entryPoints.sieve.address=:4190"
+    ports:
+      - "25:25"
+      - "465:465"
+      - "993:993"
+      - "4190:4190"
+[...]
+
+

Truncated list of necessary labels on the docker-mailserver container:

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    container_name: mailserver
+    hostname: mail.example.com
+    restart: always
+    networks:
+      - proxy
+    labels:
+      - "traefik.enable=true"
+      - "traefik.tcp.routers.smtp.rule=HostSNI(`*`)"
+      - "traefik.tcp.routers.smtp.entrypoints=smtp"
+      - "traefik.tcp.routers.smtp.service=smtp"
+      - "traefik.tcp.services.smtp.loadbalancer.server.port=25"
+      - "traefik.tcp.services.smtp.loadbalancer.proxyProtocol.version=1"
+      - "traefik.tcp.routers.smtp-ssl.rule=HostSNI(`*`)"
+      - "traefik.tcp.routers.smtp-ssl.tls=false"
+      - "traefik.tcp.routers.smtp-ssl.entrypoints=smtp-ssl"
+      - "traefik.tcp.routers.smtp-ssl.service=smtp-ssl"
+      - "traefik.tcp.services.smtp-ssl.loadbalancer.server.port=465"
+      - "traefik.tcp.services.smtp-ssl.loadbalancer.proxyProtocol.version=1"
+      - "traefik.tcp.routers.imap-ssl.rule=HostSNI(`*`)"
+      - "traefik.tcp.routers.imap-ssl.entrypoints=imap-ssl"
+      - "traefik.tcp.routers.imap-ssl.service=imap-ssl"
+      - "traefik.tcp.services.imap-ssl.loadbalancer.server.port=10993"
+      - "traefik.tcp.services.imap-ssl.loadbalancer.proxyProtocol.version=2"
+      - "traefik.tcp.routers.sieve.rule=HostSNI(`*`)"
+      - "traefik.tcp.routers.sieve.entrypoints=sieve"
+      - "traefik.tcp.routers.sieve.service=sieve"
+      - "traefik.tcp.services.sieve.loadbalancer.server.port=4190"
+[...]
+
+

Keep in mind that it is necessary to use port 10993 here. More information below at dovecot configuration.

+
+

Configuration of the Backend (dovecot and postfix)

+

The following changes can be achieved completely by adding the content to the appropriate files by using the projects function to overwrite config files.

+

Changes for postfix can be applied by adding the following content to docker-data/dms/config/postfix-main.cf:

+
postscreen_upstream_proxy_protocol = haproxy
+
+

and to docker-data/dms/config/postfix-master.cf:

+
submission/inet/smtpd_upstream_proxy_protocol=haproxy
+smtps/inet/smtpd_upstream_proxy_protocol=haproxy
+
+

Changes for dovecot can be applied by adding the following content to docker-data/dms/config/dovecot.cf:

+
haproxy_trusted_networks = <your-proxy-ip>, <optional-cidr-notation>
+haproxy_timeout = 3 secs
+service imap-login {
+  inet_listener imaps {
+    haproxy = yes
+    ssl = yes
+    port = 10993
+  }
+}
+
+
+

Note

+

Port 10993 is used here to avoid conflicts with internal systems like postscreen and amavis as they will exchange messages on the default port and obviously have a different origin then compared to the proxy.

+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/examples/use-cases/forward-only-mailserver-with-ldap-authentication/index.html b/v12.0/examples/use-cases/forward-only-mailserver-with-ldap-authentication/index.html new file mode 100644 index 00000000..6f087364 --- /dev/null +++ b/v12.0/examples/use-cases/forward-only-mailserver-with-ldap-authentication/index.html @@ -0,0 +1,1638 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use Cases | Forward-Only Mail-Server with LDAP - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Forward-Only Mail-Server with LDAP

+ +

Building a Forward-Only Mail-Server

+

A forward-only mail-server does not have any local mailboxes. Instead, it has only aliases that forward emails to external email accounts (for example to a Gmail account). You can also send email from the localhost (the computer where docker-mailserver is installed), using as sender any of the alias addresses.

+

The important settings for this setup (on mailserver.env) are these:

+
PERMIT_DOCKER=host
+ENABLE_POP3=
+ENABLE_CLAMAV=0
+SMTP_ONLY=1
+ENABLE_SPAMASSASSIN=0
+ENABLE_FETCHMAIL=0
+
+

Since there are no local mailboxes, we use SMTP_ONLY=1 to disable dovecot. We disable as well the other services that are related to local mailboxes (POP3, ClamAV, SpamAssassin, etc.)

+

We can create aliases with ./setup.sh, like this:

+
./setup.sh alias add <alias-address> <external-email-account>
+
+

Authenticating with LDAP

+

If you want to send emails from outside the mail-server you have to authenticate somehow (with a username and password). One way of doing it is described in this discussion. However if there are many user accounts, it is better to use authentication with LDAP. The settings for this on mailserver.env are:

+
ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
+ACCOUNT_PROVISIONER=LDAP
+LDAP_START_TLS=yes
+LDAP_SERVER_HOST=ldap.example.org
+LDAP_SEARCH_BASE=ou=users,dc=example,dc=org
+LDAP_BIND_DN=cn=mailserver,dc=example,dc=org
+LDAP_BIND_PW=pass1234
+
+ENABLE_SASLAUTHD=1
+SASLAUTHD_MECHANISMS=ldap
+SASLAUTHD_LDAP_SERVER=ldap.example.org
+SASLAUTHD_LDAP_START_TLS=yes
+SASLAUTHD_LDAP_BIND_DN=cn=mailserver,dc=example,dc=org
+SASLAUTHD_LDAP_PASSWORD=pass1234
+SASLAUTHD_LDAP_SEARCH_BASE=ou=users,dc=example,dc=org
+SASLAUTHD_LDAP_FILTER=(&(uid=%U)(objectClass=inetOrgPerson))
+
+

My LDAP data structure is very basic, containing only the username, password, and the external email address where to forward emails for this user. An entry looks like this:

+
add uid=username,ou=users,dc=example,dc=org
+uid: username
+objectClass: inetOrgPerson
+sn: username
+cn: username
+userPassword: {SSHA}abcdefghi123456789
+email: external-account@gmail.com
+
+

This structure is different from what is expected/assumed from the configuration scripts of docker-mailserver, so it doesn't work just by using the LDAP_QUERY_FILTER_... settings. Instead, I had to use a custom configuration (via user-patches.sh). I created the script docker-data/dms/config/user-patches.sh, with content like this:

+
#!/bin/bash
+
+rm -f /etc/postfix/{ldap-groups.cf,ldap-domains.cf}
+
+postconf \
+    "virtual_mailbox_domains = /etc/postfix/vhost" \
+    "virtual_alias_maps = ldap:/etc/postfix/ldap-aliases.cf texthash:/etc/postfix/virtual" \
+    "smtpd_sender_login_maps = ldap:/etc/postfix/ldap-users.cf"
+
+sed -i /etc/postfix/ldap-users.cf \
+    -e '/query_filter/d' \
+    -e '/result_attribute/d' \
+    -e '/result_format/d'
+cat <<EOF >> /etc/postfix/ldap-users.cf
+query_filter = (uid=%u)
+result_attribute = uid
+result_format = %s@example.org
+EOF
+
+sed -i /etc/postfix/ldap-aliases.cf \
+    -e '/domain/d' \
+    -e '/query_filter/d' \
+    -e '/result_attribute/d'
+cat <<EOF >> /etc/postfix/ldap-aliases.cf
+domain = example.org
+query_filter = (uid=%u)
+result_attribute = mail
+EOF
+
+postfix reload
+
+

You see that besides query_filter, I had to customize as well result_attribute and result_format.

+
+

See also

+

For more details about using LDAP see: LDAP managed mail-server with Postfix and Dovecot for multiple domains

+
+
+

Note

+

Another solution that serves as a forward-only mail-server is this.

+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/examples/use-cases/imap-folders/index.html b/v12.0/examples/use-cases/imap-folders/index.html new file mode 100644 index 00000000..6aaded81 --- /dev/null +++ b/v12.0/examples/use-cases/imap-folders/index.html @@ -0,0 +1,1678 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use Cases | Customize Mailbox Folders - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + + + + + + + + +
+
+ + + + + + + +

Mailboxes (aka IMAP Folders)

+

INBOX is setup as the private inbox namespace. By default target/dovecot/15-mailboxes.conf configures the special IMAP folders Drafts, Sent, Junk and Trash to be automatically created and subscribed. They are all assigned to the private inbox namespace (which implicitly provides the INBOX folder).

+

These IMAP folders are considered special because they add a "SPECIAL-USE" attribute, which is a standardized way to communicate to mail clients that the folder serves a purpose like storing spam/junk mail (\Junk) or deleted mail (\Trash). This differentiates them from regular mail folders that you may use for organizing.

+

Adding a mailbox folder

+

See target/dovecot/15-mailboxes.conf for existing mailbox folders which you can modify or uncomment to enable some other common mailboxes. For more information try the official Dovecot documentation.

+

The Archive special IMAP folder may be useful to enable. To do so, make a copy of target/dovecot/15-mailboxes.conf and uncomment the Archive mailbox definition. Mail clients should understand that this folder is intended for archiving mail due to the \Archive "SPECIAL-USE" attribute.

+

With the provided docker-compose.yml example, a volume bind mounts the host directory docker-data/dms/config/ to the container location /tmp/docker-mailserver/. Config file overrides should instead be mounted to a different location as described in Overriding Configuration for Dovecot:

+
volumes:
+  - ./docker-data/dms/config/dovecot/15-mailboxes.conf:/etc/dovecot/conf.d/15-mailboxes.conf:ro
+
+

Caution

+

Adding folders to an existing setup

+

Handling of newly added mailbox folders can be inconsistent across mail clients:

+
    +
  • Users may experience issues such as archived emails only being available locally.
    • +
  • Users may need to migrate emails manually between two folders.
    • +
+

Support for SPECIAL-USE attributes

+

Not all mail clients support the SPECIAL-USE attribute for mailboxes (defined in RFC 6154). These clients will treat the mailbox folder as any other, using the name assigned to it instead.

+

Some clients may still know to treat these folders for their intended purpose if the mailbox name matches the common names that the SPECIAL-USE attributes represent (eg Sent as the mailbox name for \Sent).

+

Internationalization (i18n)

+

Usually the mail client will know via context such as the SPECIAL-USE attribute or common English mailbox names, to provide a localized label for the users preferred language.

+

Take care to test localized names work well as well.

+

Email Clients Support

+
    +
  • If a new mail account is added without the SPECIAL-USE attribute enabled for archives:
      +
    • Thunderbird suggests and may create an Archives folder on the server.
      • +
    • Outlook for Android archives to a local folder.
      • +
    • Spark for Android archives to server folder named Archive.
      • +
    +
    • +
  • If a new mail account is added after the SPECIAL-USE attribute is enabled for archives:
      +
    • Thunderbird, Outlook for Android and Spark for Android will use the mailbox folder name assigned.
      • +
    +
    • +
+
+

Windows Mail

+

Windows Mail has been said to ignore SPECIAL-USE attribute and look only at the mailbox folder name assigned.

+
+
+

Needs citation

+

This information is provided by the community.

+

It presently lacks references to confirm the behaviour. If any information is incorrect please let us know! 😄

+
+ + + + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/faq/index.html b/v12.0/faq/index.html new file mode 100644 index 00000000..c3651539 --- /dev/null +++ b/v12.0/faq/index.html @@ -0,0 +1,2452 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + FAQ - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

FAQ

+ +

What kind of database are you using?

+

None! No database is required. The filesystem is the database. This image is based on config files that can be persisted using bind mounts (default) or Docker volumes, and as such versioned, backed up and so forth.

+

Where are emails stored?

+

Mails are stored in /var/mail/${domain}/${username}. Since v9.0.0 it is possible to add custom user_attributes for each accounts to have a different mailbox configuration (See #1792).

+

How are IMAP mailboxes (aka IMAP Folders) set up?

+

INBOX is setup by default with the special IMAP folders Drafts, Sent, Junk and Trash. You can learn how to modify or add your own folders (including additional special folders like Archive) by visiting our docs page Customizing IMAP Folders for more information.

+

How do I update DMS?

+

Make sure to read the CHANGELOG before updating to new versions, to be prepared for possible breaking changes.

+

Then, run the following commands:

+
docker-compose pull
+docker-compose down
+docker-compose up -d
+
+

You should see the new version number on startup, for example: [ INF ] Welcome to docker-mailserver 11.3.1. And you're done! Don't forget to have a look at the remaining functions of the setup.sh script with ./setup.sh help.

+

Which operating systems are supported?

+
    +
  • Linux is officially supported.
    • +
  • Windows and macOS are not supported and users and have reported various issues running the image on these hosts.
    • +
+

As you'll realistically be deploying to production on a Linux host, if you are on Windows or macOS and want to run the image locally first, it's advised to do so via a VM guest running Linux if you have issues running DMS on your host system.

+

What are the system requirements?

+ +
    +
  • 1 vCore
    • +
  • 2GB RAM
    • +
  • Swap enabled for the container
    • +
+

Minimum

+
    +
  • 1 vCore
    • +
  • 512MB RAM
    • +
  • You'll need to avoid running some services like ClamAV (disabled by default) to be able to run on a host with 512MB of RAM.
    • +
+
+

Warning

+

ClamAV can consume a lot of memory, as it reads the entire signature database into RAM.

+

Current figure is about 850M and growing. If you get errors about ClamAV or amavis failing to allocate memory you need more RAM or more swap and of course docker must be allowed to use swap (not always the case). If you can't use swap at all you may need 3G RAM.

+
+

How to alter a running DMS instance without relaunching the container?

+

docker-mailserver aggregates multiple "sub-services", such as Postfix, Dovecot, Fail2ban, SpamAssassin, etc. In many cases, one may edit a sub-service's config and reload that very sub-service, without stopping and relaunching the whole mail-server.

+

In order to do so, you'll probably want to push your config updates to your server through a Docker volume (these docs use: ./docker-data/dms/config/:/tmp/docker-mailserver/), then restart the sub-service to apply your changes, using supervisorctl. For instance, after editing fail2ban's config: supervisorctl restart fail2ban.

+

See the documentation for supervisorctl.

+
+

Tip

+

To add, update or delete an email account; there is no need to restart postfix / dovecot service inside the container after using setup.sh script.

+

For more information, see #1639.

+
+

How can I sync the container and host date/time?

+

Share the host's /etc/localtime with the container, e.g. by using a bind mount:

+
volumes:
+  - /etc/localtime:/etc/localtime:ro
+
+

Optionally, you can set the TZ ENV variable; e.g. TZ=Europe/Berlin. Check this list for which values are allowed.

+

What is the file format?

+

All files are using the Unix format with LF line endings. Please do not use CRLF.

+

Do you support multiple domains?

+

DMS supports multiple domains out of the box, so you can do this:

+
./setup.sh email add user1@example.com
+./setup.sh email add user1@example.de
+./setup.sh email add user1@server.example.org
+
+

What about backups?

+

Bind mounts (default)

+

From the location of your docker-compose.yml, create a compressed archive of your docker-data/dms/config/ and docker-data/dms/mail-* folders:

+
tar --gzip -cf "backup-$(date +%F).tar.gz" ./docker-data/dms
+
+

Then to restore docker-data/dms/config/ and docker-data/dms/mail-* folders from your backup file:

+
tar --gzip -xf backup-date.tar.gz
+
+

Volumes

+

Assuming that you use docker-compose and data volumes, you can backup the configuration, emails and logs like this:

+
# create backup
+docker run --rm -it \
+  -v "${PWD}/docker-data/dms/config/:/tmp/docker-mailserver/" \
+  -v "${PWD}/docker-data/dms-backups/:/backup/" \
+  --volumes-from mailserver \
+  alpine:latest \
+  tar czf "/backup/mail-$(date +%F).tar.gz" /var/mail /var/mail-state /var/log/mail /tmp/docker-mailserver
+
+# delete backups older than 30 days
+find "${PWD}/docker-data/dms-backups/" -type f -mtime +30 -delete
+
+

What about the ./docker-data/dms/mail-state folder?

+

When you run DMS with the ENV variable ONE_DIR=1 (default), this folder will:

+
    +
  • Provide support to persist Fail2Ban blocks, ClamAV signature updates, and the like when the container is restarted or recreated.
    • +
  • To persist that container state properly this folder should be volume mounted to /var/mail-state/ internally.
    • +
+

Service data is relocated to the mail-state folder for the following services: Postfix, Dovecot, Fail2Ban, Amavis, PostGrey, ClamAV, SpamAssassin.

+

I Want to Know More About the Ports

+

See this part of the documentation for further details and best practice advice, especially regarding security concerns.

+

How can I configure my email client?

+

Login is full email address (<user>@<domain>).

+
# IMAP
+username:           <user1@example.com>
+password:           <mypassword>
+server:             <mail.example.com>
+imap port:          143 or 993 with STARTTLS/SSL (recommended)
+imap path prefix:   INBOX
+
+# SMTP
+smtp port:          25 or 587/465 with STARTTLS/SSL (recommended)
+username:           <user1@example.com>
+password:           <mypassword>
+
+

DMS is properly configured for port 587, if possible, we recommend using port 465 for SMTP though. See this section to learn more about ports.

+

Can I use a naked/bare domain (i.e. no hostname)?

+

Yes, but not without some configuration changes. Normally it is assumed that DMS runs on a host with a name, so the fully qualified host name might be mail.example.com with the domain example.com. The MX records point to mail.example.com.

+

To use a bare domain (where the host name is example.com and the domain is also example.com), change mydestination:

+
    +
  • From: mydestination = $myhostname, localhost.$mydomain, localhost
    • +
  • To: mydestination = localhost.$mydomain, localhost
    • +
+

Add the latter line to docker-data/dms/config/postfix-main.cf. If that doesn't work, make sure that OVERRIDE_HOSTNAME is blank in your mailserver.env file. Without these changes there will be warnings in the logs like:

+
warning: do not list domain example.com in BOTH mydestination and virtual_mailbox_domains
+
+

Plus of course mail delivery fails.

+

Also you need to define hostname: example.com in your docker-compose.yml.

+
+

You might not want a bare domain

+

We encourage you to consider using a subdomain where possible.

+
    +
  • There are benefits to preferring a subdomain.
    • +
  • A bare domain is not required to have user@example.com, that is distinct from your hostname which is identified by a DNS MX record.
    • +
+
+

How can I configure a catch-all?

+

Considering you want to redirect all incoming e-mails for the domain example.com to user1@example.com, add the following line to docker-data/dms/config/postfix-virtual.cf:

+
@example.com user1@example.com
+
+

How can I delete all the emails for a specific user?

+

First of all, create a special alias named devnull by editing docker-data/dms/config/postfix-aliases.cf:

+
devnull: /dev/null
+
+

Considering you want to delete all the e-mails received for baduser@example.com, add the following line to docker-data/dms/config/postfix-virtual.cf:

+
baduser@example.com devnull
+
+
+

Important

+

If you use a catch-all rule for the main/sub domain, you need another entry in docker-data/dms/config/postfix-virtual.cf:

+
@mail.example.com hello@example.com
+baduser@example.com devnull
+devnull@mail.example.com devnull
+
+
+

What kind of SSL certificates can I use?

+

Both RSA and ECDSA certs are supported. You can provide your own cert files manually, or mount a letsencrypt generated directory (with alternative support for Traefik's acme.json). Check out the SSL_TYPE documentation for more details.

+

I just moved from my old mail server to DMS, but "it doesn't work"?

+

If this migration implies a DNS modification, be sure to wait for DNS propagation before opening an issue. +Few examples of symptoms can be found here or here.

+

This could be related to a modification of your MX record, or the IP mapped to mail.example.com. Additionally, validate your DNS configuration.

+

If everything is OK regarding DNS, please provide formatted logs and config files. This will allow us to help you.

+

If we're blind, we won't be able to do anything.

+

Can DMS run in a Rancher environment?

+

Yes, by adding the environment variable PERMIT_DOCKER: network.

+
+

Warning

+

Adding the Docker network's gateway to the list of trusted hosts, e.g. using the network or connected-networks option, can create an open relay, for instance if IPv6 is enabled on the host machine but not in Docker.

+
+

Connection refused or No response at all

+

You see errors like "Connection Refused" and "Connection closed by foreign host", or you cannot connect at all? You may not be able to connect with your mail client (MUA)? Make sure to check Fail2Ban did not ban you (for exceeding the number of tried logins for example)! You can run

+
docker exec <CONTAINER NAME> setup fail2ban
+
+

and check whether your IP address appears. Use

+
docker exec <CONTAINER NAME> setup fail2ban unban <YOUR IP>
+
+

to unban the IP address.

+

How can I authenticate users with SMTP_ONLY=1?

+

See #1247 for an example.

+
+

Todo

+

Write a How-to / Use-Case / Tutorial about authentication with SMTP_ONLY.

+
+

Common Errors

+
warning: connect to Milter service inet:localhost:8893: Connection refused
+# DMARC not running
+# => /etc/init.d/opendmarc restart
+
+warning: connect to Milter service inet:localhost:8891: Connection refused
+# DKIM not running
+# => /etc/init.d/opendkim restart
+
+mail amavis[1459]: (01459-01) (!)connect to /var/run/clamav/clamd.ctl failed, attempt #1: Can't connect to a UNIX socket /var/run/clamav/clamd.ctl: No such file or directory
+mail amavis[1459]: (01459-01) (!)ClamAV-clamd: All attempts (1) failed connecting to /var/run/clamav/clamd.ctl, retrying (2)
+mail amavis[1459]: (01459-01) (!)ClamAV-clamscan av-scanner FAILED: /usr/bin/clamscan KILLED, signal 9 (0009) at (eval 100) line 905.
+mail amavis[1459]: (01459-01) (!!)AV: ALL VIRUS SCANNERS FAILED
+# Clamav is not running (not started or because you don't have enough memory)
+# => check requirements and/or start Clamav
+
+

How to use DMS behind a proxy

+

Using user-patches.sh, update the container file /etc/postfix/main.cf to include:

+
proxy_interfaces = X.X.X.X (your public IP)
+
+

How to adjust settings with the user-patches.sh script

+

Suppose you want to change a number of settings that are not listed as variables or add things to the server that are not included?

+

docker-mailserver has a built-in way to do post-install processes. If you place a script called user-patches.sh in the config directory it will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started.

+

It is common to use a local directory for config added to docker-mailsever via a volume mount in your docker-compose.yml (eg: ./docker-data/dms/config/:/tmp/docker-mailserver/).

+

Add or create the script file to your config directory:

+
cd ./docker-data/dms/config
+touch user-patches.sh
+chmod +x user-patches.sh
+
+

Then fill user-patches.sh with suitable code.

+

If you want to test it you can move into the running container, run it and see if it does what you want. For instance:

+
# start shell in container
+./setup.sh debug login
+
+# check the file
+cat /tmp/docker-mailserver/user-patches.sh
+
+# run the script
+/tmp/docker-mailserver/user-patches.sh
+
+# exit the container shell back to the host shell
+exit
+
+

You can do a lot of things with such a script. You can find an example user-patches.sh script here: example user-patches.sh script.

+

We also have a very similar docs page specifically about this feature!

+
+

Special use-case - patching the supervisord configuration

+

It seems worth noting, that the user-patches.sh gets executed through supervisord. If you need to patch some supervisord config (e.g. /etc/supervisor/conf.d/saslauth.conf), the patching happens too late.

+

An easy workaround is to make the user-patches.sh reload the supervisord config after patching it:

+
#!/bin/bash
+sed -i 's/rimap -r/rimap/' /etc/supervisor/conf.d/saslauth.conf
+supervisorctl update
+
+
+

How to ban custom IP addresses with Fail2ban

+

Use the following command:

+
./setup.sh fail2ban ban <IP>
+
+

The default bantime is 180 days. This value can be customized.

+

What to do in case of SPF/Forwarding problems

+

If you got any problems with SPF and/or forwarding mails, give SRS a try. You enable SRS by setting ENABLE_SRS=1. See the variable description for further information.

+

Why are my emails not being delivered?

+

There are many reasons why email might be rejected, common causes are:

+
    +
  • Wrong or untrustworthy SSL certificate.
    • +
  • A TLD (your domain) or IP address with a bad reputation.
    • +
  • Misconfigured DNS records.
    • +
+

DMS does not manage those concerns, verify they are not causing your delivery problems before reporting a bug on our issue tracker. Resources that can help you troubleshoot:

+
    +
  • mail-tester can test your deliverability.
    • +
  • helloinbox provides a checklist of things to improve your deliverability.
    • +
+

SpamAssasin

+

How can I manage my custom SpamAssassin rules?

+

Antispam rules are managed in docker-data/dms/config/spamassassin-rules.cf.

+

What are acceptable SA_SPAM_SUBJECT values?

+

For no subject set SA_SPAM_SUBJECT=undef.

+

For a trailing white-space subject one can define the whole variable with quotes in docker-compose.yml:

+
environment:
+  - "SA_SPAM_SUBJECT=[SPAM] "
+
+

Why are SpamAssassin x-headers not inserted into my subdomain.example.com subdomain emails?

+

In the default setup, amavis only applies SpamAssassin x-headers into domains matching the template listed in the config file (05-domain_id in the amavis defaults).

+

The default setup @local_domains_acl = ( ".$mydomain" ); does not match subdomains. To match subdomains, you can override the @local_domains_acl directive in the amavis user config file 50-user with @local_domains_maps = ("."); to match any sort of domain template.

+

How can I make SpamAssassin better recognize spam?

+

Put received spams in .Junk/ imap folder using SPAMASSASSIN_SPAM_TO_INBOX=1 and MOVE_SPAM_TO_JUNK=1 and add a user cron like the following:

+
# This assumes you're having `environment: ONE_DIR=1` in the `mailserver.env`,
+# with a consolidated config in `/var/mail-state`
+#
+# m h dom mon dow command
+# Everyday 2:00AM, learn spam from a specific user
+0 2 * * * docker exec mailserver sa-learn --spam /var/mail/example.com/username/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin
+
+

With docker-compose you can more easily use the internal instance of cron within docker-mailserver. This is less problematic than the simple solution shown above, because it decouples the learning from the host on which docker-mailserver is running, and avoids errors if the mail-server is not running.

+

The following configuration works nicely:

+
+Example +

Create a system cron file:

+
# in the docker-compose.yml root directory
+mkdir -p ./docker-data/dms/cron
+touch ./docker-data/dms/cron/sa-learn
+chown root:root ./docker-data/dms/cron/sa-learn
+chmod 0644 ./docker-data/dms/cron/sa-learn
+
+

Edit the system cron file nano ./docker-data/dms/cron/sa-learn, and set an appropriate configuration:

+
# This assumes you're having `environment: ONE_DIR=1` in the env-mailserver,
+# with a consolidated config in `/var/mail-state`
+#
+# '> /dev/null' to send error notifications from 'stderr' to 'postmaster@example.com'
+#
+# m h dom mon dow user command
+#
+# Everyday 2:00AM, learn spam from a specific user
+# spam: junk directory
+0  2 * * * root  sa-learn --spam /var/mail/example.com/username/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
+# ham: archive directories
+15 2 * * * root  sa-learn --ham /var/mail/example.com/username/.Archive* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
+# ham: inbox subdirectories
+30 2 * * * root  sa-learn --ham /var/mail/example.com/username/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
+#
+# Everyday 3:00AM, learn spam from all users of a domain
+# spam: junk directory
+0  3 * * * root  sa-learn --spam /var/mail/not-example.com/*/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
+# ham: archive directories
+15 3 * * * root  sa-learn --ham /var/mail/not-example.com/*/.Archive* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
+# ham: inbox subdirectories
+30 3 * * * root  sa-learn --ham /var/mail/not-example.com/*/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
+
+

Then with docker-compose.yml:

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    volumes:
+      - ./docker-data/dms/cron/sa-learn:/etc/cron.d/sa-learn
+
+

Or with Docker Swarm:

+
services:
+  mailserver:
+    image: ghcr.io/docker-mailserver/docker-mailserver:latest
+    # ...
+    configs:
+      - source: my_sa_crontab
+        target: /etc/cron.d/sa-learn
+
+configs:
+  my_sa_crontab:
+    file: ./docker-data/dms/cron/sa-learn
+
+
+

With the default settings, SpamAssassin will require 200 mails trained for spam (for example with the method explained above) and 200 mails trained for ham (using the same command as above but using --ham and providing it with some ham mails). Until you provided these 200+200 mails, SpamAssassin will not take the learned mails into account. For further reference, see the SpamAssassin Wiki.

+

How do I have more control about what SpamAssassin is filtering?

+

By default, SPAM and INFECTED emails are put to a quarantine which is not very straight forward to access. Several config settings are affecting this behavior:

+

First, make sure you have the proper thresholds set:

+
SA_TAG=-100000.0
+SA_TAG2=3.75
+SA_KILL=100000.0
+
+
    +
  • The very negative vaue in SA_TAG makes sure, that all emails have the SpamAssassin headers included.
    • +
  • SA_TAG2 is the actual threshold to set the YES/NO flag for spam detection.
    • +
  • SA_KILL needs to be very high, to make sure nothing is bounced at all (SA_KILL superseeds SPAMASSASSIN_SPAM_TO_INBOX)
    • +
+

Make sure everything (including SPAM) is delivered to the inbox and not quarantined:

+
SPAMASSASSIN_SPAM_TO_INBOX=1
+
+

Use MOVE_SPAM_TO_JUNK=1 or create a sieve script which puts spam to the Junk folder:

+
require ["comparator-i;ascii-numeric","relational","fileinto"];
+
+if header :contains "X-Spam-Flag" "YES" {
+  fileinto "Junk";
+} elsif allof (
+   not header :matches "x-spam-score" "-*",
+   header :value "ge" :comparator "i;ascii-numeric" "x-spam-score" "3.75" ) {
+  fileinto "Junk";
+}
+
+

Create a dedicated mailbox for emails which are infected/bad header and everything amavis is blocking by default and put its address into docker-data/dms/config/amavis.cf

+
$clean_quarantine_to      = "amavis\@example.com";
+$virus_quarantine_to      = "amavis\@example.com";
+$banned_quarantine_to     = "amavis\@example.com";
+$bad_header_quarantine_to = "amavis\@example.com";
+$spam_quarantine_to       = "amavis\@example.com";
+
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/favicon.ico b/v12.0/favicon.ico new file mode 100644 index 00000000..7badbc70 Binary files /dev/null and b/v12.0/favicon.ico differ diff --git a/v12.0/index.html b/v12.0/index.html new file mode 100644 index 00000000..94512523 --- /dev/null +++ b/v12.0/index.html @@ -0,0 +1,1657 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Home - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Welcome to the Documentation for docker-mailserver!

+
+

This Documentation is Versioned

+

Make sure to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to the :latest image tag - the most recent stable release.

+
+

This documentation provides you not only with the basic setup and configuration of DMS but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more.

+

About

+

docker-mailserver, or DMS for short, is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). It employs only configuration files, no SQL database. The image is focused around the slogan "Keep it simple and versioned".

+

Contents

+

Getting Started

+

If you're completely new to mail servers or you want to read up on them, check out our Introduction page. If you're new to DMS as a mail server appliance, make sure to read the Usage chapter first. If you want to look at examples for Docker Compose, we have an Examples page.

+

There is also a script - setup.sh - supplied with this project. It supports you in configuring and administrating your server. Information on how to get it and how to use it is available on a dedicated page.

+

Configuration

+

We have a dedicated configuration page. It contains most of the configuration and explanation you need to setup your mail server properly. Be aware that advanced tasks may still require reading through all parts of this documentation; it may also involve inspecting your running container for debugging purposes. After all, a mail-server is a complex arrangement of various programs.

+
+

Important

+

If you'd like to change, patch or alter files or behavior of docker-mailserver, you can use a script. Just place a script called user-patches.sh in your ./docker-data/dms/config/ folder volume (which is mounted to /tmp/docker-mailserver/ inside the container) and it will be run on container startup. See the 'Modifications via Script' page for additional documentation and an example.

+
+

You might also want to check out:

+
    +
  1. A list of all configuration options via ENV
    2. +
  2. A list of all optional and automatically created configuration files and directories
    3. +
  3. How to debug your mail server
    4. +
+
+

Tip

+

Definitely check out the FAQ for more information and tips! Please do not open an issue before you have checked our documentation for answers, including the FAQ!

+
+

Tests

+

DMS employs a variety of tests. If you want to know more about our test suite, view our testing docs.

+

Contributing

+

We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the Contributing section.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/introduction/index.html b/v12.0/introduction/index.html new file mode 100644 index 00000000..8ee547d8 --- /dev/null +++ b/v12.0/introduction/index.html @@ -0,0 +1,1860 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

An Overview of Mail Server Infrastructure

+

This article answers the question "What is a mail server, and how does it perform its duty?" and it gives the reader an introduction to the field that covers everything you need to know to get started with docker-mailserver.

+

The Anatomy of a Mail Server

+

A mail server is only a part of a client-server relationship aimed at exchanging information in the form of emails. Exchanging emails requires using specific means (programs and protocols).

+

docker-mailserver provides you with the server portion, whereas the client can be anything from a terminal via text-based software (eg. Mutt) to a fully-fledged desktop application (eg. Mozilla Thunderbird, Microsoft Outlook…), to a web interface, etc.

+

Unlike the client-side where usually a single program is used to perform retrieval and viewing of emails, the server-side is composed of many specialized components. The mail server is capable of accepting, forwarding, delivering, storing and overall exchanging messages, but each one of those tasks is actually handled by a specific piece of software. All of these "agents" must be integrated with one another for the exchange to take place.

+

docker-mailserver has made informed choices about those components and their (default) configuration. It offers a comprehensive platform to run a fully featured mail server in no time!

+

Components

+

The following components are required to create a complete delivery chain:

+
    +
  • MUA: a Mail User Agent is basically any client/program capable of sending emails to a mail server; while also capable of fetching emails from a mail server for presenting them to the end users.
    • +
  • MTA: a Mail Transfer Agent is the so-called "mail server" as seen from the MUA's perspective. It's a piece of software dedicated to accepting submitted emails, then forwarding them-where exactly will depend on an email's final destination. If the receiving MTA is responsible for the FQDN the email is sent to, then an MTA is to forward that email to an MDA (see below). Otherwise, it is to transfer (ie. forward, relay) to another MTA, "closer" to the email's final destination.
    • +
  • MDA: a Mail Delivery Agent is responsible for accepting emails from an MTA and dropping them into their recipients' mailboxes, whichever the form.
    • +
+

Here's a schematic view of mail delivery:

+
Sending an email:    MUA ----> MTA ----> (MTA relays) ----> MDA
+Fetching an email:   MUA <--------------------------------- MDA
+
+

There may be other moving parts or sub-divisions (for instance, at several points along the chain, specialized programs may be analyzing, filtering, bouncing, editing… the exchanged emails).

+

In a nutshell, docker-mailserver provides you with the following components:

+
    +
  • A MTA: Postfix
    • +
  • A MDA: Dovecot
    • +
  • A bunch of additional programs to improve security and emails processing
    • +
+

Here's where docker-mailserver's toochain fits within the delivery chain:

+
                                    docker-mailserver is here:
+                                                         ┏━━━━━━━┓
+Sending an email:    MUA ---> MTA ---> (MTA relays) ---> ┫ MTA ╮ ┃
+Fetching an email:   MUA <------------------------------ ┫ MDA ╯ ┃
+                                                         ┗━━━━━━━┛
+
+
+An Example +

Let's say Alice owns a Gmail account, alice@gmail.com; and Bob owns an account on a docker-mailserver's instance, bob@dms.io.

+

Make sure not to conflate these two very different scenarios: +A) Alice sends an email to bob@dms.io => the email is first submitted to MTA smtp.gmail.com, then relayed to MTA smtp.dms.io where it is then delivered into Bob's mailbox. +B) Bob sends an email to alice@gmail.com => the email is first submitted to MTA smtp.dms.io, then relayed to MTA smtp.gmail.com and eventually delivered into Alice's mailbox.

+

In scenario A the email leaves Gmail's premises, that email's initial submission is not handled by your docker-mailserver instance(MTA); it merely receives the email after it has been relayed by Gmail's MTA. In scenario B, the docker-mailserver instance(MTA) handles the submission, prior to relaying.

+

The main takeaway is that when a third-party sends an email to a docker-mailserver instance(MTA) (or any MTA for that matter), it does not establish a direct connection with that MTA. Email submission first goes through the sender's MTA, then some relaying between at least two MTAs is required to deliver the email. That will prove very important when it comes to security management.

+
+

One important thing to note is that MTA and MDA programs may actually handle multiple tasks (which is the case with docker-mailserver's Postfix and Dovecot).

+

For instance, Postfix is both an SMTP server (accepting emails) and a relaying MTA (transferring, ie. sending emails to other MTA/MDA); Dovecot is both an MDA (delivering emails in mailboxes) and an IMAP server (allowing MUAs to fetch emails from the mail server). On top of that, Postfix may rely on Dovecot's authentication capabilities.

+

The exact relationship between all the components and their respective (sometimes shared) responsibilities is beyond the scope of this document. Please explore this wiki & the web to get more insights about docker-mailserver's toolchain.

+

About Security & Ports

+

Introduction

+

In the previous section, three components were outlined. Each one of those is responsible for a specific task when it comes to exchanging emails:

+
    +
  • Submission: for a MUA (client), the act of sending actual email data over the network, toward an MTA (server).
    • +
  • Transfer (aka. Relay): for an MTA, the act of sending actual email data over the network, toward another MTA (server) closer to the final destination (where an MTA will forward data to an MDA).
    • +
  • Retrieval: for a MUA (client), the act of fetching actual email data over the network, from an MDA.
    • +
+

Postfix handles Submission (and may handle Relay), whereas Dovecot handles Retrieval. They both need to be accessible by MUAs in order to act as servers, therefore they expose public endpoints on specific TCP ports. Those endpoints may be secured, using an encryption scheme and TLS certificates.

+

When it comes to the specifics of email exchange, we have to look at protocols and ports enabled to support all the identified purposes. There are several valid options and they've been evolving overtime.

+

Overview

+

The following picture gives a visualization of the interplay of all components and their respective ports:

+
 ┏━━━━━━━━━━ Submission ━━━━━━━━━━━━┓┏━━━━━━━━━━━━━ Transfer/Relay ━━━━━━━━━━━┓
+
+                           ┌─────────────────────┐                    ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
+MUA ----- STARTTLS ------> ┤(587)   MTA ╮    (25)├ <-- cleartext ---> ┊ Third-party MTA ┊
+    ----- implicit TLS --> ┤(465)       │        |                    └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
+    ----- cleartext -----> ┤(25)        │        |
+                           |┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄|
+MUA <---- STARTTLS ------- ┤(143)   MDA ╯        |
+    <---- implicit TLS --- ┤(993)                |
+                           └─────────────────────┘
+
+ ┗━━━━━━━━━━ Retrieval ━━━━━━━━━━━━━┛
+
+

If you're new to email infrastructure, both that table and the schema may be confusing. +Read on to expand your understanding and learn about docker-mailserver's configuration, including how you can customize it.

+

Submission - SMTP

+

For a MUA to send an email to an MTA, it needs to establish a connection with that server, then push data packets over a network that both the MUA (client) and the MTA (server) are connected to. The server implements the SMTP protocol, which makes it capable of handling Submission.

+

In the case of docker-mailserver, the MTA (SMTP server) is Postfix. The MUA (client) may vary, yet its Submission request is performed as TCP packets sent over the public internet. This exchange of information may be secured in order to counter eavesdropping.

+

Now let's say I own an account on a docker-mailserver instance, me@dms.io. There are two very different use-cases for Submission:

+
    +
  1. I want to send an email to someone
    2. +
  2. Someone wants to send you an email
    3. +
+

In the first scenario, I will be submitting my email directly to my docker-mailserver instance/MTA (Postfix), which will then relay the email to its recipient's MTA for final delivery. In this case, Submission is first handled by establishing a direct connection to my own MTA-so at least for this portion of the delivery chain, I'll be able to ensure security/confidentiality. Not so much for what comes next, ie. relaying between MTAs and final delivery.

+

In the second scenario, a third-party email account owner will be first submitting an email to some third-party MTA. I have no control over this initial portion of the delivery chain, nor do I have control over the relaying that comes next. My MTA will merely accept a relayed email coming "out of the blue".

+

My MTA will thus have to support two kinds of Submission:

+
    +
  • Outbound Submission (self-owned email is submitted directly to the MTA, then is relayed "outside")
    • +
  • Inbound Submission (third-party email has been submitted & relayed, then is accepted "inside" by the MTA)
    • +
+
 ┏━━━━ Outbound Submission ━━━━┓
+
+                    ┌────────────────────┐                    ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
+Me ---------------> ┤                    ├ -----------------> ┊                 ┊
+                    │       My MTA       │                    ┊ Third-party MTA ┊
+                    │                    ├ <----------------- ┊                 ┊
+                    └────────────────────┘                    └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
+
+                               ┗━━━━━━━━━━ Inbound Submission ━━━━━━━━━━┛
+
+

Outbound Submission

+

When it comes to securing Outbound Submission you should prefer to use Implicit TLS connection via ESMTP on port 465 (see RFC 8314). Please read our article about Understanding the Ports for more details!

+
+

Warning

+

This Submission setup is sometimes referred to as SMTPS. Long story short: this is incorrect and should be avoided.

+
+

Although a very satisfactory setup, Implicit TLS on port 465 is somewhat "cutting edge". There exists another well established mail Submission setup that must be supported as well, SMTP+STARTTLS on port 587. It uses Explicit TLS: the client starts with a cleartext connection, then the server informs a TLS-encrypted "upgraded" connection may be established, and the client may eventually decide to establish it prior to the Submission. Basically it's an opportunistic, opt-in TLS upgrade of the connection between the client and the server, at the client's discretion, using a mechanism known as STARTTLS that both ends need to implement.

+

In many implementations, the mail server doesn't enforce TLS encryption, for backwards compatibility. Clients are thus free to deny the TLS-upgrade proposal (or misled by a hacker about STARTTLS not being available), and the server accepts unencrypted (cleartext) mail exchange, which poses a confidentiality threat and, to some extent, spam issues. RFC 8314 (section 3.3) recommends for a mail server to support both Implicit and Explicit TLS for Submission, and to enforce TLS-encryption on ports 587 (Explicit TLS) and 465 (Implicit TLS). That's exactly docker-mailserver's default configuration: abiding by RFC 8314, it enforces a strict (encrypt) STARTTLS policy, where a denied TLS upgrade terminates the connection thus (hopefully but at the client's discretion) preventing unencrypted (cleartext) Submission.

+
    +
  • docker-mailserver's default configuration enables and requires Explicit TLS (STARTTLS) on port 587 for Outbound Submission.
    • +
  • It does not enable Implicit TLS Outbound Submission on port 465 by default. One may enable it through simple custom configuration, either as a replacement or (better!) supplementary mean of secure Submission.
    • +
  • It does not support old MUAs (clients) not supporting TLS encryption on ports 587/465 (those should perform Submission on port 25, more details below). One may relax that constraint through advanced custom configuration, for backwards compatibility.
    • +
+

A final Outbound Submission setup exists and is akin SMTP+STARTTLS on port 587, but on port 25. That port has historically been reserved specifically for unencrypted (cleartext) mail exchange though, making STARTTLS a bit wrong to use. As is expected by RFC 5321, docker-mailserver uses port 25 for unencrypted Submission in order to support older clients, but most importantly for unencrypted Transfer/Relay between MTAs.

+
    +
  • docker-mailserver's default configuration also enables unencrypted (cleartext) on port 25 for Outbound Submission.
    • +
  • It does not enable Explicit TLS (STARTTLS) on port 25 by default. One may enable it through advanced custom configuration, either as a replacement (bad!) or as a supplementary mean of secure Outbound Submission.
    • +
  • One may also secure Outbound Submission using advanced encryption scheme, such as DANE/DNSSEC and/or MTA-STS.
    • +
+

Inbound Submission

+

Granted it's still very difficult enforcing encryption between MTAs (Transfer/Relay) without risking dropping emails (when relayed by MTAs not supporting TLS-encryption), Inbound Submission is to be handled in cleartext on port 25 by default.

+
    +
  • docker-mailserver's default configuration enables unencrypted (cleartext) on port 25 for Inbound Submission.
    • +
  • It does not enable Explicit TLS (STARTTLS) on port 25 by default. One may enable it through advanced custom configuration, either as a replacement (bad!) or as a supplementary mean of secure Inbound Submission.
    • +
  • One may also secure Inbound Submission using advanced encryption scheme, such as DANE/DNSSEC and/or MTA-STS.
    • +
+

Overall, docker-mailserver's default configuration for SMTP looks like this:

+
 ┏━━━━ Outbound Submission ━━━━┓
+
+                    ┌────────────────────┐                    ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
+Me -- cleartext --> ┤(25)            (25)├ --- cleartext ---> ┊                 ┊
+Me -- TLS      ---> ┤(465)  My MTA       │                    ┊ Third-party MTA ┊
+Me -- STARTTLS ---> ┤(587)               │                    ┊                 ┊
+                    │                (25)├ <---cleartext ---- ┊                 ┊
+                    └────────────────────┘                    └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
+
+                               ┗━━━━━━━━━━ Inbound Submission ━━━━━━━━━━┛
+
+

Retrieval - IMAP

+

A MUA willing to fetch an email from a mail server will most likely communicate with its IMAP server. As with SMTP described earlier, communication will take place in the form of data packets exchanged over a network that both the client and the server are connected to. The IMAP protocol makes the server capable of handling Retrieval.

+

In the case of docker-mailserver, the IMAP server is Dovecot. The MUA (client) may vary, yet its Retrieval request is performed as TCP packets sent over the public internet. This exchange of information may be secured in order to counter eavesdropping.

+

Again, as with SMTP described earlier, the IMAP protocol may be secured with either Implicit TLS (aka. IMAPS / IMAP4S) or Explicit TLS (using STARTTLS).

+

The best practice as of 2020 is to enforce IMAPS on port 993, rather than IMAP+STARTTLS on port 143 (see RFC 8314); yet the latter is usually provided for backwards compatibility.

+

docker-mailserver's default configuration enables both Implicit and Explicit TLS for Retrievial, on ports 993 and 143 respectively.

+

Retrieval - POP3

+

Similarly to IMAP, the older POP3 protocol may be secured with either Implicit or Explicit TLS.

+

The best practice as of 2020 would be POP3S on port 995, rather than POP3+STARTTLS on port 110 (see RFC 8314).

+

docker-mailserver's default configuration disables POP3 altogether. One should expect MUAs to use TLS-encrypted IMAP for Retrieval.

+

How Does docker-mailserver Help With Setting Everything Up?

+

As a batteries included container image, docker-mailserver provides you with all the required components and a default configuration to run a decent and secure mail server. One may then customize all aspects of its internal components.

+ +

Eventually, it is up to you deciding exactly what kind of transportation/encryption to use and/or enforce, and to customize your instance accordingly (with looser or stricter security). Be also aware that protocols and ports on your server can only go so far with security; third-party MTAs might relay your emails on insecure connections, man-in-the-middle attacks might still prove effective, etc. Advanced counter-measure such as DANE, MTA-STS and/or full body encryption (eg. PGP) should be considered as well for increased confidentiality, but ideally without compromising backwards compatibility so as to not block emails.

+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/v12.0/search/search_index.json b/v12.0/search/search_index.json new file mode 100644 index 00000000..8cd42c46 --- /dev/null +++ b/v12.0/search/search_index.json @@ -0,0 +1 @@ +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to the Documentation for docker-mailserver!","text":"

This Documentation is Versioned

Make sure to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to the :latest image tag - the most recent stable release.

This documentation provides you not only with the basic setup and configuration of DMS but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more.

"},{"location":"#about","title":"About","text":"

docker-mailserver, or DMS for short, is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). It employs only configuration files, no SQL database. The image is focused around the slogan \"Keep it simple and versioned\".

"},{"location":"#contents","title":"Contents","text":""},{"location":"#getting-started","title":"Getting Started","text":"

If you're completely new to mail servers or you want to read up on them, check out our Introduction page. If you're new to DMS as a mail server appliance, make sure to read the Usage chapter first. If you want to look at examples for Docker Compose, we have an Examples page.

There is also a script - setup.sh - supplied with this project. It supports you in configuring and administrating your server. Information on how to get it and how to use it is available on a dedicated page.

"},{"location":"#configuration","title":"Configuration","text":"

We have a dedicated configuration page. It contains most of the configuration and explanation you need to setup your mail server properly. Be aware that advanced tasks may still require reading through all parts of this documentation; it may also involve inspecting your running container for debugging purposes. After all, a mail-server is a complex arrangement of various programs.

Important

If you'd like to change, patch or alter files or behavior of docker-mailserver, you can use a script. Just place a script called user-patches.sh in your ./docker-data/dms/config/ folder volume (which is mounted to /tmp/docker-mailserver/ inside the container) and it will be run on container startup. See the 'Modifications via Script' page for additional documentation and an example.

You might also want to check out:

  1. A list of all configuration options via ENV
  2. A list of all optional and automatically created configuration files and directories
  3. How to debug your mail server

Tip

Definitely check out the FAQ for more information and tips! Please do not open an issue before you have checked our documentation for answers, including the FAQ!

"},{"location":"#tests","title":"Tests","text":"

DMS employs a variety of tests. If you want to know more about our test suite, view our testing docs.

"},{"location":"#contributing","title":"Contributing","text":"

We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the Contributing section.

"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#what-kind-of-database-are-you-using","title":"What kind of database are you using?","text":"

None! No database is required. The filesystem is the database. This image is based on config files that can be persisted using bind mounts (default) or Docker volumes, and as such versioned, backed up and so forth.

"},{"location":"faq/#where-are-emails-stored","title":"Where are emails stored?","text":"

Mails are stored in /var/mail/${domain}/${username}. Since v9.0.0 it is possible to add custom user_attributes for each accounts to have a different mailbox configuration (See #1792).

"},{"location":"faq/#how-are-imap-mailboxes-aka-imap-folders-set-up","title":"How are IMAP mailboxes (aka IMAP Folders) set up?","text":"

INBOX is setup by default with the special IMAP folders Drafts, Sent, Junk and Trash. You can learn how to modify or add your own folders (including additional special folders like Archive) by visiting our docs page Customizing IMAP Folders for more information.

"},{"location":"faq/#how-do-i-update-dms","title":"How do I update DMS?","text":"

Make sure to read the CHANGELOG before updating to new versions, to be prepared for possible breaking changes.

Then, run the following commands:

docker-compose pull\ndocker-compose down\ndocker-compose up -d\n

You should see the new version number on startup, for example: [ INF ] Welcome to docker-mailserver 11.3.1. And you're done! Don't forget to have a look at the remaining functions of the setup.sh script with ./setup.sh help.

"},{"location":"faq/#which-operating-systems-are-supported","title":"Which operating systems are supported?","text":"
  • Linux is officially supported.
  • Windows and macOS are not supported and users and have reported various issues running the image on these hosts.

As you'll realistically be deploying to production on a Linux host, if you are on Windows or macOS and want to run the image locally first, it's advised to do so via a VM guest running Linux if you have issues running DMS on your host system.

"},{"location":"faq/#what-are-the-system-requirements","title":"What are the system requirements?","text":""},{"location":"faq/#recommended","title":"Recommended","text":"
  • 1 vCore
  • 2GB RAM
  • Swap enabled for the container
"},{"location":"faq/#minimum","title":"Minimum","text":"
  • 1 vCore
  • 512MB RAM
  • You'll need to avoid running some services like ClamAV (disabled by default) to be able to run on a host with 512MB of RAM.

Warning

ClamAV can consume a lot of memory, as it reads the entire signature database into RAM.

Current figure is about 850M and growing. If you get errors about ClamAV or amavis failing to allocate memory you need more RAM or more swap and of course docker must be allowed to use swap (not always the case). If you can't use swap at all you may need 3G RAM.

"},{"location":"faq/#how-to-alter-a-running-dms-instance-without-relaunching-the-container","title":"How to alter a running DMS instance without relaunching the container?","text":"

docker-mailserver aggregates multiple \"sub-services\", such as Postfix, Dovecot, Fail2ban, SpamAssassin, etc. In many cases, one may edit a sub-service's config and reload that very sub-service, without stopping and relaunching the whole mail-server.

In order to do so, you'll probably want to push your config updates to your server through a Docker volume (these docs use: ./docker-data/dms/config/:/tmp/docker-mailserver/), then restart the sub-service to apply your changes, using supervisorctl. For instance, after editing fail2ban's config: supervisorctl restart fail2ban.

See the documentation for supervisorctl.

Tip

To add, update or delete an email account; there is no need to restart postfix / dovecot service inside the container after using setup.sh script.

For more information, see #1639.

"},{"location":"faq/#how-can-i-sync-the-container-and-host-datetime","title":"How can I sync the container and host date/time?","text":"

Share the host's /etc/localtime with the container, e.g. by using a bind mount:

volumes:\n- /etc/localtime:/etc/localtime:ro\n

Optionally, you can set the TZ ENV variable; e.g. TZ=Europe/Berlin. Check this list for which values are allowed.

"},{"location":"faq/#what-is-the-file-format","title":"What is the file format?","text":"

All files are using the Unix format with LF line endings. Please do not use CRLF.

"},{"location":"faq/#do-you-support-multiple-domains","title":"Do you support multiple domains?","text":"

DMS supports multiple domains out of the box, so you can do this:

./setup.sh email add user1@example.com\n./setup.sh email add user1@example.de\n./setup.sh email add user1@server.example.org\n
"},{"location":"faq/#what-about-backups","title":"What about backups?","text":""},{"location":"faq/#bind-mounts-default","title":"Bind mounts (default)","text":"

From the location of your docker-compose.yml, create a compressed archive of your docker-data/dms/config/ and docker-data/dms/mail-* folders:

tar --gzip -cf \"backup-$(date +%F).tar.gz\" ./docker-data/dms\n

Then to restore docker-data/dms/config/ and docker-data/dms/mail-* folders from your backup file:

tar --gzip -xf backup-date.tar.gz\n
"},{"location":"faq/#volumes","title":"Volumes","text":"

Assuming that you use docker-compose and data volumes, you can backup the configuration, emails and logs like this:

# create backup\ndocker run --rm -it \\\n-v \"${PWD}/docker-data/dms/config/:/tmp/docker-mailserver/\" \\\n-v \"${PWD}/docker-data/dms-backups/:/backup/\" \\\n--volumes-from mailserver \\\nalpine:latest \\\ntar czf \"/backup/mail-$(date +%F).tar.gz\" /var/mail /var/mail-state /var/log/mail /tmp/docker-mailserver\n\n# delete backups older than 30 days\nfind \"${PWD}/docker-data/dms-backups/\" -type f -mtime +30 -delete\n
"},{"location":"faq/#what-about-the-docker-datadmsmail-state-folder","title":"What about the ./docker-data/dms/mail-state folder?","text":"

When you run DMS with the ENV variable ONE_DIR=1 (default), this folder will:

  • Provide support to persist Fail2Ban blocks, ClamAV signature updates, and the like when the container is restarted or recreated.
  • To persist that container state properly this folder should be volume mounted to /var/mail-state/ internally.

Service data is relocated to the mail-state folder for the following services: Postfix, Dovecot, Fail2Ban, Amavis, PostGrey, ClamAV, SpamAssassin.

"},{"location":"faq/#i-want-to-know-more-about-the-ports","title":"I Want to Know More About the Ports","text":"

See this part of the documentation for further details and best practice advice, especially regarding security concerns.

"},{"location":"faq/#how-can-i-configure-my-email-client","title":"How can I configure my email client?","text":"

Login is full email address (<user>@<domain>).

# IMAP\nusername:           <user1@example.com>\npassword:           <mypassword>\nserver:             <mail.example.com>\nimap port:          143 or 993 with STARTTLS/SSL (recommended)\nimap path prefix:   INBOX\n\n# SMTP\nsmtp port:          25 or 587/465 with STARTTLS/SSL (recommended)\nusername:           <user1@example.com>\npassword:           <mypassword>\n

DMS is properly configured for port 587, if possible, we recommend using port 465 for SMTP though. See this section to learn more about ports.

"},{"location":"faq/#can-i-use-a-nakedbare-domain-ie-no-hostname","title":"Can I use a naked/bare domain (i.e. no hostname)?","text":"

Yes, but not without some configuration changes. Normally it is assumed that DMS runs on a host with a name, so the fully qualified host name might be mail.example.com with the domain example.com. The MX records point to mail.example.com.

To use a bare domain (where the host name is example.com and the domain is also example.com), change mydestination:

  • From: mydestination = $myhostname, localhost.$mydomain, localhost
  • To: mydestination = localhost.$mydomain, localhost

Add the latter line to docker-data/dms/config/postfix-main.cf. If that doesn't work, make sure that OVERRIDE_HOSTNAME is blank in your mailserver.env file. Without these changes there will be warnings in the logs like:

warning: do not list domain example.com in BOTH mydestination and virtual_mailbox_domains\n

Plus of course mail delivery fails.

Also you need to define hostname: example.com in your docker-compose.yml.

You might not want a bare domain

We encourage you to consider using a subdomain where possible.

  • There are benefits to preferring a subdomain.
  • A bare domain is not required to have user@example.com, that is distinct from your hostname which is identified by a DNS MX record.
"},{"location":"faq/#how-can-i-configure-a-catch-all","title":"How can I configure a catch-all?","text":"

Considering you want to redirect all incoming e-mails for the domain example.com to user1@example.com, add the following line to docker-data/dms/config/postfix-virtual.cf:

@example.com user1@example.com\n
"},{"location":"faq/#how-can-i-delete-all-the-emails-for-a-specific-user","title":"How can I delete all the emails for a specific user?","text":"

First of all, create a special alias named devnull by editing docker-data/dms/config/postfix-aliases.cf:

devnull: /dev/null\n

Considering you want to delete all the e-mails received for baduser@example.com, add the following line to docker-data/dms/config/postfix-virtual.cf:

baduser@example.com devnull\n

Important

If you use a catch-all rule for the main/sub domain, you need another entry in docker-data/dms/config/postfix-virtual.cf:

@mail.example.com hello@example.com\nbaduser@example.com devnull\ndevnull@mail.example.com devnull\n
"},{"location":"faq/#what-kind-of-ssl-certificates-can-i-use","title":"What kind of SSL certificates can I use?","text":"

Both RSA and ECDSA certs are supported. You can provide your own cert files manually, or mount a letsencrypt generated directory (with alternative support for Traefik's acme.json). Check out the SSL_TYPE documentation for more details.

"},{"location":"faq/#i-just-moved-from-my-old-mail-server-to-dms-but-it-doesnt-work","title":"I just moved from my old mail server to DMS, but \"it doesn't work\"?","text":"

If this migration implies a DNS modification, be sure to wait for DNS propagation before opening an issue. Few examples of symptoms can be found here or here.

This could be related to a modification of your MX record, or the IP mapped to mail.example.com. Additionally, validate your DNS configuration.

If everything is OK regarding DNS, please provide formatted logs and config files. This will allow us to help you.

If we're blind, we won't be able to do anything.

"},{"location":"faq/#can-dms-run-in-a-rancher-environment","title":"Can DMS run in a Rancher environment?","text":"

Yes, by adding the environment variable PERMIT_DOCKER: network.

Warning

Adding the Docker network's gateway to the list of trusted hosts, e.g. using the network or connected-networks option, can create an open relay, for instance if IPv6 is enabled on the host machine but not in Docker.

"},{"location":"faq/#connection-refused-or-no-response-at-all","title":"Connection refused or No response at all","text":"

You see errors like \"Connection Refused\" and \"Connection closed by foreign host\", or you cannot connect at all? You may not be able to connect with your mail client (MUA)? Make sure to check Fail2Ban did not ban you (for exceeding the number of tried logins for example)! You can run

docker exec <CONTAINER NAME> setup fail2ban\n

and check whether your IP address appears. Use

docker exec <CONTAINER NAME> setup fail2ban unban <YOUR IP>\n

to unban the IP address.

"},{"location":"faq/#how-can-i-authenticate-users-with-smtp_only1","title":"How can I authenticate users with SMTP_ONLY=1?","text":"

See #1247 for an example.

Todo

Write a How-to / Use-Case / Tutorial about authentication with SMTP_ONLY.

"},{"location":"faq/#common-errors","title":"Common Errors","text":"
warning: connect to Milter service inet:localhost:8893: Connection refused\n# DMARC not running\n# => /etc/init.d/opendmarc restart\n\nwarning: connect to Milter service inet:localhost:8891: Connection refused\n# DKIM not running\n# => /etc/init.d/opendkim restart\n\nmail amavis[1459]: (01459-01) (!)connect to /var/run/clamav/clamd.ctl failed, attempt #1: Can't connect to a UNIX socket /var/run/clamav/clamd.ctl: No such file or directory\nmail amavis[1459]: (01459-01) (!)ClamAV-clamd: All attempts (1) failed connecting to /var/run/clamav/clamd.ctl, retrying (2)\nmail amavis[1459]: (01459-01) (!)ClamAV-clamscan av-scanner FAILED: /usr/bin/clamscan KILLED, signal 9 (0009) at (eval 100) line 905.\nmail amavis[1459]: (01459-01) (!!)AV: ALL VIRUS SCANNERS FAILED\n# Clamav is not running (not started or because you don't have enough memory)\n# => check requirements and/or start Clamav\n
"},{"location":"faq/#how-to-use-dms-behind-a-proxy","title":"How to use DMS behind a proxy","text":"

Using user-patches.sh, update the container file /etc/postfix/main.cf to include:

proxy_interfaces = X.X.X.X (your public IP)\n
"},{"location":"faq/#how-to-adjust-settings-with-the-user-patchessh-script","title":"How to adjust settings with the user-patches.sh script","text":"

Suppose you want to change a number of settings that are not listed as variables or add things to the server that are not included?

docker-mailserver has a built-in way to do post-install processes. If you place a script called user-patches.sh in the config directory it will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started.

It is common to use a local directory for config added to docker-mailsever via a volume mount in your docker-compose.yml (eg: ./docker-data/dms/config/:/tmp/docker-mailserver/).

Add or create the script file to your config directory:

cd ./docker-data/dms/config\ntouch user-patches.sh\nchmod +x user-patches.sh\n

Then fill user-patches.sh with suitable code.

If you want to test it you can move into the running container, run it and see if it does what you want. For instance:

# start shell in container\n./setup.sh debug login\n\n# check the file\ncat /tmp/docker-mailserver/user-patches.sh\n\n# run the script\n/tmp/docker-mailserver/user-patches.sh\n\n# exit the container shell back to the host shell\nexit\n

You can do a lot of things with such a script. You can find an example user-patches.sh script here: example user-patches.sh script.

We also have a very similar docs page specifically about this feature!

Special use-case - patching the supervisord configuration

It seems worth noting, that the user-patches.sh gets executed through supervisord. If you need to patch some supervisord config (e.g. /etc/supervisor/conf.d/saslauth.conf), the patching happens too late.

An easy workaround is to make the user-patches.sh reload the supervisord config after patching it:

#!/bin/bash\nsed -i 's/rimap -r/rimap/' /etc/supervisor/conf.d/saslauth.conf\nsupervisorctl update\n
"},{"location":"faq/#how-to-ban-custom-ip-addresses-with-fail2ban","title":"How to ban custom IP addresses with Fail2ban","text":"

Use the following command:

./setup.sh fail2ban ban <IP>\n

The default bantime is 180 days. This value can be customized.

"},{"location":"faq/#what-to-do-in-case-of-spfforwarding-problems","title":"What to do in case of SPF/Forwarding problems","text":"

If you got any problems with SPF and/or forwarding mails, give SRS a try. You enable SRS by setting ENABLE_SRS=1. See the variable description for further information.

"},{"location":"faq/#why-are-my-emails-not-being-delivered","title":"Why are my emails not being delivered?","text":"

There are many reasons why email might be rejected, common causes are:

  • Wrong or untrustworthy SSL certificate.
  • A TLD (your domain) or IP address with a bad reputation.
  • Misconfigured DNS records.

DMS does not manage those concerns, verify they are not causing your delivery problems before reporting a bug on our issue tracker. Resources that can help you troubleshoot:

  • mail-tester can test your deliverability.
  • helloinbox provides a checklist of things to improve your deliverability.
"},{"location":"faq/#spamassasin","title":"SpamAssasin","text":""},{"location":"faq/#how-can-i-manage-my-custom-spamassassin-rules","title":"How can I manage my custom SpamAssassin rules?","text":"

Antispam rules are managed in docker-data/dms/config/spamassassin-rules.cf.

"},{"location":"faq/#what-are-acceptable-sa_spam_subject-values","title":"What are acceptable SA_SPAM_SUBJECT values?","text":"

For no subject set SA_SPAM_SUBJECT=undef.

For a trailing white-space subject one can define the whole variable with quotes in docker-compose.yml:

environment:\n- \"SA_SPAM_SUBJECT=[SPAM] \"\n
"},{"location":"faq/#why-are-spamassassin-x-headers-not-inserted-into-my-subdomainexamplecom-subdomain-emails","title":"Why are SpamAssassin x-headers not inserted into my subdomain.example.com subdomain emails?","text":"

In the default setup, amavis only applies SpamAssassin x-headers into domains matching the template listed in the config file (05-domain_id in the amavis defaults).

The default setup @local_domains_acl = ( \".$mydomain\" ); does not match subdomains. To match subdomains, you can override the @local_domains_acl directive in the amavis user config file 50-user with @local_domains_maps = (\".\"); to match any sort of domain template.

"},{"location":"faq/#how-can-i-make-spamassassin-better-recognize-spam","title":"How can I make SpamAssassin better recognize spam?","text":"

Put received spams in .Junk/ imap folder using SPAMASSASSIN_SPAM_TO_INBOX=1 and MOVE_SPAM_TO_JUNK=1 and add a user cron like the following:

# This assumes you're having `environment: ONE_DIR=1` in the `mailserver.env`,\n# with a consolidated config in `/var/mail-state`\n#\n# m h dom mon dow command\n# Everyday 2:00AM, learn spam from a specific user\n0 2 * * * docker exec mailserver sa-learn --spam /var/mail/example.com/username/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin\n

With docker-compose you can more easily use the internal instance of cron within docker-mailserver. This is less problematic than the simple solution shown above, because it decouples the learning from the host on which docker-mailserver is running, and avoids errors if the mail-server is not running.

The following configuration works nicely:

Example

Create a system cron file:

# in the docker-compose.yml root directory\nmkdir -p ./docker-data/dms/cron\ntouch ./docker-data/dms/cron/sa-learn\nchown root:root ./docker-data/dms/cron/sa-learn\nchmod 0644 ./docker-data/dms/cron/sa-learn\n

Edit the system cron file nano ./docker-data/dms/cron/sa-learn, and set an appropriate configuration:

# This assumes you're having `environment: ONE_DIR=1` in the env-mailserver,\n# with a consolidated config in `/var/mail-state`\n#\n# '> /dev/null' to send error notifications from 'stderr' to 'postmaster@example.com'\n#\n# m h dom mon dow user command\n#\n# Everyday 2:00AM, learn spam from a specific user\n# spam: junk directory\n0  2 * * * root  sa-learn --spam /var/mail/example.com/username/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null\n# ham: archive directories\n15 2 * * * root  sa-learn --ham /var/mail/example.com/username/.Archive* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null\n# ham: inbox subdirectories\n30 2 * * * root  sa-learn --ham /var/mail/example.com/username/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null\n#\n# Everyday 3:00AM, learn spam from all users of a domain\n# spam: junk directory\n0  3 * * * root  sa-learn --spam /var/mail/not-example.com/*/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null\n# ham: archive directories\n15 3 * * * root  sa-learn --ham /var/mail/not-example.com/*/.Archive* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null\n# ham: inbox subdirectories\n30 3 * * * root  sa-learn --ham /var/mail/not-example.com/*/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null\n

Then with docker-compose.yml:

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\nvolumes:\n- ./docker-data/dms/cron/sa-learn:/etc/cron.d/sa-learn\n

Or with Docker Swarm:

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\n# ...\nconfigs:\n- source: my_sa_crontab\ntarget: /etc/cron.d/sa-learn\n\nconfigs:\nmy_sa_crontab:\nfile: ./docker-data/dms/cron/sa-learn\n

With the default settings, SpamAssassin will require 200 mails trained for spam (for example with the method explained above) and 200 mails trained for ham (using the same command as above but using --ham and providing it with some ham mails). Until you provided these 200+200 mails, SpamAssassin will not take the learned mails into account. For further reference, see the SpamAssassin Wiki.

"},{"location":"faq/#how-do-i-have-more-control-about-what-spamassassin-is-filtering","title":"How do I have more control about what SpamAssassin is filtering?","text":"

By default, SPAM and INFECTED emails are put to a quarantine which is not very straight forward to access. Several config settings are affecting this behavior:

First, make sure you have the proper thresholds set:

SA_TAG=-100000.0\nSA_TAG2=3.75\nSA_KILL=100000.0\n
  • The very negative vaue in SA_TAG makes sure, that all emails have the SpamAssassin headers included.
  • SA_TAG2 is the actual threshold to set the YES/NO flag for spam detection.
  • SA_KILL needs to be very high, to make sure nothing is bounced at all (SA_KILL superseeds SPAMASSASSIN_SPAM_TO_INBOX)

Make sure everything (including SPAM) is delivered to the inbox and not quarantined:

SPAMASSASSIN_SPAM_TO_INBOX=1\n

Use MOVE_SPAM_TO_JUNK=1 or create a sieve script which puts spam to the Junk folder:

require [\"comparator-i;ascii-numeric\",\"relational\",\"fileinto\"];\n\nif header :contains \"X-Spam-Flag\" \"YES\" {\n  fileinto \"Junk\";\n} elsif allof (\n   not header :matches \"x-spam-score\" \"-*\",\n   header :value \"ge\" :comparator \"i;ascii-numeric\" \"x-spam-score\" \"3.75\" ) {\n  fileinto \"Junk\";\n}\n

Create a dedicated mailbox for emails which are infected/bad header and everything amavis is blocking by default and put its address into docker-data/dms/config/amavis.cf

$clean_quarantine_to      = \"amavis\\@example.com\";\n$virus_quarantine_to      = \"amavis\\@example.com\";\n$banned_quarantine_to     = \"amavis\\@example.com\";\n$bad_header_quarantine_to = \"amavis\\@example.com\";\n$spam_quarantine_to       = \"amavis\\@example.com\";\n
"},{"location":"introduction/","title":"An Overview of Mail Server Infrastructure","text":"

This article answers the question \"What is a mail server, and how does it perform its duty?\" and it gives the reader an introduction to the field that covers everything you need to know to get started with docker-mailserver.

"},{"location":"introduction/#the-anatomy-of-a-mail-server","title":"The Anatomy of a Mail Server","text":"

A mail server is only a part of a client-server relationship aimed at exchanging information in the form of emails. Exchanging emails requires using specific means (programs and protocols).

docker-mailserver provides you with the server portion, whereas the client can be anything from a terminal via text-based software (eg. Mutt) to a fully-fledged desktop application (eg. Mozilla Thunderbird, Microsoft Outlook\u2026), to a web interface, etc.

Unlike the client-side where usually a single program is used to perform retrieval and viewing of emails, the server-side is composed of many specialized components. The mail server is capable of accepting, forwarding, delivering, storing and overall exchanging messages, but each one of those tasks is actually handled by a specific piece of software. All of these \"agents\" must be integrated with one another for the exchange to take place.

docker-mailserver has made informed choices about those components and their (default) configuration. It offers a comprehensive platform to run a fully featured mail server in no time!

"},{"location":"introduction/#components","title":"Components","text":"

The following components are required to create a complete delivery chain:

  • MUA: a Mail User Agent is basically any client/program capable of sending emails to a mail server; while also capable of fetching emails from a mail server for presenting them to the end users.
  • MTA: a Mail Transfer Agent is the so-called \"mail server\" as seen from the MUA's perspective. It's a piece of software dedicated to accepting submitted emails, then forwarding them-where exactly will depend on an email's final destination. If the receiving MTA is responsible for the FQDN the email is sent to, then an MTA is to forward that email to an MDA (see below). Otherwise, it is to transfer (ie. forward, relay) to another MTA, \"closer\" to the email's final destination.
  • MDA: a Mail Delivery Agent is responsible for accepting emails from an MTA and dropping them into their recipients' mailboxes, whichever the form.

Here's a schematic view of mail delivery:

Sending an email:    MUA ----> MTA ----> (MTA relays) ----> MDA\nFetching an email:   MUA <--------------------------------- MDA\n

There may be other moving parts or sub-divisions (for instance, at several points along the chain, specialized programs may be analyzing, filtering, bouncing, editing\u2026 the exchanged emails).

In a nutshell, docker-mailserver provides you with the following components:

  • A MTA: Postfix
  • A MDA: Dovecot
  • A bunch of additional programs to improve security and emails processing

Here's where docker-mailserver's toochain fits within the delivery chain:

                                    docker-mailserver is here:\n                                                         \u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\nSending an email:    MUA ---> MTA ---> (MTA relays) ---> \u252b MTA \u256e \u2503\nFetching an email:   MUA <------------------------------ \u252b MDA \u256f \u2503\n                                                         \u2517\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u251b\n
An Example

Let's say Alice owns a Gmail account, alice@gmail.com; and Bob owns an account on a docker-mailserver's instance, bob@dms.io.

Make sure not to conflate these two very different scenarios: A) Alice sends an email to bob@dms.io => the email is first submitted to MTA smtp.gmail.com, then relayed to MTA smtp.dms.io where it is then delivered into Bob's mailbox. B) Bob sends an email to alice@gmail.com => the email is first submitted to MTA smtp.dms.io, then relayed to MTA smtp.gmail.com and eventually delivered into Alice's mailbox.

In scenario A the email leaves Gmail's premises, that email's initial submission is not handled by your docker-mailserver instance(MTA); it merely receives the email after it has been relayed by Gmail's MTA. In scenario B, the docker-mailserver instance(MTA) handles the submission, prior to relaying.

The main takeaway is that when a third-party sends an email to a docker-mailserver instance(MTA) (or any MTA for that matter), it does not establish a direct connection with that MTA. Email submission first goes through the sender's MTA, then some relaying between at least two MTAs is required to deliver the email. That will prove very important when it comes to security management.

One important thing to note is that MTA and MDA programs may actually handle multiple tasks (which is the case with docker-mailserver's Postfix and Dovecot).

For instance, Postfix is both an SMTP server (accepting emails) and a relaying MTA (transferring, ie. sending emails to other MTA/MDA); Dovecot is both an MDA (delivering emails in mailboxes) and an IMAP server (allowing MUAs to fetch emails from the mail server). On top of that, Postfix may rely on Dovecot's authentication capabilities.

The exact relationship between all the components and their respective (sometimes shared) responsibilities is beyond the scope of this document. Please explore this wiki & the web to get more insights about docker-mailserver's toolchain.

"},{"location":"introduction/#about-security-ports","title":"About Security & Ports","text":""},{"location":"introduction/#introduction","title":"Introduction","text":"

In the previous section, three components were outlined. Each one of those is responsible for a specific task when it comes to exchanging emails:

  • Submission: for a MUA (client), the act of sending actual email data over the network, toward an MTA (server).
  • Transfer (aka. Relay): for an MTA, the act of sending actual email data over the network, toward another MTA (server) closer to the final destination (where an MTA will forward data to an MDA).
  • Retrieval: for a MUA (client), the act of fetching actual email data over the network, from an MDA.

Postfix handles Submission (and may handle Relay), whereas Dovecot handles Retrieval. They both need to be accessible by MUAs in order to act as servers, therefore they expose public endpoints on specific TCP ports. Those endpoints may be secured, using an encryption scheme and TLS certificates.

When it comes to the specifics of email exchange, we have to look at protocols and ports enabled to support all the identified purposes. There are several valid options and they've been evolving overtime.

"},{"location":"introduction/#overview","title":"Overview","text":"

The following picture gives a visualization of the interplay of all components and their respective ports:

 \u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 Submission \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 Transfer/Relay \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\n                           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250c\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2510\nMUA ----- STARTTLS ------> \u2524(587)   MTA \u256e    (25)\u251c <-- cleartext ---> \u250a Third-party MTA \u250a\n    ----- implicit TLS --> \u2524(465)       \u2502        |                    \u2514\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2518\n    ----- cleartext -----> \u2524(25)        \u2502        |\n                           |\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504|\nMUA <---- STARTTLS ------- \u2524(143)   MDA \u256f        |\n    <---- implicit TLS --- \u2524(993)                |\n                           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n \u2517\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 Retrieval \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u251b\n

If you're new to email infrastructure, both that table and the schema may be confusing. Read on to expand your understanding and learn about docker-mailserver's configuration, including how you can customize it.

"},{"location":"introduction/#submission-smtp","title":"Submission - SMTP","text":"

For a MUA to send an email to an MTA, it needs to establish a connection with that server, then push data packets over a network that both the MUA (client) and the MTA (server) are connected to. The server implements the SMTP protocol, which makes it capable of handling Submission.

In the case of docker-mailserver, the MTA (SMTP server) is Postfix. The MUA (client) may vary, yet its Submission request is performed as TCP packets sent over the public internet. This exchange of information may be secured in order to counter eavesdropping.

Now let's say I own an account on a docker-mailserver instance, me@dms.io. There are two very different use-cases for Submission:

  1. I want to send an email to someone
  2. Someone wants to send you an email

In the first scenario, I will be submitting my email directly to my docker-mailserver instance/MTA (Postfix), which will then relay the email to its recipient's MTA for final delivery. In this case, Submission is first handled by establishing a direct connection to my own MTA-so at least for this portion of the delivery chain, I'll be able to ensure security/confidentiality. Not so much for what comes next, ie. relaying between MTAs and final delivery.

In the second scenario, a third-party email account owner will be first submitting an email to some third-party MTA. I have no control over this initial portion of the delivery chain, nor do I have control over the relaying that comes next. My MTA will merely accept a relayed email coming \"out of the blue\".

My MTA will thus have to support two kinds of Submission:

  • Outbound Submission (self-owned email is submitted directly to the MTA, then is relayed \"outside\")
  • Inbound Submission (third-party email has been submitted & relayed, then is accepted \"inside\" by the MTA)
 \u250f\u2501\u2501\u2501\u2501 Outbound Submission \u2501\u2501\u2501\u2501\u2513\n\n                    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250c\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2510\nMe ---------------> \u2524                    \u251c -----------------> \u250a                 \u250a\n                    \u2502       My MTA       \u2502                    \u250a Third-party MTA \u250a\n                    \u2502                    \u251c <----------------- \u250a                 \u250a\n                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u2514\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2518\n\n                               \u2517\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 Inbound Submission \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u251b\n
"},{"location":"introduction/#outbound-submission","title":"Outbound Submission","text":"

When it comes to securing Outbound Submission you should prefer to use Implicit TLS connection via ESMTP on port 465 (see RFC 8314). Please read our article about Understanding the Ports for more details!

Warning

This Submission setup is sometimes referred to as SMTPS. Long story short: this is incorrect and should be avoided.

Although a very satisfactory setup, Implicit TLS on port 465 is somewhat \"cutting edge\". There exists another well established mail Submission setup that must be supported as well, SMTP+STARTTLS on port 587. It uses Explicit TLS: the client starts with a cleartext connection, then the server informs a TLS-encrypted \"upgraded\" connection may be established, and the client may eventually decide to establish it prior to the Submission. Basically it's an opportunistic, opt-in TLS upgrade of the connection between the client and the server, at the client's discretion, using a mechanism known as STARTTLS that both ends need to implement.

In many implementations, the mail server doesn't enforce TLS encryption, for backwards compatibility. Clients are thus free to deny the TLS-upgrade proposal (or misled by a hacker about STARTTLS not being available), and the server accepts unencrypted (cleartext) mail exchange, which poses a confidentiality threat and, to some extent, spam issues. RFC 8314 (section 3.3) recommends for a mail server to support both Implicit and Explicit TLS for Submission, and to enforce TLS-encryption on ports 587 (Explicit TLS) and 465 (Implicit TLS). That's exactly docker-mailserver's default configuration: abiding by RFC 8314, it enforces a strict (encrypt) STARTTLS policy, where a denied TLS upgrade terminates the connection thus (hopefully but at the client's discretion) preventing unencrypted (cleartext) Submission.

  • docker-mailserver's default configuration enables and requires Explicit TLS (STARTTLS) on port 587 for Outbound Submission.
  • It does not enable Implicit TLS Outbound Submission on port 465 by default. One may enable it through simple custom configuration, either as a replacement or (better!) supplementary mean of secure Submission.
  • It does not support old MUAs (clients) not supporting TLS encryption on ports 587/465 (those should perform Submission on port 25, more details below). One may relax that constraint through advanced custom configuration, for backwards compatibility.

A final Outbound Submission setup exists and is akin SMTP+STARTTLS on port 587, but on port 25. That port has historically been reserved specifically for unencrypted (cleartext) mail exchange though, making STARTTLS a bit wrong to use. As is expected by RFC 5321, docker-mailserver uses port 25 for unencrypted Submission in order to support older clients, but most importantly for unencrypted Transfer/Relay between MTAs.

  • docker-mailserver's default configuration also enables unencrypted (cleartext) on port 25 for Outbound Submission.
  • It does not enable Explicit TLS (STARTTLS) on port 25 by default. One may enable it through advanced custom configuration, either as a replacement (bad!) or as a supplementary mean of secure Outbound Submission.
  • One may also secure Outbound Submission using advanced encryption scheme, such as DANE/DNSSEC and/or MTA-STS.
"},{"location":"introduction/#inbound-submission","title":"Inbound Submission","text":"

Granted it's still very difficult enforcing encryption between MTAs (Transfer/Relay) without risking dropping emails (when relayed by MTAs not supporting TLS-encryption), Inbound Submission is to be handled in cleartext on port 25 by default.

  • docker-mailserver's default configuration enables unencrypted (cleartext) on port 25 for Inbound Submission.
  • It does not enable Explicit TLS (STARTTLS) on port 25 by default. One may enable it through advanced custom configuration, either as a replacement (bad!) or as a supplementary mean of secure Inbound Submission.
  • One may also secure Inbound Submission using advanced encryption scheme, such as DANE/DNSSEC and/or MTA-STS.

Overall, docker-mailserver's default configuration for SMTP looks like this:

 \u250f\u2501\u2501\u2501\u2501 Outbound Submission \u2501\u2501\u2501\u2501\u2513\n\n                    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                    \u250c\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2510\nMe -- cleartext --> \u2524(25)            (25)\u251c --- cleartext ---> \u250a                 \u250a\nMe -- TLS      ---> \u2524(465)  My MTA       \u2502                    \u250a Third-party MTA \u250a\nMe -- STARTTLS ---> \u2524(587)               \u2502                    \u250a                 \u250a\n                    \u2502                (25)\u251c <---cleartext ---- \u250a                 \u250a\n                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u2514\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2504\u2518\n\n                               \u2517\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 Inbound Submission \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u251b\n
"},{"location":"introduction/#retrieval-imap","title":"Retrieval - IMAP","text":"

A MUA willing to fetch an email from a mail server will most likely communicate with its IMAP server. As with SMTP described earlier, communication will take place in the form of data packets exchanged over a network that both the client and the server are connected to. The IMAP protocol makes the server capable of handling Retrieval.

In the case of docker-mailserver, the IMAP server is Dovecot. The MUA (client) may vary, yet its Retrieval request is performed as TCP packets sent over the public internet. This exchange of information may be secured in order to counter eavesdropping.

Again, as with SMTP described earlier, the IMAP protocol may be secured with either Implicit TLS (aka. IMAPS / IMAP4S) or Explicit TLS (using STARTTLS).

The best practice as of 2020 is to enforce IMAPS on port 993, rather than IMAP+STARTTLS on port 143 (see RFC 8314); yet the latter is usually provided for backwards compatibility.

docker-mailserver's default configuration enables both Implicit and Explicit TLS for Retrievial, on ports 993 and 143 respectively.

"},{"location":"introduction/#retrieval-pop3","title":"Retrieval - POP3","text":"

Similarly to IMAP, the older POP3 protocol may be secured with either Implicit or Explicit TLS.

The best practice as of 2020 would be POP3S on port 995, rather than POP3+STARTTLS on port 110 (see RFC 8314).

docker-mailserver's default configuration disables POP3 altogether. One should expect MUAs to use TLS-encrypted IMAP for Retrieval.

"},{"location":"introduction/#how-does-docker-mailserver-help-with-setting-everything-up","title":"How Does docker-mailserver Help With Setting Everything Up?","text":"

As a batteries included container image, docker-mailserver provides you with all the required components and a default configuration to run a decent and secure mail server. One may then customize all aspects of its internal components.

  • Simple customization is supported through docker-compose configuration and the env-mailserver configuration file.
  • Advanced customization is supported through providing \"monkey-patching\" configuration files and/or deriving your own image from docker-mailserver's upstream, for a complete control over how things run.

Eventually, it is up to you deciding exactly what kind of transportation/encryption to use and/or enforce, and to customize your instance accordingly (with looser or stricter security). Be also aware that protocols and ports on your server can only go so far with security; third-party MTAs might relay your emails on insecure connections, man-in-the-middle attacks might still prove effective, etc. Advanced counter-measure such as DANE, MTA-STS and/or full body encryption (eg. PGP) should be considered as well for increased confidentiality, but ideally without compromising backwards compatibility so as to not block emails.

"},{"location":"usage/","title":"Usage","text":"

This pages explains how to get started with DMS. The guide uses Docker Compose as a reference. In our examples, a volume mounts the host location docker-data/dms/config/ to /tmp/docker-mailserver/ inside the container.

"},{"location":"usage/#preliminary-steps","title":"Preliminary Steps","text":"

Before you can get started with deploying your own mail server, there are some requirements to be met:

  1. You need to have a host that you can manage.
  2. You need to own a domain, and you need to able to manage DNS for this domain.
"},{"location":"usage/#host-setup","title":"Host Setup","text":"

There are a few requirements for a suitable host system:

  1. The host should have a static IP address; otherwise you will need to dynamically update DNS (undesirable due to DNS caching)
  2. The host should be able to send/receive on the necessary ports for mail
  3. You should be able to set a PTR record for your host; security-hardened mail servers might otherwise reject your mail server as the IP address of your host does not resolve correctly/at all to the DNS name of your server.

On the host, you should have a suitable container runtime (like Docker or Podman) installed. We assume Docker Compose is installed.

Podman Support

If you're using podman, make sure to read the related documentation.

"},{"location":"usage/#minimal-dns-setup","title":"Minimal DNS Setup","text":"

The DNS setup is a big and essential part of the whole setup. There is a lot of confusion for newcomers and people starting out when setting up DNS. This section provides an example configuration and supplementary explanation. We expect you to be at least a bit familiar with DNS, what it does and what the individual record types are.

Now let's say you just bought example.com and you want to be able to send and receive e-mails for the address test@example.com. On the most basic level, you will need to

  1. set an MX record for your domain example.com - in our example, the MX record contains mail.example.com
  2. set an A record that resolves the name of your mail server - in our example, the A record contains 11.22.33.44
  3. (in a best-case scenario) set a PTR record that resolves the IP of your mail server - in our example, the PTR contains mail.example.com

We will later dig into DKIM, DMARC & SPF, but for now, these are the records that suffice in getting you up and running. Here is a short explanation of what the records do:

  • The MX record tells everyone which (DNS) name is responsible for e-mails on your domain. Because you want to keep the option of running another service on the domain name itself, you run your mail server on mail.example.com. This does not imply your e-mails will look like test@mail.example.com, the DNS name of your mail server is decoupled of the domain it serves e-mails for. In theory, you mail server could even serve e-mails for test@some-other-domain.com, if the MX record for some-other-domain.com points to mail.example.com.
  • The A record tells everyone which IP address the DNS name mail.example.com resolves to.
  • The PTR record is the counterpart of the A record, telling everyone what name the IP address 11.22.33.44 resolves to.

If you setup everything, it should roughly look like this:

$ dig @1.1.1.1 +short MX example.com\nmail.example.com\n$ dig @1.1.1.1 +short A mail.example.com\n11.22.33.44\n$ dig @1.1.1.1 +short -x 11.22.33.44\nmail.example.com\n
"},{"location":"usage/#deploying-the-actual-image","title":"Deploying the Actual Image","text":""},{"location":"usage/#tagging-convention","title":"Tagging Convention","text":"

To understand which tags you should use, read this section carefully. Our CI will automatically build, test and push new images to the following container registries:

  1. DockerHub (docker.io/mailserver/docker-mailserver)
  2. GitHub Container Registry (ghcr.io/docker-mailserver/docker-mailserver)

All workflows are using the tagging convention listed below. It is subsequently applied to all images.

Event Image Tags push on master edge push a tag (v1.2.3) 1.2.3, 1.2, 1, latest"},{"location":"usage/#get-all-files","title":"Get All Files","text":"

Issue the following commands to acquire the necessary files:

DMS_GITHUB_URL=\"https://github.com/docker-mailserver/docker-mailserver/blob/latest\"\nwget \"${DMS_GITHUB_URL}/docker-compose.yml\"\nwget \"${DMS_GITHUB_URL}/mailserver.env\"\n
"},{"location":"usage/#configuration-steps","title":"Configuration Steps","text":"
  1. First edit docker-compose.yml to your liking
    • Substitute mail.example.com according to your FQDN.
    • If you want to use SELinux for the ./docker-data/dms/config/:/tmp/docker-mailserver/ mount, append -z or -Z.
  2. Then configure the environment specific to the mail server by editing mailserver.env, but keep in mind that:
    • only basic VAR=VAL is supported
    • do not quote your values
    • variable substitution is not supported, e.g. OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME does not work
"},{"location":"usage/#get-up-and-running","title":"Get Up and Running","text":"

Using the Correct Commands For Stopping and Starting DMS

Use docker compose up / down, not docker compose start / stop. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.

Using Ctrl+C is not supported either!

For an overview of commands to manage DMS config, run: docker exec -it <CONTAINER NAME> setup help.

Usage of setup.sh when no DMS Container Is Running

We encourage you to directly use setup inside the container (like shown above). If you still want to use setup.sh, here's some information about it.

If no DMS container is running, any ./setup.sh command will check online for the :latest image tag (the current stable release), performing a docker pull ... if necessary followed by running the command in a temporary container:

$ ./setup.sh help\nImage 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...\nSETUP(1)\n\nNAME\n    setup - 'docker-mailserver' Administration & Configuration script\n...\n\n$ docker run --rm ghcr.io/docker-mailserver/docker-mailserver:latest setup help\nSETUP(1)\n\nNAME\n    setup - 'docker-mailserver' Administration & Configuration script\n...\n

On first start, you will need to add at least one email account (unless you're using LDAP). You have two minutes to do so, otherwise DMS will shutdown and restart. You can add accounts by running docker exec -ti <CONTAINER NAME> setup email add user@example.com. That's it! It really is that easy.

"},{"location":"usage/#further-miscellaneous-steps","title":"Further Miscellaneous Steps","text":""},{"location":"usage/#setting-up-tls","title":"Setting up TLS","text":"

You definitely want to setup TLS. Please refer to our documentation about TLS.

"},{"location":"usage/#aliases","title":"Aliases","text":"

You should add at least one alias, the postmaster alias. This is a common convention, but not strictly required.

docker exec -ti <CONTAINER NAME> setup alias add postmaster@example.com user@example.com\n
"},{"location":"usage/#dkim-keys","title":"DKIM Keys","text":"

You can (and you should) generate DKIM keys. For more information:

  • DKIM with OpenDKIM (enabled by default)
  • DKIM with Rspamd (when using ENABLE_RSPAMD=1)

When keys are generated, you can configure your DNS server by just pasting the content of config/opendkim/keys/domain.tld/mail.txt to set up DKIM. See the documentation for more details.

Note

In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:

docker exec -ti <CONTAINER NAME> setup config dkim domain '<domain.tld>[,<domain2.tld>]'\n
"},{"location":"usage/#advanced-dns-setup","title":"Advanced DNS Setup","text":"

You will very likely want to configure your DNS with these TXT records: SPF, DKIM, and DMARC.

The following illustrates what a (rather strict) set of records could look like:

$ dig @1.1.1.1 +short TXT example.com\n\"v=spf1 mx -all\"\n$ dig @1.1.1.1 +short TXT dkim-rsa._domainkey.example.com\n\"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQ...\"\n$ dig @1.1.1.1 +short TXT _dmarc.example.com\n\"v=DMARC1; p=reject; sp=reject; pct=100; adkim=s; aspf=s; fo=1\"\n
"},{"location":"usage/#custom-user-changes-patches","title":"Custom User Changes & Patches","text":"

If you'd like to change, patch or alter files or behavior of docker-mailserver, you can use a script. See this part of our documentation for a detailed explanation.

"},{"location":"usage/#testing","title":"Testing","text":"

Here are some tools you can use to verify your configuration:

  1. MX Toolbox
  2. DMARC Analyzer
  3. mail-tester.com
  4. multiRBL.valli.org
"},{"location":"config/debugging/","title":"Debugging","text":"

This page contains valuable information when it comes to resolving issues you encounter.

Contributions Welcome!

Please consider contributing solutions to the FAQ

"},{"location":"config/debugging/#preliminary-information","title":"Preliminary Information","text":""},{"location":"config/debugging/#mail-sent-from-dms-does-not-arrive-at-destination","title":"Mail sent from DMS does not arrive at destination","text":"

Some service providers block outbound traffic on port 25. Common hosting providers known to have this issue:

  • Azure
  • AWS EC2
  • Vultr

These links may advise how the provider can unblock the port through additional services offered, or via a support ticket request.

"},{"location":"config/debugging/#steps-for-debugging-dms","title":"Steps for Debugging DMS","text":"
  1. Increase log verbosity: Very helpful for troubleshooting problems during container startup. Set the environment variable LOG_LEVEL to debug or trace.
  2. Use error logs as a search query: Try finding an existing issue or search engine result from any errors in your container log output. Often you'll find answers or more insights. If you still need to open an issue, sharing links from your search may help us assist you. The mail server log can be acquired by running docker log <CONTAINER NAME> (or docker logs -f <CONTAINER NAME> if you want to follow the log).
  3. Understand the basics of mail servers: Especially for beginners, make sure you read our Introduction and Usage articles.
  4. Search the whole FAQ: Our FAQ contains answers for common problems. Make sure you go through the list.
  5. Reduce the scope: Ensure that you can run a basic setup of DMS first. Then incrementally restore parts of your original configuration until the problem is reproduced again. If you're new to DMS, it is common to find the cause is misunderstanding how to configure a minimal setup.
"},{"location":"config/debugging/#debug-a-running-container","title":"Debug a running container","text":"

To get a shell inside the container run: docker exec -it <CONTAINER NAME> bash.

If you need more flexibility than docker logs offers, within the container /var/log/mail/mail.log and /var/log/supervisor/ are the most useful locations to get relevant DMS logs. Use the tail or cat commands to view their contents.

To install additional software:

  • apt-get update is needed to update repository metadata.
  • apt-get install <PACKAGE>
  • For example if you need a text editor, nano is a good package choice for beginners.
"},{"location":"config/environment/","title":"Environment Variables","text":"

Info

Values in bold are the default values. If an option doesn't work as documented here, check if you are running the latest image. The current master branch corresponds to the image ghcr.io/docker-mailserver/docker-mailserver:edge.

"},{"location":"config/environment/#general","title":"General","text":""},{"location":"config/environment/#override_hostname","title":"OVERRIDE_HOSTNAME","text":"

If you can't set your hostname (eg: you're in a container platform that doesn't let you) specify it via this environment variable. It will have priority over docker run --hostname, or the equivalent hostname: field in docker-compose.yml.

  • empty => Uses the hostname -f command to get canonical hostname for docker-mailserver to use.
  • => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for docker-mailserver to function correctly.
"},{"location":"config/environment/#log_level","title":"LOG_LEVEL","text":"

Set the log level for DMS. This is mostly relevant for container startup scripts and change detection event feedback.

Valid values (in order of increasing verbosity) are: error, warn, info, debug and trace. The default log level is info.

"},{"location":"config/environment/#supervisor_loglevel","title":"SUPERVISOR_LOGLEVEL","text":"

Here you can adjust the log-level for Supervisor. Possible values are

  • critical => Only show critical messages
  • error => Only show erroneous output
  • warn => Show warnings
  • info => Normal informational output
  • debug => Also show debug messages

The log-level will show everything in its class and above.

"},{"location":"config/environment/#one_dir","title":"ONE_DIR","text":"
  • 0 => state in default directories.
  • 1 => consolidate all states into a single directory (/var/mail-state) to allow persistence using docker volumes. See the related FAQ entry for more information.
"},{"location":"config/environment/#account_provisioner","title":"ACCOUNT_PROVISIONER","text":"

Configures the provisioning source of user accounts (including aliases) for user queries and authentication by services managed by DMS (Postfix and Dovecot).

User provisioning via OIDC is planned for the future, see this tracking issue.

  • empty => use FILE
  • LDAP => use LDAP authentication
  • OIDC => use OIDC authentication (not yet implemented)
  • FILE => use local files (this is used as the default)

A second container for the ldap service is necessary (e.g. docker-openldap)

"},{"location":"config/environment/#permit_docker","title":"PERMIT_DOCKER","text":"

Set different options for mynetworks option (can be overwrite in postfix-main.cf) WARNING: Adding the docker network's gateway to the list of trusted hosts, e.g. using the network or connected-networks option, can create an open relay, for instance if IPv6 is enabled on the host machine but not in Docker.

  • none => Explicitly force authentication
  • container => Container IP address only.
  • host => Add docker host (ipv4 only).
  • network => Add the docker default bridge network (172.16.0.0/12); WARNING: docker-compose might use others (e.g. 192.168.0.0/16) use PERMIT_DOCKER=connected-networks in this case.
  • connected-networks => Add all connected docker networks (ipv4 only).

Note: you probably want to set POSTFIX_INET_PROTOCOLS=ipv4 to make it work fine with Docker.

"},{"location":"config/environment/#tz","title":"TZ","text":"

Set the timezone. If this variable is unset, the container runtime will try to detect the time using /etc/localtime, which you can alternatively mount into the container. The value of this variable must follow the pattern AREA/ZONE, i.e. of you want to use Germany's time zone, use Europe/Berlin. You can lookup all available timezones here.

"},{"location":"config/environment/#enable_amavis","title":"ENABLE_AMAVIS","text":"

Amavis content filter (used for ClamAV & SpamAssassin)

  • 0 => Amavis is disabled
  • 1 => Amavis is enabled
"},{"location":"config/environment/#amavis_loglevel","title":"AMAVIS_LOGLEVEL","text":"

This page provides information on Amavis' logging statistics.

  • -1/-2/-3 => Only show errors
  • 0 => Show warnings
  • 1/2 => Show default informational output
  • 3/4/5 => log debug information (very verbose)
"},{"location":"config/environment/#enable_dnsbl","title":"ENABLE_DNSBL","text":"

This enables DNS block lists in Postscreen. If you want to know which lists we are using, have a look at the default main.cf for Postfix we provide and search for postscreen_dnsbl_sites.

A Warning On DNS Block Lists

Make sure your DNS queries are properly resolved, i.e. you will most likely not want to use a public DNS resolver as these queries do not return meaningful results. We try our best to only evaluate proper return codes - this is not a guarantee that all codes are handled fine though.

Note that emails will be rejected if they don't pass the block list checks!

  • 0 => DNS block lists are disabled
  • 1 => DNS block lists are enabled
"},{"location":"config/environment/#enable_opendkim","title":"ENABLE_OPENDKIM","text":"

Enables the OpenDKIM service.

  • 1 => Enabled
  • 0 => Disabled
"},{"location":"config/environment/#enable_opendmarc","title":"ENABLE_OPENDMARC","text":"

Enables the OpenDMARC service.

  • 1 => Enabled
  • 0 => Disabled
"},{"location":"config/environment/#enable_pop3","title":"ENABLE_POP3","text":"
  • empty => POP3 service disabled
  • 1 => Enables POP3 service
"},{"location":"config/environment/#enable_clamav","title":"ENABLE_CLAMAV","text":"
  • 0 => ClamAV is disabled
  • 1 => ClamAV is enabled
"},{"location":"config/environment/#enable_fail2ban","title":"ENABLE_FAIL2BAN","text":"
  • 0 => fail2ban service disabled
  • 1 => Enables fail2ban service

If you enable Fail2Ban, don't forget to add the following lines to your docker-compose.yml:

cap_add:\n  - NET_ADMIN\n

Otherwise, nftables won't be able to ban IPs.

"},{"location":"config/environment/#fail2ban_blocktype","title":"FAIL2BAN_BLOCKTYPE","text":"
  • drop => drop packet (send NO reply)
  • reject => reject packet (send ICMP unreachable) FAIL2BAN_BLOCKTYPE=drop
"},{"location":"config/environment/#smtp_only","title":"SMTP_ONLY","text":"
  • empty => all daemons start
  • 1 => only launch postfix smtp
"},{"location":"config/environment/#ssl_type","title":"SSL_TYPE","text":"

In the majority of cases, you want letsencrypt or manual.

self-signed can be used for testing SSL until you provide a valid certificate, note that third-parties cannot trust self-signed certificates, do not use this type in production. custom is a temporary workaround that is not officially supported.

  • empty => SSL disabled.
  • letsencrypt => Support for using certificates with Let's Encrypt provisioners. (Docs: Let's Encrypt Setup)
  • manual => Provide your own certificate via separate key and cert files. (Docs: Bring Your Own Certificates)
    • Requires: SSL_CERT_PATH and SSL_KEY_PATH ENV vars to be set to the location of the files within the container.
    • Optional: SSL_ALT_CERT_PATH and SSL_ALT_KEY_PATH allow providing a 2nd certificate as a fallback for dual (aka hybrid) certificate support. Useful for ECDSA with an RSA fallback. Presently only manual mode supports this feature.
  • custom => Provide your own certificate as a single file containing both the private key and full certificate chain. (Docs: None)
  • self-signed => Provide your own self-signed certificate files. Expects a self-signed CA cert for verification. Use only for local testing of your setup. (Docs: Self-Signed Certificates)

Please read the SSL page in the documentation for more information.

"},{"location":"config/environment/#tls_level","title":"TLS_LEVEL","text":"
  • empty => modern
  • modern => Enables TLSv1.2 and modern ciphers only. (default)
  • intermediate => Enables TLSv1, TLSv1.1 and TLSv1.2 and broad compatibility ciphers.
"},{"location":"config/environment/#spoof_protection","title":"SPOOF_PROTECTION","text":"

Configures the handling of creating mails with forged sender addresses.

  • 0 => (not recommended) Mail address spoofing allowed. Any logged in user may create email messages with a forged sender address.
  • 1 => Mail spoofing denied. Each user may only send with his own or his alias addresses. Addresses with extension delimiters are not able to send messages.
"},{"location":"config/environment/#enable_srs","title":"ENABLE_SRS","text":"

Enables the Sender Rewriting Scheme. SRS is needed if docker-mailserver acts as forwarder. See postsrsd for further explanation.

  • 0 => Disabled
  • 1 => Enabled
"},{"location":"config/environment/#network_interface","title":"NETWORK_INTERFACE","text":"

In case your network interface differs from eth0, e.g. when you are using HostNetworking in Kubernetes, you can set this to whatever interface you want. This interface will then be used.

  • empty => eth0
"},{"location":"config/environment/#virusmails_delete_delay","title":"VIRUSMAILS_DELETE_DELAY","text":"

Set how many days a virusmail will stay on the server before being deleted

  • empty => 7 days
"},{"location":"config/environment/#postfix_dagent","title":"POSTFIX_DAGENT","text":"

Configure Postfix virtual_transport to deliver mail to a different LMTP client (default is a unix socket to dovecot).

Provide any valid URI. Examples:

  • empty => lmtp:unix:/var/run/dovecot/lmtp (default, configured in Postfix main.cf)
  • lmtp:unix:private/dovecot-lmtp (use socket)
  • lmtps:inet:<host>:<port> (secure lmtp with starttls)
  • lmtp:<kopano-host>:2003 (use kopano as mailstore)
"},{"location":"config/environment/#postfix_mailbox_size_limit","title":"POSTFIX_MAILBOX_SIZE_LIMIT","text":"

Set the mailbox size limit for all users. If set to zero, the size will be unlimited (default).

  • empty => 0 (no limit)
"},{"location":"config/environment/#enable_quotas","title":"ENABLE_QUOTAS","text":"
  • 1 => Dovecot quota is enabled
  • 0 => Dovecot quota is disabled

See mailbox quota.

"},{"location":"config/environment/#postfix_message_size_limit","title":"POSTFIX_MESSAGE_SIZE_LIMIT","text":"

Set the message size limit for all users. If set to zero, the size will be unlimited (not recommended!)

  • empty => 10240000 (~10 MB)
"},{"location":"config/environment/#clamav_message_size_limit","title":"CLAMAV_MESSAGE_SIZE_LIMIT","text":"

Mails larger than this limit won't be scanned. ClamAV must be enabled (ENABLE_CLAMAV=1) for this.

  • empty => 25M (25 MB)
"},{"location":"config/environment/#enable_managesieve","title":"ENABLE_MANAGESIEVE","text":"
  • empty => Managesieve service disabled
  • 1 => Enables Managesieve on port 4190
"},{"location":"config/environment/#postmaster_address","title":"POSTMASTER_ADDRESS","text":"
  • empty => postmaster@example.com
  • => Specify the postmaster address
"},{"location":"config/environment/#enable_update_check","title":"ENABLE_UPDATE_CHECK","text":"

Check for updates on container start and then once a day. If an update is available, a mail is send to POSTMASTER_ADDRESS.

  • 0 => Update check disabled
  • 1 => Update check enabled
"},{"location":"config/environment/#update_check_interval","title":"UPDATE_CHECK_INTERVAL","text":"

Customize the update check interval. Number + Suffix. Suffix must be 's' for seconds, 'm' for minutes, 'h' for hours or 'd' for days.

  • 1d => Check for updates once a day
"},{"location":"config/environment/#postscreen_action","title":"POSTSCREEN_ACTION","text":"
  • enforce => Allow other tests to complete. Reject attempts to deliver mail with a 550 SMTP reply, and log the helo/sender/recipient information. Repeat this test the next time the client connects.
  • drop => Drop the connection immediately with a 521 SMTP reply. Repeat this test the next time the client connects.
  • ignore => Ignore the failure of this test. Allow other tests to complete. Repeat this test the next time the client connects. This option is useful for testing and collecting statistics without blocking mail.
"},{"location":"config/environment/#dovecot_mailbox_format","title":"DOVECOT_MAILBOX_FORMAT","text":"
  • maildir => uses very common Maildir format, one file contains one message
  • sdbox => (experimental) uses Dovecot high-performance mailbox format, one file contains one message
  • mdbox ==> (experimental) uses Dovecot high-performance mailbox format, multiple messages per file and multiple files per box

This option has been added in November 2019. Using other format than Maildir is considered as experimental in docker-mailserver and should only be used for testing purpose. For more details, please refer to Dovecot Documentation.

"},{"location":"config/environment/#postfix_inet_protocols","title":"POSTFIX_INET_PROTOCOLS","text":"
  • all => Listen on all interfaces.
  • ipv4 => Listen only on IPv4 interfaces. Most likely you want this behind Docker.
  • ipv6 => Listen only on IPv6 interfaces.

Note: More details at http://www.postfix.org/postconf.5.html#inet_protocols

"},{"location":"config/environment/#dovecot_inet_protocols","title":"DOVECOT_INET_PROTOCOLS","text":"
  • all => Listen on all interfaces
  • ipv4 => Listen only on IPv4 interfaces. Most likely you want this behind Docker.
  • ipv6 => Listen only on IPv6 interfaces.

Note: More information at https://dovecot.org/doc/dovecot-example.conf

"},{"location":"config/environment/#move_spam_to_junk","title":"MOVE_SPAM_TO_JUNK","text":"

When enabled, e-mails marked with the

  1. X-Spam: Yes header added by Rspamd
  2. X-Spam-Flag: YES header added by SpamAssassin (requires SPAMASSASSIN_SPAM_TO_INBOX=1)

will be automatically moved to the Junk folder (with the help of a Sieve script).

  • 0 => Spam messages will be delivered in the mailbox.
  • 1 => Spam messages will be delivered in the Junk folder.
"},{"location":"config/environment/#rspamd","title":"Rspamd","text":""},{"location":"config/environment/#enable_rspamd","title":"ENABLE_RSPAMD","text":"

Enable or disable Rspamd.

Current State

Rspamd-support is under active development. Be aware that breaking changes can happen at any time. To get more information, see the detailed documentation page for Rspamd.

  • 0 => disabled
  • 1 => enabled
"},{"location":"config/environment/#enable_rspamd_redis","title":"ENABLE_RSPAMD_REDIS","text":"

Explicit control over running a Redis instance within the container. By default, this value will match what is set for ENABLE_RSPAMD.

The purpose of this setting is to opt-out of starting an internal Redis instance when enabling Rspamd, replacing it with your own external instance.

Configuring Rspamd for an external Redis instance

You will need to provide configuration at /etc/rspamd/local.d/redis.conf similar to:

servers = \"redis.example.test:6379\";\nexpand_keys = true;\n
  • 0 => Disabled
  • 1 => Enabled
"},{"location":"config/environment/#rspamd_learn","title":"RSPAMD_LEARN","text":"

When enabled,

  1. the \"autolearning\" feature is turned on;
  2. the Bayes classifier will be trained when moving mails from or to the Junk folder (with the help of Sieve scripts).

Attention

As of now, the spam learning database is global (i.e. available to all users). If one user deliberately trains it with malicious data, then it will ruin your detection rate.

This feature is suitably only for users who can tell ham from spam and users that can be trusted.

  • 0 => Disabled
  • 1 => Enabled
"},{"location":"config/environment/#reports","title":"Reports","text":""},{"location":"config/environment/#pflogsumm_trigger","title":"PFLOGSUMM_TRIGGER","text":"

Enables regular Postfix log summary (\"pflogsumm\") mail reports.

  • not set => No report
  • daily_cron => Daily report for the previous day
  • logrotate => Full report based on the mail log when it is rotated

This is a new option. The old REPORT options are still supported for backwards compatibility. If this is not set and reports are enabled with the old options, logrotate will be used.

"},{"location":"config/environment/#pflogsumm_recipient","title":"PFLOGSUMM_RECIPIENT","text":"

Recipient address for Postfix log summary reports.

  • not set => Use POSTMASTER_ADDRESS
  • => Specify the recipient address(es)
"},{"location":"config/environment/#pflogsumm_sender","title":"PFLOGSUMM_SENDER","text":"

Sender address (FROM) for pflogsumm reports (if Postfix log summary reports are enabled).

  • not set => Use REPORT_SENDER
  • => Specify the sender address
"},{"location":"config/environment/#logwatch_interval","title":"LOGWATCH_INTERVAL","text":"

Interval for logwatch report.

  • none => No report is generated
  • daily => Send a daily report
  • weekly => Send a report every week
"},{"location":"config/environment/#logwatch_recipient","title":"LOGWATCH_RECIPIENT","text":"

Recipient address for logwatch reports if they are enabled.

  • not set => Use REPORT_RECIPIENT or POSTMASTER_ADDRESS
  • => Specify the recipient address(es)
"},{"location":"config/environment/#logwatch_sender","title":"LOGWATCH_SENDER","text":"

Sender address (FROM) for logwatch reports if logwatch reports are enabled.

  • not set => Use REPORT_SENDER
  • => Specify the sender address
"},{"location":"config/environment/#report_recipient","title":"REPORT_RECIPIENT","text":"

Defines who receives reports (if they are enabled).

  • empty => Use POSTMASTER_ADDRESS
  • => Specify the recipient address
"},{"location":"config/environment/#report_sender","title":"REPORT_SENDER","text":"

Defines who sends reports (if they are enabled).

  • empty => mailserver-report@<YOUR DOMAIN>
  • => Specify the sender address
"},{"location":"config/environment/#logrotate_interval","title":"LOGROTATE_INTERVAL","text":"

Changes the interval in which log files are rotated.

  • weekly => Rotate log files weekly
  • daily => Rotate log files daily
  • monthly => Rotate log files monthly

Note

LOGROTATE_INTERVAL only manages logrotate within the container for services we manage internally.

The entire log output for the container is still available via docker logs mailserver (or your respective container name). If you want to configure external log rotation for that container output as well, : Docker Logging Drivers.

By default, the logs are lost when the container is destroyed (eg: re-creating via docker-compose down && docker-compose up -d). To keep the logs, mount a volume (to /var/log/mail/).

Note

This variable can also determine the interval for Postfix's log summary reports, see PFLOGSUMM_TRIGGER.

"},{"location":"config/environment/#spamassassin","title":"SpamAssassin","text":""},{"location":"config/environment/#enable_spamassassin","title":"ENABLE_SPAMASSASSIN","text":"
  • 0 => SpamAssassin is disabled
  • 1 => SpamAssassin is enabled
"},{"location":"config/environment/#spamassassin_spam_to_inbox","title":"SPAMASSASSIN_SPAM_TO_INBOX","text":"
  • 0 => Spam messages will be bounced (rejected) without any notification (dangerous).
  • 1 => Spam messages will be delivered to the inbox and tagged as spam using SA_SPAM_SUBJECT.
"},{"location":"config/environment/#enable_spamassassin_kam","title":"ENABLE_SPAMASSASSIN_KAM","text":"

KAM is a 3rd party SpamAssassin ruleset, provided by the McGrail Foundation. If SpamAssassin is enabled, KAM can be used in addition to the default ruleset.

  • 0 => KAM disabled
  • 1 => KAM enabled
"},{"location":"config/environment/#sa_tag","title":"SA_TAG","text":"
  • 2.0 => add spam info headers if at, or above that level

Note: this SpamAssassin setting needs ENABLE_SPAMASSASSIN=1

"},{"location":"config/environment/#sa_tag2","title":"SA_TAG2","text":"
  • 6.31 => add 'spam detected' headers at that level

Note: this SpamAssassin setting needs ENABLE_SPAMASSASSIN=1

"},{"location":"config/environment/#sa_kill","title":"SA_KILL","text":"
  • 10.0 => triggers spam evasive actions

This SpamAssassin setting needs ENABLE_SPAMASSASSIN=1

By default, docker-mailserver is configured to quarantine spam emails.

If emails are quarantined, they are compressed and stored in a location dependent on the ONE_DIR setting above. To inhibit this behaviour and deliver spam emails, set this to a very high value e.g. 100.0.

If ONE_DIR=1 (default) the location is /var/mail-state/lib-amavis/virusmails/, or if ONE_DIR=0: /var/lib/amavis/virusmails/. These paths are inside the docker container.

"},{"location":"config/environment/#sa_spam_subject","title":"SA_SPAM_SUBJECT","text":"
  • ***SPAM*** => add tag to subject if spam detected

Note: this SpamAssassin setting needs ENABLE_SPAMASSASSIN=1. Add the SpamAssassin score to the subject line by inserting the keyword _SCORE_: ***SPAM(_SCORE_)***.

"},{"location":"config/environment/#sa_shortcircuit_bayes_spam","title":"SA_SHORTCIRCUIT_BAYES_SPAM","text":"
  • 1 => will activate SpamAssassin short circuiting for bayes spam detection.

This will uncomment the respective line in /etc/spamassasin/local.cf

Note: activate this only if you are confident in your bayes database for identifying spam.

"},{"location":"config/environment/#sa_shortcircuit_bayes_ham","title":"SA_SHORTCIRCUIT_BAYES_HAM","text":"
  • 1 => will activate SpamAssassin short circuiting for bayes ham detection

This will uncomment the respective line in /etc/spamassasin/local.cf

Note: activate this only if you are confident in your bayes database for identifying ham.

"},{"location":"config/environment/#fetchmail","title":"Fetchmail","text":""},{"location":"config/environment/#enable_fetchmail","title":"ENABLE_FETCHMAIL","text":"
  • 0 => fetchmail disabled
  • 1 => fetchmail enabled
"},{"location":"config/environment/#fetchmail_poll","title":"FETCHMAIL_POLL","text":"
  • 300 => fetchmail The number of seconds for the interval
"},{"location":"config/environment/#fetchmail_parallel","title":"FETCHMAIL_PARALLEL","text":"

0 => fetchmail runs with a single config file /etc/fetchmailrc 1 => /etc/fetchmailrc is split per poll entry. For every poll entry a separate fetchmail instance is started to allow having multiple imap idle configurations defined.

Note: The defaults of your fetchmailrc file need to be at the top of the file. Otherwise it won't be added correctly to all separate fetchmail instances.

"},{"location":"config/environment/#ldap","title":"LDAP","text":""},{"location":"config/environment/#enable_ldap","title":"ENABLE_LDAP","text":"

Deprecated. See ACCOUNT_PROVISIONER.

"},{"location":"config/environment/#ldap_start_tls","title":"LDAP_START_TLS","text":"
  • empty => no
  • yes => LDAP over TLS enabled for Postfix
"},{"location":"config/environment/#ldap_server_host","title":"LDAP_SERVER_HOST","text":"
  • empty => mail.example.com
  • => Specify the dns-name/ip-address where the ldap-server is listening, or an URI like ldaps://mail.example.com
  • NOTE: If you going to use docker-mailserver in combination with docker-compose.yml you can set the service name here
"},{"location":"config/environment/#ldap_search_base","title":"LDAP_SEARCH_BASE","text":"
  • empty => ou=people,dc=domain,dc=com
  • => e.g. LDAP_SEARCH_BASE=dc=mydomain,dc=local
"},{"location":"config/environment/#ldap_bind_dn","title":"LDAP_BIND_DN","text":"
  • empty => cn=admin,dc=domain,dc=com
  • => take a look at examples of SASL_LDAP_BIND_DN
"},{"location":"config/environment/#ldap_bind_pw","title":"LDAP_BIND_PW","text":"
  • empty => admin
  • => Specify the password to bind against ldap
"},{"location":"config/environment/#ldap_query_filter_user","title":"LDAP_QUERY_FILTER_USER","text":"
  • e.g. (&(mail=%s)(mailEnabled=TRUE))
  • => Specify how ldap should be asked for users
"},{"location":"config/environment/#ldap_query_filter_group","title":"LDAP_QUERY_FILTER_GROUP","text":"
  • e.g. (&(mailGroupMember=%s)(mailEnabled=TRUE))
  • => Specify how ldap should be asked for groups
"},{"location":"config/environment/#ldap_query_filter_alias","title":"LDAP_QUERY_FILTER_ALIAS","text":"
  • e.g. (&(mailAlias=%s)(mailEnabled=TRUE))
  • => Specify how ldap should be asked for aliases
"},{"location":"config/environment/#ldap_query_filter_domain","title":"LDAP_QUERY_FILTER_DOMAIN","text":"
  • e.g. (&(|(mail=*@%s)(mailalias=*@%s)(mailGroupMember=*@%s))(mailEnabled=TRUE))
  • => Specify how ldap should be asked for domains
"},{"location":"config/environment/#ldap_query_filter_senders","title":"LDAP_QUERY_FILTER_SENDERS","text":"
  • empty => use user/alias/group maps directly, equivalent to (|($LDAP_QUERY_FILTER_USER)($LDAP_QUERY_FILTER_ALIAS)($LDAP_QUERY_FILTER_GROUP))
  • => Override how ldap should be asked if a sender address is allowed for a user
"},{"location":"config/environment/#dovecot_tls","title":"DOVECOT_TLS","text":"
  • empty => no
  • yes => LDAP over TLS enabled for Dovecot
"},{"location":"config/environment/#dovecot","title":"Dovecot","text":"

The following variables overwrite the default values for /etc/dovecot/dovecot-ldap.conf.ext.

"},{"location":"config/environment/#dovecot_base","title":"DOVECOT_BASE","text":"
  • empty => same as LDAP_SEARCH_BASE
  • => Tell Dovecot to search only below this base entry. (e.g. ou=people,dc=domain,dc=com)
"},{"location":"config/environment/#dovecot_default_pass_scheme","title":"DOVECOT_DEFAULT_PASS_SCHEME","text":"
  • empty => SSHA
  • => Select one crypt scheme for password hashing from this list of password schemes.
"},{"location":"config/environment/#dovecot_dn","title":"DOVECOT_DN","text":"
  • empty => same as LDAP_BIND_DN
  • => Bind dn for LDAP connection. (e.g. cn=admin,dc=domain,dc=com)
"},{"location":"config/environment/#dovecot_dnpass","title":"DOVECOT_DNPASS","text":"
  • empty => same as LDAP_BIND_PW
  • => Password for LDAP dn sepecifified in DOVECOT_DN.
"},{"location":"config/environment/#dovecot_uris","title":"DOVECOT_URIS","text":"
  • empty => same as LDAP_SERVER_HOST
  • => Specify a space separated list of LDAP uris.
  • Note: If the protocol is missing, ldap:// will be used.
  • Note: This deprecates DOVECOT_HOSTS (as it didn't allow to use LDAPS), which is currently still supported for backwards compatibility.
"},{"location":"config/environment/#dovecot_ldap_version","title":"DOVECOT_LDAP_VERSION","text":"
  • empty => 3
  • 2 => LDAP version 2 is used
  • 3 => LDAP version 3 is used
"},{"location":"config/environment/#dovecot_auth_bind","title":"DOVECOT_AUTH_BIND","text":"
  • empty => no
  • yes => Enable LDAP authentication binds
"},{"location":"config/environment/#dovecot_user_filter","title":"DOVECOT_USER_FILTER","text":"
  • e.g. (&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
"},{"location":"config/environment/#dovecot_user_attrs","title":"DOVECOT_USER_ATTRS","text":"
  • e.g. homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail
  • => Specify the directory to dovecot attribute mapping that fits your directory structure.
  • Note: This is necessary for directories that do not use the Postfix Book Schema.
  • Note: The left-hand value is the directory attribute, the right hand value is the dovecot variable.
  • More details on the Dovecot Wiki
"},{"location":"config/environment/#dovecot_pass_filter","title":"DOVECOT_PASS_FILTER","text":"
  • e.g. (&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
  • empty => same as DOVECOT_USER_FILTER
"},{"location":"config/environment/#dovecot_pass_attrs","title":"DOVECOT_PASS_ATTRS","text":"
  • e.g. uid=user,userPassword=password
  • => Specify the directory to dovecot variable mapping that fits your directory structure.
  • Note: This is necessary for directories that do not use the Postfix Book Schema.
  • Note: The left-hand value is the directory attribute, the right hand value is the dovecot variable.
  • More details on the Dovecot Wiki
"},{"location":"config/environment/#postgrey","title":"Postgrey","text":""},{"location":"config/environment/#enable_postgrey","title":"ENABLE_POSTGREY","text":"
  • 0 => postgrey is disabled
  • 1 => postgrey is enabled
"},{"location":"config/environment/#postgrey_delay","title":"POSTGREY_DELAY","text":"
  • 300 => greylist for N seconds

Note: This postgrey setting needs ENABLE_POSTGREY=1

"},{"location":"config/environment/#postgrey_max_age","title":"POSTGREY_MAX_AGE","text":"
  • 35 => delete entries older than N days since the last time that they have been seen

Note: This postgrey setting needs ENABLE_POSTGREY=1

"},{"location":"config/environment/#postgrey_auto_whitelist_clients","title":"POSTGREY_AUTO_WHITELIST_CLIENTS","text":"
  • 5 => whitelist host after N successful deliveries (N=0 to disable whitelisting)

Note: This postgrey setting needs ENABLE_POSTGREY=1

"},{"location":"config/environment/#postgrey_text","title":"POSTGREY_TEXT","text":"
  • Delayed by Postgrey => response when a mail is greylisted

Note: This postgrey setting needs ENABLE_POSTGREY=1

"},{"location":"config/environment/#sasl-auth","title":"SASL Auth","text":""},{"location":"config/environment/#enable_saslauthd","title":"ENABLE_SASLAUTHD","text":"
  • 0 => saslauthd is disabled
  • 1 => saslauthd is enabled
"},{"location":"config/environment/#saslauthd_mechanisms","title":"SASLAUTHD_MECHANISMS","text":"
  • empty => pam
  • ldap => authenticate against ldap server
  • shadow => authenticate against local user db
  • mysql => authenticate against mysql db
  • rimap => authenticate against imap server
  • NOTE: can be a list of mechanisms like pam ldap shadow
"},{"location":"config/environment/#saslauthd_mech_options","title":"SASLAUTHD_MECH_OPTIONS","text":"
  • empty => None
  • e.g. with SASLAUTHD_MECHANISMS rimap you need to specify the ip-address/servername of the imap server ==> xxx.xxx.xxx.xxx
"},{"location":"config/environment/#saslauthd_ldap_server","title":"SASLAUTHD_LDAP_SERVER","text":"
  • empty => same as LDAP_SERVER_HOST
  • Note: since version 10.0.0, you can specify a protocol here (like ldaps://); this deprecates SASLAUTHD_LDAP_SSL.
"},{"location":"config/environment/#saslauthd_ldap_start_tls","title":"SASLAUTHD_LDAP_START_TLS","text":"
  • empty => no
  • yes => Enable ldap_start_tls option
"},{"location":"config/environment/#saslauthd_ldap_tls_check_peer","title":"SASLAUTHD_LDAP_TLS_CHECK_PEER","text":"
  • empty => no
  • yes => Enable ldap_tls_check_peer option
"},{"location":"config/environment/#saslauthd_ldap_tls_cacert_dir","title":"SASLAUTHD_LDAP_TLS_CACERT_DIR","text":"

Path to directory with CA (Certificate Authority) certificates.

  • empty => Nothing is added to the configuration
  • Any value => Fills the ldap_tls_cacert_dir option
"},{"location":"config/environment/#saslauthd_ldap_tls_cacert_file","title":"SASLAUTHD_LDAP_TLS_CACERT_FILE","text":"

File containing CA (Certificate Authority) certificate(s).

  • empty => Nothing is added to the configuration
  • Any value => Fills the ldap_tls_cacert_file option
"},{"location":"config/environment/#saslauthd_ldap_bind_dn","title":"SASLAUTHD_LDAP_BIND_DN","text":"
  • empty => same as LDAP_BIND_DN
  • specify an object with privileges to search the directory tree
  • e.g. active directory: SASLAUTHD_LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=net
  • e.g. openldap: SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=mydomain,dc=net
"},{"location":"config/environment/#saslauthd_ldap_password","title":"SASLAUTHD_LDAP_PASSWORD","text":"
  • empty => same as LDAP_BIND_PW
"},{"location":"config/environment/#saslauthd_ldap_search_base","title":"SASLAUTHD_LDAP_SEARCH_BASE","text":"
  • empty => same as LDAP_SEARCH_BASE
  • specify the search base
"},{"location":"config/environment/#saslauthd_ldap_filter","title":"SASLAUTHD_LDAP_FILTER","text":"
  • empty => default filter (&(uniqueIdentifier=%u)(mailEnabled=TRUE))
  • e.g. for active directory: (&(sAMAccountName=%U)(objectClass=person))
  • e.g. for openldap: (&(uid=%U)(objectClass=person))
"},{"location":"config/environment/#saslauthd_ldap_password_attr","title":"SASLAUTHD_LDAP_PASSWORD_ATTR","text":"

Specify what password attribute to use for password verification.

  • empty => Nothing is added to the configuration but the documentation says it is userPassword by default.
  • Any value => Fills the ldap_password_attr option
"},{"location":"config/environment/#saslauthd_ldap_auth_method","title":"SASLAUTHD_LDAP_AUTH_METHOD","text":"
  • empty => bind will be used as a default value
  • fastbind => The fastbind method is used
  • custom => The custom method uses userPassword attribute to verify the password
"},{"location":"config/environment/#saslauthd_ldap_mech","title":"SASLAUTHD_LDAP_MECH","text":"

Specify the authentication mechanism for SASL bind.

  • empty => Nothing is added to the configuration
  • Any value => Fills the ldap_mech option
"},{"location":"config/environment/#srs-sender-rewriting-scheme","title":"SRS (Sender Rewriting Scheme)","text":""},{"location":"config/environment/#srs_sender_classes","title":"SRS_SENDER_CLASSES","text":"

An email has an \"envelope\" sender (indicating the sending server) and a \"header\" sender (indicating who sent it). More strict SPF policies may require you to replace both instead of just the envelope sender.

More info.

  • envelope_sender => Rewrite only envelope sender address
  • header_sender => Rewrite only header sender (not recommended)
  • envelope_sender,header_sender => Rewrite both senders
"},{"location":"config/environment/#srs_exclude_domains","title":"SRS_EXCLUDE_DOMAINS","text":"
  • empty => Envelope sender will be rewritten for all domains
  • provide comma separated list of domains to exclude from rewriting
"},{"location":"config/environment/#srs_secret","title":"SRS_SECRET","text":"
  • empty => generated when the container is started for the first time
  • provide a secret to use in base64
  • you may specify multiple keys, comma separated. the first one is used for signing and the remaining will be used for verification. this is how you rotate and expire keys
  • if you have a cluster/swarm make sure the same keys are on all nodes
  • example command to generate a key: dd if=/dev/urandom bs=24 count=1 2>/dev/null | base64
"},{"location":"config/environment/#srs_domainname","title":"SRS_DOMAINNAME","text":"
  • empty => Derived from OVERRIDE_HOSTNAME, $DOMAINNAME (internal), or the container's hostname
  • Set this if auto-detection fails, isn't what you want, or you wish to have a separate container handle DSNs
"},{"location":"config/environment/#default-relay-host","title":"Default Relay Host","text":""},{"location":"config/environment/#default_relay_host","title":"DEFAULT_RELAY_HOST","text":"
  • empty => don't set default relayhost setting in main.cf
  • default host and port to relay all mail through. Format: [example.com]:587 (don't forget the brackets if you need this to be compatible with $RELAY_USER and $RELAY_PASSWORD, explained below).
"},{"location":"config/environment/#multi-domain-relay-hosts","title":"Multi-domain Relay Hosts","text":""},{"location":"config/environment/#relay_host","title":"RELAY_HOST","text":"
  • empty => don't configure relay host
  • default host to relay mail through
"},{"location":"config/environment/#relay_port","title":"RELAY_PORT","text":"
  • empty => 25
  • default port to relay mail through
"},{"location":"config/environment/#relay_user","title":"RELAY_USER","text":"
  • empty => no default
  • default relay username (if no specific entry exists in postfix-sasl-password.cf)
"},{"location":"config/environment/#relay_password","title":"RELAY_PASSWORD","text":"
  • empty => no default
  • password for default relay user
"},{"location":"config/pop3/","title":"Mail Delivery with POP3","text":"

If you want to use POP3(S), you have to add the ports 110 and/or 995 (TLS secured) and the environment variable ENABLE_POP3 to your docker-compose.yml:

mailserver:\nports:\n- \"25:25\"    # SMTP  (explicit TLS => STARTTLS)\n- \"143:143\"  # IMAP4 (explicit TLS => STARTTLS)\n- \"465:465\"  # ESMTP (implicit TLS)\n- \"587:587\"  # ESMTP (explicit TLS => STARTTLS)\n- \"993:993\"  # IMAP4 (implicit TLS)\n- \"110:110\"  # POP3\n- \"995:995\"  # POP3 (with TLS)\nenvironment:\n- ENABLE_POP3=1\n
"},{"location":"config/setup.sh/","title":"Your best friend setup.sh","text":"

setup.sh is an administration script that helps with the most common tasks, including initial configuration. It is intended to be run from the host machine, not from inside your running container.

The latest version of the script is included in the docker-mailserver repository. You may retrieve it at any time by running this command in your console:

wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh\nchmod a+x ./setup.sh\n
"},{"location":"config/setup.sh/#usage","title":"Usage","text":"

Run ./setup.sh help and you'll get all you have ever wanted some usage information:

SETUP(1)\n\nNAME\n    setup.sh - docker-mailserver administration script\n\nSYNOPSIS\n    ./setup.sh [ OPTIONS... ] COMMAND [ help | ARGUMENTS... ]\n\n    COMMAND := { email | alias | quota | config | relay | debug } SUBCOMMAND\n\nDESCRIPTION\n    This is the main administration script that you use for all your interactions with\n    'docker-mailserver'. Setup, configuration and much more is done with this script.\n\n    Please note that the script executes most of the commands inside the container itself.\n    If the image was not found, this script will pull the ':latest' tag of\n    'docker.io/mailserver/docker-mailserver'. This tag refers to the latest release,\n    see the tagging convention in the README under\n    https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md\n\n    You will be able to see detailed information about the script you're invoking and\n    its arguments by appending help after your command. Currently, this\n    does not work with all scripts.\n\n[SUB]COMMANDS\n    COMMAND email :=\n        ./setup.sh email add <EMAIL ADDRESS> [<PASSWORD>]\n        ./setup.sh email update <EMAIL ADDRESS> [<PASSWORD>]\n        ./setup.sh email del [ OPTIONS... ] <EMAIL ADDRESS> [ <EMAIL ADDRESS>... ]\n        ./setup.sh email restrict <add|del|list> <send|receive> [<EMAIL ADDRESS>]\n        ./setup.sh email list\n\n    COMMAND alias :=\n        ./setup.sh alias add <EMAIL ADDRESS> <RECIPIENT>\n        ./setup.sh alias del <EMAIL ADDRESS> <RECIPIENT>\n        ./setup.sh alias list\n\n    COMMAND quota :=\n        ./setup.sh quota set <EMAIL ADDRESS> [<QUOTA>]\n        ./setup.sh quota del <EMAIL ADDRESS>\n\n    COMMAND config :=\n        ./setup.sh config dkim [ ARGUMENTS... ]\n\n    COMMAND relay :=\n        ./setup.sh relay add-auth <DOMAIN> <USERNAME> [<PASSWORD>]\n        ./setup.sh relay add-domain <DOMAIN> <HOST> [<PORT>]\n        ./setup.sh relay exclude-domain <DOMAIN>\n\n    COMMAND fail2ban =\n        ./setup.sh fail2ban\n        ./setup.sh fail2ban ban <IP>\n        ./setup.sh fail2ban unban <IP>\n\n    COMMAND debug :=\n        ./setup.sh debug fetchmail\n        ./setup.sh debug login <COMMANDS>\n        ./setup.sh debug show-mail-logs\n\nEXAMPLES\n    ./setup.sh email add test@example.com [password]\n        Add the email account test@example.com. You will be prompted\n        to input a password afterwards if no password was supplied.\n        When supplying `[password]`, it should be in plaintext.\n\n    ./setup.sh config dkim keysize 2048 domain 'example.com,not-example.com'\n        Creates keys of length 2048 but in an LDAP setup where domains are not known to\n        Postfix by default, so you need to provide them yourself in a comma-separated list.\n\n    ./setup.sh config dkim help\n        This will provide you with a detailed explanation on how to use the\n        config dkim command, showing what arguments can be passed and what they do.\n\nOPTIONS\n    Config path, container or image adjustments\n        -i IMAGE_NAME\n            Provides the name of the 'docker-mailserver' image. The default value is\n            'docker.io/mailserver/docker-mailserver:latest'\n\n        -c CONTAINER_NAME\n            Provides the name of the running container.\n\n        -p PATH\n            Provides the config folder path to the temporary container\n            (does not work if a 'docker-mailserver' container already exists).\n\n    SELinux\n        -z\n            Allows container access to the bind mount content that is shared among\n            multiple containers on a SELinux-enabled host.\n\n        -Z\n            Allows container access to the bind mount content that is private and\n            unshared with other containers on a SELinux-enabled host.\n\nEXIT STATUS\n    Exit status is 0 if the command was successful. If there was an unexpected error, an error\n    message is shown describing the error. In case of an error, the script will exit with exit\n    status 1.\n
"},{"location":"config/user-management/","title":"User Management","text":""},{"location":"config/user-management/#accounts","title":"Accounts","text":"

Users (email accounts) are managed in /tmp/docker-mailserver/postfix-accounts.cf. The best way to manage accounts is to use the reliable setup command inside the container. Just run docker exec <CONTAINER NAME> setup help and have a look at the section about subcommands, specifically the email subcommand.

"},{"location":"config/user-management/#adding-a-new-account","title":"Adding a new Account","text":""},{"location":"config/user-management/#via-setup-inside-the-container","title":"Via setup inside the container","text":"

You can add an account by running docker exec -ti <CONTAINER NAME> setup email add <NEW ADDRESS>. This method is strongly preferred.

"},{"location":"config/user-management/#manually","title":"Manually","text":"

Warning

This method is discouraged!

Alternatively, you may directly add the full email address and its encrypted password, separated by a pipe. To generate a new mail account data, directly from your host, you could for example run the following:

docker run --rm -it                                      \\\n--env MAIL_USER=user1@example.com                      \\\n--env MAIL_PASS=mypassword                             \\\nghcr.io/docker-mailserver/docker-mailserver:latest     \\\n/bin/bash -c \\\n'echo \"${MAIL_USER}|$(doveadm pw -s SHA512-CRYPT -u ${MAIL_USER} -p ${MAIL_PASS})\" >>docker-data/dms/config/postfix-accounts.cf'\n

You will then be asked for a password, and be given back the data for a new account entry, as text. To actually add this new account, just copy all the output text in docker-data/dms/config/postfix-accounts.cf file of your running container.

The result could look like this:

user1@example.com|{SHA512-CRYPT}$6$2YpW1nYtPBs2yLYS$z.5PGH1OEzsHHNhl3gJrc3D.YMZkvKw/vp.r5WIiwya6z7P/CQ9GDEJDr2G2V0cAfjDFeAQPUoopsuWPXLk3u1\n
"},{"location":"config/user-management/#quotas","title":"Quotas","text":"
  • imap-quota is enabled and allow clients to query their mailbox usage.
  • When the mailbox is deleted, the quota directive is deleted as well.
  • Dovecot quotas support LDAP, but it's not implemented (PRs are welcome!).
"},{"location":"config/user-management/#aliases","title":"Aliases","text":"

The best way to manage aliases is to use the reliable setup script inside the container. Just run docker exec <CONTAINER NAME> setup help and have a look at the section about subcommands, specifically the alias-subcommand.

"},{"location":"config/user-management/#about","title":"About","text":"

You may read Postfix's documentation on virtual aliases first. Aliases are managed in /tmp/docker-mailserver/postfix-virtual.cf. An alias is a full email address that will either be:

  • delivered to an existing account registered in /tmp/docker-mailserver/postfix-accounts.cf
  • redirected to one or more other email addresses

Alias and target are space separated. An example on a server with example.com as its domain:

# Alias delivered to an existing account\nalias1@example.com user1@example.com\n\n# Alias forwarded to an external email address\nalias2@example.com external-account@gmail.com\n
"},{"location":"config/user-management/#configuring-regexp-aliases","title":"Configuring RegExp Aliases","text":"

Additional regexp aliases can be configured by placing them into docker-data/dms/config/postfix-regexp.cf. The regexp aliases get evaluated after the virtual aliases (container path: /tmp/docker-mailserver/postfix-virtual.cf). For example, the following docker-data/dms/config/postfix-regexp.cf causes all email sent to \"test\" users to be delivered to qa@example.com instead:

/^test[0-9][0-9]*@example.com/ qa@example.com\n
"},{"location":"config/user-management/#address-tags-extension-delimiters-as-an-alternative-to-aliases","title":"Address Tags (Extension Delimiters) as an alternative to Aliases","text":"

Postfix supports so-called address tags, in the form of plus (+) tags - i.e. address+tag@example.com will end up at address@example.com. This is configured by default and the (configurable!) separator is set to +. For more info, see Postfix's official documentation.

Note

If you do decide to change the configurable separator, you must add the same line to both docker-data/dms/config/postfix-main.cf and docker-data/dms/config/dovecot.cf, because Dovecot is acting as the delivery agent. For example, to switch to -, add:

recipient_delimiter = -\n
"},{"location":"config/advanced/auth-ldap/","title":"Advanced | LDAP Authentication","text":""},{"location":"config/advanced/auth-ldap/#introduction","title":"Introduction","text":"

Getting started with ldap and docker-mailserver we need to take 3 parts in account:

  • postfix for incoming & outgoing email
  • dovecot for accessing mailboxes
  • saslauthd for SMTP authentication (this can also be delegated to dovecot)
"},{"location":"config/advanced/auth-ldap/#variables-to-control-provisioning-by-the-container","title":"Variables to Control Provisioning by the Container","text":"

Have a look at the ENV page for information on the default values.

"},{"location":"config/advanced/auth-ldap/#ldap_query_filter_","title":"LDAP_QUERY_FILTER_*","text":"

Those variables contain the LDAP lookup filters for postfix, using %s as the placeholder for the domain or email address in question. This means that...

  • ...for incoming email, the domain must return an entry for the DOMAIN filter (see virtual_alias_domains).
  • ...for incoming email, the inboxes which receive the email are chosen by the USER, ALIAS and GROUP filters.
    • The USER filter specifies personal mailboxes, for which only one should exist per address, for example (mail=%s) (also see virtual_mailbox_maps)
    • The ALIAS filter specifies aliases for mailboxes, using virtual_alias_maps, for example (mailAlias=%s)
    • The GROUP filter specifies the personal mailboxes in a group (for emails that multiple people shall receive), using virtual_alias_maps, for example (mailGroupMember=%s).
    • Technically, there is no difference between ALIAS and GROUP, but ideally you should use ALIAS for personal aliases for a singular person (like ceo@example.org) and GROUP for multiple people (like hr@example.org).
  • ...for outgoing email, the sender address is put through the SENDERS filter, and only if the authenticated user is one of the returned entries, the email can be sent.
    • This only applies if SPOOF_PROTECTION=1.
    • If the SENDERS filter is missing, the USER, ALIAS and GROUP filters will be used in in a disjunction (OR).
    • To for example allow users from the admin group to spoof any sender email address, and to force everyone else to only use their personal mailbox address for outgoing email, you can use something like this: (|(memberOf=cn=admin,*)(mail=%s))
Example

A really simple LDAP_QUERY_FILTER configuration, using only the user filter and allowing only admin@* to spoof any sender addresses.

- ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER\n- LDAP_START_TLS=yes\n- ACCOUNT_PROVISIONER=LDAP\n- LDAP_SERVER_HOST=ldap.example.org\n- LDAP_SEARCH_BASE=dc=example,dc=org\"\n- LDAP_BIND_DN=cn=admin,dc=example,dc=org\n- LDAP_BIND_PW=mypassword\n- SPOOF_PROTECTION=1\n\n- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)\n- LDAP_QUERY_FILTER_USER=(mail=%s)\n- LDAP_QUERY_FILTER_ALIAS=(|) # doesn't match anything\n- LDAP_QUERY_FILTER_GROUP=(|) # doesn't match anything\n- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(mail=admin@*))\n
"},{"location":"config/advanced/auth-ldap/#dovecot__filter-dovecot__attrs","title":"DOVECOT_*_FILTER & DOVECOT_*_ATTRS","text":"

These variables specify the LDAP filters that dovecot uses to determine if a user can log in to their IMAP account, and which mailbox is responsible to receive email for a specific postfix user.

This is split into the following two lookups, both using %u as the placeholder for the full login name (see dovecot documentation for a full list of placeholders). Usually you only need to set DOVECOT_USER_FILTER, in which case it will be used for both filters.

  • DOVECOT_USER_FILTER is used to get the account details (uid, gid, home directory, quota, ...) of a user.
  • DOVECOT_PASS_FILTER is used to get the password information of the user, and is in pretty much all cases identical to DOVECOT_USER_FILTER (which is the default behaviour if left away).

If your directory doesn't have the postfix-book schema installed, then you must change the internal attribute handling for dovecot. For this you have to change the pass_attr and the user_attr mapping, as shown in the example below:

- DOVECOT_PASS_ATTRS=<YOUR_USER_IDENTIFIER_ATTRIBUTE>=user,<YOUR_USER_PASSWORD_ATTRIBUTE>=password\n- DOVECOT_USER_ATTRS=<YOUR_USER_HOME_DIRECTORY_ATTRIBUTE>=home,<YOUR_USER_MAILSTORE_ATTRIBUTE>=mail,<YOUR_USER_MAIL_UID_ATTRIBUTE>=uid,<YOUR_USER_MAIL_GID_ATTRIBUTE>=gid\n

Note

For DOVECOT_*_ATTRS, you can replace ldapAttr=dovecotAttr with =dovecotAttr=%{ldap:ldapAttr} for more flexibility, like for example =home=/var/mail/%{ldap:uid} or just =uid=5000.

A list of dovecot attributes can be found in the dovecot documentation.

Defaults 
- DOVECOT_USER_ATTRS=mailHomeDirectory=home,mailUidNumber=uid,mailGidNumber=gid,mailStorageDirectory=mail\n- DOVECOT_PASS_ATTRS=uniqueIdentifier=user,userPassword=password\n- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))\n
Example

Setup for a directory that has the qmail-schema installed and uses uid:

- DOVECOT_PASS_ATTRS=uid=user,userPassword=password\n- DOVECOT_USER_ATTRS=homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail\n- DOVECOT_USER_FILTER=(&(objectClass=qmailUser)(uid=%u)(accountStatus=active))\n

The LDAP server configuration for dovecot will be taken mostly from postfix, other options can be found in the environment section in the docs.

"},{"location":"config/advanced/auth-ldap/#dovecot_auth_bind","title":"DOVECOT_AUTH_BIND","text":"

Set this to yes to enable authentication binds (more details in the dovecot documentation). Currently, only DN lookup is supported without further changes to the configuration files, so this is only useful when you want to bind as a readonly user without the permission to read passwords.

"},{"location":"config/advanced/auth-ldap/#saslauthd_ldap_filter","title":"SASLAUTHD_LDAP_FILTER","text":"

This filter is used for saslauthd, which is called by postfix when someone is authenticating through SMTP (assuming that SASLAUTHD_MECHANISMS=ldap is being used). Note that you'll need to set up the LDAP server for saslauthd separately from postfix.

The filter variables are explained in detail in the LDAP_SASLAUTHD file, but unfortunately, this method doesn't really support domains right now - that means that %U is the only token that makes sense in this variable.

When to use this and how to avoid it

Using a separate filter for SMTP authentication allows you to for example allow noreply@example.org to send email, but not log in to IMAP or receive email: (&(mail=%U@example.org)(|(memberOf=cn=email,*)(mail=noreply@example.org)))

If you don't want to use a separate filter for SMTP authentication, you can set SASLAUTHD_MECHANISMS=rimap and SASLAUTHD_MECH_OPTIONS=127.0.0.1 to authenticate against dovecot instead - this means that the DOVECOT_USER_FILTER and DOVECOT_PASS_FILTER will be used for SMTP authentication as well.

Configure LDAP with saslauthd 
- ENABLE_SASLAUTHD=1\n- SASLAUTHD_MECHANISMS=ldap\n- SASLAUTHD_LDAP_FILTER=(mail=%U@example.org)\n
"},{"location":"config/advanced/auth-ldap/#secure-connection-with-ldaps-or-starttls","title":"Secure Connection with LDAPS or StartTLS","text":"

To enable LDAPS, all you need to do is to add the protocol to LDAP_SERVER_HOST, for example ldaps://example.org:636.

To enable LDAP over StartTLS (on port 389), you need to set the following environment variables instead (the protocol must not be ldaps:// in this case!):

- LDAP_START_TLS=yes\n- DOVECOT_TLS=yes\n- SASLAUTHD_LDAP_START_TLS=yes\n
"},{"location":"config/advanced/auth-ldap/#active-directory-configurations-tested-with-samba4-ad-implementation","title":"Active Directory Configurations (Tested with Samba4 AD Implementation)","text":"

In addition to LDAP explanation above, when Docker Mailserver is intended to be used with Active Directory (or the equivalent implementations like Samba4 AD DC) the following points should be taken into consideration:

  • Samba4 Active Directory requires a secure connection to the domain controller (DC), either via SSL/TLS (LDAPS) or via StartTLS.
  • The username equivalent in Active Directory is: sAMAccountName.
  • proxyAddresses can be used to store email aliases of single users. The convention is to prefix the email aliases with smtp: (e.g: smtp:some.name@example.com).
  • Active Directory is used typically not only as LDAP Directory storage, but also as a domain controller, i.e., it will do many things including authenticating users. Mixing Linux and Windows clients requires the usage of RFC2307 attributes, namely uidNumber, gidNumber instead of the typical uid. Assigning different owner to email folders can also be done in this approach, nevertheless there is a bug at the moment in Docker Mailserver that overwrites all permissions when starting the container. Either a manual fix is necessary now, or a temporary workaround to use a hard-coded ldap:uidNumber that equals to 5000 until this issue is fixed.
  • To deliver the emails to different members of Active Directory Security Group or Distribution Group (similar to mailing lists), use a user-patches.sh script to modify ldap-groups.cf so that it includes leaf_result_attribute = mail and special_result_attribute = member. This can be achieved simply by:

The configuration shown to get the Group to work is from here and here.

# user-patches.sh\n\n...\ngrep -q '^leaf_result_attribute = mail$' /etc/postfix/ldap-groups.cf || echo \"leaf_result_attribute = mail\" >> /etc/postfix/ldap-groups.cf\ngrep -q '^special_result_attribute = member$' /etc/postfix/ldap-groups.cf || echo \"special_result_attribute = member\" >> /etc/postfix/ldap-groups.cf\n...\n
  • In /etc/ldap/ldap.conf, if the TLS_REQCERT is demand / hard (default), the CA certificate used to verify the LDAP server certificate must be recognized as a trusted CA. This can be done by volume mounting the ca.crt file and updating the trust store via a user-patches.sh script:
# user-patches.sh\n\n...\ncp /MOUNTED_FOLDER/ca.crt /usr/local/share/ca-certificates/\nupdate-ca-certificates\n...\n

The changes on the configurations necessary to work with Active Directory (only changes are listed, the rest of the LDAP configuration can be taken from the other examples shown in this documentation):

# If StartTLS is the chosen method to establish a secure connection with Active Directory.\n- LDAP_START_TLS=yes\n- SASLAUTHD_LDAP_START_TLS=yes\n- DOVECOT_TLS=yes\n\n- LDAP_QUERY_FILTER_USER=(&(objectclass=person)(mail=%s))\n- LDAP_QUERY_FILTER_ALIAS=(&(objectclass=person)(proxyAddresses=smtp:%s))\n# Filters Active Directory groups (mail lists). Additional changes on ldap-groups.cf are also required as shown above.\n- LDAP_QUERY_FILTER_GROUP=(&(objectClass=group)(mail=%s))\n- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)\n# Allows only Domain admins to send any sender email address, otherwise the sender address must match the LDAP attribute `mail`.\n- SPOOF_PROTECTION=1\n- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(proxyAddresses=smtp:%s)(memberOf=cn=Domain Admins,cn=Users,dc=*))\n\n- DOVECOT_USER_FILTER=(&(objectclass=person)(sAMAccountName=%n))\n# At the moment to be able to use %{ldap:uidNumber}, a manual bug fix as described above must be used. Otherwise %{ldap:uidNumber} %{ldap:uidNumber} must be replaced by the hard-coded value 5000.\n- DOVECOT_USER_ATTRS==uid=%{ldap:uidNumber},=gid=5000,=home=/var/mail/%Ln,=mail=maildir:~/Maildir\n- DOVECOT_PASS_ATTRS=sAMAccountName=user,userPassword=password\n- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))\n
"},{"location":"config/advanced/auth-ldap/#ldap-setup-examples","title":"LDAP Setup Examples","text":"Basic Setup 
services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\nhostname: mail.example.com\n\nports:\n- \"25:25\"\n- \"143:143\"\n- \"587:587\"\n- \"993:993\"\n\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/mail-logs/:/var/log/mail/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n- /etc/localtime:/etc/localtime:ro\n\nenvironment:\n- ENABLE_SPAMASSASSIN=1\n- ENABLE_CLAMAV=1\n- ENABLE_FAIL2BAN=1\n- ENABLE_POSTGREY=1\n\n# >>> Postfix LDAP Integration\n- ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER\n- ACCOUNT_PROVISIONER=LDAP\n- LDAP_SERVER_HOST=ldap.example.org\n- LDAP_BIND_DN=cn=admin,ou=users,dc=example,dc=org\n- LDAP_BIND_PW=mypassword\n- LDAP_SEARCH_BASE=dc=example,dc=org\n- LDAP_QUERY_FILTER_DOMAIN=(|(mail=*@%s)(mailAlias=*@%s)(mailGroupMember=*@%s))\n- LDAP_QUERY_FILTER_USER=(&(objectClass=inetOrgPerson)(mail=%s))\n- LDAP_QUERY_FILTER_ALIAS=(&(objectClass=inetOrgPerson)(mailAlias=%s))\n- LDAP_QUERY_FILTER_GROUP=(&(objectClass=inetOrgPerson)(mailGroupMember=%s))\n- LDAP_QUERY_FILTER_SENDERS=(&(objectClass=inetOrgPerson)(|(mail=%s)(mailAlias=%s)(mailGroupMember=%s)))\n- SPOOF_PROTECTION=1\n# <<< Postfix LDAP Integration\n\n# >>> Dovecot LDAP Integration\n- DOVECOT_USER_FILTER=(&(objectClass=inetOrgPerson)(mail=%u))\n- DOVECOT_PASS_ATTRS=uid=user,userPassword=password\n- DOVECOT_USER_ATTRS==home=/var/mail/%{ldap:uid},=mail=maildir:~/Maildir,uidNumber=uid,gidNumber=gid\n# <<< Dovecot LDAP Integration\n\n# >>> SASL LDAP Authentication\n- ENABLE_SASLAUTHD=1\n- SASLAUTHD_MECHANISMS=ldap\n- SASLAUTHD_LDAP_FILTER=(&(mail=%U@example.org)(objectClass=inetOrgPerson))\n# <<< SASL LDAP Authentication\n\n- SSL_TYPE=letsencrypt\n- PERMIT_DOCKER=host\n\ncap_add:\n- NET_ADMIN\n
Kopano / Zarafa 
services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\nhostname: mail.example.com\n\nports:\n- \"25:25\"\n- \"143:143\"\n- \"587:587\"\n- \"993:993\"\n\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n\nenvironment:\n# We are not using dovecot here\n- SMTP_ONLY=1\n- ENABLE_SPAMASSASSIN=1\n- ENABLE_CLAMAV=1\n- ENABLE_FAIL2BAN=1\n- ENABLE_POSTGREY=1\n- SASLAUTHD_PASSWD=\n\n# >>> SASL Authentication\n- ENABLE_SASLAUTHD=1\n- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))\n- SASLAUTHD_MECHANISMS=ldap\n# <<< SASL Authentication\n\n# >>> Postfix Ldap Integration\n- ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER\n- ACCOUNT_PROVISIONER=LDAP\n- LDAP_SERVER_HOST=<yourLdapContainer/yourLdapServer>\n- LDAP_SEARCH_BASE=dc=mydomain,dc=loc\n- LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=loc\n- LDAP_BIND_PW=mypassword\n- LDAP_QUERY_FILTER_USER=(&(objectClass=user)(mail=%s))\n- LDAP_QUERY_FILTER_GROUP=(&(objectclass=group)(mail=%s))\n- LDAP_QUERY_FILTER_ALIAS=(&(objectClass=user)(otherMailbox=%s))\n- LDAP_QUERY_FILTER_DOMAIN=(&(|(mail=*@%s)(mailalias=*@%s)(mailGroupMember=*@%s))(mailEnabled=TRUE))\n# <<< Postfix Ldap Integration\n\n# >>> Kopano Integration\n- POSTFIX_DAGENT=lmtp:kopano:2003\n# <<< Kopano Integration\n\n- SSL_TYPE=letsencrypt\n- PERMIT_DOCKER=host\n\ncap_add:\n- NET_ADMIN\n
"},{"location":"config/advanced/dovecot-master-accounts/","title":"Advanced | Dovecot master accounts","text":""},{"location":"config/advanced/dovecot-master-accounts/#introduction","title":"Introduction","text":"

A dovecot master account is able to login as any configured user. This is useful for administrative tasks like hot backups.

"},{"location":"config/advanced/dovecot-master-accounts/#configuration","title":"Configuration","text":"

It is possible to create, update, delete and list dovecot master accounts using setup.sh. See setup.sh help for usage.

This feature is presently not supported with LDAP.

"},{"location":"config/advanced/dovecot-master-accounts/#logging-in","title":"Logging in","text":"

Once a master account is configured, it is possible to connect to any users mailbox using this account. Log in over POP3/IMAP using the following credential scheme:

Username: <EMAIL ADDRESS>*<MASTER ACCOUNT NAME>

Password: <MASTER ACCOUNT PASSWORD>

"},{"location":"config/advanced/full-text-search/","title":"Advanced | Full-Text Search","text":""},{"location":"config/advanced/full-text-search/#overview","title":"Overview","text":"

Full-text search allows all messages to be indexed, so that mail clients can quickly and efficiently search messages by their full text content. Dovecot supports a variety of community supported FTS indexing backends.

docker-mailserver comes pre-installed with two plugins that can be enabled with a dovecot config file.

Please be aware that indexing consumes memory and takes up additional disk space.

"},{"location":"config/advanced/full-text-search/#xapian","title":"Xapian","text":"

The dovecot-fts-xapian plugin makes use of Xapian. Xapian enables embedding an FTS engine without the need for additional backends.

The indexes will be stored as a subfolder named xapian-indexes inside your local mail-data folder (/var/mail internally). With the default settings, 10GB of email data may generate around 4GB of indexed data.

While indexing is memory intensive, you can configure the plugin to limit the amount of memory consumed by the index workers. With Xapian being small and fast, this plugin is a good choice for low memory environments (2GB) as compared to Solr.

"},{"location":"config/advanced/full-text-search/#setup","title":"Setup","text":"

  1. To configure fts-xapian as a dovecot plugin, create a file at docker-data/dms/config/dovecot/fts-xapian-plugin.conf and place the following in it:

    mail_plugins = $mail_plugins fts fts_xapian\n\nplugin {\n    fts = xapian\n    fts_xapian = partial=3 full=20 verbose=0\n\n    fts_autoindex = yes\n    fts_enforced = yes\n\n    # disable indexing of folders\n    # fts_autoindex_exclude = \\Trash\n\n    # Index attachements\n    # fts_decoder = decode2text\n}\n\nservice indexer-worker {\n    # limit size of indexer-worker RAM usage, ex: 512MB, 1GB, 2GB\n    vsz_limit = 1GB\n}\n\n# service decode2text {\n#     executable = script /usr/libexec/dovecot/decode2text.sh\n#     user = dovecot\n#     unix_listener decode2text {\n#         mode = 0666\n#     }\n# }\n

    adjust the settings to tune for your desired memory limits, exclude folders and enable searching text inside of attachments

  2. Update docker-compose.yml to load the previously created dovecot plugin config file:

      services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\nhostname: mail.example.com\nenv_file: mailserver.env\nports:\n- \"25:25\"    # SMTP  (explicit TLS => STARTTLS)\n- \"143:143\"  # IMAP4 (explicit TLS => STARTTLS)\n- \"465:465\"  # ESMTP (implicit TLS)\n- \"587:587\"  # ESMTP (explicit TLS => STARTTLS)\n- \"993:993\"  # IMAP4 (implicit TLS)\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/mail-logs/:/var/log/mail/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n- ./docker-data/dms/config/dovecot/fts-xapian-plugin.conf:/etc/dovecot/conf.d/10-plugin.conf:ro\n- /etc/localtime:/etc/localtime:ro\nrestart: always\nstop_grace_period: 1m\ncap_add:\n- NET_ADMIN\n

  3. Recreate containers:

    docker-compose down\ndocker-compose up -d\n

  4. Initialize indexing on all users for all mail:

    docker-compose exec mailserver doveadm index -A -q \\*\n

  5. Run the following command in a daily cron job:

    docker-compose exec mailserver doveadm fts optimize -A\n
    Or like the Spamassassin example shows, you can instead use cron from within docker-mailserver to avoid potential errors if the mail-server is not running:

Example

Create a system cron file:

# in the docker-compose.yml root directory\nmkdir -p ./docker-data/dms/cron # if you didn't have this folder before\ntouch ./docker-data/dms/cron/fts_xapian\nchown root:root ./docker-data/dms/cron/fts_xapian\nchmod 0644 ./docker-data/dms/cron/fts_xapian\n

Edit the system cron file nano ./docker-data/dms/cron/fts_xapian, and set an appropriate configuration:

# Adding `MAILTO=\"\"` prevents cron emailing notifications of the task outcome each run\nMAILTO=\"\"\n#\n# m h dom mon dow user command\n#\n# Everyday 4:00AM, optimize index files\n0  4 * * * root  doveadm fts optimize -A\n

Then with docker-compose.yml:

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\nvolumes:\n- ./docker-data/dms/cron/fts_xapian:/etc/cron.d/fts_xapian\n
"},{"location":"config/advanced/full-text-search/#solr","title":"Solr","text":"

The dovecot-solr Plugin is used in conjunction with Apache Solr running in a separate container. This is quite straightforward to setup using the following instructions.

Solr is a mature and fast indexing backend that runs on the JVM. The indexes are relatively compact compared to the size of your total email.

However, Solr also requires a fair bit of RAM. While Solr is highly tuneable, it may require a bit of testing to get it right.

"},{"location":"config/advanced/full-text-search/#setup_1","title":"Setup","text":"

  1. docker-compose.yml:

      solr:\nimage: lmmdock/dovecot-solr:latest\nvolumes:\n- ./docker-data/dms/config/dovecot/solr-dovecot:/opt/solr/server/solr/dovecot\nrestart: always\n\nmailserver:\ndepends_on:\n- solr\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\n...\nvolumes:\n...\n- ./docker-data/dms/config/dovecot/10-plugin.conf:/etc/dovecot/conf.d/10-plugin.conf:ro\n...\n

  2. ./docker-data/dms/config/dovecot/10-plugin.conf:

    mail_plugins = $mail_plugins fts fts_solr\n\nplugin {\nfts = solr\nfts_autoindex = yes\nfts_solr = url=http://solr:8983/solr/dovecot/\n}\n

  3. Recreate containers: docker-compose down ; docker-compose up -d

  4. Flag all user mailbox FTS indexes as invalid, so they are rescanned on demand when they are next searched: docker-compose exec mailserver doveadm fts rescan -A

"},{"location":"config/advanced/full-text-search/#further-discussion","title":"Further Discussion","text":"

See #905

"},{"location":"config/advanced/ipv6/","title":"Advanced | IPv6","text":""},{"location":"config/advanced/ipv6/#background","title":"Background","text":"

If your container host supports IPv6, then docker-mailserver will automatically accept IPv6 connections by way of the docker host's IPv6. However, incoming mail will fail SPF checks because they will appear to come from the IPv4 gateway that docker is using to proxy the IPv6 connection (172.20.0.1 is the gateway).

This can be solved by supporting IPv6 connections all the way to the docker-mailserver container.

"},{"location":"config/advanced/ipv6/#setup-steps","title":"Setup steps","text":"
+++ b/serv/docker-compose.yml\n@@ ... @@ services:\n\n+  ipv6nat:\n+    image: robbertkl/ipv6nat\n+    restart: always\n+    network_mode: \"host\"\n+    cap_add:\n+      - NET_ADMIN\n+      - SYS_MODULE\n+    volumes:\n+      - /var/run/docker.sock:/var/run/docker.sock:ro\n+      - /lib/modules:/lib/modules:ro\n\n@@ ... @@ networks:\n\n+  default:\n+    driver: bridge\n+    enable_ipv6: true\n+    ipam:\n+      driver: default\n+      config:\n+        - subnet: fd00:0123:4567::/48\n+          gateway: fd00:0123:4567::1\n
"},{"location":"config/advanced/ipv6/#further-discussion","title":"Further Discussion","text":"

See #1438

"},{"location":"config/advanced/kubernetes/","title":"Advanced | Kubernetes","text":""},{"location":"config/advanced/kubernetes/#introduction","title":"Introduction","text":"

This article describes how to deploy docker-mailserver to Kubernetes. Please note that there is also a Helm chart available.

Requirements

We assume basic knowledge about Kubernetes from the reader. Moreover, we assume the reader to have a basic understanding of mail servers. Ideally, the reader has deployed docker-mailserver before in an easier setup with Docker (Compose).

About Support for Kubernetes

Please note that Kubernetes is not officially supported and we do not build images specifically designed for it. When opening an issue, please remember that only Docker & Docker Compose are officially supported.

This content is entirely community-supported. If you find errors, please open an issue and provide a PR.

"},{"location":"config/advanced/kubernetes/#manifests","title":"Manifests","text":""},{"location":"config/advanced/kubernetes/#configuration","title":"Configuration","text":"

We want to provide the basic configuration in the form of environment variables with a ConfigMap. Note that this is just an example configuration; tune the ConfigMap to your needs.

---\napiVersion: v1\nkind: ConfigMap\n\nmetadata:\nname: mailserver.environment\n\nimmutable: false\n\ndata:\nTLS_LEVEL: modern\nPOSTSCREEN_ACTION: drop\nOVERRIDE_HOSTNAME: mail.example.com\nFAIL2BAN_BLOCKTYPE: drop\nPOSTMASTER_ADDRESS: postmaster@example.com\nUPDATE_CHECK_INTERVAL: 10d\nPOSTFIX_INET_PROTOCOLS: ipv4\nONE_DIR: '1'\nENABLE_CLAMAV: '1'\nENABLE_POSTGREY: '0'\nENABLE_FAIL2BAN: '1'\nAMAVIS_LOGLEVEL: '-1'\nSPOOF_PROTECTION: '1'\nMOVE_SPAM_TO_JUNK: '1'\nENABLE_UPDATE_CHECK: '1'\nENABLE_SPAMASSASSIN: '1'\nSUPERVISOR_LOGLEVEL: warn\nSPAMASSASSIN_SPAM_TO_INBOX: '1'\n\n# here, we provide an example for the SSL configuration\nSSL_TYPE: manual\nSSL_CERT_PATH: /secrets/ssl/rsa/tls.crt\nSSL_KEY_PATH: /secrets/ssl/rsa/tls.key\n

We can also make use of user-provided configuration files, e.g. user-patches.sh, postfix-accounts.cf and more, to adjust docker-mailserver to our likings. We encourage you to have a look at Kustomize for creating ConfigMaps from multiple files, but for now, we will provide a simple, hand-written example. This example is absolutely minimal and only goes to show what can be done.

---\napiVersion: v1\nkind: ConfigMap\n\nmetadata:\nname: mailserver.files\n\ndata:\npostfix-accounts.cf: |\ntest@example.com|{SHA512-CRYPT}$6$someHashValueHere\nother@example.com|{SHA512-CRYPT}$6$someOtherHashValueHere\n

Static Configuration

With the configuration shown above, you can not dynamically add accounts as the configuration file mounted into the mail server can not be written to.

Use persistent volumes for production deployments.

"},{"location":"config/advanced/kubernetes/#persistence","title":"Persistence","text":"

Thereafter, we need persistence for our data. Make sure you have a storage provisioner and that you choose the correct storageClassName.

---\napiVersion: v1\nkind: PersistentVolumeClaim\n\nmetadata:\nname: data\n\nspec:\nstorageClassName: local-path\naccessModes:\n- ReadWriteOnce\nresources:\nrequests:\nstorage: 25Gi\n
"},{"location":"config/advanced/kubernetes/#service","title":"Service","text":"

A Service is required for getting the traffic to the pod itself. The service is somewhat crucial. Its configuration determines whether the original IP from the sender will be kept. More about this further down below.

The configuration you're seeing does keep the original IP, but you will not be able to scale this way. We have chosen to go this route in this case because we think most Kubernetes users will only want to have one instance.

---\napiVersion: v1\nkind: Service\n\nmetadata:\nname: mailserver\nlabels:\napp: mailserver\n\nspec:\ntype: LoadBalancer\n\nselector:\napp: mailserver\n\nports:\n# Transfer\n- name: transfer\nport: 25\ntargetPort: transfer\nprotocol: TCP\n# ESMTP with implicit TLS\n- name: esmtp-implicit\nport: 465\ntargetPort: esmtp-implicit\nprotocol: TCP\n# ESMTP with explicit TLS (STARTTLS)\n- name: esmtp-explicit\nport: 587\ntargetPort: esmtp-explicit\nprotocol: TCP\n# IMAPS with implicit TLS\n- name: imap-implicit\nport: 993\ntargetPort: imap-implicit\nprotocol: TCP\n
"},{"location":"config/advanced/kubernetes/#deployments","title":"Deployments","text":"

Last but not least, the Deployment becomes the most complex component. It instructs Kubernetes how to run the docker-mailserver container and how to apply your ConfigMaps, persisted storage, etc. Additionally, we can set options to enforce runtime security here.

---\napiVersion: apps/v1\nkind: Deployment\n\nmetadata:\nname: mailserver\n\nannotations:\nignore-check.kube-linter.io/run-as-non-root: >-\n'mailserver' needs to run as root\nignore-check.kube-linter.io/privileged-ports: >-\n'mailserver' needs privilegdes ports\nignore-check.kube-linter.io/no-read-only-root-fs: >-\nThere are too many files written to make The\nroot FS read-only\n\nspec:\nreplicas: 1\nselector:\nmatchLabels:\napp: mailserver\n\ntemplate:\nmetadata:\nlabels:\napp: mailserver\n\nannotations:\ncontainer.apparmor.security.beta.kubernetes.io/mailserver: runtime/default\n\nspec:\nhostname: mail\ncontainers:\n- name: mailserver\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\nimagePullPolicy: IfNotPresent\n\nsecurityContext:\nallowPrivilegeEscalation: false\nreadOnlyRootFilesystem: false\nrunAsUser: 0\nrunAsGroup: 0\nrunAsNonRoot: false\nprivileged: false\ncapabilities:\nadd:\n# file permission capabilities\n- CHOWN\n- FOWNER\n- MKNOD\n- SETGID\n- SETUID\n- DAC_OVERRIDE\n# network capabilities\n- NET_ADMIN  # needed for F2B\n- NET_RAW    # needed for F2B\n- NET_BIND_SERVICE\n# miscellaneous  capabilities\n- SYS_CHROOT\n- KILL\ndrop: [ALL]\nseccompProfile:\ntype: RuntimeDefault\n\n# You want to tune this to your needs. If you disable ClamAV,\n#   you can use less RAM and CPU. This becomes important in\n#   case you're low on resources and Kubernetes refuses to\n#   schedule new pods.\nresources:\nlimits:\nmemory: 4Gi\ncpu: 1500m\nrequests:\nmemory: 2Gi\ncpu: 600m\n\nvolumeMounts:\n- name: files\nsubPath: postfix-accounts.cf\nmountPath: /tmp/docker-mailserver/postfix-accounts.cf\nreadOnly: true\n\n# PVCs\n- name: data\nmountPath: /var/mail\nsubPath: data\nreadOnly: false\n- name: data\nmountPath: /var/mail-state\nsubPath: state\nreadOnly: false\n- name: data\nmountPath: /var/log/mail\nsubPath: log\nreadOnly: false\n\n# certificates\n- name: certificates-rsa\nmountPath: /secrets/ssl/rsa/\nreadOnly: true\n\n# other\n- name: tmp-files\nmountPath: /tmp\nreadOnly: false\n\nports:\n- name: transfer\ncontainerPort: 25\nprotocol: TCP\n- name: esmtp-implicit\ncontainerPort: 465\nprotocol: TCP\n- name: esmtp-explicit\ncontainerPort: 587\n- name: imap-implicit\ncontainerPort: 993\nprotocol: TCP\n\nenvFrom:\n- configMapRef:\nname: mailserver.environment\n\nrestartPolicy: Always\n\nvolumes:\n# configuration files\n- name: files\nconfigMap:\nname: mailserver.files\n\n# PVCs\n- name: data\npersistentVolumeClaim:\nclaimName: data\n\n# certificates\n- name: certificates-rsa\nsecret:\nsecretName: mail-tls-certificate-rsa\nitems:\n- key: tls.key\npath: tls.key\n- key: tls.crt\npath: tls.crt\n\n# other\n- name: tmp-files\nemptyDir: {}\n
"},{"location":"config/advanced/kubernetes/#certificates-an-example","title":"Certificates - An Example","text":"

In this example, we use cert-manager to supply RSA certificates. You can also supply RSA certificates as fallback certificates, which docker-mailserver supports out of the box with SSL_ALT_CERT_PATH and SSL_ALT_KEY_PATH, and provide ECDSA as the proper certificates.

---\napiVersion: cert-manager.io/v1\nkind: Certificate\n\nmetadata:\nname: mail-tls-certificate-rsa\n\nspec:\nsecretName: mail-tls-certificate-rsa\nisCA: false\nprivateKey:\nalgorithm: RSA\nencoding: PKCS1\nsize: 2048\ndnsNames: [mail.example.com]\nissuerRef:\nname: mail-issuer\nkind: Issuer\n

Attention

You will need to have cert-manager configured. Especially the issue will need to be configured. Since we do not know how you want or need your certificates to be supplied, we do not provide more configuration here. The documentation for cert-manager is excellent.

"},{"location":"config/advanced/kubernetes/#sensitive-data","title":"Sensitive Data","text":"

Sensitive Data

For storing OpenDKIM keys, TLS certificates or any sort of sensitive data, you should be using Secrets. You can mount secrets like ConfigMaps and use them the same way.

The TLS docs page provides guidance when it comes to certificates and transport layer security. Always provide sensitive information vai Secrets.

"},{"location":"config/advanced/kubernetes/#exposing-your-mail-server-to-the-outside-world","title":"Exposing your Mail-Server to the Outside World","text":"

The more difficult part with Kubernetes is to expose a deployed docker-mailserver to the outside world. Kubernetes provides multiple ways for doing that; each has downsides and complexity. The major problem with exposing docker-mailserver to outside world in Kubernetes is to preserve the real client IP. The real client IP is required by docker-mailserver for performing IP-based SPF checks and spam checks. If you do not require SPF checks for incoming mails, you may disable them in your Postfix configuration by dropping the line that states: check_policy_service unix:private/policyd-spf.

The easiest approach was covered above, using externalTrafficPolicy: Local, which disables the service proxy, but makes the service local as well (which does not scale). This approach only works when you are given the correct (that is, a public and routable) IP address by a load balancer (like MetalLB). In this sense, the approach above is similar to the next example below. We want to provide you with a few alternatives too. But we also want to communicate the idea of another simple method: you could use a load-balancer without an external IP and DNAT the network traffic to the mail-server. After all, this does not interfere with SPF checks because it keeps the origin IP address. If no dedicated external IP address is available, you could try the latter approach, if one is available, use the former.

"},{"location":"config/advanced/kubernetes/#external-ips-service","title":"External IPs Service","text":"

The simplest way is to expose docker-mailserver as a Service with external IPs. This is very similar to the approach taken above. Here, an external IP is given to the service directly by you. With the approach above, you tell your load-balancer to do this.

---\napiVersion: v1\nkind: Service\n\nmetadata:\nname: mailserver\nlabels:\napp: mailserver\n\nspec:\nselector:\napp: mailserver\nports:\n- name: smtp\nport: 25\ntargetPort: smtp\n# ...\n\nexternalIPs:\n- 80.11.12.10\n

This approach

  • does not preserve the real client IP, so SPF check of incoming mail will fail.
  • requires you to specify the exposed IPs explicitly.
"},{"location":"config/advanced/kubernetes/#proxy-port-to-service","title":"Proxy port to Service","text":"

The proxy pod helps to avoid the necessity of specifying external IPs explicitly. This comes at the cost of complexity; you must deploy a proxy pod on each Node you want to expose docker-mailserver on.

This approach

  • does not preserve the real client IP, so SPF check of incoming mail will fail.
"},{"location":"config/advanced/kubernetes/#bind-to-concrete-node-and-use-host-network","title":"Bind to concrete Node and use host network","text":"

One way to preserve the real client IP is to use hostPort and hostNetwork: true. This comes at the cost of availability; you can reach docker-mailserver from the outside world only via IPs of Node where docker-mailserver is deployed.

---\napiVersion: extensions/v1beta1\nkind: Deployment\n\nmetadata:\nname: mailserver\n\n# ...\nspec:\nhostNetwork: true\n\n# ...\ncontainers:\n# ...\nports:\n- name: smtp\ncontainerPort: 25\nhostPort: 25\n- name: smtp-auth\ncontainerPort: 587\nhostPort: 587\n- name: imap-secure\ncontainerPort: 993\nhostPort: 993\n#  ...\n

With this approach,

  • it is not possible to access docker-mailserver via other cluster Nodes, only via the Node docker-mailserver was deployed at.
  • every Port within the Container is exposed on the Host side.
"},{"location":"config/advanced/kubernetes/#proxy-port-to-service-via-proxy-protocol","title":"Proxy Port to Service via PROXY Protocol","text":"

This way is ideologically the same as using a proxy pod, but instead of a separate proxy pod, you configure your ingress to proxy TCP traffic to the docker-mailserver pod using the PROXY protocol, which preserves the real client IP.

"},{"location":"config/advanced/kubernetes/#configure-your-ingress","title":"Configure your Ingress","text":"

With an NGINX ingress controller, set externalTrafficPolicy: Local for its service, and add the following to the TCP services config map (as described here):

25:  \"mailserver/mailserver:25::PROXY\"\n465: \"mailserver/mailserver:465::PROXY\"\n587: \"mailserver/mailserver:587::PROXY\"\n993: \"mailserver/mailserver:993::PROXY\"\n

HAProxy

With HAProxy, the configuration should look similar to the above. If you know what it actually looks like, add an example here.

"},{"location":"config/advanced/kubernetes/#configure-the-mailserver","title":"Configure the Mailserver","text":"

Then, configure both Postfix and Dovecot to expect the PROXY protocol:

HAProxy Example 
kind: ConfigMap\napiVersion: v1\nmetadata:\nname: mailserver.config\nlabels:\napp: mailserver\ndata:\npostfix-main.cf: |\npostscreen_upstream_proxy_protocol = haproxy\npostfix-master.cf: |\nsmtp/inet/postscreen_upstream_proxy_protocol=haproxy\nsubmission/inet/smtpd_upstream_proxy_protocol=haproxy\nsmtps/inet/smtpd_upstream_proxy_protocol=haproxy\ndovecot.cf: |\n# Assuming your ingress controller is bound to 10.0.0.0/8\nhaproxy_trusted_networks = 10.0.0.0/8, 127.0.0.0/8\nservice imap-login {\ninet_listener imap {\nhaproxy = yes\n}\ninet_listener imaps {\nhaproxy = yes\n}\n}\n# ...\n---\n\nkind: Deployment\napiVersion: extensions/v1beta1\nmetadata:\nname: mailserver\nspec:\ntemplate:\nspec:\ncontainers:\n- name: docker-mailserver\nvolumeMounts:\n- name: config\nsubPath: postfix-main.cf\nmountPath: /tmp/docker-mailserver/postfix-main.cf\nreadOnly: true\n- name: config\nsubPath: postfix-master.cf\nmountPath: /tmp/docker-mailserver/postfix-master.cf\nreadOnly: true\n- name: config\nsubPath: dovecot.cf\nmountPath: /tmp/docker-mailserver/dovecot.cf\nreadOnly: true\n

With this approach,

  • it is not possible to access docker-mailserver via cluster-DNS, as the PROXY protocol is required for incoming connections.
"},{"location":"config/advanced/mail-fetchmail/","title":"Advanced | Email Gathering with Fetchmail","text":"

To enable the fetchmail service to retrieve e-mails set the environment variable ENABLE_FETCHMAIL to 1. Your docker-compose.yml file should look like following snippet:

environment:\n- ENABLE_FETCHMAIL=1\n- FETCHMAIL_POLL=300\n

Generate a file called fetchmail.cf and place it in the docker-data/dms/config/ folder. Your docker-mailserver folder should look like this example:

\u251c\u2500\u2500 docker-data/dms/config\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 dovecot.cf\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fetchmail.cf\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 postfix-accounts.cf\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 postfix-virtual.cf\n\u251c\u2500\u2500 docker-compose.yml\n\u2514\u2500\u2500 README.md\n
"},{"location":"config/advanced/mail-fetchmail/#configuration","title":"Configuration","text":"

A detailed description of the configuration options can be found in the online version of the manual page.

"},{"location":"config/advanced/mail-fetchmail/#imap-configuration","title":"IMAP Configuration","text":"

Example

poll 'imap.gmail.com' proto imap\n  user 'username'\n  pass 'secret'\n  is 'user1@example.com'\n  ssl\n
"},{"location":"config/advanced/mail-fetchmail/#pop3-configuration","title":"POP3 Configuration","text":"

Example

poll 'pop3.gmail.com' proto pop3\n  user 'username'\n  pass 'secret'\n  is 'user2@example.com'\n  ssl\n

Caution

Don\u2019t forget the last line! (eg: is 'user1@example.com'). After is, you have to specify an email address from the configuration file: docker-data/dms/config/postfix-accounts.cf.

More details how to configure fetchmail can be found in the fetchmail man page in the chapter \u201cThe run control file\u201d.

"},{"location":"config/advanced/mail-fetchmail/#polling-interval","title":"Polling Interval","text":"

By default the fetchmail service searches every 5 minutes for new mails on your external mail accounts. You can override this default value by changing the ENV variable FETCHMAIL_POLL:

environment:\n- FETCHMAIL_POLL=60\n

You must specify a numeric argument which is a polling interval in seconds. The example above polls every minute for new mails.

"},{"location":"config/advanced/mail-fetchmail/#debugging","title":"Debugging","text":"

To debug your fetchmail.cf configuration run this command:

./setup.sh debug fetchmail\n

For more informations about the configuration script setup.sh read the corresponding docs.

Here a sample output of ./setup.sh debug fetchmail:

fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:09 2016: poll started\nTrying to connect to 132.245.48.18/995...connected.\nfetchmail: Server certificate:\nfetchmail: Issuer Organization: Microsoft Corporation\nfetchmail: Issuer CommonName: Microsoft IT SSL SHA2\nfetchmail: Subject CommonName: outlook.com\nfetchmail: Subject Alternative Name: outlook.com\nfetchmail: Subject Alternative Name: *.outlook.com\nfetchmail: Subject Alternative Name: office365.com\nfetchmail: Subject Alternative Name: *.office365.com\nfetchmail: Subject Alternative Name: *.live.com\nfetchmail: Subject Alternative Name: *.internal.outlook.com\nfetchmail: Subject Alternative Name: *.outlook.office365.com\nfetchmail: Subject Alternative Name: outlook.office.com\nfetchmail: Subject Alternative Name: attachment.outlook.office.net\nfetchmail: Subject Alternative Name: attachment.outlook.officeppe.net\nfetchmail: Subject Alternative Name: *.office.com\nfetchmail: outlook.office365.com key fingerprint: 3A:A4:58:42:56:CD:BD:11:19:5B:CF:1E:85:16:8E:4D\nfetchmail: POP3< +OK The Microsoft Exchange POP3 service is ready. [SABFADEAUABSADAAMQBDAEEAMAAwADAANwAuAGUAdQByAHAAcgBkADAAMQAuAHAAcgBvAGQALgBlAHgAYwBoAGEAbgBnAGUAbABhAGIAcwAuAGMAbwBtAA==]\nfetchmail: POP3> CAPA\nfetchmail: POP3< +OK\nfetchmail: POP3< TOP\nfetchmail: POP3< UIDL\nfetchmail: POP3< SASL PLAIN\nfetchmail: POP3< USER\nfetchmail: POP3< .\nfetchmail: POP3> USER user1@outlook.com\nfetchmail: POP3< +OK\nfetchmail: POP3> PASS *\nfetchmail: POP3< +OK User successfully logged on.\nfetchmail: POP3> STAT\nfetchmail: POP3< +OK 0 0\nfetchmail: No mail for user1@outlook.com at outlook.office365.com\nfetchmail: POP3> QUIT\nfetchmail: POP3< +OK Microsoft Exchange Server 2016 POP3 server signing off.\nfetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:11 2016: poll completed\nfetchmail: normal termination, status 1\n
"},{"location":"config/advanced/mail-sieve/","title":"Advanced | Email Filtering with Sieve","text":""},{"location":"config/advanced/mail-sieve/#user-defined-sieve-filters","title":"User-Defined Sieve Filters","text":"

Sieve allows to specify filtering rules for incoming emails that allow for example sorting mails into different folders depending on the title of an email. There are global and user specific filters which are filtering the incoming emails in the following order:

  • Global-before -> User specific -> Global-after

Global filters are applied to EVERY incoming mail for EVERY email address. To specify a global Sieve filter provide a docker-data/dms/config/before.dovecot.sieve or a docker-data/dms/config/after.dovecot.sieve file with your filter rules. If any filter in this filtering chain discards an incoming mail, the delivery process will stop as well and the mail will not reach any following filters(e.g. global-before stops an incoming spam mail: The mail will get discarded and a user-specific filter won't get applied.)

To specify a user-defined Sieve filter place a .dovecot.sieve file into a virtual user's mail folder e.g. /var/mail/example.com/user1/.dovecot.sieve. If this file exists dovecot will apply the filtering rules.

It's even possible to install a user provided Sieve filter at startup during users setup: simply include a Sieve file in the docker-data/dms/config/ path for each user login that needs a filter. The file name provided should be in the form <user_login>.dovecot.sieve, so for example for user1@example.com you should provide a Sieve file named docker-data/dms/config/user1@example.com.dovecot.sieve.

An example of a sieve filter that moves mails to a folder INBOX/spam depending on the sender address:

Example

require [\"fileinto\", \"reject\"];\n\nif address :contains [\"From\"] \"spam@spam.com\" {\n  fileinto \"INBOX.spam\";\n} else {\n  keep;\n}\n

Warning

That folders have to exist beforehand if sieve should move them.

Another example of a sieve filter that forward mails to a different address:

Example

require [\"copy\"];\n\nredirect :copy \"user2@not-example.com\";\n

Just forward all incoming emails and do not save them locally:

Example

redirect \"user2@not-example.com\";\n

You can also use external programs to filter or pipe (process) messages by adding executable scripts in docker-data/dms/config/sieve-pipe or docker-data/dms/config/sieve-filter. This can be used in lieu of a local alias file, for instance to forward an email to a webservice. These programs can then be referenced by filename, by all users. Note that the process running the scripts run as a privileged user. For further information see Dovecot's wiki.

require [\"vnd.dovecot.pipe\"];\npipe \"external-program\";\n

For more examples or a detailed description of the Sieve language have a look at the official site. Other resources are available on the internet where you can find several examples.

"},{"location":"config/advanced/mail-sieve/#automatic-sorting-based-on-subaddresses","title":"Automatic Sorting Based on Subaddresses","text":"

It is possible to sort subaddresses such as user+mailing-lists@example.com into a corresponding folder (here: INBOX/Mailing-lists) automatically.

require [\"envelope\", \"fileinto\", \"mailbox\", \"subaddress\", \"variables\"];\n\nif envelope :detail :matches \"to\" \"*\" {\n    set :lower :upperfirst \"tag\" \"${1}\";\n    if mailboxexists \"INBOX.${1}\" {\n        fileinto \"INBOX.${1}\";\n    } else {\n        fileinto :create \"INBOX.${tag}\";\n    }\n}\n
"},{"location":"config/advanced/mail-sieve/#manage-sieve","title":"Manage Sieve","text":"

The Manage Sieve extension allows users to modify their Sieve script by themselves. The authentication mechanisms are the same as for the main dovecot service. ManageSieve runs on port 4190 and needs to be enabled using the ENABLE_MANAGESIEVE=1 environment variable.

Example

# docker-compose.yml\nports:\n- \"4190:4190\"\nenvironment:\n- ENABLE_MANAGESIEVE=1\n

All user defined sieve scripts that are managed by ManageSieve are stored in the user's home folder in /var/mail/example.com/user1/sieve. Just one sieve script might be active for a user and is sym-linked to /var/mail/example.com/user1/.dovecot.sieve automatically.

Note

ManageSieve makes sure to not overwrite an existing .dovecot.sieve file. If a user activates a new sieve script the old one is backuped and moved to the sieve folder.

The extension is known to work with the following ManageSieve clients:

  • Sieve Editor a portable standalone application based on the former Thunderbird plugin.
  • Kmail the mail client of KDE's Kontact Suite.
"},{"location":"config/advanced/optional-config/","title":"Advanced | Optional Configuration","text":"

This is a list of all configuration files and directories which are optional or automatically generated in your docker-data/dms/config/ directory.

"},{"location":"config/advanced/optional-config/#directories","title":"Directories","text":"
  • sieve-filter: directory for sieve filter scripts. (Docs: Sieve)
  • sieve-pipe: directory for sieve pipe scripts. (Docs: Sieve)
  • opendkim: DKIM directory. Auto-configurable via setup.sh config dkim. (Docs: DKIM)
  • ssl: SSL Certificate directory if SSL_TYPE is set to self-signed or custom. (Docs: SSL)
"},{"location":"config/advanced/optional-config/#files","title":"Files","text":"
  • {user_email_address}.dovecot.sieve: User specific Sieve filter file. (Docs: Sieve)
  • before.dovecot.sieve: Global Sieve filter file, applied prior to the ${login}.dovecot.sieve filter. (Docs: Sieve)
  • after.dovecot.sieve: Global Sieve filter file, applied after the ${login}.dovecot.sieve filter. (Docs: Sieve)
  • postfix-main.cf: Every line will be added to the postfix main configuration. (Docs: Override Postfix Defaults)
  • postfix-master.cf: Every line will be added to the postfix master configuration. (Docs: Override Postfix Defaults)
  • postfix-accounts.cf: User accounts file. Modify via the setup.sh email script.
  • postfix-send-access.cf: List of users denied sending. Modify via setup.sh email restrict.
  • postfix-receive-access.cf: List of users denied receiving. Modify via setup.sh email restrict.
  • postfix-virtual.cf: Alias configuration file. Modify via setup.sh alias.
  • postfix-sasl-password.cf: listing of relayed domains with their respective <username>:<password>. Modify via setup.sh relay add-auth <domain> <username> [<password>]. (Docs: Relay-Hosts Auth)
  • postfix-relaymap.cf: domain-specific relays and exclusions. Modify via setup.sh relay add-domain and setup.sh relay exclude-domain. (Docs: Relay-Hosts Senders)
  • postfix-regexp.cf: Regular expression alias file. (Docs: Aliases)
  • ldap-users.cf: Configuration for the virtual user mapping virtual_mailbox_maps. See the setup-stack.sh script.
  • ldap-groups.cf: Configuration for the virtual alias mapping virtual_alias_maps. See the setup-stack.sh script.
  • ldap-aliases.cf: Configuration for the virtual alias mapping virtual_alias_maps. See the setup-stack.sh script.
  • ldap-domains.cf: Configuration for the virtual domain mapping virtual_mailbox_domains. See the setup-stack.sh script.
  • whitelist_clients.local: Whitelisted domains, not considered by postgrey. Enter one host or domain per line.
  • spamassassin-rules.cf: Antispam rules for Spamassassin. (Docs: FAQ - SpamAssassin Rules)
  • fail2ban-fail2ban.cf: Additional config options for fail2ban.cf. (Docs: Fail2Ban)
  • fail2ban-jail.cf: Additional config options for fail2ban's jail behaviour. (Docs: Fail2Ban)
  • amavis.cf: replaces the /etc/amavis/conf.d/50-user file
  • dovecot.cf: replaces /etc/dovecot/local.conf. (Docs: Override Dovecot Defaults)
  • dovecot-quotas.cf: list of custom quotas per mailbox. (Docs: Accounts)
  • user-patches.sh: this file will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started. (Docs: FAQ - How to adjust settings with the user-patches.sh script)
  • rspamd-commands: list of simple commands to adjust Rspamd modules in an easy way (Docs: Rspamd)
"},{"location":"config/advanced/podman/","title":"Advanced | Podman","text":""},{"location":"config/advanced/podman/#introduction","title":"Introduction","text":"

Podman is a daemonless container engine for developing, managing, and running OCI Containers on your Linux System.

About Support for Podman

Please note that Podman is not officially supported as docker-mailserver is built and verified on top of the Docker Engine. This content is entirely community supported. If you find errors, please open an issue and provide a PR.

About this Guide

This guide was tested with Fedora 34 using systemd and firewalld. Moreover, it requires Podman version >= 3.2. You may be able to substitute dnf - Fedora's package manager - with others such as apt.

About Security

Running podman in rootless mode requires additional modifications in order to keep your mailserver secure. Make sure to read the related documentation.

"},{"location":"config/advanced/podman/#installation-in-rootfull-mode","title":"Installation in Rootfull Mode","text":"

While using Podman, you can just manage docker-mailserver as what you did with Docker. Your best friend setup.sh includes the minimum code in order to support Podman since it's 100% compatible with the Docker CLI.

The installation is basically the same. Podman v3.2 introduced a RESTful API that is 100% compatible with the Docker API, so you can use docker-compose with Podman easily. Install Podman and docker-compose with your package manager first.

sudo dnf install podman docker-compose\n

Then enable podman.socket using systemctl.

systemctl enable --now podman.socket\n

This will create a unix socket locate under /run/podman/podman.sock, which is the entrypoint of Podman's API. Now, configure docker-mailserver and start it.

export DOCKER_HOST=\"unix:///run/podman/podman.sock\"\ndocker-compose up -d mailserver\ndocker-compose ps\n

You should see that docker-mailserver is running now.

"},{"location":"config/advanced/podman/#self-start-in-rootfull-mode","title":"Self-start in Rootfull Mode","text":"

Podman is daemonless, that means if you want docker-mailserver self-start while boot up the system, you have to generate a systemd file with Podman CLI.

podman generate systemd mailserver > /etc/systemd/system/mailserver.service\nsystemctl daemon-reload\nsystemctl enable --now mailserver.service\n
"},{"location":"config/advanced/podman/#installation-in-rootless-mode","title":"Installation in Rootless Mode","text":"

Running rootless containers is one of Podman's major features. But due to some restrictions, deploying docker-mailserver in rootless mode is not as easy compared to rootfull mode.

  • a rootless container is running in a user namespace so you cannot bind ports lower than 1024
  • a rootless container's systemd file can only be placed in folder under ~/.config
  • a rootless container can result in an open relay, make sure to read the security section.

Also notice that Podman's rootless mode is not about running as a non-root user inside the container, but about the mapping of (normal, non-root) host users to root inside the container.

Warning

In order to make rootless docker-mailserver work we must modify some settings in the Linux system, it requires some basic linux server knowledge so don't follow this guide if you not sure what this guide is talking about. Podman rootfull mode and Docker are still good and security enough for normal daily usage.

First, enable podman.socket in systemd's userspace with a non-root user.

systemctl enable --now --user podman.socket\n

The socket file should be located at /var/run/user/$(id -u)/podman/podman.sock. Then, modify docker-compose.yml to make sure all ports are bindings are on non-privileged ports.

services:\nmailserver:\nports:\n- \"10025:25\"   # SMTP  (explicit TLS => STARTTLS)\n- \"10143:143\"  # IMAP4 (explicit TLS => STARTTLS)\n- \"10465:465\"  # ESMTP (implicit TLS)\n- \"10587:587\"  # ESMTP (explicit TLS => STARTTLS)\n- \"10993:993\"  # IMAP4 (implicit TLS)\n

Then, setup your mailserver.env file follow the documentation and use docker-compose to start the container.

export DOCKER_HOST=\"unix:///var/run/user/$(id -u)/podman/podman.sock\"\ndocker-compose up -d mailserver\ndocker-compose ps\n
"},{"location":"config/advanced/podman/#security-in-rootless-mode","title":"Security in Rootless Mode","text":"

In rootless mode, podman resolves all incoming IPs as localhost, which results in an open gateway in the default configuration. There are two workarounds to fix this problem, both of which have their own drawbacks.

"},{"location":"config/advanced/podman/#enforce-authentication-from-localhost","title":"Enforce authentication from localhost","text":"

The PERMIT_DOCKER variable in the mailserver.env file allows to specify trusted networks that do not need to authenticate. If the variable is left empty, only requests from localhost and the container IP are allowed, but in the case of rootless podman any IP will be resolved as localhost. Setting PERMIT_DOCKER=none enforces authentication also from localhost, which prevents sending unauthenticated emails.

"},{"location":"config/advanced/podman/#use-the-slip4netns-network-driver","title":"Use the slip4netns network driver","text":"

The second workaround is slightly more complicated because the docker-compose.yml has to be modified. As shown in the fail2ban section the slirp4netns network driver has to be enabled. This network driver enables podman to correctly resolve IP addresses but it is not compatible with user defined networks which might be a problem depending on your setup.

Rootless Podman requires adding the value slirp4netns:port_handler=slirp4netns to the --network CLI option, or network_mode setting in your docker-compose.yml.

You must also add the ENV NETWORK_INTERFACE=tap0, because Podman uses a hard-coded interface name for slirp4netns.

Example

services:\nmailserver:\nnetwork_mode: \"slirp4netns:port_handler=slirp4netns\"\nenvironment:\n- NETWORK_INTERFACE=tap0\n...\n

Note

podman-compose is not compatible with this configuration.

"},{"location":"config/advanced/podman/#self-start-in-rootless-mode","title":"Self-start in Rootless Mode","text":"

Generate a systemd file with the Podman CLI.

podman generate systemd mailserver > ~/.config/systemd/user/mailserver.service\nsystemctl --user daemon-reload\nsystemctl enable --user --now mailserver.service\n

Systemd's user space service is only started when a specific user logs in and stops when you log out. In order to make it to start with the system, we need to enable linger with loginctl

loginctl enable-linger <username>\n

Remember to run this command as root user.

"},{"location":"config/advanced/podman/#port-forwarding","title":"Port Forwarding","text":"

When it comes to forwarding ports using firewalld, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/securing_networks/using-and-configuring-firewalld_securing-networks#port-forwarding_using-and-configuring-firewalld for more information.

firewall-cmd --permanent --add-forward-port=port=<25|143|465|587|993>:proto=<tcp>:toport=<10025|10143|10465|10587|10993>\n...\n\n# After you set all ports up.\nfirewall-cmd --reload\n

Notice that this will only open the access to the external client. If you want to access privileges port in your server, do this:

firewall-cmd --permanent --direct --add-rule <ipv4|ipv6> nat OUTPUT 0 -p <tcp|udp> -o lo --dport <25|143|465|587|993> -j REDIRECT --to-ports <10025|10143|10465|10587|10993>\n...\n# After you set all ports up.\nfirewall-cmd --reload\n

Just map all the privilege port with non-privilege port you set in docker-compose.yml before as root user.

"},{"location":"config/advanced/mail-forwarding/aws-ses/","title":"Mail Forwarding | AWS SES","text":"

Amazon SES (Simple Email Service) is intended to provide a simple way for cloud based applications to send email and receive email. For the purposes of this project only sending email via SES is supported. Older versions of docker-mailserver used AWS_SES_HOST and AWS_SES_USERPASS to configure sending, this has changed and the setup is mananged through Configure Relay Hosts.

You will need to create some Amazon SES SMTP credentials. The SMTP credentials you create will be used to populate the RELAY_USER and RELAY_PASSWORD environment variables.

The RELAY_HOST should match your AWS SES region, the RELAY_PORT will be 587.

If all of your email is being forwarded through AWS SES, DEFAULT_RELAY_HOST should be set accordingly.

Example: 

DEFAULT_RELAY_HOST=[email-smtp.us-west-2.amazonaws.com]:587\n

Note

If you set up AWS Easy DKIM you can safely skip setting up DKIM as the AWS SES will take care of signing your outgoing email.

To verify proper operation, send an email to some external account of yours and inspect the mail headers. You will also see the connection to SES in the mail logs. For example:

May 23 07:09:36 mail postfix/smtp[692]: Trusted TLS connection established to email-smtp.us-east-1.amazonaws.com[107.20.142.169]:25:\nTLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)\nMay 23 07:09:36 mail postfix/smtp[692]: 8C82A7E7: to=<someone@example.com>, relay=email-smtp.us-east-1.amazonaws.com[107.20.142.169]:25,\ndelay=0.35, delays=0/0.02/0.13/0.2, dsn=2.0.0, status=sent (250 Ok 01000154dc729264-93fdd7ea-f039-43d6-91ed-653e8547867c-000000)\n
"},{"location":"config/advanced/mail-forwarding/relay-hosts/","title":"Mail Forwarding | Relay Hosts","text":""},{"location":"config/advanced/mail-forwarding/relay-hosts/#introduction","title":"Introduction","text":"

Rather than having Postfix deliver mail directly, you can configure Postfix to send mail via another mail relay (smarthost). Examples include Mailgun, Sendgrid and AWS SES.

Depending on the domain of the sender, you may want to send via a different relay, or authenticate in a different way.

"},{"location":"config/advanced/mail-forwarding/relay-hosts/#basic-configuration","title":"Basic Configuration","text":"

Basic configuration is done via environment variables:

  • RELAY_HOST: default host to relay mail through, empty (aka '', or no ENV set) will disable this feature
  • RELAY_PORT: port on default relay, defaults to port 25
  • RELAY_USER: username for the default relay
  • RELAY_PASSWORD: password for the default user

Setting these environment variables will cause mail for all sender domains to be routed via the specified host, authenticating with the user/password combination.

Warning

For users of the previous AWS_SES_* variables: please update your configuration to use these new variables, no other configuration is required.

"},{"location":"config/advanced/mail-forwarding/relay-hosts/#advanced-configuration","title":"Advanced Configuration","text":""},{"location":"config/advanced/mail-forwarding/relay-hosts/#sender-dependent-authentication","title":"Sender-dependent Authentication","text":"

Sender dependent authentication is done in docker-data/dms/config/postfix-sasl-password.cf. You can create this file manually, or use:

setup.sh relay add-auth <domain> <username> [<password>]\n

An example configuration file looks like this:

@domain1.com           relay_user_1:password_1\n@domain2.com           relay_user_2:password_2\n

If there is no other configuration, this will cause Postfix to deliver email through the relay specified in RELAY_HOST env variable, authenticating as relay_user_1 when sent from domain1.com and authenticating as relay_user_2 when sending from domain2.com.

Note

To activate the configuration you must either restart the container, or you can also trigger an update by modifying a mail account.

"},{"location":"config/advanced/mail-forwarding/relay-hosts/#sender-dependent-relay-host","title":"Sender-dependent Relay Host","text":"

Sender dependent relay hosts are configured in docker-data/dms/config/postfix-relaymap.cf. You can create this file manually, or use:

setup.sh relay add-domain <domain> <host> [<port>]\n

An example configuration file looks like this:

@domain1.com        [relay1.org]:587\n@domain2.com        [relay2.org]:2525\n

Combined with the previous configuration in docker-data/dms/config/postfix-sasl-password.cf, this will cause Postfix to deliver mail sent from domain1.com via relay1.org:587, authenticating as relay_user_1, and mail sent from domain2.com via relay2.org:2525 authenticating as relay_user_2.

Note

You still have to define RELAY_HOST to activate the feature

"},{"location":"config/advanced/mail-forwarding/relay-hosts/#excluding-sender-domains","title":"Excluding Sender Domains","text":"

If you want mail sent from some domains to be delivered directly, you can exclude them from being delivered via the default relay by adding them to docker-data/dms/config/postfix-relaymap.cf with no destination. You can also do this via:

setup.sh relay exclude-domain <domain>\n

Extending the configuration file from above:

@domain1.com        [relay1.org]:587\n@domain2.com        [relay2.org]:2525\n@domain3.com\n

This will cause email sent from domain3.com to be delivered directly.

"},{"location":"config/advanced/maintenance/update-and-cleanup/","title":"Maintenance | Update and Cleanup","text":""},{"location":"config/advanced/maintenance/update-and-cleanup/#automatic-update","title":"Automatic Update","text":"

Docker images are handy but it can become a hassle to keep them updated. Also when a repository is automated you want to get these images when they get out.

One could setup a complex action/hook-based workflow using probes, but there is a nice, easy to use docker image that solves this issue and could prove useful: watchtower.

A docker-compose example:

services:\nwatchtower:\nrestart: always\nimage: containrrr/watchtower:latest\nvolumes:\n- /var/run/docker.sock:/var/run/docker.sock\n

For more details, see the manual

"},{"location":"config/advanced/maintenance/update-and-cleanup/#automatic-cleanup","title":"Automatic Cleanup","text":"

When you are pulling new images in automatically, it would be nice to have them cleaned up as well. There is also a docker image for this: spotify/docker-gc.

A docker-compose example:

services:\ndocker-gc:\nrestart: always\nimage: spotify/docker-gc:latest\nvolumes:\n- /var/run/docker.sock:/var/run/docker.sock\n

For more details, see the manual

Or you can just use the --cleanup option provided by containrrr/watchtower.

"},{"location":"config/advanced/override-defaults/dovecot/","title":"Override the Default Configs | Dovecot","text":""},{"location":"config/advanced/override-defaults/dovecot/#add-configuration","title":"Add Configuration","text":"

The Dovecot default configuration can easily be extended providing a docker-data/dms/config/dovecot.cf file. Dovecot documentation remains the best place to find configuration options.

Your docker-mailserver folder should look like this example:

\u251c\u2500\u2500 docker-data/dms/config\n\u2502   \u251c\u2500\u2500 dovecot.cf\n\u2502   \u251c\u2500\u2500 postfix-accounts.cf\n\u2502   \u2514\u2500\u2500 postfix-virtual.cf\n\u251c\u2500\u2500 docker-compose.yml\n\u2514\u2500\u2500 README.md\n

One common option to change is the maximum number of connections per user:

mail_max_userip_connections = 100\n

Another important option is the default_process_limit (defaults to 100). If high-security mode is enabled you'll need to make sure this count is higher than the maximum number of users that can be logged in simultaneously.

This limit is quickly reached if users connect to the docker-mailserver with multiple end devices.

"},{"location":"config/advanced/override-defaults/dovecot/#override-configuration","title":"Override Configuration","text":"

For major configuration changes it\u2019s best to override the dovecot configuration files. For each configuration file you want to override, add a list entry under the volumes key.

services:\nmailserver:\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/config/dovecot/10-master.conf:/etc/dovecot/conf.d/10-master.conf\n

You will first need to obtain the configuration from the running container (where mailserver is the container name):

mkdir -p ./docker-data/dms/config/dovecot\ndocker cp mailserver:/etc/dovecot/conf.d/10-master.conf ./docker-data/dms/config/dovecot/10-master.conf\n
"},{"location":"config/advanced/override-defaults/dovecot/#debugging","title":"Debugging","text":"

To debug your dovecot configuration you can use:

  • This command: ./setup.sh debug login doveconf | grep <some-keyword>
  • Or: docker exec -it mailserver doveconf | grep <some-keyword>

Note

setup.sh is included in the docker-mailserver repository. Make sure to use the one matching your image version release.

The file docker-data/dms/config/dovecot.cf is copied internally to /etc/dovecot/local.conf. To verify the file content, run:

docker exec -it mailserver cat /etc/dovecot/local.conf\n
"},{"location":"config/advanced/override-defaults/postfix/","title":"Override the Default Configs | Postfix","text":"

Our default Postfix configuration can easily be extended to add parameters or modify existing ones by providing a docker-data/dms/config/postfix-main.cf. This file uses the same format as Postfix main.cf does (See official docs for all parameters and syntax rules).

Example

One can easily increase the backwards-compatibility level and set new Postscreen options:

# increase the compatibility level from 2 (default) to 3\ncompatibility_level = 3\n# set a threshold value for Spam detection\npostscreen_dnsbl_threshold = 4\n

How are your changes applied?

The custom configuration you supply is appended to the default configuration located at /etc/postfix/main.cf, and then postconf -nf is run to remove earlier duplicate entries that have since been replaced. This happens early during container startup before Postfix is started.

Similarly, it is possible to add a custom docker-data/dms/config/postfix-master.cf file that will override the standard master.cf. Note: Each line in this file will be passed to postconf -P, i.e. the file is not appended as a whole to /etc/postfix/master.cf like docker-data/dms/config/postfix-main.cf! The expected format is <service_name>/<type>/<parameter>, for example:

# adjust the submission \"reject_unlisted_recipient\" option\nsubmission/inet/smtpd_reject_unlisted_recipient=no\n

Attention

There should be no space between the parameter and the value.

Run postconf -Mf in the container without arguments to see the active master options.

"},{"location":"config/advanced/override-defaults/user-patches/","title":"Custom User Changes & Patches | Scripting","text":"

If you'd like to change, patch or alter files or behavior of docker-mailserver, you can use a script.

In case you cloned this repository, you can copy the file user-patches.sh.dist (under config/) with cp config/user-patches.sh.dist docker-data/dms/config/user-patches.sh in order to create the user-patches.sh script.

If you are managing your directory structure yourself, create a docker-data/dms/config/ directory and add the user-patches.sh file yourself.

# 1. Either create the docker-data/dms/config/ directory yourself\n#    or let docker-mailserver create it on initial startup\n/tmp $ mkdir -p docker-data/dms/config/ && cd docker-data/dms/config/\n\n# 2. Create the user-patches.sh file and edit it\n/tmp/docker-data/dms/config $ touch user-patches.sh\n/tmp/docker-data/dms/config $ nano user-patches.sh\n

The contents could look like this:

#!/bin/bash\n\ncat >/etc/amavis/conf.d/50-user << \"END\"\nuse strict;\n\n$undecipherable_subject_tag = undef;\n$admin_maps_by_ccat{+CC_UNCHECKED} =  undef;\n\n#------------ Do not modify anything below this line -------------\n1;  # ensure a defined return\nEND\n

And you're done. The user patches script runs right before starting daemons. That means, all the other configuration is in place, so the script can make final adjustments.

Note

Many \"patches\" can already be done with the Docker Compose-/Stack-file. Adding hostnames to /etc/hosts is done with the extra_hosts: section, sysctl commands can be managed with the sysctls: section, etc.

"},{"location":"config/best-practices/autodiscover/","title":"Best Practices | Auto-discovery","text":"

Email auto-discovery means a client email is able to automagically find out about what ports and security options to use, based on the mail-server URI. It can help simplify the tedious / confusing task of adding own's email account for non-tech savvy users.

Email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address

There exists autodiscover-email-settings on which provides IMAP/POP/SMTP/LDAP autodiscover capabilities on Microsoft Outlook/Apple Mail, autoconfig capabilities for Thunderbird or kmail and configuration profiles for iOS/Apple Mail.

"},{"location":"config/best-practices/dkim/","title":"Best Practices | DKIM","text":"

DKIM is a security measure targeting email spoofing. It is greatly recommended one activates it.

Note

See the Wikipedia page for more details on DKIM.

"},{"location":"config/best-practices/dkim/#enabling-dkim-signature","title":"Enabling DKIM Signature","text":"

To enable DKIM signature, you must have created at least one email account. Once its done, just run the following command to generate the signature:

./setup.sh config dkim\n

After generating DKIM keys, you should restart docker-mailserver. DNS edits may take a few minutes to hours to propagate.

The script should ideally be run with a volume for config attached (eg: ./docker-data/dms/config/:/tmp/docker-mailserver/), otherwise by default it will mount ./config/:/tmp/docker-mailserver/.

The default keysize when generating the signature is 4096 bits for now. If you need to change it (e.g. your DNS provider limits the size), then provide the size as the first parameter of the command:

./setup.sh config dkim keysize <keysize>\n

For LDAP systems that do not have any directly created user account you can run the following command (since 8.0.0) to generate the signature by additionally providing the desired domain name (if you have multiple domains use the command multiple times or provide a comma-separated list of domains):

./setup.sh config dkim keysize <key-size> domain <example.com>[,<not-example.com>]\n

Now the keys are generated, you can configure your DNS server with DKIM signature, simply by adding a TXT record. If you have direct access to your DNS zone file, then it's only a matter of pasting the content of docker-data/dms/config/opendkim/keys/example.com/mail.txt in your example.com.hosts zone.

$ dig mail._domainkey.example.com TXT\n---\n;; ANSWER SECTION\nmail._domainkey.<DOMAIN> 300 IN TXT    \"v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN\"\n
"},{"location":"config/best-practices/dkim/#configuration-using-a-web-interface","title":"Configuration using a Web Interface","text":"
  1. Generate a new record of the type TXT.
  2. Paste mail._domainkey the Name txt field.
  3. In the Target or Value field fill in v=DKIM1; k=rsa; p=AZERTYUGHJKLMWX....
  4. In TTL (time to live): Time span in seconds. How long the DNS server should cache the TXT record.
  5. Save.

Note

Sometimes the key in docker-data/dms/config/opendkim/keys/example.com/mail.txt can be on multiple lines. If so then you need to concatenate the values in the TXT record:

$ dig mail._domainkey.example.com TXT\n---\n;; ANSWER SECTION\nmail._domainkey.<DOMAIN> 300 IN TXT \"v=DKIM1; k=rsa; \"\n    \"p=AZERTYUIOPQSDF...\"\n    \"asdfQWERTYUIOPQSDF...\"\n

The target (or value) field must then have all the parts together: v=DKIM1; k=rsa; p=AZERTYUIOPQSDF...asdfQWERTYUIOPQSDF...

"},{"location":"config/best-practices/dkim/#verify-only","title":"Verify-Only","text":"

If you want DKIM to only verify incoming emails, the following version of /etc/opendkim.conf may be useful (right now there is no easy mechanism for installing it other than forking the repo):

# This is a simple config file verifying messages only\n\n#LogWhy                 yes\nSyslog                  yes\nSyslogSuccess           yes\n\nSocket                  inet:12301@localhost\nPidFile                 /var/run/opendkim/opendkim.pid\n\nReportAddress           postmaster@example.com\nSendReports             yes\n\nMode                    v\n
"},{"location":"config/best-practices/dkim/#switch-off-dkim","title":"Switch Off DKIM","text":"

Simply remove the DKIM key by recreating (not just relaunching) the docker-mailserver container.

"},{"location":"config/best-practices/dkim/#debugging","title":"Debugging","text":"
  • DKIM-verifer: A add-on for the mail client Thunderbird.
  • You can debug your TXT records with the dig tool.
$ dig TXT mail._domainkey.example.com\n---\n; <<>> DiG 9.10.3-P4-Debian <<>> TXT mail._domainkey.example.com\n;; global options: +cmd\n;; Got answer:\n;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 39669\n;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1\n\n;; OPT PSEUDOSECTION:\n; EDNS: version: 0, flags:; udp: 512\n;; QUESTION SECTION:\n;mail._domainkey.example.com. IN TXT\n\n;; ANSWER SECTION:\nmail._domainkey.example.com. 3600 IN TXT \"v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxBSjG6RnWAdU3oOlqsdf2WC0FOUmU8uHVrzxPLW2R3yRBPGLrGO1++yy3tv6kMieWZwEBHVOdefM6uQOQsZ4brahu9lhG8sFLPX4MaKYN/NR6RK4gdjrZu+MYSdfk3THgSbNwIDAQAB\"\n\n;; Query time: 50 msec\n;; SERVER: 127.0.1.1#53(127.0.1.1)\n;; WHEN: Wed Sep 07 18:22:57 CEST 2016\n;; MSG SIZE  rcvd: 310\n

Key sizes >=4096-bit

Keys of 4096 bits could de denied by some mail-servers. According to https://tools.ietf.org/html/rfc6376 keys are preferably between 512 and 2048 bits. See issue #1854.

"},{"location":"config/best-practices/dmarc/","title":"Best Practices | DMARC","text":"

More information at DMARC Guide.

"},{"location":"config/best-practices/dmarc/#enabling-dmarc","title":"Enabling DMARC","text":"

In docker-mailserver, DMARC is pre-configured out of the box. The only thing you need to do in order to enable it, is to add new TXT entry to your DNS.

In contrast with DKIM, the DMARC DNS entry does not require any keys, but merely setting the configuration values. You can either handcraft the entry by yourself or use one of available generators (like this one).

Typically something like this should be good to start with (don't forget to replace @example.com to your actual domain):

_dmarc.example.com. IN TXT \"v=DMARC1; p=none; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; sp=none; ri=86400\"\n

Or a bit more strict policies (mind p=quarantine and sp=quarantine):

_dmarc IN TXT \"v=DMARC1; p=quarantine; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; sp=quarantine\"\n

DMARC status is not being displayed instantly in Gmail for instance. If you want to check it directly after DNS entries, you can use some services around the Internet such as from Global Cyber Alliance or RedSift. In other cases, email clients will show \"DMARC: PASS\" in ~1 day or so.

Reference: #1511

"},{"location":"config/best-practices/spf/","title":"Best Practices | SPF","text":"

From Wikipedia:

Quote

Sender Policy Framework (SPF) is a simple email-validation system designed to detect email spoofing by providing a mechanism to allow receiving mail exchangers to check that incoming mail from a domain comes from a host authorized by that domain's administrators. The list of authorized sending hosts for a domain is published in the Domain Name System (DNS) records for that domain in the form of a specially formatted TXT record. Email spam and phishing often use forged \"from\" addresses, so publishing and checking SPF records can be considered anti-spam techniques.

Note

For a more technical review: https://github.com/internetstandards/toolbox-wiki/blob/master/SPF-how-to.md

"},{"location":"config/best-practices/spf/#add-a-spf-record","title":"Add a SPF Record","text":"

To add a SPF record in your DNS, insert the following line in your DNS zone:

; MX record must be declared for SPF to work\nexample.com. IN  MX 1 mail.example.com.\n\n; SPF record\nexample.com. IN TXT \"v=spf1 mx ~all\"\n

This enables the Softfail mode for SPF. You could first add this SPF record with a very low TTL.

SoftFail is a good setting for getting started and testing, as it lets all email through, with spams tagged as such in the mailbox.

After verification, you might want to change your SPF record to v=spf1 mx -all so as to enforce the HardFail policy. See http://www.open-spf.org/SPF_Record_Syntax for more details about SPF policies.

In any case, increment the SPF record's TTL to its final value.

"},{"location":"config/best-practices/spf/#backup-mx-secondary-mx","title":"Backup MX, Secondary MX","text":"

For whitelisting an IP Address from the SPF test, you can create a config file (see policyd-spf.conf) and mount that file into /etc/postfix-policyd-spf-python/policyd-spf.conf.

Example:

Create and edit a policyd-spf.conf file at docker-data/dms/config/postfix-policyd-spf.conf:

debugLevel = 1\n#0(only errors)-4(complete data received)\n\nskip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1\n\n# Preferably use IP-Addresses for whitelist lookups:\nWhitelist = 192.168.0.0/31,192.168.1.0/30\n# Domain_Whitelist = mx1.not-example.com,mx2.not-example.com\n

Then add this line to docker-compose.yml:

volumes:\n- ./docker-data/dms/config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf\n
"},{"location":"config/security/fail2ban/","title":"Security | Fail2Ban","text":"

Fail2Ban is installed automatically and bans IP addresses for 3 hours after 3 failed attempts in 10 minutes by default.

"},{"location":"config/security/fail2ban/#configuration-files","title":"Configuration files","text":"

If you want to change this, you can easily edit our github example file: config-examples/fail2ban-jail.cf.

You can do the same with the values from fail2ban.conf, e.g dbpurgeage. In that case you need to edit: config-examples/fail2ban-fail2ban.cf.

The configuration files need to be located at the root of the /tmp/docker-mailserver/ volume bind (usually ./docker-data/dms/config/:/tmp/docker-mailserver/).

This following configuration files from /tmp/docker-mailserver/ will be copied during container startup.

  • fail2ban-jail.cf -> /etc/fail2ban/jail.d/user-jail.local
  • fail2ban-fail2ban.cf -> /etc/fail2ban/fail2ban.local
"},{"location":"config/security/fail2ban/#docker-compose-config","title":"Docker-compose config","text":"

Example configuration volume bind:

    volumes:\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n

Attention

docker-mailserver must be launched with the NET_ADMIN capability in order to be able to install the nftables rules that actually ban IP addresses.

Thus either include --cap-add=NET_ADMIN in the docker run command, or the equivalent in docker-compose.yml:

cap_add:\n- NET_ADMIN\n
"},{"location":"config/security/fail2ban/#running-fail2ban-in-a-rootless-container","title":"Running fail2ban in a rootless container","text":"

RootlessKit is the fakeroot implementation for supporting rootless mode in Docker and Podman. By default RootlessKit uses the builtin port forwarding driver, which does not propagate source IP addresses.

It is necessary for fail2ban to have access to the real source IP addresses in order to correctly identify clients. This is achieved by changing the port forwarding driver to slirp4netns, which is slower than builtin but does preserve the real source IPs.

"},{"location":"config/security/fail2ban/#docker-with-slirp4netns-port-driver","title":"Docker with slirp4netns port driver","text":"

For rootless mode in Docker, create ~/.config/systemd/user/docker.service.d/override.conf with the following content:

[Service]\nEnvironment=\"DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns\"\n

And then restart the daemon:

$ systemctl --user daemon-reload\n$ systemctl --user restart docker\n

Note

This changes the port driver for all rootless containers managed by Docker.

Per container configuration is not supported, if you need that consider Podman instead.

"},{"location":"config/security/fail2ban/#podman-with-slirp4netns-port-driver","title":"Podman with slirp4netns port driver","text":"

Rootless Podman requires adding the value slirp4netns:port_handler=slirp4netns to the --network CLI option, or network_mode setting in your docker-compose.yml.

You must also add the ENV NETWORK_INTERFACE=tap0, because Podman uses a hard-coded interface name for slirp4netns.

Example

services:\nmailserver:\nnetwork_mode: \"slirp4netns:port_handler=slirp4netns\"\nenvironment:\n- ENABLE_FAIL2BAN=1\n- NETWORK_INTERFACE=tap0\n...\n

Note

slirp4netns is not compatible with user-defined networks.

"},{"location":"config/security/fail2ban/#manage-bans","title":"Manage bans","text":"

You can also manage and list the banned IPs with the setup.sh script.

"},{"location":"config/security/fail2ban/#list-bans","title":"List bans","text":"
./setup.sh fail2ban\n
"},{"location":"config/security/fail2ban/#un-ban","title":"Un-ban","text":"

Here 192.168.1.15 is our banned IP.

./setup.sh fail2ban unban 192.168.1.15\n
"},{"location":"config/security/mail_crypt/","title":"Security | mail_crypt (email/storage encryption)","text":"

Info

The Mail crypt plugin is used to secure email messages stored in a Dovecot system. Messages are encrypted before written to storage and decrypted after reading. Both operations are transparent to the user.

In case of unauthorized access to the storage backend, the messages will, without access to the decryption keys, be unreadable to the offending party.

There can be a single encryption key for the whole system or each user can have a key of their own. The used cryptographical methods are widely used standards and keys are stored in portable formats, when possible.

Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/

"},{"location":"config/security/mail_crypt/#single-encryption-key-global-method","title":"Single Encryption Key / Global Method","text":"

  1. Create 10-custom.conf and populate it with the following:

    # Enables mail_crypt for all services (imap, pop3, etc)\nmail_plugins = $mail_plugins mail_crypt\nplugin {\n  mail_crypt_global_private_key = </certs/ecprivkey.pem\n  mail_crypt_global_public_key = </certs/ecpubkey.pem\n  mail_crypt_save_version = 2\n}\n

  2. Shutdown your mailserver (docker-compose down)

  3. You then need to generate your global EC key. We named them /certs/ecprivkey.pem and /certs/ecpubkey.pem in step #1.

  4. The EC key needs to be available in the container. I prefer to mount a /certs directory into the container: 

    services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\nvolumes:\n. . .\n- ./certs/:/certs\n. . .\n

  5. While you're editing the docker-compose.yml, add the configuration file: 

    services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\nvolumes:\n. . .\n- ./config/dovecot/10-custom.conf:/etc/dovecot/conf.d/10-custom.conf\n- ./certs/:/certs\n. . .\n

  6. Start the container, monitor the logs for any errors, send yourself a message, and then confirm the file on disk is encrypted: 

    [root@ip-XXXXXXXXXX ~]# cat -A /mnt/efs-us-west-2/maildata/awesomesite.com/me/cur/1623989305.M6v\ufffdz\ufffd@\ufffd\ufffd m}\ufffd\ufffd,\ufffd\ufffd9\ufffd\ufffd\ufffd\ufffdB*\ufffd247.us-west-2.compute.inE\ufffd\ufffd\\Ck*\ufffd@7795,W=7947:2,\nT\ufffd9\ufffd8t\ufffd6\ufffd\ufffd t\ufffd\ufffd\ufffde\ufffdW\ufffd\ufffdS   `\ufffdH\ufffd\ufffdC\ufffd\u06a4 \ufffdyeY\ufffd\ufffdXZ\ufffd\ufffd^\ufffdd\ufffd/\ufffd\ufffd+\ufffdA\n

This should be the minimum required for encryption of the mail while in storage.

"},{"location":"config/security/rspamd/","title":"Security | Rspamd","text":"

The current state of Rspamd integration into DMS

Recent pull requests have stabilized integration of Rspamd to a point that we encourage users to test the feature. We are confident that there are no major bugs in our integration that make using Rspamd infeasible. Please note that there may still be (breaking) changes ahead as integration is still work in progress!

We expect to stabilize this feature with version v12.1.0.

"},{"location":"config/security/rspamd/#about","title":"About","text":"

Rspamd is a \"fast, free and open-source spam filtering system\". DMS integrates Rspamd like any other service. We provide a very simple but easy to maintain setup of Rspamd.

If you want to have a look at the default configuration files for Rspamd that DMS packs, navigate to target/rspamd/ inside the repository. Please consult the section \"The Default Configuration\" section down below for a written overview.

AMD64 vs ARM64

We are currently doing a best-effort installation of Rspamd for ARM64 (from the Debian backports repository for Debian 11). The current version difference is two minor versions (AMD64 is at version 3.4, ARM64 at 3.2 [13th Feb 2023]).

Maintainers noticed only few differences, some of them with a big impact though. For those running Rspamd on ARM64, we recommend disabling the DKIM signing module if you don't use it.

The following environment variables are related to Rspamd:

  1. ENABLE_RSPAMD
  2. ENABLE_RSPAMD_REDIS
  3. RSPAMD_LEARN
  4. MOVE_SPAM_TO_JUNK
"},{"location":"config/security/rspamd/#the-default-configuration","title":"The Default Configuration","text":""},{"location":"config/security/rspamd/#mode-of-operation","title":"Mode of Operation","text":"

The proxy worker operates in self-scan mode. This simplifies the setup as we do not require a normal worker. You can easily change this though by overriding the configuration by DMS.

DMS does not set a default password for the controller worker. You may want to do that yourself. In setups where you already have an authentication provider in front of the Rspamd webpage, you may want to set the secure_ip option to \"0.0.0.0/0\" for the controller worker to disable password authentication inside Rspamd completely.

"},{"location":"config/security/rspamd/#persistence-with-redis","title":"Persistence with Redis","text":"

When Rspamd is enabled, we implicitly also start an instance of Redis in the container. Redis is configured to persist it's data via RDB snapshots to disk in the directory /var/lib/redis (which is a symbolic link to /var/mail-state/lib-redis/ when ONE_DIR=1 and a volume is mounted to /var/mail-state/). With the volume mount the snapshot will restore the Redis data across container restarts, and provide a way to keep backup.

Redis uses /etc/redis/redis.conf for configuration. We adjust this file when enabling the internal Redis service. If you have an external instance of Redis to use, the internal Redis service can be opt-out via setting the ENV ENABLE_RSPAMD_REDIS=0 (link also details required changes to the DMS rspamd config).

"},{"location":"config/security/rspamd/#modules","title":"Modules","text":"

You can find a list of all Rspamd modules on their website.

"},{"location":"config/security/rspamd/#disabled-by-default","title":"Disabled By Default","text":"

DMS disables certain modules (clickhouse, elastic, greylist, neural, reputation, spamassassin, url_redirector, metric_exporter) by default. We believe these are not required in a standard setup, and they would otherwise needlessly use system resources.

"},{"location":"config/security/rspamd/#anti-virus-clamav","title":"Anti-Virus (ClamAV)","text":"

You can choose to enable ClamAV, and Rspamd will then use it to check for viruses. Just set the environment variable ENABLE_CLAMAV=1.

"},{"location":"config/security/rspamd/#rbls-realtime-blacklists-dnsbls-dns-based-blacklists","title":"RBLs (Realtime Blacklists) / DNSBLs (DNS-based Blacklists)","text":"

The RBL module is enabled by default. As a consequence, Rspamd will perform DNS lookups to a variety of blacklists. Whether an RBL or a DNSBL is queried depends on where the domain name was obtained: RBL servers are queried with IP addresses extracted from message headers, DNSBL server are queried with domains and IP addresses extracted from the message body [source].

Rspamd and DNS Block Lists

When the RBL module is enabled, Rspamd will do a variety of DNS requests to (amongst other things) DNSBLs. There are a variety of issues involved when using DNSBLs. Rspamd will try to mitigate some of them by properly evaluating all return codes. This evaluation is a best effort though, so if the DNSBL operators change or add return codes, it may take a while for Rspamd to adjust as well.

If you want to use DNSBLs, try to use your own DNS resolver and make sure it is set up correctly, i.e. it should be a non-public & recursive resolver. Otherwise, you might not be able (see this Spamhaus post) to make use of the block lists.

"},{"location":"config/security/rspamd/#providing-custom-settings-overriding-settings","title":"Providing Custom Settings & Overriding Settings","text":""},{"location":"config/security/rspamd/#manually","title":"Manually","text":"

DMS brings sane default settings for Rspamd. They are located at /etc/rspamd/local.d/ inside the container (or target/rspamd/local.d/ in the repository). If you want to change these settings and / or provide your own settings, you can

  1. place files at /etc/rspamd/override.d/ which will override Rspamd settings and DMS settings
  2. (re-)place files at /etc/rspamd/local.d/ to override DMS settings and merge them with Rspamd settings

Clashing Overrides

Note that when also using the rspamd-commands file, files in override.d may be overwritten in case you adjust them manually and with the help of the file.

"},{"location":"config/security/rspamd/#with-the-help-of-a-custom-file","title":"With the Help of a Custom File","text":"

DMS provides the ability to do simple adjustments to Rspamd modules with the help of a single file. Just place a file called rspamd-modules.conf into the directory docker-data/dms/config/ (which translates to /tmp/docker-mailserver/ in the container). If this file is present, DMS will evaluate it. The structure is very simple. Each line in the file looks like this:

COMMAND ARGUMENT1 ARGUMENT2 ARGUMENT3\n

where COMMAND can be:

  1. disable-module: disables the module with name ARGUMENT1
  2. enable-module: explicitly enables the module with name ARGUMENT1
  3. set-option-for-module: sets the value for option ARGUMENT2 to ARGUMENT3 inside module ARGUMENT1
  4. set-option-for-controller: set the value of option ARGUMENT1 to ARGUMENT2 for the controller worker
  5. set-option-for-proxy: set the value of option ARGUMENT1 to ARGUMENT2 for the proxy worker
  6. set-common-option: set the option ARGUMENT1 that defines basic Rspamd behaviour to value ARGUMENT2
  7. add-line: this will add the complete line after ARGUMENT1 (with all characters) to the file /etc/rspamd/override.d/<ARGUMENT1>

An Example Is Shown Down Below

File Names & Extensions

For command 1 - 3, we append the .conf suffix to the module name to get the correct file name automatically. For commands 4 - 6, the file name is fixed (you don't even need to provide it). For command 7, you will need to provide the whole file name (including the suffix) yourself!

You can also have comments (the line starts with #) and blank lines in rspamd-modules.conf - they are properly handled and not evaluated.

Adjusting Modules This Way

These simple commands are meant to give users the ability to easily alter modules and their options. As a consequence, they are not powerful enough to enable multi-line adjustments. If you need to do something more complex, we advise to do that manually!

"},{"location":"config/security/rspamd/#examples-advanced-configuration","title":"Examples & Advanced Configuration","text":""},{"location":"config/security/rspamd/#a-very-basic-configuration","title":"A Very Basic Configuration","text":"

You want to start using Rspamd? Rspamd is disabled by default, so you need to set the following environment variables:

ENABLE_RSPAMD=1\nENABLE_OPENDKIM=0\nENABLE_OPENDMARC=0\nENABLE_AMAVIS=0\nENABLE_SPAMASSASSIN=0\n

This will enable Rspamd and disable services you don't need when using Rspamd. Note that with this setup, the default DKIM signing that DMS provides does not work (as it is disabled)! To solve this issue, look at this subsection.

"},{"location":"config/security/rspamd/#adjusting-and-extending-the-very-basic-configuration","title":"Adjusting and Extending The Very Basic Configuration","text":"

Rspamd is running, but you want or need to adjust it?

  1. Say you want to be able to easily look at the frontend Rspamd provides on port 11334 (default) without the need to enter a password (maybe because you already provide authorization and authentication). You will need to adjust the controller worker: create a file called rspamd-modules.conf and add the line set-option-for-controller secure_ip \"0.0.0.0/0\". Place the file rspamd-modules.conf inside the directory on the host you mount to /tmp/docker-mailserver/ inside the container (in our documentation, we use docker-data/dms/config on the host for this purpose). And you're done! Note: this disables authentication on the website - make sure you know what you're doing!
  2. You additionally want to enable the auto-spam-learning for the Bayes module? No problem, just add another line to rspamd-modules.conf that looks like this: set-option-for-module classifier-bayes autolearn true.
  3. But the chartable module gets on your nerves? Just disable it by adding another line: disable-module chartable.
"},{"location":"config/security/rspamd/#dkim-signing","title":"DKIM Signing","text":"

By default, DMS offers no option to generate and configure signing e-mails with DKIM. This is because the parsing would be difficult. But don't worry: the process is relatively straightforward nevertheless. The official Rspamd documentation for the DKIM signing module is pretty good. Basically, you need to

  1. exec into the container
  2. Run a command similar to rspamadm dkim_keygen -s 'woosh' -b 2048 -d example.com -k example.private > example.txt, adjusted to your needs
  3. Make sure to then persists the files example.private and example.txt (created in step 2) in the container (for example with a Docker bind mount)
  4. Create a configuration for the DKIM signing module, i.e. a file called dkim_signing.conf that you mount to /etc/rspamd/local.d/ or /etc/rspamd/override.d/. We provide example configurations down below. We recommend mounting this file into the container as well (as described here); do not use rspamd-modules.conf for this purpose.
DKIM Signing Module Configuration Examples

A simple configuration could look like this:

# documentation: https://rspamd.com/doc/modules/dkim_signing.html\n\nenabled = true;\n\nsign_authenticated = true;\nsign_local = true;\n\nuse_domain = \"header\";\nuse_redis = false; # don't change unless Redis also provides the DKIM keys\nuse_esld = true;\ncheck_pubkey = true;\n\ndomain {\nexample.com {\npath = \"/path/to/example.private\";\nselector = \"woosh\";\n}\n}\n

If you have multiple domains and you want to sign with the modern ED25519 elliptic curve but also with RSA (you will likely want to have RSA as a fallback!):

# documentation: https://rspamd.com/doc/modules/dkim_signing.html\n\nenabled = true;\n\nsign_authenticated = true;\nsign_local = true;\n\nuse_domain = \"header\";\nuse_redis = false; # don't change unless Redis also provides the DKIM keys\nuse_esld = true;\ncheck_pubkey = true;\n\ndomain {\nexample.com {\nselectors [\n{\npath = \"/path/to/com.example.rsa.private\";\nselector = \"dkim-rsa\";\n},\n{\npath = /path/to/com.example.ed25519.private\";\nselector = \"dkim-ed25519\";\n}\n]\n}\nexample.org {\nselectors [\n{\npath = \"/path/to/org.example.rsa.private\";\nselector = \"dkim-rsa\";\n},\n{\npath = \"/path/to/org.example.ed25519.private\";\nselector = \"dkim-ed25519\";\n}\n]\n}\n}\n
"},{"location":"config/security/rspamd/#abusix-integration","title":"Abusix Integration","text":"

This subsection gives information about the integration of Abusix, \"a set of blocklists that work as an additional email security layer for your existing mail environment\". The setup is straight-forward and well documented:

  1. Create an account
  2. Retrieve your API key
  3. Navigate to the \"Getting Started\" documentation for Rspamd and follow the steps described there
  4. Make sure to change <APIKEY> to your private API key

We recommend mounting the files directly into the container, as they are rather big and not manageable with the modules script. If mounted to the correct location, Rspamd will automatically pick them up.

While Abusix can be integrated into Postfix, Postscreen and a multitude of other software, we recommend integrating Abusix only into a single piece of software running in your mail server - everything else would be excessive and wasting queries. Moreover, we recommend the integration into suitable filtering software and not Postfix itself, as software like Postscreen or Rspamd can properly evaluate the return codes and other configuration.

"},{"location":"config/security/ssl/","title":"Security | TLS (aka SSL)","text":"

There are multiple options to enable SSL (via SSL_TYPE):

  • Using letsencrypt (recommended)
  • Using Caddy
  • Using Traefik
  • Using self-signed certificates
  • Using your own certificates

After installation, you can test your setup with:

  • checktls.com
  • testssl.sh

Exposure of DNS labels through Certificate Transparency

All public Certificate Authorities (CAs) are required to log certificates they issue publicly via Certificate Transparency. This helps to better establish trust.

When using a public CA for certificates used in private networks, be aware that the associated DNS labels in the certificate are logged publicly and easily searchable. These logs are append only, you cannot redact this information.

You could use a wildcard certificate. This avoids accidentally leaking information to the internet, but keep in mind the potential security risks of wildcard certs.

"},{"location":"config/security/ssl/#the-fqdn","title":"The FQDN","text":"

An FQDN (Fully Qualified Domain Name) such as mail.example.com is required for docker-mailserver to function correctly, especially for looking up the correct SSL certificate to use.

  • mail.example.com will still use user@example.com as the mail address. You do not need a bare domain for that.
  • We usually discourage assigning a bare domain (When your DNS MX record does not point to a subdomain) to represent docker-mailserver. However, an FQDN of just example.com is also supported.
  • Internally, hostname -f will be used to retrieve the FQDN as configured in the below examples.
  • Wildcard certificates (eg: *.example.com) are supported for SSL_TYPE=letsencrypt. Your configured FQDN below may be mail.example.com, and your wildcard certificate provisioned to /etc/letsencrypt/live/example.com which will be checked as a fallback FQDN by docker-mailserver.

Setting the hostname correctly

Change mail.example.com below to your own FQDN.

# CLI:\ndocker run --hostname mail.example.com\n

or

# docker-compose.yml\nservices:\nmailserver:\nhostname: mail.example.com\n
"},{"location":"config/security/ssl/#provisioning-methods","title":"Provisioning methods","text":""},{"location":"config/security/ssl/#lets-encrypt-recommended","title":"Let's Encrypt (Recommended)","text":"

To enable Let's Encrypt for docker-mailserver, you have to:

  1. Get your certificate using the Let's Encrypt client Certbot.

  2. For your docker-mailserver container:

    • Add the environment variable SSL_TYPE=letsencrypt.
    • Mount your local letsencrypt folder as a volume to /etc/letsencrypt.

You don't have to do anything else. Enjoy!

Note

/etc/letsencrypt/live stores provisioned certificates in individual folders named by their FQDN.

Make sure that the entire folder is mounted to docker-mailserver as there are typically symlinks from /etc/letsencrypt/live/mail.example.com to /etc/letsencrypt/archive.

Example

Add these additions to the mailserver service in your docker-compose.yml:

services:\nmailserver:\nhostname: mail.example.com\nenvironment:\n- SSL_TYPE=letsencrypt\nvolumes:\n- /etc/letsencrypt:/etc/letsencrypt\n
"},{"location":"config/security/ssl/#example-using-docker-for-lets-encrypt","title":"Example using Docker for Let's Encrypt","text":"

Certbot provisions certificates to /etc/letsencrypt. Add a volume to store these, so that they can later be accessed by docker-mailserver container. You may also want to persist Certbot logs, just in case you need to troubleshoot.

  1. Getting a certificate is this simple! (Referencing: Certbot docker instructions and certonly --standalone mode):

    # Requires access to port 80 from the internet, adjust your firewall if needed.\ndocker run --rm -it \\\n-v \"${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/\" \\\n-v \"${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/\" \\\n-p 80:80 \\\ncertbot/certbot certonly --standalone -d mail.example.com\n

  2. Add a volume for docker-mailserver that maps the local certbot/certs/ folder to the container path /etc/letsencrypt/.

    Example

    Add these additions to the mailserver service in your docker-compose.yml:

    services:\nmailserver:\nhostname: mail.example.com\nenvironment:\n- SSL_TYPE=letsencrypt\nvolumes:\n- ./docker-data/certbot/certs/:/etc/letsencrypt\n

  3. The certificate setup is complete, but remember it will expire. Consider automating renewals.

Renewing Certificates

When running the above certonly --standalone snippet again, the existing certificate is renewed if it would expire within 30 days.

Alternatively, Certbot can look at all the certificates it manages, and only renew those nearing their expiry via the renew command:

# This will need access to port 443 from the internet, adjust your firewall if needed.\ndocker run --rm -it \\\n-v \"${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/\" \\\n-v \"${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/\" \\\n-p 80:80 \\\n-p 443:443 \\\ncertbot/certbot renew\n

This process can also be automated via cron or systemd timers.

Using a different ACME CA

Certbot does support alternative certificate providers via the --server option. In most cases you'll want to use the default Let's Encrypt.

"},{"location":"config/security/ssl/#example-using-certbot-dns-cloudflare-with-docker","title":"Example using certbot-dns-cloudflare with Docker","text":"

If you are unable get a certificate via the HTTP-01 (port 80) or TLS-ALPN-01 (port 443) challenge types, the DNS-01 challenge can be useful (this challenge can additionally issue wildcard certificates). This guide shows how to use the DNS-01 challenge with Cloudflare as your DNS provider.

Obtain a Cloudflare API token:

  1. Login into your Cloudflare dashboard.
  2. Navigate to the API Tokens page.

  3. Click \"Create Token\", and choose the Edit zone DNS template (Certbot requires the ZONE:DNS:Edit permission).

    Only include the necessary Zone resource configuration

    Be sure to configure \"Zone Resources\" section on this page to Include -> Specific zone -> <your zone here>.

    This restricts the API token to only this zone (domain) which is an important security measure.

  4. Store the API token you received in a file cloudflare.ini with content:

    dns_cloudflare_api_token = YOUR_CLOUDFLARE_TOKEN_HERE\n

  5. As this is sensitive data, you should restrict access to it with chmod 600 and chown 0:0.

  6. Store the file in a folder if you like, such as docker-data/certbot/secrets/.

  7. Your docker-compose.yml should include the following:

    services:\nmailserver:\nenvironments:\n# Set SSL certificate type.\n- SSL_TYPE=letsencrypt\nvolumes:\n# Mount the cert folder generated by Certbot into mail-server:\n- ./docker-data/certbot/certs/:/etc/letsencrypt/:ro\n\ncertbot-cloudflare:\nimage: certbot/dns-cloudflare:latest\ncommand: certonly --dns-cloudflare --dns-cloudflare-credentials /run/secrets/cloudflare-api-token -d mail.example.com\nvolumes:\n- ./docker-data/certbot/certs/:/etc/letsencrypt/\n- ./docker-data/certbot/logs/:/var/log/letsencrypt/\nsecrets:\n- cloudflare-api-token\n\n# Docs: https://docs.docker.com/engine/swarm/secrets/#use-secrets-in-compose\n# WARNING: In compose configs without swarm, the long syntax options have no effect,\n# Ensure that you properly `chmod 600` and `chown 0:0` the file on disk. Effectively treated as a bind mount.\nsecrets:\ncloudflare-api-token:\nfile: ./docker-data/certbot/secrets/cloudflare.ini\n

    Alternative using the docker run command (secrets feature is not available):

    docker run \\\n--volume \"${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/\" \\\n--volume \"${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/\" \\\n--volume \"${PWD}/docker-data/certbot/secrets/:/tmp/secrets/certbot/\"\ncertbot/dns-cloudflare \\\ncertonly --dns-cloudflare --dns-cloudflare-credentials /tmp/secrets/certbot/cloudflare.ini -d mail.example.com\n

  8. Run the service to provision a certificate:

    docker-compose run certbot-cloudflare\n

  9. You should see the following log output:

    Saving debug log to /var/log/letsencrypt/letsencrypt. log | Requesting a certificate for mail.example.com\nWaiting 10 seconds for DNS changes to propagate\nSuccessfully received certificate.\nCertificate is saved at: /etc/letsencrypt/live/mail.example.com/fullchain.pem\nKey is saved at: /etc/letsencrypt/live/mail.example.com/privkey.pem\nThis certificate expires on YYYY-MM-DD.\nThese files will be updated when the certificate renews.\nNEXT STEPS:\n- The certificate will need to be renewed before it expires. Certbot can automatically renew the certificate in background, but you may need to take steps to enable that functionality. See https://certbot.org/renewal structions.\n

After completing the steps above, your certificate should be ready to use.

Renewing a certificate (Optional)

We've only demonstrated how to provision a certificate, but it will expire in 90 days and need to be renewed before then.

In the following example, add a new service (certbot-cloudflare-renew) into docker-compose.yml that will handle certificate renewals:

services:\ncertbot-cloudflare-renew:\nimage: certbot/dns-cloudflare:latest\ncommand: renew --dns-cloudflare --dns-cloudflare-credentials /run/secrets/cloudflare-api-token\nvolumes:\n- ./docker-data/certbot/certs/:/etc/letsencrtypt/\n- ./docker-data/certbot/logs/:/var/log/letsencrypt/\nsecrets:\n- cloudflare-api-token\n

You can manually run this service to renew the cert within 90 days:

docker-compose run certbot-cloudflare-renew\n

You should see the following output (The following log was generated with --dry-run options)

Saving debug log to /var/log/letsencrypt/letsencrypt.log\n\n- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\nProcessing /etc/letsencrypt/renewal/mail.example.com.conf\n- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\nAccount registered.\nSimulating renewal of an existing certificate for mail.example.com\nWaiting 10 seconds for DNS changes to propagate\n\n- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\nCongratulations, all simulated renewals succeeded:\n  /etc/letsencrypt/live/mail.example.com/fullchain.pem (success)\n- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\n

It is recommended to automate this renewal via a task scheduler like a systemd timer or in crontab (crontab example: Checks every day if the certificate should be renewed)

0 0 * * * docker-compose -f PATH_TO_YOUR_DOCKER_COMPOSE_YML up certbot-cloudflare-renew\n
"},{"location":"config/security/ssl/#example-using-nginx-proxy-and-acme-companion-with-docker","title":"Example using nginx-proxy and acme-companion with Docker","text":"

If you are running a web server already, port 80 will be in use which Certbot requires. You could use the Certbot --webroot feature, but it is more common to leverage a reverse proxy that manages the provisioning and renewal of certificates for your services automatically.

In the following example, we show how docker-mailserver can be run alongside the docker containers nginx-proxy and acme-companion (Referencing: acme-companion documentation):

  1. Start the reverse proxy (nginx-proxy):

    docker run --detach \\\n--name nginx-proxy \\\n--restart always \\\n--publish 80:80 \\\n--publish 443:443 \\\n--volume \"${PWD}/docker-data/nginx-proxy/html/:/usr/share/nginx/html/\" \\\n--volume \"${PWD}/docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/\" \\\n--volume \"${PWD}/docker-data/acme-companion/certs/:/etc/nginx/certs/:ro\" \\\n--volume '/var/run/docker.sock:/tmp/docker.sock:ro' \\\nnginxproxy/nginx-proxy\n

  2. Then start the certificate provisioner (acme-companion), which will provide certificates to nginx-proxy:

    # Inherit `nginx-proxy` volumes via `--volumes-from`, but make `certs/` writeable:\ndocker run --detach \\\n--name nginx-proxy-acme \\\n--restart always \\\n--volumes-from nginx-proxy \\\n--volume \"${PWD}/docker-data/acme-companion/certs/:/etc/nginx/certs/:rw\" \\\n--volume \"${PWD}/docker-data/acme-companion/acme-state/:/etc/acme.sh/\" \\\n--volume '/var/run/docker.sock:/var/run/docker.sock:ro' \\\n--env 'DEFAULT_EMAIL=admin@example.com' \\\nnginxproxy/acme-companion\n

  3. Start the rest of your web server containers as usual.

  4. Start a dummy container to provision certificates for your FQDN (eg: mail.example.com). acme-companion will detect the container and generate a Let's Encrypt certificate for your domain, which can be used by docker-mailserver:

    docker run --detach \\\n--name webmail \\\n--env 'VIRTUAL_HOST=mail.example.com' \\\n--env 'LETSENCRYPT_HOST=mail.example.com' \\\n--env 'LETSENCRYPT_EMAIL=admin@example.com' \\\nnginx\n

    You may want to add --env LETSENCRYPT_TEST=true to the above while testing, to avoid the Let's Encrypt certificate generation rate limits.

  5. Make sure your mount path to the letsencrypt certificates directory is correct. Edit your docker-compose.yml for the mailserver service to have volumes added like below:

    volumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n- ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro\n

  6. Then from the docker-compose.yml project directory, run: docker-compose up -d mailserver.

"},{"location":"config/security/ssl/#example-using-nginx-proxy-and-acme-companion-with-docker-compose","title":"Example using nginx-proxy and acme-companion with docker-compose","text":"

The following example is the basic setup you need for using nginx-proxy and acme-companion with docker-mailserver (Referencing: acme-companion documentation):

Example: docker-compose.yml

You should have an existing docker-compose.yml with a mailserver service. Below are the modifications to add for integrating with nginx-proxy and acme-companion services:

services:\n# Add the following `environment` and `volumes` to your existing `mailserver` service:\nmailserver:\nenvironment:\n# SSL_TYPE:         Uses the `letsencrypt` method to find mounted certificates.\n# VIRTUAL_HOST:     The FQDN that `nginx-proxy` will configure itself to handle for HTTP[S] connections.\n# LETSENCRYPT_HOST: The FQDN for a certificate that `acme-companion` will provision and renew.\n- SSL_TYPE=letsencrypt\n- VIRTUAL_HOST=mail.example.com\n- LETSENCRYPT_HOST=mail.example.com\nvolumes:\n- ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro\n\n# If you don't yet have your own `nginx-proxy` and `acme-companion` setup,\n# here is an example you can use:\nreverse-proxy:\nimage: nginxproxy/nginx-proxy\ncontainer_name: nginx-proxy\nrestart: always\nports:\n# Port  80: Required for HTTP-01 challenges to `acme-companion`.\n# Port 443: Only required for containers that need access over HTTPS. TLS-ALPN-01 challenge not supported.\n- \"80:80\"\n- \"443:443\"\nvolumes:\n# `certs/`:      Managed by the `acme-companion` container (_read-only_).\n# `docker.sock`: Required to interact with containers via the Docker API.\n- ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/\n- ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/\n- ./docker-data/acme-companion/certs/:/etc/nginx/certs/:ro\n- /var/run/docker.sock:/tmp/docker.sock:ro\n\nacme-companion:\nimage: nginxproxy/acme-companion\ncontainer_name: nginx-proxy-acme\nrestart: always\nenvironment:\n# Only docker-compose v2 supports: `volumes_from: [nginx-proxy]`,\n# reference the _reverse-proxy_ `container_name` here:\n- NGINX_PROXY_CONTAINER=nginx-proxy\nvolumes:\n# `html/`:       Write ACME HTTP-01 challenge files that `nginx-proxy` will serve.\n# `vhost.d/`:    To enable web access via `nginx-proxy` to HTTP-01 challenge files.\n# `certs/`:      To store certificates and private keys.\n# `acme-state/`: To persist config and state for the ACME provisioner (`acme.sh`).\n# `docker.sock`: Required to interact with containers via the Docker API.\n- ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/\n- ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/\n- ./docker-data/acme-companion/certs/:/etc/nginx/certs/:rw\n- ./docker-data/acme-companion/acme-state/:/etc/acme.sh/\n- /var/run/docker.sock:/var/run/docker.sock:ro\n

Optional ENV vars worth knowing about

Per container ENV that acme-companion will detect to override default provisioning settings:

  • LETSENCRYPT_TEST=true: Recommended during initial setup. Otherwise the default production endpoint has a rate limit of 5 duplicate certificates per week. Overrides ACME_CA_URI to use the Let's Encrypt staging endpoint.
  • LETSENCRYPT_EMAIL: For when you don't use DEFAULT_EMAIL on acme-companion, or want to assign a different email contact for this container.
  • LETSENCRYPT_KEYSIZE: Allows you to configure the type (RSA or ECDSA) and size of the private key for your certificate. Default is RSA 4096.
  • LETSENCRYPT_RESTART_CONTAINER=true: When the certificate is renewed, the entire container will be restarted to ensure the new certificate is used.

acme-companion ENV for default settings that apply to all containers using LETSENCRYPT_HOST:

  • DEFAULT_EMAIL: An email address that the CA (eg: Let's Encrypt) can contact you about expiring certificates, failed renewals, or for account recovery. You may want to use an email address not handled by your mail-server to ensure deliverability in the event your mail-server breaks.
  • CERTS_UPDATE_INTERVAL: If you need to adjust the frequency to check for renewals. 3600 seconds (1 hour) by default.
  • DEBUG=1: Should be helpful when troubleshooting provisioning issues from acme-companion logs.
  • ACME_CA_URI: Useful in combination with CA_BUNDLE to use a private CA. To change the default Let's Encrypt endpoint to the staging endpoint, use https://acme-staging-v02.api.letsencrypt.org/directory.
  • CA_BUNDLE: If you want to use a private CA instead of Let's Encrypt.

Alternative to required ENV on mailserver service

While you will still need both nginx-proxy and acme-companion containers, you can manage certificates without adding ENV vars to containers. Instead the ENV is moved into a file and uses the acme-companion feature Standalone certificates.

This requires adding another shared volume between nginx-proxy and acme-companion:

services:\nreverse-proxy:\nvolumes:\n- ./docker-data/nginx-proxy/conf.d/:/etc/nginx/conf.d/\n\nacme-companion:\nvolumes:\n- ./docker-data/nginx-proxy/conf.d/:/etc/nginx/conf.d/\n- ./docker-data/acme-companion/standalone.sh:/app/letsencrypt_user_data:ro\n

acme-companion mounts a shell script (standalone.sh), which defines variables to customize certificate provisioning:

# A list IDs for certificates to provision:\nLETSENCRYPT_STANDALONE_CERTS=('mail')\n\n# Each ID inserts itself into the standard `acme-companion` supported container ENV vars below.\n# The LETSENCRYPT_<ID>_HOST var is a list of FQDNs to provision a certificate for as the SAN field:\nLETSENCRYPT_mail_HOST=('mail.example.com')\n\n# Optional variables:\nLETSENCRYPT_mail_TEST=true\nLETSENCRYPT_mail_EMAIL='admin@example.com'\n# RSA-4096 => `4096`, ECDSA-256 => `ec-256`:\nLETSENCRYPT_mail_KEYSIZE=4096\n

Unlike with the equivalent ENV for containers, changes to this file will not be detected automatically. You would need to wait until the next renewal check by acme-companion (every hour by default), restart acme-companion, or manually invoke the service loop:

docker exec nginx-proxy-acme /app/signal_le_service

"},{"location":"config/security/ssl/#example-using-lets-encrypt-certificates-with-a-synology-nas","title":"Example using Let's Encrypt Certificates with a Synology NAS","text":"

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.

Amongst other things, you can use these to secure your mail-server. DSM locates the generated certificates in a folder below /usr/syno/etc/certificate/_archive/.

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 docker-compose.yml declaration file:

volumes:\n- /usr/syno/etc/certificate/_archive/<your-folder>/:/tmp/dms/custom-certs/\nenvironment:\n- SSL_TYPE=manual\n- SSL_CERT_PATH=/tmp/dms/custom-certs/fullchain.pem\n- SSL_KEY_PATH=/tmp/dms/custom-certs/privkey.pem\n

DSM-generated letsencrypt certificates get auto-renewed every three months.

"},{"location":"config/security/ssl/#caddy","title":"Caddy","text":"

For Caddy v2 you can specify the key_type in your server's global settings, which would end up looking something like this if you're using a Caddyfile:

{\n  debug\n  admin localhost:2019\n  http_port 80\n  https_port 443\n  default_sni example.com\n  key_type rsa4096\n}\n

If you are instead using a json config for Caddy v2, you can set it in your site's TLS automation policies:

Caddy v2 JSON example snippet 
{\n\"apps\": {\n\"http\": {\n\"servers\": {\n\"srv0\": {\n\"listen\": [\n\":443\"\n],\n\"routes\": [\n{\n\"match\": [\n{\n\"host\": [\n\"mail.example.com\",\n]\n}\n],\n\"handle\": [\n{\n\"handler\": \"subroute\",\n\"routes\": [\n{\n\"handle\": [\n{\n\"body\": \"\",\n\"handler\": \"static_response\"\n}\n]\n}\n]\n}\n],\n\"terminal\": true\n},\n]\n}\n}\n},\n\"tls\": {\n\"automation\": {\n\"policies\": [\n{\n\"subjects\": [\n\"mail.example.com\",\n],\n\"key_type\": \"rsa2048\",\n\"issuer\": {\n\"email\": \"admin@example.com\",\n\"module\": \"acme\"\n}\n},\n{\n\"issuer\": {\n\"email\": \"admin@example.com\",\n\"module\": \"acme\"\n}\n}\n]\n}\n}\n}\n}\n

The generated certificates can then be mounted:

volumes:\n- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem\n- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem\n
"},{"location":"config/security/ssl/#traefik-v2","title":"Traefik v2","text":"

Traefik is an open-source application proxy using the ACME protocol. Traefik can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc. We strongly recommend to use Traefik's major version 2.

Traefik's storage format is natively supported if the acme.json store is mounted into the container at /etc/letsencrypt/acme.json. The file is also monitored for changes and will trigger a reload of the mail services (Postfix and Dovecot).

Wildcard certificates are supported. If your FQDN is mail.example.com and your wildcard certificate is *.example.com, add the ENV: SSL_DOMAIN=example.com.

The mail-server will select it's certificate from acme.json checking these ENV for a matching FQDN (in order of priority):

  1. ${SSL_DOMAIN}
  2. ${HOSTNAME}
  3. ${DOMAINNAME}

This setup only comes with one caveat: The domain has to be configured on another service for Traefik to actually request it from Let's Encrypt, i.e. Traefik will not issue a certificate without a service / router demanding it.

Example Code

Here is an example setup for docker-compose:

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\nhostname: mail.example.com\nvolumes:\n- ./docker-data/traefik/acme.json:/etc/letsencrypt/acme.json:ro\nenvironment:\nSSL_TYPE: letsencrypt\nSSL_DOMAIN: mail.example.com\n# for a wildcard certificate, use\n# SSL_DOMAIN: example.com\n\nreverse-proxy:\nimage: docker.io/traefik:latest #v2.5\ncontainer_name: docker-traefik\nports:\n- \"80:80\"\n- \"443:443\"\ncommand:\n- --providers.docker\n- --entrypoints.http.address=:80\n- --entrypoints.http.http.redirections.entryPoint.to=https\n- --entrypoints.http.http.redirections.entryPoint.scheme=https\n- --entrypoints.https.address=:443\n- --entrypoints.https.http.tls.certResolver=letsencrypt\n- --certificatesresolvers.letsencrypt.acme.email=admin@example.com\n- --certificatesresolvers.letsencrypt.acme.storage=/acme.json\n- --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=http\nvolumes:\n- ./docker-data/traefik/acme.json:/acme.json\n- /var/run/docker.sock:/var/run/docker.sock:ro\n\nwhoami:\nimage: docker.io/traefik/whoami:latest\nlabels:\n- \"traefik.http.routers.whoami.rule=Host(`mail.example.com`)\"\n
"},{"location":"config/security/ssl/#self-signed-certificates","title":"Self-Signed Certificates","text":"

Warning

Use self-signed certificates only for testing purposes!

This feature requires you to provide the following files into your docker-data/dms/config/ssl/ directory (internal location: /tmp/docker-mailserver/ssl/):

  • <FQDN>-key.pem
  • <FQDN>-cert.pem
  • demoCA/cacert.pem

Where <FQDN> is the FQDN you've configured for your docker-mailserver container.

Add SSL_TYPE=self-signed to your docker-mailserver environment variables. Postfix and Dovecot will be configured to use the provided certificate (.pem files above) during container startup.

"},{"location":"config/security/ssl/#generating-a-self-signed-certificate","title":"Generating a self-signed certificate","text":"

One way to generate self-signed certificates is with Smallstep's step CLI. This is exactly what docker-mailserver does for creating test certificates.

For example with the FQDN mail.example.test, you can generate the required files by running:

#! /bin/sh\nmkdir -p demoCA\n\nstep certificate create \"Smallstep Root CA\" \"demoCA/cacert.pem\" \"demoCA/cakey.pem\" \\\n--no-password --insecure \\\n--profile root-ca \\\n--not-before \"2021-01-01T00:00:00+00:00\" \\\n--not-after \"2031-01-01T00:00:00+00:00\" \\\n--san \"example.test\" \\\n--san \"mail.example.test\" \\\n--kty RSA --size 2048\n\nstep certificate create \"Smallstep Leaf\" mail.example.test-cert.pem mail.example.test-key.pem \\\n--no-password --insecure \\\n--profile leaf \\\n--ca \"demoCA/cacert.pem\" \\\n--ca-key \"demoCA/cakey.pem\" \\\n--not-before \"2021-01-01T00:00:00+00:00\" \\\n--not-after \"2031-01-01T00:00:00+00:00\" \\\n--san \"example.test\" \\\n--san \"mail.example.test\" \\\n--kty RSA --size 2048\n

If you'd rather not install the CLI tool locally to run the step commands above; you can save the script above to a file such as generate-certs.sh (and make it executable chmod +x generate-certs.sh) in a directory that you want the certs to be placed (eg: docker-data/dms/custom-certs/), then use docker to run that script in a container:

# '--user' is to keep ownership of the files written to\n# the local volume to use your systems User and Group ID values.\ndocker run --rm -it \\\n--user \"$(id -u):$(id -g)\" \\\n--volume \"${PWD}/docker-data/dms/custom-certs/:/tmp/step-ca/\" \\\n--workdir \"/tmp/step-ca/\" \\\n--entrypoint \"/tmp/step-ca/generate-certs.sh\" \\\nsmallstep/step-ca\n
"},{"location":"config/security/ssl/#bring-your-own-certificates","title":"Bring Your Own Certificates","text":"

You can also provide your own certificate files. Add these entries to your docker-compose.yml:

volumes:\n- ./docker-data/dms/custom-certs/:/tmp/dms/custom-certs/:ro\nenvironment:\n- SSL_TYPE=manual\n# Values should match the file paths inside the container:\n- SSL_CERT_PATH=/tmp/dms/custom-certs/public.crt\n- SSL_KEY_PATH=/tmp/dms/custom-certs/private.key\n

This will mount the path where your certificate files reside locally into the read-only container folder: /tmp/dms/custom-certs.

The local and internal paths may be whatever you prefer, so long as both SSL_CERT_PATH and SSL_KEY_PATH point to the correct internal file paths. The certificate files may also be named to your preference, but should be PEM encoded.

SSL_ALT_CERT_PATH and SSL_ALT_KEY_PATH are additional ENV vars to support a 2nd certificate as a fallback. Commonly known as hybrid or dual certificate support. This is useful for using a modern ECDSA as your primary certificate, and RSA as your fallback for older connections. They work in the same manner as the non-ALT versions.

Info

You may have to restart docker-mailserver once the certificates change.

"},{"location":"config/security/ssl/#testing-a-certificate-is-valid","title":"Testing a Certificate is Valid","text":"

  • From your host:

    docker exec mailserver openssl s_client \\\n-connect 0.0.0.0:25 \\\n-starttls smtp \\\n-CApath /etc/ssl/certs/\n

  • Or:

    docker exec mailserver openssl s_client \\\n-connect 0.0.0.0:143 \\\n-starttls imap \\\n-CApath /etc/ssl/certs/\n

And you should see the certificate chain, the server certificate and: Verify return code: 0 (ok)

In addition, to verify certificate dates:

docker exec mailserver openssl s_client \\\n-connect 0.0.0.0:25 \\\n-starttls smtp \\\n-CApath /etc/ssl/certs/ \\\n2>/dev/null | openssl x509 -noout -dates\n
"},{"location":"config/security/ssl/#plain-text-access","title":"Plain-Text Access","text":"

Warning

Not recommended for purposes other than testing.

Add this to docker-data/dms/config/dovecot.cf:

ssl = yes\ndisable_plaintext_auth=no\n

These options in conjunction mean:

  • SSL/TLS is offered to the client, but the client isn't required to use it.
  • The client is allowed to login with plaintext authentication even when SSL/TLS isn't enabled on the connection.
  • This is insecure, because the plaintext password is exposed to the internet.
"},{"location":"config/security/ssl/#importing-certificates-obtained-via-another-source","title":"Importing Certificates Obtained via Another Source","text":"

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: external certificate import script.

This is a community contributed script, and in most cases you will have better support via our Change Detection service (automatic for SSL_TYPE of manual and letsencrypt) - Unless you're using LDAP which disables the service.

Script Compatibility

  • Relies on private filepaths /etc/dms/tls/cert and /etc/dms/tls/key intended for internal use only.
  • Only supports hard-coded fullchain.key + privkey.pem as your mounted file names. That may not align with your provisioning method.
  • No support for ALT fallback certificates (for supporting dual/hybrid, RSA + ECDSA).

The steps to follow are these:

  1. Transfer the new certificates to ./docker-data/dms/custom-certs/ (volume mounted to: /tmp/ssl/)
  2. You should provide fullchain.key and privkey.pem
  3. Place the script in ./docker-data/dms/config/ (volume mounted to: /tmp/docker-mailserver/)
  4. Make the script executable (chmod +x tomav-renew-certs.sh)
  5. Run the script: docker exec mailserver /tmp/docker-mailserver/tomav-renew-certs.sh

If an error occurs the script will inform you. If not you will see both postfix and dovecot restart.

After the certificates have been loaded you can check the certificate:

openssl s_client \\\n-servername mail.example.com \\\n-connect 192.168.0.72:465 \\\n2>/dev/null | openssl x509\n\n# or\n\nopenssl s_client \\\n-servername mail.example.com \\\n-connect mail.example.com:465 \\\n2>/dev/null | openssl x509\n

Or you can check how long the new certificate is valid with commands like:

export SITE_URL=\"mail.example.com\"\nexport SITE_IP_URL=\"192.168.0.72\" # can also use `mail.example.com`\nexport SITE_SSL_PORT=\"993\" # imap port dovecot\n\n##works: check if certificate will expire in two weeks\n#2 weeks is 1209600 seconds\n#3 weeks is 1814400\n#12 weeks is 7257600\n#15 weeks is 9072000\n\ncertcheck_2weeks=`openssl s_client -connect ${SITE_IP_URL}:${SITE_SSL_PORT} \\\n-servername ${SITE_URL} 2> /dev/null | openssl x509 -noout -checkend 1209600`\n\n####################################\n#notes: output could be either:\n#Certificate will not expire\n#Certificate will expire\n####################\n

What does the script that imports the certificates do:

  1. Check if there are new certs in the internal container folder: /tmp/ssl.
  2. Check with the ssl cert fingerprint if they differ from the current certificates.
  3. If so it will copy the certs to the right places.
  4. And restart postfix and dovecot.

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:

# This script is run inside docker-mailserver via 'docker exec ...', using the 'mail' command to send alerts.\n## code below will alert if certificate expires in less than two weeks\n## please adjust varables!\n## make sure the 'mail -s' command works! Test!\n\nexport SITE_URL=\"mail.example.com\"\nexport SITE_IP_URL=\"192.168.2.72\" # can also use `mail.example.com`\nexport SITE_SSL_PORT=\"993\" # imap port dovecot\n# Below can be from a different domain; like your personal email, not handled by this docker-mailserver:\nexport ALERT_EMAIL_ADDR=\"external-account@gmail.com\"\n\ncertcheck_2weeks=`openssl s_client -connect ${SITE_IP_URL}:${SITE_SSL_PORT} \\\n-servername ${SITE_URL} 2> /dev/null | openssl x509 -noout -checkend 1209600`\n\n####################################\n#notes: output can be\n#Certificate will not expire\n#Certificate will expire\n####################\n\n#echo \"certcheck 2 weeks gives $certcheck_2weeks\"\n\n##automated check you might run by cron or something\n## does the certificate expire within two weeks?\n\nif [ \"$certcheck_2weeks\" = \"Certificate will not expire\" ]; then\necho \"all is well, certwatch 2 weeks says $certcheck_2weeks\"\nelse\necho \"Cert seems to be expiring pretty soon, within two weeks: $certcheck_2weeks\"\necho \"we will send an alert email and log as well\"\nlogger Certwatch: cert $SITE_URL will expire in two weeks\n    echo \"Certwatch: cert $SITE_URL will expire in two weeks\" | mail -s \"cert $SITE_URL expires in two weeks \" $ALERT_EMAIL_ADDR\nfi\n
"},{"location":"config/security/ssl/#custom-dh-parameters","title":"Custom DH Parameters","text":"

By default docker-mailserver uses ffdhe4096 from IETF RFC 7919. These are standardized pre-defined DH groups and the only available DH groups for TLS 1.3. It is discouraged to generate your own DH parameters as it is often less secure.

Despite this, if you must use non-standard DH parameters or you would like to swap ffdhe4096 for a different group (eg ffdhe2048); Add your own PEM encoded DH params file via a volume to /tmp/docker-mailserver/dhparams.pem. This will replace DH params for both Dovecot and Postfix services during container startup.

"},{"location":"config/security/understanding-the-ports/","title":"Security | Understanding the Ports","text":""},{"location":"config/security/understanding-the-ports/#quick-reference","title":"Quick Reference","text":"

Prefer ports with Implicit TLS ports, they're more secure than ports using Explicit TLS, and if you use a Reverse Proxy should be less hassle.

"},{"location":"config/security/understanding-the-ports/#overview-of-email-ports","title":"Overview of Email Ports","text":"Protocol Explicit TLS1 Implicit TLS Purpose Enabled by Default ESMTP 25 N/A Transfer2 Yes ESMTP 587 4653 Submission Yes POP3 110 995 Retrieval No IMAP4 143 993 Retrieval Yes
  1. A connection may be secured over TLS when both ends support STARTTLS. On ports 110, 143 and 587, docker-mailserver will reject a connection that cannot be secured. Port 25 is required to support insecure connections.
  2. Receives email, docker-mailserver additionally filters for spam and viruses. For submitting email to the server to be sent to third-parties, you should prefer the submission ports (465, 587) - which require authentication. Unless a relay host is configured (eg: SendGrid), outgoing email will leave the server via port 25 (thus outbound traffic must not be blocked by your provider or firewall).
  3. A submission port since 2018 (RFC 8314).
Beware of outdated advice on port 465

There is a common misconception of this port due to it's history detailed by various communities and blogs articles on the topic (including by popular mail relay services).

Port 465 was briefly assigned the role of SMTPS in 1997 as an secure alternative to Port 25 between MTA exchanges. Then RFC 2487 (STARTTLS) while still in a draft status in late 1998 had IANA revoke the SMTPS assignment. The draft history was modified to exclude all mention of port 465 and SMTPS.

In 2018 RFC 8314 was published which revives Port 465 as an Implicit TLS alternative to Port 587 for mail submission. It details very clearly that gaining adoption of 465 as the preferred port will take time. IANA reassigned port 465 as the submissions service. Any unofficial usage as SMTPS is legacy and has been for over two decades.

Understand that port 587 is more broadly supported due to this history and that lots of software in that time has been built or configured with that port in mind. STARTTLS is known to have various CVEs discovered even in recent years, do not be misled by any advice implying it should be preferred over implicit TLS. Trust in more official sources, such as the config Postfix has which acknowledges the submissions port (465).

"},{"location":"config/security/understanding-the-ports/#what-ports-should-i-use-smtp","title":"What Ports Should I Use? (SMTP)","text":"
flowchart LR\n    subgraph your-server [\"Your Server\"]\n        in_25(25) --> server\n        in_465(465) --> server\n        server((\"docker-mailserver<br/>hello@world.com\"))\n        server --- out_25(25)\n        server --- out_465(465)\n    end\n\n    third-party(\"Third-party<br/>(sending you email)\") ---|\"Receive email for<br/>hello@world.com\"| in_25\n\n    subgraph clients [\"Clients (MUA)\"]\n        mua-client(Thunderbird,<br/>Webmail,<br/>Mutt,<br/>etc)\n        mua-service(Backend software<br/>on another server)\n    end\n    clients ---|\"Send email as<br/>hello@world.com\"| in_465\n\n    out_25(25) -->|\"Direct<br/>Delivery\"| tin_25\n    out_465(465) --> relay(\"MTA<br/>Relay Server\") --> tin_25(25)\n\n    subgraph third-party-server[\"Third-party Server\"]\n        third-party-mta(\"MTA<br/>friend@example.com\")\n        tin_25(25) --> third-party-mta\n    end
"},{"location":"config/security/understanding-the-ports/#inbound-traffic-on-the-left","title":"Inbound Traffic (On the left)","text":"

Mail arriving at your server will be processed and stored in a mailbox, or sent outbound to another mail server.

  • Port 25:
    • Think of this like a physical mailbox, anyone can deliver mail to you here. Typically most mail is delivered to you on this port. -docker-mailserver will actively filter email delivered on this port for spam or viruses, and refuse mail from known bad sources.
    • Connections to this port may be secure through STARTTLS, but is not mandatory as mail is allowed to arrive via an unencrypted connection.
    • It is possible for internal clients to submit mail to be sent outbound (without requiring authentication), but that is discouraged. Prefer the submission ports.
  • Port 465 and 587:
    • This is the equivalent of a post office box where you would send email to be delivered on your behalf (docker-mailserver is that metaphorical post office, aka the MTA).
    • These two ports are known as the submission ports, they enable mail to be sent outbound to another MTA (eg: Outlook or Gmail) but require authentication via a mail account.
    • For inbound traffic, this is relevant when you send mail from your MUA (eg: ThunderBird). It's also used when docker-mailserver is configured as a mail relay, or when you have a service sending transactional mail (eg: order confirmations, password resets, notifications) through docker-mailserver.
    • Prefer port 465 over port 587, as 465 provides Implicit TLS.

Note

When submitting mail (inbound) to be sent (outbound), this involves two separate connections to negotiate and secure. There may be additional intermediary connections which docker-mailserver is not involved in, and thus unable to ensure encrypted transit throughout delivery.

"},{"location":"config/security/understanding-the-ports/#outbound-traffic-on-the-right","title":"Outbound Traffic (On the Right)","text":"

Mail being sent from your server is either being relayed through another MTA (eg: SendGrid), or direct to an MTA responsible for an email address (eg: Gmail).

  • Port 25:
    • As most MTA use port 25 to receive inbound mail, when no authenticated relay is involved this is the outbound port used.
    • Outbound traffic on this port is often blocked by service providers (eg: VPS, ISP) to prevent abuse by spammers. If the port cannot be unblocked, you will need to relay outbound mail through a service to send on your behalf.
  • Port 465 and 587:
    • Submission ports for outbound traffic establish trust to forward mail through a third-party relay service. This requires authenticating to an account on the relay service. The relay will then deliver the mail through port 25 on your behalf.
    • These are the two typical ports used, but smart hosts like SendGrid often document support for additional non-standard ports as alternatives if necessary.
    • Usually you'll only use these outbound ports for relaying. It is possible to deliver directly to the relevant MTA for email address, but requires having credentials for each MTA.

Tip

docker-mailserver can function as a relay too, but professional relay services have a trusted reputation (which increases success of delivery).

An MTA with low reputation can affect if mail is treated as junk, or even rejected.

Note

At best, you can only ensure a secure connection between the MTA you directly connect to. The receiving MTA may relay that mail to another MTA (and so forth), each connection may not be enforcing TLS.

"},{"location":"config/security/understanding-the-ports/#explicit-vs-implicit-tls","title":"Explicit vs Implicit TLS","text":""},{"location":"config/security/understanding-the-ports/#explicit-tls-aka-opportunistic-tls-opt-in-encryption","title":"Explicit TLS (aka Opportunistic TLS) - Opt-in Encryption","text":"

Communication on these ports begin in cleartext. Upgrading to an encrypted connection must be requested explicitly through the STARTTLS protocol and successfully negotiated.

Sometimes a reverse-proxy is involved, but is misconfigured or lacks support for the STARTTLS negotiation to succeed.

Note

  • By default, docker-mailserver is configured to reject connections that fail to establish a secure connection (when authentication is required), rather than allow an insecure connection.
  • Port 25 does not require authentication. If STARTTLS is unsuccessful, mail can be received over an unencrypted connection. You can better secure this port between trusted parties with the addition of MTA-STS, STARTTLS Policy List, DNSSEC and DANE.

Warning

STARTTLS continues to have vulnerabilities found (Nov 2021 article), as per RFC 8314 (Section 4.1) you are encouraged to prefer Implicit TLS where possible.

Support for STARTTLS is not always implemented correctly, which can lead to leaking credentials (like a client sending too early) prior to a TLS connection being established. Third-parties such as some ISPs have also been known to intercept the STARTTLS exchange, modifying network traffic to prevent establishing a secure connection.

"},{"location":"config/security/understanding-the-ports/#implicit-tls-enforced-encryption","title":"Implicit TLS - Enforced Encryption","text":"

Communication on these ports are always encrypted (enforced, thus implicit), avoiding the potential risks with STARTTLS (Explicit TLS).

While Explicit TLS can provide the same benefit (when STARTTLS is successfully negotiated), Implicit TLS more reliably avoids concerns with connection manipulation and compatibility.

"},{"location":"config/security/understanding-the-ports/#security","title":"Security","text":"

Todo

This section should provide any related configuration advice, and probably expand on and link to resources about DANE, DNSSEC, MTA-STS and STARTTLS Policy list, with advice on how to configure/setup these added security layers.

Todo

A related section or page on ciphers used may be useful, although less important for users to be concerned about.

"},{"location":"config/security/understanding-the-ports/#tls-connections-for-a-mail-server-compared-to-web-browsers","title":"TLS connections for a Mail-Server, compared to web browsers","text":"

Unlike with HTTP where a web browser client communicates directly with the server providing a website, a secure TLS connection as discussed below does not provide the equivalent safety that HTTPS does when the transit of email (receiving or sending) is sent through third-parties, as the secure connection is only between two machines, any additional machines (MTAs) between the MUA and the MDA depends on them establishing secure connections between one another successfully.

Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a cleartext connection through interception.

"},{"location":"contributing/general/","title":"Contributing | General Information","text":""},{"location":"contributing/general/#coding-style","title":"Coding Style","text":"

When refactoring, writing or altering scripts or other files, adhere to these rules:

  1. Adjust your style of coding to the style that is already present! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all scripts consistent.
  2. Use shellcheck to check your scripts! Your contributions are checked by GitHub Actions too, so you will need to do this. You can lint your work with make lint to check against all targets.
  3. Use the provided .editorconfig file.
  4. Use /bin/bash instead of /bin/sh in scripts
"},{"location":"contributing/general/#documentation","title":"Documentation","text":"

You will need to have Docker installed. Navigate into the docs/ directory. Then run:

docker run --rm -it -p 8000:8000 -v \"${PWD}:/docs\" squidfunk/mkdocs-material\n

This serves the documentation on your local machine on port 8000. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result.

"},{"location":"contributing/issues-and-pull-requests/","title":"Contributing | Issues and Pull Requests","text":"

This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation.

"},{"location":"contributing/issues-and-pull-requests/#opening-an-issue","title":"Opening an Issue","text":"

Attention

Before opening an issue, read the README carefully, study the docs for your version (maybe latest), the Postfix/Dovecot documentation and your search engine you trust. The issue tracker is not meant to be used for unrelated questions!

When opening an issue, please provide details use case to let the community reproduce your problem. Please start docker-mailserver with the environment variable LOG_LEVEL set to debug or trace and paste the output into the issue.

Attention

Use the issue templates to provide the necessary information. Issues which do not use these templates are not worked on and closed.

By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution.

Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and comply with the rules.

"},{"location":"contributing/issues-and-pull-requests/#pull-requests","title":"Pull Requests","text":"

Motivation

You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results.

"},{"location":"contributing/issues-and-pull-requests/#submit-a-pull-request","title":"Submit a Pull-Request","text":"

The development workflow is the following:

  1. Fork the project and clone your fork with git clone --recurse-submodules ... or run git submodule update --init --recursive after you cloned your fork
  2. Write the code that is needed :D
  3. Add integration tests if necessary
  4. Prepare your environment and run linting and tests
  5. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the ENV documentation) and add your changes the changelog under the \"Unreleased\" section
  6. Commit (and sign your commit), push and create a pull-request to merge into master. Please use the pull-request template to provide a minimum of contextual information and make sure to meet the requirements of the checklist.

Pull requests are automatically tested against the CI and will be reviewed when tests pass. When your changes are validated, your branch is merged. CI builds the new :edge image immediately and your changes will be includes in the next version release.

"},{"location":"contributing/tests/","title":"Tests","text":"

Program testing can be used to show the presence of bugs, but never to show their absence!

\u2013 Edsger Wybe Dijkstra

"},{"location":"contributing/tests/#introduction","title":"Introduction","text":"

DMS employs a variety of unit and integration tests. All tests and associated configuration is stored in the test/ directory. If you want to change existing functionality or integrate a new feature into DMS, you will probably need to work with our test suite.

Can I use macOS?

We do not support running linting, tests, etc. on macOS at this time. Please use a Linux VM, Debian/Ubuntu is recommended.

"},{"location":"contributing/tests/#about","title":"About","text":"

We use BATS (Bash Automated Testing System) and additional support libraries. BATS is very similar to Bash, and one can easily and quickly get an understanding of how tests in a single file are run. A test file template provides a minimal working example for newcomers to look at.

"},{"location":"contributing/tests/#structure","title":"Structure","text":"

The test/ directory contains multiple directories. Among them is the bats/ directory (which is the BATS git submodule) and the helper/ directory. The latter is especially interesting because it contains common support functionality used in almost every test. Actual tests are located in test/tests/.

Test suite undergoing refactoring

We are currently in the process of restructuring all of our tests. Tests will be moved into test/tests/parallel/ and new tests should be placed there as well.

"},{"location":"contributing/tests/#using-our-helper-functions","title":"Using Our Helper Functions","text":"

There are many functions that aid in writing tests. We urge you to use them! They will not only ease writing a test but they will also do their best to ensure there are no race conditions or other unwanted side effects. To learn about the functions we provide, you can:

  1. look into existing tests for helper functions we already used
  2. look into the test/helper/ directory which contains all files that can (and will) be loaded in test files

We encourage you to try both of the approaches mentioned above. To make understanding and using the helper functions easy, every function contains detailed documentation comments. Read them carefully!

"},{"location":"contributing/tests/#how-are-tests-run","title":"How Are Tests Run?","text":"

Tests are split into two categories:

  • test/tests/parallel/: Multiple test files are run concurrently to reduce the required time to complete the test suite. A test file will presently run it's own defined test-cases in a sequential order.
  • test/tests/serial/: Each test file is queued up to run sequentially. Tests that are unable to support running concurrently belong here.

Parallel tests are further partitioned into smaller sets. If your system has the resources to support running more than one of those sets at a time this is perfectly ok (our CI runs tests by distributing the sets across multiple test runners). Care must be taken not to mix running the serial tests while a parallel set is also running; this is handled for you when using make tests.

"},{"location":"contributing/tests/#running-tests","title":"Running Tests","text":""},{"location":"contributing/tests/#prerequisites","title":"Prerequisites","text":"

To run the test suite, you will need to:

  1. Install Docker
  2. Install jq and (GNU) parallel (under Ubuntu, use sudo apt-get -y install jq parallel)
  3. Execute git submodule update --init --recursive if you haven't already initialized the git submodules
"},{"location":"contributing/tests/#executing-tests","title":"Executing Test(s)","text":"

We use make to run commands.

  1. Run make build to create or update the local mailserver-testing:ci Docker image (using the projects Dockerfile)
  2. Run all tests: make clean tests
  3. Run a single test: make clean generate-accounts test/<TEST NAME WITHOUT .bats SUFFIX>
  4. Run multiple unrelated tests: make clean generate-accounts test/<TEST NAME WITHOUT .bats SUFFIX>,<TEST NAME WITHOUT .bats SUFFIX> (just add a , and then immediately write the new test name)
  5. Run a whole set or all serial tests: make clean generate-accounts tests/parallel/setX where X is the number of the set or make clean generate-accounts tests/serial
Setting the Degree of Parallelization for Tests

If your machine is capable, you can increase the amount of tests that are run simultaneously by prepending the make clean all command with BATS_PARALLEL_JOBS=X (i.e. BATS_PARALLEL_JOBS=X make clean all). This wil speed up the test procedure. You can also run all tests in serial by setting BATS_PARALLEL_JOBS=1 this way.

The default value of BATS_PARALLEL_JOBS is 2. This can be increased if your system has the resources spare to support running more jobs at once to complete the test suite sooner.

Test Output when Running in Parallel

When running tests in parallel (with make clean generate-accounts tests/parallel/setX), BATS will delay outputting the results until completing all test cases within a file.

This likewise delays the reporting of test-case failures. When troubleshooting parallel set tests, you may prefer to run specific tests you're working on serially (as demonstrated in the example below).

When writing tests, ensure that parallel set tests still pass when run in parallel. You need to account for other tests running in parallel that may interfere with your own tests logic.

"},{"location":"contributing/tests/#an-example","title":"An Example","text":"

In this example, you've made a change to the Rspamd feature support (or adjusted it's tests). First verify no regressions have been introduced by running it's specific test file:

$ make clean generate-accounts test/rspamd\nrspamd.bats\n \u2713 [Rspamd] Postfix's main.cf was adjusted [12]\n \u2713 [Rspamd] normal mail passes fine [44]\n \u2713 [Rspamd] detects and rejects spam [122]\n \u2713 [Rspamd] detects and rejects virus [189]\n

As your feature work progresses your change for Rspamd also affects ClamAV. As your change now spans more than just the Rspamd test file, you could run multiple test files serially:

$ make clean generate-accounts test/rspamd,clamav\nrspamd.bats\n \u2713 [Rspamd] Postfix's main.cf was adjusted [12]\n \u2713 [Rspamd] normal mail passes fine [44]\n \u2713 [Rspamd] detects and rejects spam [122]\n \u2713 [Rspamd] detects and rejects virus [189]\nclamav.bats\n \u2713 [ClamAV] log files exist at /var/log/mail directory [68]\n \u2713 [ClamAV] should be identified by Amavis [67]\n \u2713 [ClamAV] freshclam cron is enabled [76]\n \u2713 [ClamAV] env CLAMAV_MESSAGE_SIZE_LIMIT is set correctly [63]\n \u2713 [ClamAV] rejects virus [60]\n

You're almost finished with your change before submitting it as a PR. It's a good idea to run the full parallel set those individual tests belong to (especially if you've modified any tests):

$ make clean generate-accounts tests/parallel/set1\ndefault_relay_host.bats\n \u2713 [Relay] (ENV) 'DEFAULT_RELAY_HOST' should configure 'main.cf:relayhost' [88]\nspam_virus/amavis.bats\n \u2713 [Amavis] SpamAssassin integration should be active [1165]\nspam_virus/clamav.bats\n \u2713 [ClamAV] log files exist at /var/log/mail directory [73]\n \u2713 [ClamAV] should be identified by Amavis [67]\n \u2713 [ClamAV] freshclam cron is enabled [76]\n...\n

Even better, before opening a PR run the full test suite:

$ make clean tests\n...\n
"},{"location":"examples/tutorials/basic-installation/","title":"Tutorials | Basic Installation","text":""},{"location":"examples/tutorials/basic-installation/#a-basic-example-with-relevant-environmental-variables","title":"A Basic Example With Relevant Environmental Variables","text":"

This example provides you only with a basic example of what a minimal setup could look like. We strongly recommend that you go through the configuration file yourself and adjust everything to your needs. The default docker-compose.yml can be used for the purpose out-of-the-box, see the Usage chapter.

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\n# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)\nhostname: mail.example.com\nports:\n- \"25:25\"\n- \"465:465\"\n- \"587:587\"\n- \"993:993\"\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/mail-logs/:/var/log/mail/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n- /etc/localtime:/etc/localtime:ro\nenvironment:\n- ENABLE_RSPAMD=1\n- ENABLE_CLAMAV=1\n- ENABLE_FAIL2BAN=1\ncap_add:\n- NET_ADMIN # For Fail2Ban to work\nrestart: always\n
"},{"location":"examples/tutorials/basic-installation/#a-basic-ldap-setup","title":"A Basic LDAP Setup","text":"

Note There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\n# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)\nhostname: mail.example.com\nports:\n- \"25:25\"\n- \"465:465\"\n- \"587:587\"\n- \"993:993\"\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/mail-logs/:/var/log/mail/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n- /etc/localtime:/etc/localtime:ro\nenvironment:\n- ACCOUNT_PROVISIONER=LDAP\n- LDAP_SERVER_HOST=ldap # your ldap container/IP/ServerName\n- LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain\n- LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain\n- LDAP_BIND_PW=admin\n- LDAP_QUERY_FILTER_USER=(&(mail=%s)(mailEnabled=TRUE))\n- LDAP_QUERY_FILTER_GROUP=(&(mailGroupMember=%s)(mailEnabled=TRUE))\n- LDAP_QUERY_FILTER_ALIAS=(|(&(mailAlias=%s)(objectClass=PostfixBookMailForward))(&(mailAlias=%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE)))\n- LDAP_QUERY_FILTER_DOMAIN=(|(&(mail=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailGroupMember=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailalias=*@%s)(objectClass=PostfixBookMailForward)))\n- DOVECOT_PASS_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))\n- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))\n- ENABLE_SASLAUTHD=1\n- SASLAUTHD_MECHANISMS=ldap\n- SASLAUTHD_LDAP_SERVER=ldap\n- SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain\n- SASLAUTHD_LDAP_PASSWORD=admin\n- SASLAUTHD_LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain\n- SASLAUTHD_LDAP_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%U))\n- POSTMASTER_ADDRESS=postmaster@localhost.localdomain\nrestart: always\n
"},{"location":"examples/tutorials/basic-installation/#using-dms-as-a-local-mail-relay-for-containers","title":"Using DMS as a local mail relay for containers","text":"

Info

This was originally a community contributed guide. Please let us know via a Github Issue if you're having any difficulty following the guide so that we can update it.

This guide is focused on only using SMTP ports (not POP3 and IMAP) with the intent to relay mail received from another service to an external email address (eg: user@gmail.com). It is not intended for mailbox storage of real users.

In this setup docker-mailserver is not intended to receive email from the outside world, so no anti-spam or anti-virus software is needed, making the service lighter to run.

setup

The setup command used below is to be run inside the container.

Open Relays

Adding the docker network's gateway to the list of trusted hosts (eg: using the network or connected-networks option), can create an open relay. For instance if IPv6 is enabled on the host machine, but not in Docker.

  1. Create the file docker-compose.yml with a content like this:

    Example

    services:\nmailserver:\nimage: docker.io/mailserver/docker-mailserver:latest\ncontainer_name: mailserver\n# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)\nhostname: mail.example.com\nports:\n- \"25:25\"\n- \"587:587\"\n- \"465:465\"\nvolumes:\n- ./docker-data/dms/mail-data/:/var/mail/\n- ./docker-data/dms/mail-state/:/var/mail-state/\n- ./docker-data/dms/mail-logs/:/var/log/mail/\n- ./docker-data/dms/config/:/tmp/docker-mailserver/\n- /etc/localtime:/etc/localtime:ro\nenvironment:\n- ENABLE_FAIL2BAN=1\n# Using letsencrypt for SSL/TLS certificates:\n- SSL_TYPE=letsencrypt\n# Allow sending emails from other docker containers:\n# Beware creating an Open Relay: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#permit_docker\n- PERMIT_DOCKER=network\n# You may want to enable this: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#spoof_protection\n# See step 6 below, which demonstrates setup with enabled/disabled SPOOF_PROTECTION:\n- SPOOF_PROTECTION=0\ncap_add:\n- NET_ADMIN # For Fail2Ban to work\nrestart: always\n

    The docs have a detailed page on Environment Variables for reference.

    Firewalled ports

    If you have a firewall running, you may need to open ports 25, 587 and 465.

    For example, with the firewall ufw, run:

    ufw allow 25\nufw allow 587\nufw allow 465\n

    Caution: This may not be sound advice.

  2. Configure your DNS service to use an MX record for the hostname (eg: mail) you configured in the previous step and add the SPF TXT record.

    If you manually manage the DNS zone file for the domain

    It would look something like this:

    $ORIGIN example.com\n@     IN  A      10.11.12.13\nmail  IN  A      10.11.12.13\n\n; mail-server for example.com\n@     IN  MX  10 mail.example.com.\n\n; Add SPF record\n@     IN  TXT    \"v=spf1 mx -all\"\n

    Then don't forget to change the SOA serial number, and to restart the service.

  3. Generate DKIM keys for your domain via setup config dkim.

    Copy the content of the file docker-data/dms/config/opendkim/keys/example.com/mail.txt and add it to your DNS records as a TXT like SPF was handled above.

    I use bind9 for managing my domains, so I just paste it on example.com.db:

    mail._domainkey IN      TXT     ( \"v=DKIM1; h=sha256; k=rsa; \"\n        \"p=MIIBIjANBgkqhkiG9w0BAQEFACAQ8AMIIBCgKCAQEAaH5KuPYPSF3Ppkt466BDMAFGOA4mgqn4oPjZ5BbFlYA9l5jU3bgzRj3l6/Q1n5a9lQs5fNZ7A/HtY0aMvs3nGE4oi+LTejt1jblMhV/OfJyRCunQBIGp0s8G9kIUBzyKJpDayk2+KJSJt/lxL9Iiy0DE5hIv62ZPP6AaTdHBAsJosLFeAzuLFHQ6USyQRojefqFQtgYqWQ2JiZQ3\"\n        \"iqq3bD/BVlwKRp5gH6TEYEmx8EBJUuDxrJhkWRUk2VDl1fqhVBy8A9O7Ah+85nMrlOHIFsTaYo9o6+cDJ6t1i6G1gu+bZD0d3/3bqGLPBQV9LyEL1Rona5V7TJBGg099NQkTz1IwIDAQAB\" )  ; ----- DKIM key mail for example.com\n

  4. Get an SSL certificate, we have a guide for you here (Let's Encrypt is a popular service to get free SSL certificates).

  5. Start docker-mailserver and check the terminal output for any errors: docker-compose up.

  6. Create email accounts and aliases:

    With SPOOF_PROTECTION=0

    setup email add admin@example.com passwd123\nsetup email add info@example.com passwd123\nsetup alias add admin@example.com external-account@gmail.com\nsetup alias add info@example.com external-account@gmail.com\nsetup email list\nsetup alias list\n

    Aliases make sure that any email that comes to these accounts is forwarded to your third-party email address (external-account@gmail.com), where they are retrieved (eg: via third-party web or mobile app), instead of connecting directly to docker-mailserer with POP3 / IMAP.

    With SPOOF_PROTECTION=1

    setup email add admin.gmail@example.com passwd123\nsetup email add info.gmail@example.com passwd123\nsetup alias add admin@example.com admin.gmail@example.com\nsetup alias add info@example.com info.gmail@example.com\nsetup alias add admin.gmail@example.com external-account@gmail.com\nsetup alias add info.gmail@example.com external-account@gmail.com\nsetup email list\nsetup alias list\n

    This extra step is required to avoid the 553 5.7.1 Sender address rejected: not owned by user error (the accounts used for submitting mail to Gmail are admin.gmail@example.com and info.gmail@example.com)

  7. Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with ctrl+c and start it again as a daemon: docker-compose up -d.

"},{"location":"examples/tutorials/blog-posts/","title":"Tutorials | Blog Posts","text":"

This site lists blog entries that write about the project. If you blogged about docker-mailserver let us know so we can add it here!

  • Installing docker-mailserver by @andrewlow
  • Self hosted mail-server by @matrixes
  • Docker-mailserver on kubernetes by @ErikEngerd
"},{"location":"examples/tutorials/docker-build/","title":"Tutorials | Docker Build","text":""},{"location":"examples/tutorials/docker-build/#building-your-own-docker-image","title":"Building your own Docker image","text":""},{"location":"examples/tutorials/docker-build/#submodules","title":"Submodules","text":"

You'll need to retrieve the git submodules prior to building your own Docker image. From within your copy of the git repo run the following to retrieve the submodules and build the Docker image:

git submodule update --init --recursive\ndocker build -t <YOUR CUSTOM IMAGE NAME> .\n

Or, you can clone and retrieve the submodules in one command:

git clone --recurse-submodules https://github.com/docker-mailserver/docker-mailserver\n
"},{"location":"examples/tutorials/docker-build/#about-docker","title":"About Docker","text":""},{"location":"examples/tutorials/docker-build/#version","title":"Version","text":"

We make use of build-features that require a recent version of Docker. Depending on your distribution, please have a look at the official installation documentation for Docker to get the latest version. Otherwise, you may encounter issues, for example with the --link flag for a COPY command.

"},{"location":"examples/tutorials/docker-build/#environment","title":"Environment","text":"

If you are not using make to build the image, note that you will need to provide DOCKER_BUILDKIT=1 to the docker build command for the build to succeed.

"},{"location":"examples/tutorials/docker-build/#build-arguments","title":"Build Arguments","text":"

The Dockerfile takes additional, so-called build arguments. These are

  1. VCS_VERSION: the image version (default = edge)
  2. VCS_REVISION: the image revision (default = unknown)

When using make to build the image, these are filled with proper values. You can build the image without supplying these arguments just fine though.

"},{"location":"examples/tutorials/mailserver-behind-proxy/","title":"Tutorials | Mail-Server behind a Proxy","text":""},{"location":"examples/tutorials/mailserver-behind-proxy/#using-docker-mailserver-behind-a-proxy","title":"Using docker-mailserver behind a Proxy","text":""},{"location":"examples/tutorials/mailserver-behind-proxy/#information","title":"Information","text":"

If you are hiding your container behind a proxy service you might have discovered that the proxied requests from now on contain the proxy IP as the request origin. Whilst this behavior is technical correct it produces certain problems on the containers behind the proxy as they cannot distinguish the real origin of the requests anymore.

To solve this problem on TCP connections we can make use of the proxy protocol. Compared to other workarounds that exist (X-Forwarded-For which only works for HTTP requests or Tproxy that requires you to recompile your kernel) the proxy protocol:

  • It is protocol agnostic (can work with any layer 7 protocols, even when encrypted).
  • It does not require any infrastructure changes.
  • NAT-ing firewalls have no impact it.
  • It is scalable.

There is only one condition: both endpoints of the connection MUST be compatible with proxy protocol.

Luckily dovecot and postfix are both Proxy-Protocol ready softwares so it depends only on your used reverse-proxy / loadbalancer.

"},{"location":"examples/tutorials/mailserver-behind-proxy/#configuration-of-the-used-proxy-software","title":"Configuration of the used Proxy Software","text":"

The configuration depends on the used proxy system. I will provide the configuration examples of traefik v2 using IMAP and SMTP with implicit TLS.

Feel free to add your configuration if you achieved the same goal using different proxy software below:

Traefik v2

Truncated configuration of traefik itself:

services:\nreverse-proxy:\nimage: docker.io/traefik:latest # v2.5\ncontainer_name: docker-traefik\nrestart: always\ncommand:\n- \"--providers.docker\"\n- \"--providers.docker.exposedbydefault=false\"\n- \"--providers.docker.network=proxy\"\n- \"--entrypoints.web.address=:80\"\n- \"--entryPoints.websecure.address=:443\"\n- \"--entryPoints.smtp.address=:25\"\n- \"--entryPoints.smtp-ssl.address=:465\"\n- \"--entryPoints.imap-ssl.address=:993\"\n- \"--entryPoints.sieve.address=:4190\"\nports:\n- \"25:25\"\n- \"465:465\"\n- \"993:993\"\n- \"4190:4190\"\n[...]\n

Truncated list of necessary labels on the docker-mailserver container:

services:\nmailserver:\nimage: ghcr.io/docker-mailserver/docker-mailserver:latest\ncontainer_name: mailserver\nhostname: mail.example.com\nrestart: always\nnetworks:\n- proxy\nlabels:\n- \"traefik.enable=true\"\n- \"traefik.tcp.routers.smtp.rule=HostSNI(`*`)\"\n- \"traefik.tcp.routers.smtp.entrypoints=smtp\"\n- \"traefik.tcp.routers.smtp.service=smtp\"\n- \"traefik.tcp.services.smtp.loadbalancer.server.port=25\"\n- \"traefik.tcp.services.smtp.loadbalancer.proxyProtocol.version=1\"\n- \"traefik.tcp.routers.smtp-ssl.rule=HostSNI(`*`)\"\n- \"traefik.tcp.routers.smtp-ssl.tls=false\"\n- \"traefik.tcp.routers.smtp-ssl.entrypoints=smtp-ssl\"\n- \"traefik.tcp.routers.smtp-ssl.service=smtp-ssl\"\n- \"traefik.tcp.services.smtp-ssl.loadbalancer.server.port=465\"\n- \"traefik.tcp.services.smtp-ssl.loadbalancer.proxyProtocol.version=1\"\n- \"traefik.tcp.routers.imap-ssl.rule=HostSNI(`*`)\"\n- \"traefik.tcp.routers.imap-ssl.entrypoints=imap-ssl\"\n- \"traefik.tcp.routers.imap-ssl.service=imap-ssl\"\n- \"traefik.tcp.services.imap-ssl.loadbalancer.server.port=10993\"\n- \"traefik.tcp.services.imap-ssl.loadbalancer.proxyProtocol.version=2\"\n- \"traefik.tcp.routers.sieve.rule=HostSNI(`*`)\"\n- \"traefik.tcp.routers.sieve.entrypoints=sieve\"\n- \"traefik.tcp.routers.sieve.service=sieve\"\n- \"traefik.tcp.services.sieve.loadbalancer.server.port=4190\"\n[...]\n

Keep in mind that it is necessary to use port 10993 here. More information below at dovecot configuration.

"},{"location":"examples/tutorials/mailserver-behind-proxy/#configuration-of-the-backend-dovecot-and-postfix","title":"Configuration of the Backend (dovecot and postfix)","text":"

The following changes can be achieved completely by adding the content to the appropriate files by using the projects function to overwrite config files.

Changes for postfix can be applied by adding the following content to docker-data/dms/config/postfix-main.cf:

postscreen_upstream_proxy_protocol = haproxy\n

and to docker-data/dms/config/postfix-master.cf:

submission/inet/smtpd_upstream_proxy_protocol=haproxy\nsmtps/inet/smtpd_upstream_proxy_protocol=haproxy\n

Changes for dovecot can be applied by adding the following content to docker-data/dms/config/dovecot.cf:

haproxy_trusted_networks = <your-proxy-ip>, <optional-cidr-notation>\nhaproxy_timeout = 3 secs\nservice imap-login {\ninet_listener imaps {\nhaproxy = yes\nssl = yes\nport = 10993\n}\n}\n

Note

Port 10993 is used here to avoid conflicts with internal systems like postscreen and amavis as they will exchange messages on the default port and obviously have a different origin then compared to the proxy.

"},{"location":"examples/use-cases/forward-only-mailserver-with-ldap-authentication/","title":"Use Cases | Forward-Only Mail-Server with LDAP","text":""},{"location":"examples/use-cases/forward-only-mailserver-with-ldap-authentication/#building-a-forward-only-mail-server","title":"Building a Forward-Only Mail-Server","text":"

A forward-only mail-server does not have any local mailboxes. Instead, it has only aliases that forward emails to external email accounts (for example to a Gmail account). You can also send email from the localhost (the computer where docker-mailserver is installed), using as sender any of the alias addresses.

The important settings for this setup (on mailserver.env) are these:

PERMIT_DOCKER=host\nENABLE_POP3=\nENABLE_CLAMAV=0\nSMTP_ONLY=1\nENABLE_SPAMASSASSIN=0\nENABLE_FETCHMAIL=0\n

Since there are no local mailboxes, we use SMTP_ONLY=1 to disable dovecot. We disable as well the other services that are related to local mailboxes (POP3, ClamAV, SpamAssassin, etc.)

We can create aliases with ./setup.sh, like this:

./setup.sh alias add <alias-address> <external-email-account>\n
"},{"location":"examples/use-cases/forward-only-mailserver-with-ldap-authentication/#authenticating-with-ldap","title":"Authenticating with LDAP","text":"

If you want to send emails from outside the mail-server you have to authenticate somehow (with a username and password). One way of doing it is described in this discussion. However if there are many user accounts, it is better to use authentication with LDAP. The settings for this on mailserver.env are:

ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER\nACCOUNT_PROVISIONER=LDAP\nLDAP_START_TLS=yes\nLDAP_SERVER_HOST=ldap.example.org\nLDAP_SEARCH_BASE=ou=users,dc=example,dc=org\nLDAP_BIND_DN=cn=mailserver,dc=example,dc=org\nLDAP_BIND_PW=pass1234\n\nENABLE_SASLAUTHD=1\nSASLAUTHD_MECHANISMS=ldap\nSASLAUTHD_LDAP_SERVER=ldap.example.org\nSASLAUTHD_LDAP_START_TLS=yes\nSASLAUTHD_LDAP_BIND_DN=cn=mailserver,dc=example,dc=org\nSASLAUTHD_LDAP_PASSWORD=pass1234\nSASLAUTHD_LDAP_SEARCH_BASE=ou=users,dc=example,dc=org\nSASLAUTHD_LDAP_FILTER=(&(uid=%U)(objectClass=inetOrgPerson))\n

My LDAP data structure is very basic, containing only the username, password, and the external email address where to forward emails for this user. An entry looks like this:

add uid=username,ou=users,dc=example,dc=org\nuid: username\nobjectClass: inetOrgPerson\nsn: username\ncn: username\nuserPassword: {SSHA}abcdefghi123456789\nemail: external-account@gmail.com\n

This structure is different from what is expected/assumed from the configuration scripts of docker-mailserver, so it doesn't work just by using the LDAP_QUERY_FILTER_... settings. Instead, I had to use a custom configuration (via user-patches.sh). I created the script docker-data/dms/config/user-patches.sh, with content like this:

#!/bin/bash\n\nrm -f /etc/postfix/{ldap-groups.cf,ldap-domains.cf}\n\npostconf \\\n\"virtual_mailbox_domains = /etc/postfix/vhost\" \\\n\"virtual_alias_maps = ldap:/etc/postfix/ldap-aliases.cf texthash:/etc/postfix/virtual\" \\\n\"smtpd_sender_login_maps = ldap:/etc/postfix/ldap-users.cf\"\n\nsed -i /etc/postfix/ldap-users.cf \\\n-e '/query_filter/d' \\\n-e '/result_attribute/d' \\\n-e '/result_format/d'\ncat <<EOF >> /etc/postfix/ldap-users.cf\nquery_filter = (uid=%u)\nresult_attribute = uid\nresult_format = %s@example.org\nEOF\n\nsed -i /etc/postfix/ldap-aliases.cf \\\n-e '/domain/d' \\\n-e '/query_filter/d' \\\n-e '/result_attribute/d'\ncat <<EOF >> /etc/postfix/ldap-aliases.cf\ndomain = example.org\nquery_filter = (uid=%u)\nresult_attribute = mail\nEOF\n\npostfix reload\n

You see that besides query_filter, I had to customize as well result_attribute and result_format.

See also

For more details about using LDAP see: LDAP managed mail-server with Postfix and Dovecot for multiple domains

Note

Another solution that serves as a forward-only mail-server is this.

"},{"location":"examples/use-cases/imap-folders/","title":"Mailboxes (aka IMAP Folders)","text":"

INBOX is setup as the private inbox namespace. By default target/dovecot/15-mailboxes.conf configures the special IMAP folders Drafts, Sent, Junk and Trash to be automatically created and subscribed. They are all assigned to the private inbox namespace (which implicitly provides the INBOX folder).

These IMAP folders are considered special because they add a \"SPECIAL-USE\" attribute, which is a standardized way to communicate to mail clients that the folder serves a purpose like storing spam/junk mail (\\Junk) or deleted mail (\\Trash). This differentiates them from regular mail folders that you may use for organizing.

"},{"location":"examples/use-cases/imap-folders/#adding-a-mailbox-folder","title":"Adding a mailbox folder","text":"

See target/dovecot/15-mailboxes.conf for existing mailbox folders which you can modify or uncomment to enable some other common mailboxes. For more information try the official Dovecot documentation.

The Archive special IMAP folder may be useful to enable. To do so, make a copy of target/dovecot/15-mailboxes.conf and uncomment the Archive mailbox definition. Mail clients should understand that this folder is intended for archiving mail due to the \\Archive \"SPECIAL-USE\" attribute.

With the provided docker-compose.yml example, a volume bind mounts the host directory docker-data/dms/config/ to the container location /tmp/docker-mailserver/. Config file overrides should instead be mounted to a different location as described in Overriding Configuration for Dovecot:

volumes:\n- ./docker-data/dms/config/dovecot/15-mailboxes.conf:/etc/dovecot/conf.d/15-mailboxes.conf:ro\n
"},{"location":"examples/use-cases/imap-folders/#caution","title":"Caution","text":""},{"location":"examples/use-cases/imap-folders/#adding-folders-to-an-existing-setup","title":"Adding folders to an existing setup","text":"

Handling of newly added mailbox folders can be inconsistent across mail clients:

  • Users may experience issues such as archived emails only being available locally.
  • Users may need to migrate emails manually between two folders.
"},{"location":"examples/use-cases/imap-folders/#support-for-special-use-attributes","title":"Support for SPECIAL-USE attributes","text":"

Not all mail clients support the SPECIAL-USE attribute for mailboxes (defined in RFC 6154). These clients will treat the mailbox folder as any other, using the name assigned to it instead.

Some clients may still know to treat these folders for their intended purpose if the mailbox name matches the common names that the SPECIAL-USE attributes represent (eg Sent as the mailbox name for \\Sent).

"},{"location":"examples/use-cases/imap-folders/#internationalization-i18n","title":"Internationalization (i18n)","text":"

Usually the mail client will know via context such as the SPECIAL-USE attribute or common English mailbox names, to provide a localized label for the users preferred language.

Take care to test localized names work well as well.

"},{"location":"examples/use-cases/imap-folders/#email-clients-support","title":"Email Clients Support","text":"
  • If a new mail account is added without the SPECIAL-USE attribute enabled for archives:
    • Thunderbird suggests and may create an Archives folder on the server.
    • Outlook for Android archives to a local folder.
    • Spark for Android archives to server folder named Archive.
  • If a new mail account is added after the SPECIAL-USE attribute is enabled for archives:
    • Thunderbird, Outlook for Android and Spark for Android will use the mailbox folder name assigned.

Windows Mail

Windows Mail has been said to ignore SPECIAL-USE attribute and look only at the mailbox folder name assigned.

Needs citation

This information is provided by the community.

It presently lacks references to confirm the behaviour. If any information is incorrect please let us know!

"}]} \ No newline at end of file diff --git a/v12.0/sitemap.xml b/v12.0/sitemap.xml new file mode 100644 index 00000000..cc66640a --- /dev/null +++ b/v12.0/sitemap.xml @@ -0,0 +1,213 @@ + + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/faq/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/introduction/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/usage/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/debugging/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/environment/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/pop3/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/setup.sh/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/user-management/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/auth-ldap/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/dovecot-master-accounts/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/full-text-search/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/ipv6/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/kubernetes/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/mail-fetchmail/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/mail-sieve/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/optional-config/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/podman/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/mail-forwarding/aws-ses/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/mail-forwarding/relay-hosts/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/maintenance/update-and-cleanup/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/override-defaults/dovecot/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/override-defaults/postfix/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/advanced/override-defaults/user-patches/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/best-practices/autodiscover/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/best-practices/dkim/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/best-practices/dmarc/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/best-practices/spf/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/security/fail2ban/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/security/mail_crypt/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/security/rspamd/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/security/ssl/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/config/security/understanding-the-ports/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/contributing/general/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/contributing/issues-and-pull-requests/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/contributing/tests/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/examples/tutorials/basic-installation/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/examples/tutorials/blog-posts/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/examples/tutorials/docker-build/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/examples/tutorials/mailserver-behind-proxy/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/examples/use-cases/forward-only-mailserver-with-ldap-authentication/ + 2023-04-10 + daily + + + https://docker-mailserver.github.io/docker-mailserver/v12.0/examples/use-cases/imap-folders/ + 2023-04-10 + daily + + \ No newline at end of file diff --git a/v12.0/usage/index.html b/v12.0/usage/index.html new file mode 100644 index 00000000..e11b2aff --- /dev/null +++ b/v12.0/usage/index.html @@ -0,0 +1,1931 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Usage - Docker Mailserver + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + + + + +
+
+ + + +
+
+
+ + + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Usage

+ +

This pages explains how to get started with DMS. The guide uses Docker Compose as a reference. In our examples, a volume mounts the host location docker-data/dms/config/ to /tmp/docker-mailserver/ inside the container.

+

Preliminary Steps

+

Before you can get started with deploying your own mail server, there are some requirements to be met:

+
    +
  1. You need to have a host that you can manage.
    2. +
  2. You need to own a domain, and you need to able to manage DNS for this domain.
    3. +
+

Host Setup

+

There are a few requirements for a suitable host system:

+
    +
  1. The host should have a static IP address; otherwise you will need to dynamically update DNS (undesirable due to DNS caching)
    2. +
  2. The host should be able to send/receive on the necessary ports for mail
    3. +
  3. You should be able to set a PTR record for your host; security-hardened mail servers might otherwise reject your mail server as the IP address of your host does not resolve correctly/at all to the DNS name of your server.
    4. +
+

On the host, you should have a suitable container runtime (like Docker or Podman) installed. We assume Docker Compose is installed.

+
+

Podman Support

+

If you're using podman, make sure to read the related documentation.

+
+

Minimal DNS Setup

+

The DNS setup is a big and essential part of the whole setup. There is a lot of confusion for newcomers and people starting out when setting up DNS. This section provides an example configuration and supplementary explanation. We expect you to be at least a bit familiar with DNS, what it does and what the individual record types are.

+

Now let's say you just bought example.com and you want to be able to send and receive e-mails for the address test@example.com. On the most basic level, you will need to

+
    +
  1. set an MX record for your domain example.com - in our example, the MX record contains mail.example.com
    2. +
  2. set an A record that resolves the name of your mail server - in our example, the A record contains 11.22.33.44
    3. +
  3. (in a best-case scenario) set a PTR record that resolves the IP of your mail server - in our example, the PTR contains mail.example.com
    4. +
+

We will later dig into DKIM, DMARC & SPF, but for now, these are the records that suffice in getting you up and running. Here is a short explanation of what the records do:

+
    +
  • The MX record tells everyone which (DNS) name is responsible for e-mails on your domain. + Because you want to keep the option of running another service on the domain name itself, you run your mail server on mail.example.com. + This does not imply your e-mails will look like test@mail.example.com, the DNS name of your mail server is decoupled of the domain it serves e-mails for. + In theory, you mail server could even serve e-mails for test@some-other-domain.com, if the MX record for some-other-domain.com points to mail.example.com.
    • +
  • The A record tells everyone which IP address the DNS name mail.example.com resolves to.
    • +
  • The PTR record is the counterpart of the A record, telling everyone what name the IP address 11.22.33.44 resolves to.
    • +
+

If you setup everything, it should roughly look like this:

+
$ dig @1.1.1.1 +short MX example.com
+mail.example.com
+$ dig @1.1.1.1 +short A mail.example.com
+11.22.33.44
+$ dig @1.1.1.1 +short -x 11.22.33.44
+mail.example.com
+
+

Deploying the Actual Image

+

Tagging Convention

+

To understand which tags you should use, read this section carefully. Our CI will automatically build, test and push new images to the following container registries:

+
    +
  1. DockerHub (docker.io/mailserver/docker-mailserver)
    2. +
  2. GitHub Container Registry (ghcr.io/docker-mailserver/docker-mailserver)
    3. +
+

All workflows are using the tagging convention listed below. It is subsequently applied to all images.

+ + + + + + + + + + + + + + + + + +
EventImage Tags
push on masteredge
push a tag (v1.2.3)1.2.3, 1.2, 1, latest
+

Get All Files

+

Issue the following commands to acquire the necessary files:

+
DMS_GITHUB_URL="https://github.com/docker-mailserver/docker-mailserver/blob/latest"
+wget "${DMS_GITHUB_URL}/docker-compose.yml"
+wget "${DMS_GITHUB_URL}/mailserver.env"
+
+

Configuration Steps

+
    +
  1. First edit docker-compose.yml to your liking
      +
    • Substitute mail.example.com according to your FQDN.
      • +
    • If you want to use SELinux for the ./docker-data/dms/config/:/tmp/docker-mailserver/ mount, append -z or -Z.
      • +
    +
    2. +
  2. Then configure the environment specific to the mail server by editing mailserver.env, but keep in mind that:
      +
    • only basic VAR=VAL is supported
      • +
    • do not quote your values
      • +
    • variable substitution is not supported, e.g. OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME does not work
      • +
    +
    3. +
+

Get Up and Running

+
+

Using the Correct Commands For Stopping and Starting DMS

+

Use docker compose up / down, not docker compose start / stop. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.

+

Using Ctrl+C is not supported either!

+
+

For an overview of commands to manage DMS config, run: docker exec -it <CONTAINER NAME> setup help.

+
+Usage of setup.sh when no DMS Container Is Running +

We encourage you to directly use setup inside the container (like shown above). If you still want to use setup.sh, here's some information about it.

+

If no DMS container is running, any ./setup.sh command will check online for the :latest image tag (the current stable release), performing a docker pull ... if necessary followed by running the command in a temporary container:

+
$ ./setup.sh help
+Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...
+SETUP(1)
+
+NAME
+    setup - 'docker-mailserver' Administration & Configuration script
+...
+
+$ docker run --rm ghcr.io/docker-mailserver/docker-mailserver:latest setup help
+SETUP(1)
+
+NAME
+    setup - 'docker-mailserver' Administration & Configuration script
+...
+
+
+

On first start, you will need to add at least one email account (unless you're using LDAP). You have two minutes to do so, otherwise DMS will shutdown and restart. You can add accounts by running docker exec -ti <CONTAINER NAME> setup email add user@example.com. That's it! It really is that easy.

+

Further Miscellaneous Steps

+

Setting up TLS

+

You definitely want to setup TLS. Please refer to our documentation about TLS.

+

Aliases

+

You should add at least one alias, the postmaster alias. This is a common convention, but not strictly required.

+
docker exec -ti <CONTAINER NAME> setup alias add postmaster@example.com user@example.com
+
+

DKIM Keys

+

You can (and you should) generate DKIM keys. For more information:

+ +

When keys are generated, you can configure your DNS server by just pasting the content of config/opendkim/keys/domain.tld/mail.txt to set up DKIM. See the documentation for more details.

+
+

Note

+

In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:

+
docker exec -ti <CONTAINER NAME> setup config dkim domain '<domain.tld>[,<domain2.tld>]'
+
+
+

Advanced DNS Setup

+

You will very likely want to configure your DNS with these TXT records: SPF, DKIM, and DMARC.

+

The following illustrates what a (rather strict) set of records could look like:

+
$ dig @1.1.1.1 +short TXT example.com
+"v=spf1 mx -all"
+$ dig @1.1.1.1 +short TXT dkim-rsa._domainkey.example.com
+"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQ..."
+$ dig @1.1.1.1 +short TXT _dmarc.example.com
+"v=DMARC1; p=reject; sp=reject; pct=100; adkim=s; aspf=s; fo=1"
+
+

Custom User Changes & Patches

+

If you'd like to change, patch or alter files or behavior of docker-mailserver, you can use a script. See this part of our documentation for a detailed explanation.

+

Testing

+

Here are some tools you can use to verify your configuration:

+
    +
  1. MX Toolbox
    2. +
  2. DMARC Analyzer
    3. +
  3. mail-tester.com
    4. +
  4. multiRBL.valli.org
    5. +
+ + + + + + +
+
+ + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file