URL: https://github.com/freeipa/freeipa/pull/352 Author: pspacek Title: #352: Clarify meaning of --domain and --realm in installers Action: opened
PR body: """ Man pages need bigger overhaul. Take this as hot-fix for FAQ. https://fedorahosted.org/freeipa/ticket/6574 """ To pull the PR as Git branch: git remote add ghfreeipa https://github.com/freeipa/freeipa git fetch ghfreeipa pull/352/head:pr352 git checkout pr352
From b3787598a84918614032dbdf4774eee6918500be Mon Sep 17 00:00:00 2001 From: Petr Spacek <pspa...@redhat.com> Date: Mon, 19 Dec 2016 15:09:59 +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 | 29 +++++++++-------------- install/tools/man/ipa-replica-install.1 | 40 +++++++++++++++----------------- install/tools/man/ipa-server-install.1 | 41 +++++++++++++++++---------------- ipalib/install/service.py | 6 +++-- 5 files changed, 66 insertions(+), 81 deletions(-) diff --git a/client/man/ipa-client-install.1 b/client/man/ipa-client-install.1 index 9ae0b8b..ae769bc 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 existing IPA deployment e.g. example.com. This DNS domain should contain the SRV records generated by IPA server installer. Usually the name is lower-cased name of 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). + +Default value used by the installer is domain part of the hostname. This option needs to be specified if the primary IPA DNS domain is different than 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 existing IPA deployment. Usually it is 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..1f1e9a4 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> +.\" A man page for ipa-server-install +.\" 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 integrated DNS server on this IPA server, create DNS zone with name of the IPA primary DNS domain, and fill it in with service records necessary for IPA deployment. +In cases where IPA server name does not belong to the primary DNS domain and is not resolvable using DNS, create DNS zone containing IPA server name as well. + +IPA provides an integrated DNS server which can be used to ease IPA deployment. If you decide to use it, IPA will automatically maintain SRV and other service records when you change your topology. + +DNS component in FreeIPA is optional and you may choose to manage all your DNS records manually in other 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 the 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..6baf8c3 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. +.\" A man page for ipa-server-install +.\" 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 existing IPA deployment e.g. example.com. +This DNS domain should contain the SRV records generated by 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 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 integrated DNS server, create primary DNS zone (named specified by \-\-domain or taken from existing deployment), and fill it in with service records necessary for IPA deployment. +In cases where IPA server name does not belong to the primary DNS domain and is not resolvable using DNS, create DNS zone containing 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..1fac96d 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 upper-cased name of 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 upper-cased domain name. + +The realm name cannot be changed after 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 IPA server installer. Specified DNS domain must not contain DNS records for any other LDAP or Kerberos based management system (like Active Directory or MIT Kerberos). + +It is strongly recommended to \fBuse lower-cased name of IPA Kerberos realm name.\fR + +The primary DNS domain name cannot be changed after 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 ease IPA deployment. If you decide to use it, IPA will automatically maintain SRV and other service records when you change your topology. + +DNS component in FreeIPA is optional and you may choose to manage all your DNS records manually in other 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 integrated DNS server, create DNS zone specified by \-\-domain, and fill it in with service records necessary for IPA deployment. +In cases where IPA server name does not belong to the primary DNS domain and is not resolvable using DNS, create DNS zone containing 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..e18b273 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 necessairly related to 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 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
