Directory Cleanup Commands

The cleanup commands remove what is left in Active Directory after a domain controller, a domain, or a trust is gone: a dead domain controller's NTDS Settings, server, and computer objects and its replication memberships; an orphaned domain's remaining domain controller metadata, its crossRef, and its partition; or this forest's side of a trust. They also record in the Manager that an object no longer exists, so that its inventory stops presenting it.

Note: Important: A cleanup cannot be undone. To bring back a domain controller whose metadata has been cleaned up, you must promote a new one. Run the plan first, read it, and confirm only when every object it lists should go.

For how to run cdr and the global options, see Command-Line Reference.

How a cleanup runs

1. Plan (the default)—Without --confirm, cdr cleanup dc, domain, and trust are a dry run. They bind to a domain controller, read the directory, and print every object they would remove, in the order they would remove it, followed by any refusals. Nothing is changed.

2. Checks—Anything that can be checked beforehand is checked, and a failed check is a refusal, not a warning. For example, a domain controller that still answers is refused, because removing the metadata of a running domain controller is the worst outcome available. A few refusals can be passed with --force when you know something the tool cannot; the others cannot be overridden. See Refusal codes.

3. Removal—With --confirm and the object's own name, the objects are removed in order. NTDS Settings goes first, because that is what makes Active Directory treat the domain controller as removed and replicate the removal; the rest is tidying up the objects it leaves behind. If an object cannot be removed, the cleanup stops there and leaves everything after it alone, and the command exits with code 7. An object that is already gone is reported as absent, which is normal after a partial cleanup by hand.

4. Retirement—After a successful removal, cdr tells the Manager that the object is gone, with the reason you gave. If nothing was left to remove, a confirmed run still records the retirement. If recording it fails, the directory change stands, and cdr tells you the command that records it. Use --skip-retire to leave the Manager's inventory unchanged.

Exit codes: 0 when the plan was shown or the cleanup succeeded; 4 when the cleanup is refused; 7 when it stopped partway.

Required rights

• Directory rights—An account with Domain Admin rights in the affected domain, or Enterprise Admin rights. Removing a domain from the forest needs Enterprise Admin rights. cdr uses your own Windows identity, or the account in --user, whose password is read from the CYGNADR_CLEANUP_PASSWORD environment variable or prompted for. The credential goes only to the directory; the Manager never sees it, and the domain controller's security log records who removed what.
• Manager capabilities—Without --server, cdr asks the Manager for a domain controller it knows is up, which needs the environment.view capability. Recording a retirement needs the backup.manage capability (Backup Operator role).
• Windows—The cleanup dc, domain, and trust commands run on Windows only, and need LDAP access to the domain controller they bind to.

Options shared by cleanup dc, domain, and trust

Option	Description
-s, --server <DC>	The domain controller to bind to, by name or IP address. Default: one the Manager knows is up.
-u, --user <ACCOUNT>	The account to use, as DOMAIN\user or user@domain. The password is read from CYGNADR_CLEANUP_PASSWORD, or prompted for. Default: your own Windows identity.
--confirm <NAME>	Type the object's own name—the domain controller's FQDN, the domain's FQDN, or the trust partner's name—to carry out the removal. Without it, the command only shows the plan.
--force	Pass the refusals that can be overridden. Never all of them. Only with --confirm.
--skip-dns	Leave DNS records in place.
--skip-sites	Leave a site object in place when its last server is removed.
--skip-retire	Do not tell the Manager that the object is gone. Its inventory keeps showing it.
--reason <TEXT>	Why the object was removed. Recorded with the Manager's record of the object. Required with --confirm, unless you give --skip-retire.

cleanup list

Lists what the Manager's inventory suggests can be cleaned up, and why: domain controllers that have been missing from every directory read for a period. With --retired, it lists the machines already recorded as removed instead.

Requirements: The environment.view capability (every role).

Syntax

cdr cleanup list [options]

Options

Option	Description
--stale-days <DAYS>	How long a domain controller must have been missing from every directory read to be listed. Minimum: 1. Default: 30.
--retired	List machines already recorded as removed, instead of candidates for removal.

Examples

cdr cleanup list --stale-days 90
cdr cleanup list --retired

cleanup dc

Removes a dead domain controller's objects and metadata from the directory: its NTDS Settings and DNS Settings objects, its server object, its computer object, its FRS or DFSR replication memberships, and, unless you skip them, its DNS records and a site left with no servers.

The plan is refused if the domain controller still answers, holds an operations master role (seize the roles elsewhere first), or is the last domain controller in its domain.

Requirements: See Required rights.

Syntax

cdr cleanup dc <FQDN> [options]

Argument	Description
<FQDN>	Required. The domain controller to remove from the directory.

Takes the shared cleanup options.

Examples

cdr cleanup dc dc09.corp.example.com --server dc01.corp.example.com
cdr cleanup dc dc09.corp.example.com -u CORP\Administrator --confirm dc09.corp.example.com --reason "Hardware failed; replaced by dc11"

cleanup domain

Removes a dead domain from the forest: the metadata of its remaining domain controllers, the application partitions beneath it that no other domain controller hosts, this forest's own trusts that name it, and then its crossRef and partition.

The plan is refused for the forest root domain, for a domain that still has domain controllers or that a trust still references, and for a domain with a child domain or an application partition still in use. A domain whose domain controller objects are only leftover metadata can be removed with --force, after you have confirmed that none of them is running.

Requirements: See Required rights. Removing a domain needs Enterprise Admin rights.

