- add instructions for FreeBSD.org SMTP access setup

Reviewed by:	bcr, mat, rpokala, allanjude
Differential Revision:	https://reviews.freebsd.org/D18708

2 files changed, 79 insertions, 1 deletions

diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml
index 70488425fe..54972d40db 100644
--- a/en_US.ISO8859-1/articles/committers-guide/article.xml
+++ b/en_US.ISO8859-1/articles/committers-guide/article.xml
@@ -36,6 +36,7 @@
       <year>2016</year>
       <year>2017</year>
       <year>2018</year>
+      <year>2019</year>
       <holder>The &os; Documentation Project</holder>
     </copyright>
 
@@ -91,6 +92,13 @@
 	  </row>
 
 	  <row>
+	    <entry><emphasis>SMTP Host</emphasis></entry>
+	    <entry><literal><systemitem
+	        class="fqdomainname">smtp.FreeBSD.org</systemitem>:587</literal>
+	      (see also <xref linkend="smtp-setup"/>).</entry>
+	  </row>
+
+	  <row>
 	    <entry><emphasis><literal>src/</literal> Subversion
 		Root</emphasis></entry>
 	    <entry><literal>svn+ssh://</literal><systemitem
@@ -2235,6 +2243,13 @@ freebsd-mfc-after = 2 weeks</programlisting>
 	    without warning if space needs to be freed, so forward it
 	    or save it elsewhere.</para>
 
+	  <note>
+	    <para>If your e-mail system uses SPF with strict rules, you
+	      should whitelist <systemitem
+	      class="fqdomainname">mx2.FreeBSD.org</systemitem> from
+	      SPF checks.</para>
+	  </note>
+
 	  <para>Due to the severe load dealing with SPAM places on the
 	    central mail servers that do the mailing list processing,
 	    the front-end server does do some basic checks and will
@@ -2255,6 +2270,69 @@ freebsd-mfc-after = 2 weeks</programlisting>
 	  lists.  The subscriptions are derived from the access
 	  rights.</para>
       </note>
+
+      <sect3 xml:id="smtp-setup">
+        <title>SMTP Access Setup</title>
+
+	<para>For those willing to send e-mail messages through the
+	  FreeBSD.org infrastructure, follow the instructions
+	  below:</para>
+
+	<procedure>
+	  <step>
+	    <para>Point your mail client at <literal><systemitem
+	        class="fqdomainname">smtp.FreeBSD.org</systemitem>:587</literal>.</para>
+	  </step>
+	  
+	  <step>
+	    <para>Enable STARTTLS.</para>
+	  </step>
+
+	  <step>
+	    <para>Ensure your <literal>From:</literal> address is set
+	      to
+	      <literal><replaceable>yourusername</replaceable>@FreeBSD.org</literal>.</para>
+	  </step>
+
+	  <step>
+	    <para>For authentication, you can use your &os; Kerberos
+	      username and password (see <xref
+	        linkend="kerberos-ldap"/>).  The
+	      <literal><replaceable>yourusername</replaceable>/mail</literal>
+	      principal is preferred, as it is only valid for
+	      authenticating to mail resources.</para>
+
+	    <note>
+	      <para>Do not include <literal>@FreeBSD.org</literal>
+		when entering in your username.</para>
+	    </note>
+	  </step>
+	</procedure>
+
+	<note>
+	  <title>Additional notes</title>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para>Will only accept mail from
+	        <literal><replaceable>yourusername</replaceable>@FreeBSD.org</literal>.
+		If you are authenticated as one user, you are not
+		permitted to send mail from another.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>A header will be appended with the SASL username:
+		(<literal>Authenticated sender:
+		 <replaceable>username</replaceable></literal>).</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>Host has various rate limits in place to cut down
+		on brute force attempts.</para>
+	    </listitem>
+	  </itemizedlist>
+	</note>
+      </sect3>
     </sect2>
 
     <sect2 xml:id="mentors">
diff --git a/share/xml/docbook50.dtd b/share/xml/docbook50.dtd
index 0ce2daac12..9bb6f37f10 100644
--- a/share/xml/docbook50.dtd
+++ b/share/xml/docbook50.dtd
@@ -3429,7 +3429,7 @@
 
 >
 
-<!ELEMENT literal (#PCDATA|inlinemediaobject|remark|superscript|subscript|xref|link|olink|anchor|biblioref|alt|annotation|indexterm|phrase|replaceable)*>
+<!ELEMENT literal (#PCDATA|inlinemediaobject|remark|superscript|subscript|systemitem|xref|link|olink|anchor|biblioref|alt|annotation|indexterm|phrase|replaceable)*>
 
 <!ATTLIST literal
 	xmlns	CDATA	#FIXED	"http://docbook.org/ns/docbook"