[Freeipa-devel] [PATCH 0030][DOC] Chapter 1 and 2 updates to documentation

[Petr Spacek]

Hello,

I did proof-reading of patch 0030. It seems that you have canibalized RHEL 
docs which is a bit unfortunate, they are not entirely correct.

RHEL docs are being review and fixed right now so it would be better to wait 
until RHEL guide is fixed.

On 9.8.2014 04:44, Gabe Alford wrote:
> - Patch 0030 update DNS instructions, installation options/examples,
> prerequisites, replica information, etc.

I started to read the patch and found following:

> +                                       <note><title>NOTE</title>
>                                                 <para>
> -                                                       It is recommended that a separate DNS domain be allocated for the &IPA; server. While not required (clients from other domains can still be enrolled in the &IPA; domain), this is a convenience for overall DNS management.
> -                                               </para>
> -                                       </listitem>
> -                               </itemizedlist>
> -                               <note><title>TIP</title>
> +                                               If the &IPA; server is configured to host its own DNS server, the &IPA; DNS service processes all DNS queries. The &IPA; DNS records take precedence, and any previous existing DNS configuration is ignored.
> +                                       </para>
> +                                       <para>
> +                                               All systems within the domain must be configured to use the &IPA;-managed DNS server.
> +                                       </para>
> +                                       </note>
> +                               </section>

This is incorrect (and really important). This text should say that if IdM is 
a DNS server then there has to be correct delegation from parent domain to IdM 
servers.

I.e. if IdM domain is ipa.example.com. is has to be delegated properly from 
example.com. domain. This follows normal rules for DNS, nothing special.


> +                                                       <important><title>IMPORTANT</title>
> +                                                               <para>
> +                                                                       This must be a valid DNS name, which means only numbers, alphabetic characters, underscores(_), and hyphens (-) are allowed. Other characters in the hostname will cause DNS failures.
> +                                                               </para>
> +                                                       </important>
Underscore is not allowed. (Even if it is technically possible docs shouldn't 
encourage people to do that.)


> +                                               <listitem>
> +                                                       <para>
> +                                                               The A and PTR records do not need to match the &IPA; server.
> +                                                       </para>
> +                                               </listitem>
The A and PTR records do not need to match for the server. Forward DNS record 
(A, AAAA) need to match.

> -<screen>[root at server ~]# iptables -A INPUT -p tcp --dport 389 -j ACCEPT</screen>
> +<screen>[root at server ~]# firewalld -A INPUT -p tcp --dport 389 -j ACCEPT</screen>

This is wrong. One cannot just replace "iptables" command with "firewalld" and 
hope it works. I would rather skip this command at all and just point to 
firewalld man page.

And so on and so on.

At this point I have realized that the same mistakes are in RHEL docs so it 
would be better to drop the patch and wait until RHEL docs are fixed.

In future, please use IP address ranges reserved for documentation:
IPv6: http://tools.ietf.org/html/rfc3849
IPv4: http://tools.ietf.org/html/rfc5737

It prevents people from screwing real networks when doing copy&paste. (This 
concern is well based. Copy&paste mistakes in the past caused huge routing 
problems on public Internet.)

Thank you for understanding - and have a nice day!

-- 
Petr^2 Spacek