IntenseWebs/freeipa
3
0
Fork 0
mirror of https://salsa.debian.org/freeipa-team/freeipa.git synced 2024-12-30 10:47:08 -06:00
Code Issues Packages Projects Releases Wiki Activity
a38d93f65f
freeipa/ipa-client/man/ipa-join.1

143 lines
5.2 KiB
Groff
Raw Normal View History

Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.\" A man page for ipa-join
.\" Copyright (C) 2009 Red Hat, Inc.
.\"
Change FreeIPA license to GPLv3+ The changes include: * Change license blobs in source files to mention GPLv3+ not GPLv2 only * Add GPLv3+ license text * Package COPYING not LICENSE as the license blobs (even the old ones) mention COPYING specifically, it is also more common, I think https://fedorahosted.org/freeipa/ticket/239
2010-12-09 06:59:11 -06:00
.\" 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.
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.\"
.\" 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.
.\"
Change FreeIPA license to GPLv3+ The changes include: * Change license blobs in source files to mention GPLv3+ not GPLv2 only * Add GPLv3+ license text * Package COPYING not LICENSE as the license blobs (even the old ones) mention COPYING specifically, it is also more common, I think https://fedorahosted.org/freeipa/ticket/239
2010-12-09 06:59:11 -06:00
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.\"
.\" Author: Rob Crittenden <rcritten@redhat.com>
.\"
Improve man pages structure There are too many options in ipa-*-install scripts which makes it difficult to read. This patch adds subsections to install script online help and man pages to improve readability. No option has been changed. To further improve man pages: 1) All man pages were changed to have the same header and top-center title to provide united look. 2) Few typos in man pages have been fixed https://fedorahosted.org/freeipa/ticket/1687
2011-09-05 04:04:17 -05:00
.TH "ipa-join" "1" "Oct 8 2009" "FreeIPA" "FreeIPA Manual Pages"
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.SH "NAME"
ipa\-join \- Join a machine to an IPA realm and get a keytab for the host service principal
.SH "SYNOPSIS"
Make ipa-join work against an LDAP server that disallows anon binds We determine the realm in the client installer so we can deduce the base dn, pass that into ipa-join so we don't have to hunt for it. Re-order the bind so when doing an OTP enrollment so we can use the host entry to authenticate before we retrieve the subject base, then initiate the enrollment. If ipa-join is called without a basedn it will still attempt to determine it, but it will fail if anonymous binds are not allowed. https://fedorahosted.org/freeipa/ticket/1935
2011-10-11 16:30:33 -05:00
ipa\-join [\fB\-d\fR|\fB\-\-debug\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-u\fR|\fB\-\-unenroll\fR] [\fB\-h\fR|\fB\-\-hostname\fR hostname] [\fB\-s\fR|\fB\-\-server\fR hostame] [\fB\-k\fR|\fB\-\-keytab\fR filename] [\fB\-w\fR|\fB\-\-bindpw\fR password] [\fB-b\fR|\-\-\fBbasedn basedn\fR] [\fB\-?\fR|\fB\-\-help\fR] [\fB\-\-usage\fR]
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.SH "DESCRIPTION"
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
Joins a host to an IPA realm and retrieves a kerberos \fIkeytab\fR for the host service principal, or unenrolls an enrolled host from an IPA server.
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
Kerberos keytabs are used for services (like sshd) to perform kerberos authentication. A keytab is a file with one or more secrets (or keys) for a kerberos principal.
The ipa\-join command will create and retrieve a service principal for host/foo.example.com@EXAMPLE.COM and place it by default into /etc/krb5.keytab. The location can be overridden with the \-k option.
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
The IPA server to contact is set in /etc/ipa/default.conf by default and can be overridden using the \-s,\-\-server option.
Update available options and descriptions in client man pages
2010-02-24 10:38:59 -06:00
In order to join the machine needs to be authenticated. This can happen in one of two ways:
* Authenticate using the current kerberos principal
* Provide a password to authenticate with
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
If a client host has already been joined to the IPA realm the ipa\-join command will fail. The host will need to be removed from the server using `ipa host\-del FQDN` in order to join the client to the realm.
Update available options and descriptions in client man pages
2010-02-24 10:38:59 -06:00
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
This command is normally executed by the ipa\-client\-install command as part of the enrollment process.
The reverse is unenrollment. Unenrolling a host removes the Kerberos key on the IPA server. This prepares the host to be re\-enrolled. This uses the host principal stored in /etc/krb5.conf to authenticate to the IPA server to perform the unenrollment.
Improve ipa-join man page Make it clear in man pages that ipa-join -u does not remove keytab. https://fedorahosted.org/freeipa/ticket/1317
2011-09-05 05:34:43 -05:00
Please note, that while the ipa\-join option removes the client from the domain, it does not actually uninstall the client or properly remove all of the IPA\-related configuration. The only way to uninstall a client completely is to use ipa\-client\-install \-\-uninstall
(see
.BR ipa\-client\-install (1)).
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.SH "OPTIONS"
.TP
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
\fB\-h,\-\-hostname hostname\fR
Update available options and descriptions in client man pages
2010-02-24 10:38:59 -06:00
The hostname of this server (FQDN). By default of nodename from uname(2) is used.
.TP
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
\fB\-s,\-\-server server\fR
Fixes in ipa-join man page https://fedorahosted.org/freeipa/ticket/784 https://fedorahosted.org/freeipa/ticket/786 https://fedorahosted.org/freeipa/ticket/787
2011-02-15 07:22:13 -06:00
The hostname of the IPA server (FQDN). Note that by default there is no /etc/ipa/default.conf, in most cases it needs to be supplied.
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.TP
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
\fB\-k,\-\-keytab keytab\-file\fR
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
The keytab file where to append the new key (will be created if it does not exist). Default: /etc/krb5.keytab
.TP
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
\fB\-w,\-\-bindpw password\fR
Fixes in ipa-join man page https://fedorahosted.org/freeipa/ticket/784 https://fedorahosted.org/freeipa/ticket/786 https://fedorahosted.org/freeipa/ticket/787
2011-02-15 07:22:13 -06:00
The password to use if not using Kerberos to authenticate. Use a password of this particular host (one time password created on IPA server)
Update available options and descriptions in client man pages
2010-02-24 10:38:59 -06:00
.TP
Make ipa-join work against an LDAP server that disallows anon binds We determine the realm in the client installer so we can deduce the base dn, pass that into ipa-join so we don't have to hunt for it. Re-order the bind so when doing an OTP enrollment so we can use the host entry to authenticate before we retrieve the subject base, then initiate the enrollment. If ipa-join is called without a basedn it will still attempt to determine it, but it will fail if anonymous binds are not allowed. https://fedorahosted.org/freeipa/ticket/1935
2011-10-11 16:30:33 -05:00
\fB\-b,\-\-basedn basedn\fR
The basedn of the IPA server (of the form dc=example,dc=com). This is only needed when not using Kerberos to authenticate and anonymous binds are disallowed in the IPA LDAP server.
.TP
Add support for re-enrolling hosts using keytab A host that has been recreated and does not have its host entry disabled or removed, can be re-enrolled using a previously backed up keytab file. A new option --keytab has been added to ipa-client-install. This can be used to specify path to the keytab and can be used instead of -p or -w options. A new option -f has been added to ipa-join. It forces client to join even if the host entry already exits. A new certificate, ssh keys are generated, ipaUniqueID stays the same. Design page: http://freeipa.org/page/V3/Client_install_using_keytab https://fedorahosted.org/freeipa/ticket/3374
2013-02-26 06:20:13 -06:00
\fB\-f,\-\-force\fR
Force enrolling the host even if host entry exists.
.TP
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
\fB\-u,\-\-unenroll\fR
Improve ipa-join man page Make it clear in man pages that ipa-join -u does not remove keytab. https://fedorahosted.org/freeipa/ticket/1317
2011-09-05 05:34:43 -05:00
Unenroll this host from the IPA server. No keytab entry is removed in the process
(see
.BR ipa-rmkeytab (1)).
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
.TP
\fB\-q,\-\-quiet\fR
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
Quiet mode. Only errors are displayed.
.TP
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
\fB\-d,\-\-debug\fR
Fixes in ipa-join man page https://fedorahosted.org/freeipa/ticket/784 https://fedorahosted.org/freeipa/ticket/786 https://fedorahosted.org/freeipa/ticket/787
2011-02-15 07:22:13 -06:00
Print the raw XML-RPC output in GSSAPI mode.
Add man page for ipa-join command
2009-10-08 10:10:21 -05:00
.SH "EXAMPLES"
Join IPA domain and retrieve a keytab with kerberos credentials.
# kinit admin
# ipa\-join
Join IPA domain and retrieve a keytab using a one\-time password.
# ipa\-join \-w secret123
Join IPA domain and save the keytab in another location.
# ipa\-join \-k /tmp/host.keytab
.SH "EXIT STATUS"
The exit status is 0 on success, nonzero on error.
Unenroll the client from the IPA server on uninstall. Unenrollment means that the host keytab is disabled on the server making it possible to re-install on the client. This host principal is how we distinguish an enrolled vs an unenrolled client machine on the server. I added a --unroll option to ipa-join that binds using the host credentials and disables its own keytab. I fixed a couple of other unrelated problems in ipa-join at the same time. I also documented all the possible return values of ipa-getkeytab and ipa-join. There is so much overlap because ipa-join calls ipa-getkeytab and it returns whatever value ipa-getkeytab returned on failure. ticket 242
2010-09-17 20:37:32 -05:00
0 Success
1 Kerberos context initialization failed
2 Incorrect usage
3 Out of memory
4 Invalid service principal name
5 No Kerberos credentials cache
6 No Kerberos principal and no bind DN and password
7 Failed to open keytab
8 Failed to create key material
9 Setting keytab failed
10 Bind password required when using a bind DN
11 Failed to add key to keytab
12 Failed to close keytab
13 Host is already enrolled
14 LDAP failure
15 Incorrect bulk password
16 Host name must be fully\-qualified
17 XML\-RPC fault
18 Principal not found in host entry
19 Unable to generate Kerberos credentials cache
20 Unenrollment result not in XML\-RPC response
Unchecked return values in ipa-join krb5_get_default_realm() and asprintf() return values were ignored. This could lead to unhandled error issues or memory access issues. This patch adds return value checks to all such functions. As a consequence, one new return value has been added to man page. https://fedorahosted.org/freeipa/ticket/720
2011-01-11 04:48:22 -06:00
21 Failed to get default Kerberos realm
Improve ipa-join man page Make it clear in man pages that ipa-join -u does not remove keytab. https://fedorahosted.org/freeipa/ticket/1317
2011-09-05 05:34:43 -05:00
.SH "SEE ALSO"
.BR ipa-rmkeytab (1)
Fix various typos. https://fedorahosted.org/freeipa/ticket/3089
2012-09-16 11:35:56 -05:00
.BR ipa-client-install (1)
Reference in New Issue Copy Permalink