Clarify meaning of --domain and --realm in installers

Man pages need bigger overhaul. Take this as hot-fix for FAQ.

https://fedorahosted.org/freeipa/ticket/6574

Reviewed-By: Fraser Tweedale <ftweedal@redhat.com>

3 files changed, 48 insertions, 58 deletions

diff --git a/install/tools/man/ipa-dns-install.1 b/install/tools/man/ipa-dns-install.1
index ad937cc59..3ae9f6d4b 100644
--- a/install/tools/man/ipa-dns-install.1
+++ b/install/tools/man/ipa-dns-install.1
@@ -1,20 +1,5 @@
 .\" A man page for ipa-dns-install
-.\" Copyright (C) 2010 Red Hat, Inc.
-.\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation, either version 3 of the License, or
-.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-.\" General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
-.\"
-.\" Author: Rob Crittenden <rcritten@redhat.com>
+.\" Copyright (C) 2010-2016  FreeIPA Contributors see COPYING for license
 .\"
 .TH "ipa-dns-install" "1" "Jun 28, 2012" "FreeIPA" "FreeIPA Manual Pages"
 .SH "NAME"
@@ -22,7 +7,15 @@ ipa\-dns\-install \- Add DNS as a service to an IPA server
 .SH "SYNOPSIS"
 ipa\-dns\-install [\fIOPTION\fR]...
 .SH "DESCRIPTION"
-Adds DNS as an IPA\-managed service. This requires that the IPA server is already installed and configured.
+Configure an integrated DNS server on this IPA server, create DNS zone with the name of the IPA primary DNS domain, and fill it in with service records necessary for IPA deployment.
+In cases where the IPA server name does not belong to the primary DNS domain and is not resolvable using DNS, create a DNS zone containing the IPA server name as well.
+
+IPA provides an integrated DNS server which can be used to simplify IPA deployment. If you decide to use it, IPA will automatically maintain SRV and other service records when you change your topology.
+
+The DNS component in FreeIPA is optional and you may choose to manage all your DNS records manually on another third party DNS server. IPA DNS is not a general-purpose DNS server. If you need advanced features like DNS views, do not deploy IPA DNS.
+
+This command requires that an IPA server is already installed and configured.
+
 .SH "OPTIONS"
 .TP
 \fB\-d\fR, \fB\-\-debug\fR
diff --git a/install/tools/man/ipa-replica-install.1 b/install/tools/man/ipa-replica-install.1
index af37b0795..2c0966661 100644
--- a/install/tools/man/ipa-replica-install.1
+++ b/install/tools/man/ipa-replica-install.1
@@ -1,22 +1,7 @@
 .\" A man page for ipa-replica-install
-.\" Copyright (C) 2008-2012 Red Hat, Inc.
+.\" Copyright (C) 2008-2016  FreeIPA Contributors see COPYING for license
 .\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation, either version 3 of the License, or
-.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-.\" General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
-.\"
-.\" Author: Rob Crittenden <rcritten@redhat.com>
-.\"
-.TH "ipa-replica-install" "1" "May 16 2012" "FreeIPA" "FreeIPA Manual Pages"
+.TH "ipa-replica-install" "1" "Dec 19 2016" "FreeIPA" "FreeIPA Manual Pages"
 .SH "NAME"
 ipa\-replica\-install \- Create an IPA replica
 .SH "SYNOPSIS"
@@ -54,7 +39,9 @@ The Kerberos password for the given principal.
 .SS "DOMAIN LEVEL 1 CLIENT ENROLLMENT OPTIONS"
 To install client and promote it to replica using a host keytab or One Time Password, the host needs to be a member of ipaservers group. This requires to create a host entry and add it to the host group prior replica installation.
 
---server, --domain, --realm  options are autodiscovered via DNS records by default.
+\-\-server, \-\-domain, \-\-realm  options are autodiscovered via DNS records by default. See manual page
+.BR ipa\-client\-install (1)
+for further details about these options.
 
 .TP
 \fB\-p\fR \fIPASSWORD\fR, \fB\-\-password\fR=\fIPASSWORD\fR
@@ -67,10 +54,11 @@ Path to host keytab.
 The fully qualified domain name of the IPA server to enroll to.
 .TP
 \fB\-n\fR, \fB\-\-domain\fR=\fIDOMAIN\fR
-Set the domain name to DOMAIN.
+The primary DNS domain of an existing IPA deployment, e.g. example.com.
+This DNS domain should contain the SRV records generated by the IPA server installer.
 .TP
 \fB\-r\fR, \fB\-\-realm\fR=\fIREALM_NAME\fR
-Set the IPA realm name to REALM_NAME.
+The Kerberos realm of an existing IPA deployment.
 .TP
 \fB\-\-hostname\fR
 The hostname of this machine (FQDN). If specified, the hostname will be set and the system configuration will be updated to persist over reboot.
@@ -161,9 +149,17 @@ Skip check for updated CA DS schema on the remote master
 .SS "DNS OPTIONS"
 .TP
 \fB\-\-setup\-dns\fR
