ipa-join(1)

1ipa-join(1)                  FreeIPA Manual Pages                  ipa-join(1)
2
3
4

NAME

6       ipa-join - Join a machine to an IPA realm and get a keytab for the host
7       service principal
8

SYNOPSIS

10       ipa-join [-d|--debug] [-q|--quiet] [-u|--unenroll] [-h|--hostname host‐
11       name]  [-s|--server  hostame] [-k|--keytab filename] [-w|--bindpw pass‐
12       word] [-b|--basedn basedn] [-?|--help] [--usage]
13
14

DESCRIPTION

16       Joins a host to an IPA realm and retrieves a kerberos  keytab  for  the
17       host  service  principal,  or  unenrolls  an  enrolled host from an IPA
18       server.
19
20       Kerberos keytabs are used for services (like sshd) to perform  kerberos
21       authentication.  A  keytab is a file with one or more secrets (or keys)
22       for a kerberos principal.
23
24       The ipa-join command will create and retrieve a service  principal  for
25       host/foo.example.com@EXAMPLE.COM   and   place   it   by  default  into
26       /etc/krb5.keytab. The location can be overridden with the -k option.
27
28       The IPA server to contact is set in  /etc/ipa/default.conf  by  default
29       and can be overridden using the -s,--server option.
30
31       In order to join the machine needs to be authenticated. This can happen
32       in one of two ways:
33
34       * Authenticate using the current kerberos principal
35
36       * Provide a password to authenticate with
37
38       If a client host has already been joined to the IPA realm the  ipa-join
39       command  will  fail.  The  host will need to be removed from the server
40       using `ipa host-del FQDN` in order to join the client to the realm.
41
42       This command is normally executed by the ipa-client-install command  as
43       part of the enrollment process.
44
45       The  reverse  is  unenrollment. Unenrolling a host removes the Kerberos
46       key on the IPA server. This prepares the host to be  re-enrolled.  This
47       uses the host principal stored in /etc/krb5.conf to authenticate to the
48       IPA server to perform the unenrollment.
49
50       Please note, that while the ipa-join option removes the client from the
51       domain,  it  does  not actually uninstall the client or properly remove
52       all of the IPA-related configuration.  The  only  way  to  uninstall  a
53       client   completely  is  to  use  ipa-client-install  --uninstall  (see
54       ipa-client-install(1)).
55
56

OPTIONS

58       -h,--hostname hostname
59              The hostname of this server (FQDN). By default of nodename  from
60              uname(2) is used.
61
62       -s,--server server
63              The  hostname  of  the  IPA  server (FQDN). Note that by default
64              there is no /etc/ipa/default.conf, in most cases it needs to  be
65              supplied.
66
67       -k,--keytab keytab-file
68              The  keytab file where to append the new key (will be created if
69              it does not exist). Default: /etc/krb5.keytab
70
71       -w,--bindpw password
72              The password to use if not using Kerberos to authenticate. Use a
73              password  of  this particular host (one time password created on
74              IPA server)
75
76       -b,--basedn basedn
77              The basedn of the IPA server (of  the  form  dc=example,dc=com).
78              This  is only needed when not using Kerberos to authenticate and
79              anonymous binds are disallowed in the IPA LDAP server.
80
81       -f,--force
82              Force enrolling the host even if host entry exists.
83
84       -u,--unenroll
85              Unenroll this host from the  IPA  server.  No  keytab  entry  is
86              removed in the process (see ipa-rmkeytab(1)).
87
88       -q,--quiet
89              Quiet mode. Only errors are displayed.
90
91       -d,--debug
92              Print the raw XML-RPC output in GSSAPI mode.
93

EXAMPLES

95       Join IPA domain and retrieve a keytab with kerberos credentials.
96
97         # kinit admin
98         # ipa-join
99
100       Join IPA domain and retrieve a keytab using a one-time password.
101
102         # ipa-join -w secret123
103
104       Join IPA domain and save the keytab in another location.
105
106         # ipa-join -k /tmp/host.keytab
107

EXIT STATUS

109       The exit status is 0 on success, nonzero on error.
110
111       0 Success
112
113       1 Kerberos context initialization failed
114
115       2 Incorrect usage
116
117       3 Out of memory
118
119       4 Invalid service principal name
120
121       5 No Kerberos credentials cache
122
123       6 No Kerberos principal and no bind DN and password
124
125       7 Failed to open keytab
126
127       8 Failed to create key material
128
129       9 Setting keytab failed
130
131       10 Bind password required when using a bind DN
132
133       11 Failed to add key to keytab
134
135       12 Failed to close keytab
136
137       13 Host is already enrolled
138
139       14 LDAP failure
140
141       15 Incorrect bulk password
142
143       16 Host name must be fully-qualified
144
145       17 XML-RPC fault
146
147       18 Principal not found in host entry
148
149       19 Unable to generate Kerberos credentials cache
150
151       20 Unenrollment result not in XML-RPC response
152
153       21 Failed to get default Kerberos realm
154
155

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

EXIT STATUS

SEE ALSO