URL: https://github.com/freeipa/freeipa/pull/362 Author: stlaz Title: #362: Clarify meaning of --domain and --realm in installers Action: synchronized
To pull the PR as Git branch: git remote add ghfreeipa https://github.com/freeipa/freeipa git fetch ghfreeipa pull/362/head:pr362 git checkout pr362
From c3232015baf2f519bd887f2f70082e031a1a31cd Mon Sep 17 00:00:00 2001 From: Stanislav Laznicka <slazn...@redhat.com> Date: Mon, 2 Jan 2017 13:22:07 +0100 Subject: [PATCH] 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 --- client/man/ipa-client-install.1 | 31 ++++++++++--------------- install/tools/man/ipa-dns-install.1 | 27 ++++++++-------------- install/tools/man/ipa-replica-install.1 | 38 ++++++++++++++---------------- install/tools/man/ipa-server-install.1 | 41 +++++++++++++++++---------------- ipalib/install/service.py | 6 +++-- 5 files changed, 64 insertions(+), 79 deletions(-) diff --git a/client/man/ipa-client-install.1 b/client/man/ipa-client-install.1 index 9ae0b8b..319952c 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 <rcrit...@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. diff --git a/install/tools/man/ipa-dns-install.1 b/install/tools/man/ipa-dns-install.1 index ad937cc..3ae9f6d 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 <rcrit...@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 af37b07..2c09666 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 <rcrit...@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 69316fb..2249e22 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 <rcrit...@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 diff --git a/ipalib/install/service.py b/ipalib/install/service.py index fc430fb..73b8fd8 100644 --- a/ipalib/install/service.py +++ b/ipalib/install/service.py @@ -103,7 +103,8 @@ class ServiceInstallInterface(common.Installable, domain_name = knob( str, None, - description="domain name", + description="primary DNS domain of the IPA deployment " + "(not necessarily related to the current hostname)", cli_names='--domain', ) @@ -121,7 +122,8 @@ def domain_name(self, value): realm_name = knob( str, None, - description="realm name", + description="Kerberos realm name of the IPA deployment (typically" + "an upper-cased name of the primary DNS domain)", cli_names='--realm', )
-- Manage your subscription for the Freeipa-devel mailing list: https://www.redhat.com/mailman/listinfo/freeipa-devel Contribute to FreeIPA: http://www.freeipa.org/page/Contribute/Code