-Generate a DNS zone if it does not exist already and configure the DNS server.
+Configure  an integrated DNS server, create a primary DNS zone (name specified by \-\-domain or taken from an existing deployment), and fill it with service records necessary for IPA deployment.
+In cases where the IPA server name does not belong to the primary DNS domain and is not resolvable using DNS, create a DNS zone containing the IPA server name as well.
+
 This option requires that you either specify at least one DNS forwarder through
 the \fB\-\-forwarder\fR option or use the \fB\-\-no\-forwarders\fR option.
+
+Note that you can set up a DNS at any time after the initial IPA server install by running
+.B ipa-dns-install
+(see
+.BR ipa-dns-install (1)).
+IPA DNS cannot be uninstalled.
 .TP
 \fB\-\-forwarder\fR=\fIIP_ADDRESS\fR
 Add a DNS forwarder to the DNS configuration. You can use this option multiple
diff --git a/install/tools/man/ipa-server-install.1 b/install/tools/man/ipa-server-install.1
index 69316fb83..2249e221c 100644
--- a/install/tools/man/ipa-server-install.1
+++ b/install/tools/man/ipa-server-install.1
@@ -1,22 +1,7 @@
 .\" A man page for ipa-server-install
-.\" Copyright (C) 2008 Red Hat, Inc.
+.\" Copyright (C) 2008-2016  FreeIPA Contributors see COPYING for license
 .\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation, either version 3 of the License, or
-.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-.\" General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
-.\"
-.\" Author: Rob Crittenden <rcritten@redhat.com>
-.\"
-.TH "ipa-server-install" "1" "Jun 28 2012" "FreeIPA" "FreeIPA Manual Pages"
+.TH "ipa-server-install" "1" "Dec 19 2016" "FreeIPA" "FreeIPA Manual Pages"
 .SH "NAME"
 ipa\-server\-install \- Configure an IPA server
 .SH "SYNOPSIS"
@@ -28,10 +13,18 @@ Configures the services needed by an IPA server. This includes setting up a Kerb
 .SS "BASIC OPTIONS"
 .TP
 \fB\-r\fR \fIREALM_NAME\fR, \fB\-\-realm\fR=\fIREALM_NAME\fR
-The Kerberos realm name for the IPA server. You will not be able to estabilish trust with Active Directory unless the realm name is uppercased domain name.
+The Kerberos realm name for the new IPA deployment.
+
+It is strongly recommended to \fBuse an upper-cased name of the primary DNS domain name\fR of your IPA deployment. You will not be able to estabilish trust with Active Directory unless the realm name is the upper-cased domain name.
+
+The realm name cannot be changed after the installation.
 .TP
 \fB\-n\fR \fIDOMAIN_NAME\fR, \fB\-\-domain\fR=\fIDOMAIN_NAME\fR
-Your DNS domain name
+The primary DNS domain of the IPA deployment, e.g. example.com. This DNS domain should contain the SRV records generated by the IPA server installer. The specified DNS domain must not contain DNS records of any other LDAP or Kerberos based management system (like Active Directory or MIT Kerberos).
+
+It is strongly recommended to \fBuse a lower-cased name of the IPA Kerberos realm name.\fR
+
+The primary DNS domain name cannot be changed after the installation.
 .TP
 \fB\-p\fR \fIDM_PASSWORD\fR, \fB\-\-ds\-password\fR=\fIDM_PASSWORD\fR
 The password to be used by the Directory Server for the Directory Manager user
@@ -136,9 +129,15 @@ The certificate subject base (default O=REALM.NAME)
 Signing algorithm of the IPA CA certificate. Possible values are SHA1withRSA, SHA256withRSA, SHA512withRSA. Default value is SHA256withRSA. Use this option with --external-ca if the external CA does not support the default signing algorithm.
 
 .SS "DNS OPTIONS"
+IPA provides an integrated DNS server which can be used to simplify IPA deployment. If you decide to use it, IPA will automatically maintain SRV and other service records when you change your topology.
+
+The DNS component in FreeIPA is optional and you may choose to manage all your DNS records manually on another third party DNS server. IPA DNS is not a general-purpose DNS server. If you need advanced features like DNS views, do not deploy IPA DNS.
+
 .TP
 \fB\-\-setup\-dns\fR
-Generate a DNS zone if it does not exist already and configure the DNS server.
+Configure an integrated DNS server, create DNS zone specified by \-\-domain, and fill it with service records necessary for IPA deployment.
+In cases where the IPA server name does not belong to the primary DNS domain and is not resolvable using DNS, create a DNS zone containing the IPA server name as well.
+
 This option requires that you either specify at least one DNS forwarder through
 the \fB\-\-forwarder\fR option or use the \fB\-\-no\-forwarders\fR option.
 
@@ -146,6 +145,8 @@ Note that you can set up a DNS at any time after the initial IPA server install
 .B ipa-dns-install
 (see
 .BR ipa-dns-install (1)).
+IPA DNS cannot be uninstalled.
+
 .TP
 \fB\-\-forwarder\fR=\fIIP_ADDRESS\fR
 Add a DNS forwarder to the DNS configuration. You can use this option multiple