1ipa-replica-manage(1)          IPA Manual Pages          ipa-replica-manage(1)
2
3
4

NAME

6       ipa-replica-manage - Manage an IPA replica
7

SYNOPSIS

9       ipa-replica-manage [OPTION]... [COMMAND]
10

DESCRIPTION

12       Manages the replication agreements of an IPA server.
13
14       To manage IPA replication agreements in a domain at domain level 1, use
15       IPA CLI or Web UI, see `ipa help topology` for additional information.
16
17       The available commands are:
18
19       connect [SERVER_A] <SERVER_B>
20              - Adds a new replication  agreement  between  SERVER_A/localhost
21              and  SERVER_B.  At  domain  level  1 applicable only for winsync
22              agreements.
23
24       disconnect [SERVER_A] <SERVER_B>
25              - Removes a replication agreement between SERVER_A/localhost and
26              SERVER_B.  At  domain level 1 applicable only for winsync agree‐
27              ments.
28
29       del <SERVER>
30              - Removes all replication agreements and data about  SERVER.  At
31              domain  level 1 it removes data and agreements for both suffixes
32              - domain and ca.
33
34       list [SERVER]
35              - Lists all the servers or the list of agreements of SERVER
36
37       re-initialize
38              - Forces a full re-initialization of the IPA  server  retrieving
39              data from the server specified with the --from option
40
41       force-sync
42              -  Immediately  flush  any  data  to be replicated from a server
43              specified with the --from option
44
45       list-ruv
46              - List the replication IDs on this server.
47
48       clean-ruv [REPLICATION_ID]
49              - Run the CLEANALLRUV task to remove a replication ID.
50
51       clean-dangling-ruv
52              - Cleans all RUVs and CS-RUVs that are left in the  system  from
53              uninstalled replicas.
54
55       abort-clean-ruv [REPLICATION_ID]
56              - Abort a running CLEANALLRUV task. With --force option the task
57              does not wait for all the replica servers to have been sent  the
58              abort task, or be online, before completing.
59
60       list-clean-ruv
61              - List all running CLEANALLRUV and abort CLEANALLRUV tasks.
62
63       dnarange-show [SERVER]
64              - List the DNA ranges
65
66       dnarange-set SERVER START-END
67              - Set the DNA range on a master
68
69       dnanextrange-show [SERVER]
70              - List the next DNA ranges
71
72       dnanextrange-set SERVER START-END
73              - Set the DNA next range on a master
74
75       The  connect  and disconnect options are used to manage the replication
76       topology. When a replica is created it is only connected with the  mas‐
77       ter  that  created  it. The connect option may be used to connect it to
78       other existing replicas.
79
80       The disconnect option cannot be used to  remove  the  last  link  of  a
81       replica. To remove a replica from the topology use the del option.
82
83       If  a  replica  is  deleted and then re-added within a short time-frame
84       then the 389-ds instance on  the  master  that  created  it  should  be
85       restarted  before  re-installing  the replica. The master will have the
86       old service principals cached which will cause replication to fail.
87
88       Each IPA master server has a unique replication ID. This ID is used  by
89       389-ds-base when storing information about replication status. The out‐
90       put consists of the masters and their respective  replication  ID.  See
91       clean-ruv
92
93       When a master is removed, all other masters need to remove its replica‐
94       tion ID from the list of masters. Normally  this  occurs  automatically
95       when  a  master is deleted with ipa-replica-manage. If one or more mas‐
96       ters was down or unreachable when ipa-replica-manage was executed  then
97       this  replica  ID may still exist. The clean-ruv command may be used to
98       clean up an unused replication ID.
99
100       NOTE: clean-ruv is VERY DANGEROUS. Execution against the wrong replica‐
101       tion  ID  can  result  in  inconsistent data on that master. The master
102       should be re-initialized from another if this happens.
103
104       The replication topology is examined when a master is deleted and  will
105       attempt  to  prevent a master from being orphaned. For example, if your
106       topology is A <-> B <-> C and you attempt to delete master  B  it  will
107       fail because that would leave masters and A and C orphaned.
108
109       The  list  of  masters  is  stored in cn=masters,cn=ipa,cn=etc,dc=exam‐
110       ple,dc=com. This should be cleaned up automatically when  a  master  is
111       deleted.  If  it  occurs  that  you have deleted the master and all the
112       agreements but these entries still exist then you will not be  able  to
113       re-install IPA on it, the installation will fail with:
114
115       An  IPA  master  host cannot be deleted or disabled using standard com‐
116       mands (host-del, for example).
117
118       An orphaned master may be cleaned up using the del directive  with  the
119       --cleanup   option.   This   will   remove  the  entries  from  cn=mas‐
120       ters,cn=ipa,cn=etc that otherwise prevent host-del  from  working,  its
121       dna  profile, s4u2proxy configuration, service principals and remove it
122       from the default DUA profile defaultServerList.
123

