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

OPTIONS

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

EXAMPLES

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

WINSYNC

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

PASSSYNC

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

EXIT STATUS

321       0 if the command was successful
322
323       1 if an error occurred
324
325
326
327FreeIPA                           Jul 12 2016            ipa-replica-manage(1)
Impressum