Syntax

cdr cleanup domain <FQDN> [options]

Argument	Description
<FQDN>	Required. The domain to remove from the forest.

Takes the shared cleanup options.

Examples

cdr cleanup domain blue.corp.example.com
cdr cleanup domain blue.corp.example.com --force --confirm blue.corp.example.com --reason "Orphaned crossRef; its DC objects are residue"

cleanup trust

Removes this forest's side of a trust with another forest, domain, or realm, together with its trust account. The partner keeps its own side; remove that separately on the partner. The plan says what kind of trust it is about to remove.

Requirements: See Required rights.

Syntax

cdr cleanup trust <PARTNER> [options]

Argument or option	Description
<PARTNER>	Required. The trust partner: the other forest, domain, or realm.
--from <DOMAIN>	Which of this forest's domains holds the local side. Default: found automatically when there is only one.

Also takes the shared cleanup options.

Examples

cdr cleanup trust partner.example.com --from corp.example.com
cdr cleanup trust partner.example.com --confirm partner.example.com --reason "Partnership ended; agreed removal date passed"

cleanup retire

Records that a domain controller, domain, or trust is no longer defined in the directory. Use it for an object that someone removed by other means, so that there is nothing left for a cleanup command to remove. It changes the Manager's inventory only. The Manager checks the claim: it refuses, and the command exits with code 4, if a current complete read of the directory still lists the object, or if the object is not in its inventory.

Discovery records most removals by itself. Use this command for removals it holds for review, or that it has not yet waited long enough to confirm.

Requirements: The backup.manage capability (Backup Operator role).

Syntax

cdr cleanup retire <NAME> --reason <TEXT> [options]

Argument or option	Description
<NAME>	Required. What the directory no longer defines: a domain controller's FQDN, a domain's FQDN, or a trust partner's name. A trust can also be named from-domain->partner, as alerts print it.
--kind <KIND>	dc, domain, or trust. Default: dc.
--from <DOMAIN>	With --kind trust, only this domain's trust to the partner. Default: every domain's trust to the partner.
--reason <TEXT>	Required. Why it is gone. Recorded with the Manager's record of the object.

Examples

cdr cleanup retire dc02.corp.example.com --reason "Demoted and metadata-cleaned by hand in 2023"
cdr cleanup retire partner.example.com --kind trust --from corp.example.com --reason "Forest trust removed in Active Directory Domains and Trusts"

cleanup unretire

Withdraws the Manager's record that an object is gone, so that the inventory presents it again. It changes the Manager's inventory only, and nothing in the directory.

Requirements: The backup.manage capability (Backup Operator role).

Syntax

cdr cleanup unretire <KIND> <KEY>

Argument	Description
<KIND>	Required. What was recorded as gone: dc, domain, or trust.
<KEY>	Required. The object: a domain controller's FQDN, a domain's FQDN, or the trust partner's name.

Example

cdr cleanup unretire dc dc09.corp.example.com

cleanup forget

Deletes a retired domain controller's record from the Manager when nothing else refers to it. It does not touch the directory. Without --confirm, it says what would happen. The Manager keeps the record while any of these is true, and the command lists which:

• It is not recorded as removed from the directory.
• An agent is still enrolled under that name.
• Backup jobs exist for it.
• A backup schedule still names it.

Requirements: The backup.manage capability (Backup Operator role).

Syntax

cdr cleanup forget <FQDN> [--confirm <FQDN>]

Argument or option	Description
<FQDN>	Required. The retired domain controller whose record is deleted from the Manager.
--confirm <NAME>	Type the machine's own name to delete its record. Without it, cdr only says what would happen.

Examples

cdr cleanup forget dc02.corp.example.com
cdr cleanup forget dc02.corp.example.com --confirm dc02.corp.example.com

Refusal codes

The plan output names each refusal by its code. Refusals marked as overridable can be passed with --force together with --confirm; cdr still prints them before anything runs, and the JSON output lists them as overridden.

Code	Meaning	Overridable
target-is-alive	The domain controller answered when contacted. It may be running and replicating, or the answer may come from a stale DNS record or a rebuilt machine with the same name.	Yes
holds-fsmo-roles	The domain controller holds an operations master role. Seize the role on another domain controller first.	No
last-dc-in-domain	Removing it would leave its domain with no domain controllers. To remove the domain, use cdr cleanup domain.	No
domain-unknown	The domain the machine belonged to could not be worked out, typically after a partial demotion. Only its configuration partition objects can be removed.	Yes
presence-unknown	Whether an object exists could not be established, because the read failed. Bind to a domain controller that can see it with --server.	No
server-has-unrecognised-children	The server object has a child object other than NTDS Settings and DNS Settings. Look at it before you remove anything.	No
is-forest-root	The forest root domain cannot be removed.	No
not-a-domain-partition	The crossRef names a partition that is not a domain, such as a DNS application partition.	No
domain-still-has-dcs	The domain still shows domain controllers. Remove them first, one at a time. If they are leftover metadata of machines long gone, override.	Yes
child-partition-in-use	A child domain, or an application partition hosted by a domain controller outside the plan, is beneath the domain. Remove the child domain first.	No
domain-still-trusted	A trust still references the domain being removed.	No
trust-unconfirmed	The global catalog shows another domain holding a trust that names the domain being removed, and no domain controller of that domain could be read to confirm it. Override when that domain is itself gone.	Yes
not-found	Nothing by that name was found to clean up.	No
not-confirmed	The --confirm value did not match the object's own name.	No