OPTIONS

125       -H HOST, --host=HOST
126              The IPA server to manage.  The default is the machine  on  which
127              the command is run Not honoured by the re-initialize command.
128
129       -p DM_PASSWORD, --password=DM_PASSWORD
130              The Directory Manager password to use for authentication
131
132       -v, --verbose
133              Provide additional information
134
135       -f, --force
136              Ignore some types of errors, don't prompt when deleting a master
137
138       -c, --cleanup
139              When  deleting  a  master with the --force flag, remove leftover
140              references to an already deleted master.
141
142       --no-lookup
143              Do not perform DNS lookup checks.
144
145       --binddn=ADMIN_DN
146              Bind DN to use with remote server (default is cn=Directory  Man‐
147              ager) - Be careful to quote this value on the command line
148
149       --bindpw=ADMIN_PWD
150              Password  for  Bind DN to use with remote server (default is the
151              DM_PASSWORD above)
152
153       --winsync
154              Specifies to create/use a Windows Sync Agreement
155
156       --cacert=/path/to/cacertfile
157              Full path and filename of CA certificate to use with TLS/SSL  to
158              the remote server - this CA certificate will be installed in the
159              directory server's certificate database
160
161       --win-subtree=cn=Users,dc=example,dc=com
162              DN of Windows subtree containing the  users  you  want  to  sync
163              (default  cn=Users,<domain suffix> - this is typically what Win‐
164              dows AD uses as the default value) - Be careful  to  quote  this
165              value on the command line
166
167       --passsync=PASSSYNC_PWD
168              Password  for  the  IPA system user used by the Windows PassSync
169              plugin to synchronize passwords. Required when using  --winsync.
170              This does not mean you have to use the PassSync service.
171
172       --from=SERVER
173              The  server to pull the data from, used by the re-initialize and
174              force-sync commands.
175
176
177       RANGES
178              IPA uses the 389-ds Distributed Numeric Assignment (DNA)  Plugin
179              to  allocate  POSIX ids for users and groups. A range is created
180              when IPA is installed and half the  range  is  assigned  to  the
181              first IPA master for the purposes of allocation.
182
183       New  IPA  masters  do  not  automatically get a DNA range assignment. A
184       range assignment is done only when a user or POSIX group  is  added  on
185       that master.
186
187       The  DNA plugin also supports an "on-deck" or next range configuration.
188       When the primary range is exhaused, rather than going to another master
189       to  ask for more, it will use its on-deck range if one is defined. Each
190       master can have only one range and one on-deck range defined.
191
192       When a master is removed an attempt is made to save  its  DNA  range(s)
193       onto  another  master  in  its  on-deck  range. IPA will not attempt to
194       extend or merge ranges. If there are no available on-deck  range  slots
195       then this is reported to the user. The range is effectively lost unless
196       it is manually merged into the range of another master.
197
198       The DNA range and on-deck  (next)  values  can  be  managed  using  the
199       dnarange-set  and  dnanextrange-set  commands.  The  rules for managing
200       these ranges are:
201              - The range must be completely contained within a local range as
202              defined by the ipa idrange command.
203
204              -  The  range  cannot  overlap the DNA range or on-deck range on
205              another IPA master.
206
207              - The range cannot overlap the ID range of an AD Trust.
208
209              - The primary DNA range cannot be removed.
210
211              - An on-deck range range can be removed by setting  it  to  0-0.
212              The  assumption  is  that  the  range  will be manually moved or
213              merged elsewhere.
214
215       The range and next range of a specific master can be displayed by pass‐
216       ing  the  FQDN of that master to the dnarange-show or dnanextrange-show
217       command.
218
219       Performing range changes as a delegated administrator (e.g.  not  using
220       the  Directory Manager password) requires additional 389-ds ACIs. These
221       are installed in upgraded masters but not existing ones. The changs are
222       made  in  cn=config  which  is  not  replicated. The result is that DNA
223       ranges cannot be managed on non-upgraded masters as a delegated  admin‐
224       istrator.
225

