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>

1 files changed, 12 insertions, 19 deletions

diff --git a/client/man/ipa-client-install.1 b/client/man/ipa-client-install.1
index 9ae0b8bc4..319952cb6 100644
--- a/client/man/ipa-client-install.1
+++ b/client/man/ipa-client-install.1
@@ -1,22 +1,7 @@
 .\" A man page for ipa-client-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-client-install" "1" "Jan 31 2013" "FreeIPA" "FreeIPA Manual Pages"
+.TH "ipa-client-install" "1" "Dec 19 2016" "FreeIPA" "FreeIPA Manual Pages"
 .SH "NAME"
 ipa\-client\-install \- Configure an IPA client
 .SH "SYNOPSIS"
@@ -84,13 +69,21 @@ Consequences of the re\-enrollment on the host entry:
 .SS "BASIC OPTIONS"
 .TP
 \fB\-\-domain\fR=\fIDOMAIN\fR
-Set the domain name to DOMAIN. When no \-\-server option is specified, the installer will try to discover all available servers via DNS SRV record autodiscovery (see DNS Autodiscovery section for details).
+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. Usually the name is a lower-cased name of an IPA Kerberos realm name.
+
+When no \-\-server option is specified, this domain will be used by the installer to discover all available servers via DNS SRV record autodiscovery (see DNS Autodiscovery section for details).
+
+The default value used by the installer is the domain part of the hostname. This option needs to be specified if the primary IPA DNS domain is different from the default value.
 .TP
 \fB\-\-server\fR=\fISERVER\fR
 Set the FQDN of the IPA server to connect to. May be specified multiple times to add multiple servers to ipa_server value in sssd.conf or krb5.conf. Only the first value is considered when used with \-\-no\-sssd. When this option is used, DNS autodiscovery for Kerberos is disabled and a fixed list of KDC and Admin servers is configured.
+
+Under normal circumstances, this option is not needed as the list of servers is retrieved from the primary IPA DNS domain.
 .TP
 \fB\-\-realm\fR=\fIREALM_NAME\fR
-Set the IPA realm name to REALM_NAME. Under normal circumstances, this option is not needed as the realm name is retrieved from the IPA server.
+The Kerberos realm of an existing IPA deployment. Usually it is an upper-cased name of the primary DNS domain used by the IPA installation.
+
+Under normal circumstances, this option is not needed as the realm name is retrieved from the IPA server.
 .TP
 \fB\-\-fixed\-primary\fR
 Configure SSSD to use a fixed server as the primary IPA server. The default is to use DNS SRV records to determine the primary server to use and fall back to the server the client is enrolled with. When used in conjunction with \-\-server then no _srv_ value is set in the ipa_server option in sssd.conf.