KRB5-SYNC(8)

💖 KRB5-SYNC 💖

okay bestie, gather round, because this is the little command-line bestie that syncs your passwords and account status with Active Directory. It lives in section 8 of the manual, so yes, it's an admin-tool girlie. Let's get into it. ✨

---

✨ SYNOPSIS ✨

krb5-sync [-d | -e] [-p password] user

krb5-sync -f file

---

🌸 DESCRIPTION 🌸

So krb5-sync is literally the command-line interface to the exact same functions that the password and status synchronization plugin gives you. It can push a brand-new password over to Active Directory — or, fr fr, to any password store that supports the Kerberos set-password protocol — or it can activate or deactivate an account in Active Directory. Versatile queen. 👑

Wanna synchronize passwords? Hand over the -p option and specify the password. But listen, bestie, important tea: the password is given on the command line, so it must be quoted if it contains special characters, and the password will be exposed to any other users on the system where this command is run. 😭 That means it's useful primarily for testing and should not be used with production passwords. Synchronization to Active Directory will be attempted based on the configuration in krb5.conf (more on that below, keep reading).

Wanna enable or disable an account? Provide the -e or -d option respectively. And yes, you can absolutely run these in conjunction with -p to take both actions at once. Main character multitasking. 💅

Either way, user should be the principal name you're taking these actions for. user may be either unqualified or in the local realm; either way, the Active Directory realm where the changes actually get made is taken from the krb5.conf configuration. No need to stress about which one you type.

Alternately — plot twist — krb5-sync also supports processing actions from a file. To do that, use the -f flag and give the file on the command line. The format of the file should be as follows:

<account>
ad
password | enable | disable
<password>

where that fourth line is present only if the <action> is "password". <account> should be the unqualified name of the account. The second line should be the string "ad" to push the change to Windows Active Directory. The third line should be one of "password", "enable", or "disable", corresponding to the -p, -e, and -d options respectively. The "enable" and "disable" actions are only supported for AD.

Heads up though: the file format is not particularly forgiving. 😤 All of the keywords are case-sensitive, and there must not be any whitespace at the beginning or end of the lines (except in the password, and only if that whitespace is part of the password), just a single newline terminating each line. She's strict. Respect her.

When the -f option is given, the file will be deleted if the action was successful but left alone if the action failed. No take-backs, only clean-up-on-success. 🧹

The configuration block in krb5.conf should look something like this:

krb5-sync = {
    ad_keytab       = /etc/krb5kdc/ad-keytab
    ad_principal    = service/sync@WINDOWS.EXAMPLE.COM
    ad_realm        = WINDOWS.EXAMPLE.COM
    ad_admin_server = dc1.windows.example.com
    ad_ldap_base    = ou=People
}

If the configuration required for an action is not given, that action will not be performed but will apparently succeed from the perspective of the krb5-sync utility. 💀 So if this utility reports success but no change is happening, double-check the configuration to make sure all required options are present. She will lie to your face with a smile, and it's not even her fault.

Now, the deets on the config options themselves:

• "ad_keytab" specifies the location of a keytab for authenticating to the other realm.
• "ad_principal" specifies the principal to authenticate as (using the key in the keytab).
• "ad_realm" specifies the foreign realm.
• "ad_admin_server" is the host to contact via LDAP to push account status changes.
• "ad_ldap_base" specifies the base tree inside Active Directory where account information is stored. Omit the trailing "dc=" part; it will be added automatically from "ad_realm".

Be aware that the "ad_instances", "ad_base_instance", and "ad_queue_only" configuration options that are used by the krb5-sync plugin are ignored by krb5-sync. The krb5-sync command will push changes to whatever principal it was given, regardless of the normal limits on instances, and does not do any of the principal remapping configured with "ad_base_instance". She's a free spirit, she doesn't do remapping. 🦋

---

🎀 OPTIONS 🎀

• -d — Disable the specified user in Active Directory. Requires that all of the ad_* options be set in krb5.conf. This option may not be specified at the same time as -e.
• -e — Enable the specified user in Active Directory. Requires that all of the ad_* options be set in krb5.conf. This option may not be specified at the same time as -e. (yes, it really says -e there, we're just reading what the page says 🙈)
• -f file — Rather than perform a particular action based on a username given on the command line, read a queue file and take action based on it. The format of the queue file is described above. If the action fails, the file will be left alone. If the action succeeds, the file will be deleted.
• -p password — Change the user's password to password in Active Directory.

---

⭐ EXAMPLES ⭐

Disable the account "jdoe" in Active Directory (using the AD configuration found in krb5.conf):

krb5-sync -d jdoe

Change the password of the account "testuser" in Active Directory to "changeme":

krb5-sync -p changeme testuser@EXAMPLE.COM

The same, except also enable the account in Active Directory:

krb5-sync -e -p changeme testuser

Note that the realm for the user given on the command line is optional and ignored. So type it or don't, she literally does not care. 💅

Given a file named jdoe-ad-1168560492 containing:

jdoe
ad
password
changeme

the command:

krb5-sync -f jdoe-ad-1168560492

will change jdoe's password to "changeme" in Active Directory and then delete the file. Ate and left no crumbs. 🔥

---

🌈 SEE ALSO 🌈

The current version of this program is available from its web page at <http://www.eyrie.org/~eagle/software/krb5-sync/>.

---

💜 AUTHOR 💜

Russ Allbery <eagle@eyrie.org>

---

👑 COPYRIGHT AND LICENSE 👑

Copyright 2007, 2008, 2010, 2012 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

---

and that's the whole page bestie!! 🫶 this is version 3.1, dated 2015-08-19, from the krb5-sync manual — she's vintage, she's iconic, she's giving Kerberos-admin realness. go forth and sync responsibly. 💖✨🎀