EXAMPLES

227       List all masters:
228               # ipa-replica-manage list
229               srv1.example.com: master
230               srv2.example.com: master
231               srv3.example.com: master
232               srv4.example.com: master
233
234       List a server's replication agreements.
235               # ipa-replica-manage list srv1.example.com
236               srv2.example.com: replica
237               srv3.example.com: replica
238
239       Re-initialize a replica:
240               # ipa-replica-manage re-initialize --from srv2.example.com
241
242              This will re-initialize the data on the server where you execute
243              the command,  retrieving  the  data  from  the  srv2.example.com
244              replica
245
246       Add a new replication agreement:
247               # ipa-replica-manage connect srv2.example.com srv4.example.com
248
249       Remove an existing replication agreement:
250               #  ipa-replica-manage  disconnect  srv1.example.com  srv3.exam‐
251              ple.com
252
253       Completely remove a replica:
254               # ipa-replica-manage del srv4.example.com
255
256       Using connect/disconnect you can manage the replication topology.
257
258       List the replication IDs in use:
259               # ipa-replica-manage list-ruv
260               Replica Update Vectors:
261                   srv1.example.com:389: 7
262                   srv2.example.com:389: 4
263               Certificate Server Replica Update Vectors:
264                   srv1.example.com:389: 9
265
266       Remove references to an orphaned and deleted master:
267               # ipa-replica-manage del --force --cleanup master.example.com
268

WINSYNC

270       Creating a Windows AD Synchronization agreement is similar to  creating
271       an IPA replication agreement, there are just a couple of extra steps.
272
273       A  special  user  entry  is created for the PassSync service. The DN of
274       this entry is uid=passsync,cn=sysaccounts,cn=etc,<basedn>. You are  not
275       required to use PassSync to use a Windows synchronization agreement but
276       setting a password for the user is required.
277
278       The following examples use the AD administrator account as the synchro‐
279       nization user. This is not mandatory but the user must have read-access
280       to the subtree.
281
282
283       1. Transfer the base64-encoded Windows AD CA Certificate  to  your  IPA
284       Server
285
286       2. Remove any existing kerberos credentials
287                # kdestroy
288
289       3. Add the winsync replication agreement
290                #   ipa-replica-manage   connect  --winsync  --passsync=<bind‐
291              pwd_for_syncuser_that     will_be_used_for_agreement>     --cac‐
292              ert=/path/to/adscacert/WIN-CA.cer    --binddn    "cn=administra‐
293              tor,cn=users,dc=ad,dc=example,dc=com" --bindpw  <ads_administra‐
294              tor_password> -v <adserver.fqdn>
295
296       You will be prompted to supply the Directory Manager's password.
297
298       Create a winsync replication agreement:
299
300               #   ipa-replica-manage  connect  --winsync  --passsync=MySecret
301              --cacert=/root/WIN-CA.cer        --binddn        "cn=administra‐
302              tor,cn=users,dc=ad,dc=example,dc=com"  --bindpw MySecret -v win‐
303              dows.ad.example.com
304
305
306       Remove a winsync replication agreement:
307               # ipa-replica-manage disconnect windows.ad.example.com
308

PASSSYNC

310       PassSync is a Windows service that runs on  AD  Domain  Controllers  to
311       intercept  password changes. It sends these password changes to the IPA
312       LDAP server over TLS. These password changes bypass normal IPA password
313       policy settings and the password is not set to immediately expire. This
314       is because by the time IPA receives the password change it has  already
315       been accepted by AD so it is too late to reject it.
316
317       IPA  maintains  a  list  of DNs that are exempt from password policy. A
318       special user is added automatically when a winsync  replication  agree‐
319       ment  is  created.  The  DN of this user is added to the exemption list
320       stored in passSyncManagersDNs in  the  entry  cn=ipa_pwd_extop,cn=plug‐
321       ins,cn=config.
322

EXIT STATUS

324       0 if the command was successful
325
326       1 if an error occurred
327
328
329
330IPA                               Jul 12 2016            ipa-replica-manage(1)
Impressum