1msktutil(1) General Commands Manual msktutil(1)
2
6 msktutil - fetches and manages kerberos keytabs in an Active Directory
7 environment
8
10 msktutil [mode] [parameter 1] [parameter 2] ...
11
13 msktutil is a Unix/Linux keytab utility for Microsoft Active Directory
14 environments. This program is capable of creating accounts in Active
15 Directory, adding service principals to those accounts, and creating
16 local keytab files so that kerberizied services can utilize Active Di‐
17 rectory as a Kerberos infrastructure. msktutil will create and manage
18 machine accounts by default. The --use-service-account option lets
19 msktutil operate on service accounts. msktutil requires that the Ker‐
20 beros client libraries are properly installed and configured to use Ac‐
21 tive Directory as a realm.
22 Whenever a principal is added or a keytab is updated, the secret pass‐
24 word for the corresponding account is changed. By default, the pass‐
25 word is not stored, so it needs to be reset each time msktutil is exe‐
26 cuted. All entries in the keytab will be automatically updated when‐
27 ever the password is reset. The previous entries will be left in the
28 keytab, so sessions using the older key versions will not break. This
29 behavior is similar to the way Windows hosts handle machine password
30 changes.
31
33 There are two common methods of using this program. The first is to
34 "kinit" with Administrator-like credentials which have permission to
35 create computer objects in your Active Directory server. If you invoke
36 the program with such credentials, you can create a new computer ac‐
37 count or service account from scratch.
38 The second is to pre-create the accounts with such credentials, and
40 then invoke msktutil on a machine without any special permissions.
41 When the computer account or service account exists already, msktutil
42 will attempt to authenticate as that account using either the existing
43 keytab, or if that fails, a default password. When that default pass‐
44 word is not specified with the option --old-account-password, msktutil
45 will use the default machine password. It will then change the pass‐
46 word and update the keytab appropriately. This is usually the more
47 convenient option when joining many computers to the domain.
48 To pre-create a computer account, you may use the Active Directory
50 Users and Computers GUI, select "new computer" from the right click
51 menu, and type the short DNS name, then right click on the newly cre‐
52 ated object and select "Reset account" to set the password to the de‐
53 fault value. Another alternative is to run msktutil in the pre-create
54 mode. Both methods accomplish the same thing.
55 To pre-create a service account, you may use the Active Directory Users
57 and Computers GUI, select "new user" from the right click menu, fill in
58 all required data, set the password to a specific value and use set‐
59 spn.exe to set the desired servicePrincipalName(s). You may also se‐
60 lect "must change password at next logon".
61
63 create Creates a keytab for the current host or a given service ac‐
64 count. Equivalent to update --service host.
65 update Forces a password change and updates all related service princi‐
67 pal entries from the servicePrincipalName and userPrincipalName
68 attributes. Updates dNSHostName for machine accounts and always
69 updates msDS-supportedEncryptionTypes attributes with current
70 values, and applies other changes as specified.
71 auto-update
73 Checks if the password is at least 30 days old (from pwdLastSet
74 attribute), and that the account does not have password expiry
75 disabled. If those conditions are met, acts just like msktutil
76 update. Will also update if the keytab failed to authenticate
77 but the default password did work (e.g. after resetting the ac‐
78 count in AD). Otherwise, exits without doing anything (even if
79 attribute modifying options are given). This option is intended
80 for use from a daily crontab to ensure that the password is ro‐
81 tated regularly.
82 pre-create
84 Pre-create (or update) an account for the given host with de‐
85 fault password. Does not use or update local keytab. Requires
86 -h or --computer-name argument. Implies --user-creds-only.
87 Generally requires administrator credentials.
88 flush Flushes out principals for the current accountname from the
90 keytab, and makes corresponding changes to the machine or ser‐
91 vice account.
92 cleanup
94 Deletes entries from the keytab that are no longer needed.
95 delete Deletes the host or service account from Active Direc‐
96 tory.
97
99 COMMON OPTIONS
100 -v, --version
101 Displays version information
102 --help Displays a help message
104 --verbose
106 Enables verbose status messages. May be specified more then
107 once to get LDAP debugging.
108 CONNECTION/SETUP OPTIONS
110 -b, --base <base ou>
111 Specifies an LDAP base OU when creating a new account. Unless
112 the given string ends with the domain's base DN, it is assume to
113 be a relative path: For example, specifying '-b OU=Unix' for a
114 computer named SERVER in an Active Directory domain example.com
115 would create a computer account in the LDAP path:
116 CN=SERVER,OU=Unix,DC=EXAMPLE,DC=COM. This option can also be
117 specified by setting the MSKTUTIL_LDAP_BASE environment variable
118 to the desired value.
119 If not specified, the default value is read from AD (and the de‐
121 fault there, unless modified by an admin, is CN=Computers for
122 machine accounts and CN=Users for service accounts).
123 --computer-name <name>
125 Specifies that the new account should use <name> for the com‐
126 puter account name and the SAM Account Name. Note that a '$'
127 will be automatically appended to the SAM Account Name. De‐
128 faults to the machine's hostname, excluding the realm, with dots
129 replaced with dashes.
130 That is: if the realm is EXAMPLE.COM, and the hostname is
132 FOO.EXAMPLE.COM, the default computer name is FOO. If the host‐
133 name is FOO.BAR.EXAMPLE.COM, the default computer name is FOO-
134 BAR.
135 --account-name <name>
137 An alias for --computer-name that can be used when operating on
138 service accounts. Note that a '$' will not be automatically ap‐
139 pended to the SAM Account Name when using service accounts.
140 --old-account-password <password>
142 Use supplied account password for authentication. This is use‐
143 ful if the keytab does not yet exist but the password of the
144 computer account is known. This password will be changed by
145 msktutil in order to create or update the keytab
146 --password <new_password>
148 Specify the new account password instead of generating a random
149 one. Consider the password policy settings when defining the
150 string.
151 --dont-change-password
153 Do not create a new password. Try to use existing keys when per‐
154 forming keytab updates or the old password when creating a new
155 keytab. This is useful for adding new SPNs to a machine or ser‐
156 vice account. This option is only available in update or create
157 mode. In create mode the old password needs to be specified with
158 --old-account-password
159 -h, --hostname <name>
161 Overrides the current hostname to be used to be <name>. If this
162 is not specified, the local host name will be used. Note that
163 the local name lookup service will be to qualify and resolve
164 names into fully-qualified names, including a domain extension.
165 This affects the default hostname for other arguments, and the
166 default computer-name. The hostname is also used to set the
167 dNSHostName attribute.
168 -k, --keytab <file>
170 Specifies to use <file> for the keytab. This option can also be
171 specified by setting the MSKTUTIL_KEYTAB environment variable to
172 the name of the desired keytab file. This keytab is both read
173 from, in order to authenticate as the given account, and written
174 to, after updating the account password. Default:
175 /etc/krb5.keytab
176 --keytab-auth-as <name>
178 Specifies which principal name we should try to use, when we au‐
179 thenticate from a keytab. Normally, msktutil will try to use the
180 account name or the host principal for the current host. If this
181 option is specified, instead msktutil will try to use the given
182 principal name first, and only fall back to the default behavior
183 if we fail to authenticate with the given name. This option can
184 be useful if you do not know the current password for the rele‐
185 vant account, do not have a keytab with the account principal,
186 but you do have a keytab with a service principal associated
187 with that account.
188 --server <server>
190 Specifies to use <server> as the domain controller. This af‐
191 fects both kerberos and ldap operations. The server can also be
192 specified by setting the MSKTUTIL_SERVER environment variable.
193 Default: looked up in DNS from the realm name.
194 --server-behind-nat
196 When the server is behind a firewall that performs Network Ad‐
197 dress Translation, KRB-PRIV messages fail validation. This is
198 because the IP address in the encrypted part of the message can‐
199 not be rewritten in the NAT process. This option ignores the
200 resulting error for the password change process, allowing sys‐
201 tems outside the NAT firewall to join the domain managed by
202 servers inside the NAT firewall.
203 --realm <realm>
205 Specifies to use <realm> as kerberos realm. Default: use the
206 default_realm from [libdefaults] section of krb5.conf.
207 --site <site>
209 Find and use domain controller in specific AD site. This option
210 is ignored if option --server is used.
211 -N, --no-reverse-lookups
213 Do not attempt to canonicalize the name of the domain controller
214 via DNS reverse lookups. You may need to do this if your client
215 cannot resolve the PTR records for a domain controller or your
216 DNS servers store incorrect PTR records. Default: Use DNS re‐
217 verse lookups to canonicalize DC names.
218 -n, --no-canonical-name
220 Do not attempt to canonicalize the hostname while creating names
221 of kerberos principals. Instead use supplied hostname. This may
222 be needed for systems where forward and reverse DNS lookups do
223 not return the same (an dynamic dns system for example where
224 lookup for myhost.mydomain returns IP X.Y.Z.W , but lookup for
225 IP X.Y.Z.W returns a name different than myhost.mydomain).
226 --user-creds-only
228 Don't attempt to authenticate with a keytab: only use user's
229 credentials (from e.g. kinit). You may need to do this to mod‐
230 ify certain attributes that require Administrator credentials
231 (description, userAccountControl, userPrincipalName, in a de‐
232 fault AD setup).
233 --auto-update-interval <days>
235 Number of <days> when msktutil auto-update will change the ac‐
236 count password. Defaults to 30 days.
237 -m, --sasl-mechanisms <mechanisms list>
239 A space-separated list of candidate SASL mechanisms to use when
240 performing the LDAP bind. The first mechanism in the list that
241 is supported by both the client (the host running msktutil) and
242 the server (Active Directory) will be used. If providing more
243 than one candidate mechanism, make sure to quote the list to
244 protect the whitespace from the shell. Default: "GSS-SPNEGO
245 GSSAPI".
246 OBJECT TYPE/ATTRIBUTE-SETTING OPTIONS
248 --use-service-account
249 Create and maintain service accounts instead of machine ac‐
250 counts.
251 --delegation
253 Enables the account to be trusted for delegation. This option
254 can also be enabled by setting the MSKTUTIL_DELEGATION environ‐
255 ment variable. This modifies the userAccountControl attribute.
256 Generally requires administrator credentials.
257 --description <text>
259 Sets the account's description attribute to the given text (or
260 removes if text is ''). Generally requires administrator cre‐
261 dentials.
262 --disable-delegation
264 Disables the account from being trusted for delegation. This
265 modifies the userAccountControl attribute. Generally requires
266 administrator credentials.
267 --disable-no-pac
269 Unsets the flag that disables the KDC's including of a PAC in
270 the machine's service tickets. This modifies the userAccount‐
271 Control attribute. Generally requires administrator creden‐
272 tials.
273 --dont-expire-password
275 Sets the DONT_EXPIRE_PASSSWORD bit in the userAccountControl at‐
276 tribute, which disables password expiry for this account. If
277 you don't run a cron job to periodically rotate the keytab, you
278 will want to set this flag. Generally requires administrator
279 credentials.
280 --do-expire-password
282 Unsets the DONT_EXPIRE_PASSWORD flag in the userAccountControl
283 attribute. Generally requires administrator credentials.
284 --dont-update-dnshostname
286 Do not update dnsHostName attribute. In some AD installations
287 modification of this attribute is not allowed (unless using ad‐
288 ministrator credentials), using this option will avoid con‐
289 straint violation warning.
290 --enable
292 Unsets the UF_ACCOUNT_DISABLE flag in the userAccountControl at‐
293 tribute. When a computer leaves the domain this flag is nor‐
294 mally set. Generally requires administrator credentials.
295 --enctypes <integer>
297 Sets the supported encryption types in the msDs-supportedEncryp‐
298 tionTypes field.
299 You may OR together the following values:
301 0x1=des-cbc-crc
302 0x2=des-cbc-md5
303 0x4=rc4-hmac-md5
304 0x8=aes128-cts-hmac-sha1
305 0x10=aes256-cts-hmac-sha1
306 This value is used to determine which encryption types AD will
308 offer to use, and which encryption types to put in the keytab.
309 If the value is set to 0x3 (that is: only the two DES types), it
311 also attempts to set the DES-only flag in userAccountControl.
312 Note: Windows 2008R2 refuses to use DES by default; you thus
314 cannot use DES-only keys unless you have enabled DES encryption
315 for your domain first. Recent versions of MIT kerberos clients
316 similarly refuse to use DES by default.
317 Default: sets the value to 0x1C: that is, use anything but DES.
319 --allow-weak-crypto
321 Enables the usage of DES keys for authentication. This is equiv‐
322 alent to MIT's krb5.conf parameter allow_weak_crypto.
323 --no-pac
325 Specifies that service tickets for this account should not con‐
326 tain a PAC. This modifies the userAccountControl attribute.
327 See Microsoft Knowledge Base article #832575 for details. This
328 option can also be specified by setting the MSKTUTIL_NO_PAC en‐
329 vironment variable. Generally requires administrator creden‐
330 tials.
331 -s, --service <principal>
333 Specifies a service principal to add to the account (and thus
334 keytab, if appropriate). The service is of the form <ser‐
335 vice>/<hostname>. If the hostname is omitted, assumes current
336 hostname. May be specified multiple times. When creating ma‐
337 chine accounts, entries for the host service are created by de‐
338 fault, unless --service is given. Unqualified service names
339 (without a '/' component) are qualified with the full and the
340 short hostnames, eg. host/hostname.example.com and host/host‐
341 name.
342 --remove-service <principal>
344 Specifies a service principal to remove from the account (and
345 keytab if appropriate).
346 --upn <principal>
348 Sets the userPrincipalName attribute of the computer account or
349 service account to be <principal>.
350 The userPrincipalName can be used in addition to the sAMAccount‐
352 Name (e.g. computername$ for computer accounts) for kinit.
353 <principal> can be provided in short form (e.g. host/host‐
355 name.example.com) or in long form (e.g. host/hostname.exam‐
356 ple.com@EXAMPLE.COM). In short form the default realm will auto‐
357 matically be appended.
358 This operation requires administrator privileges.
360 --set-samba-secret
362 Use Samba's net changesecretpw command to locally set the ma‐
363 chine account password in Samba's secrets.tdb. $PATH need to
364 include Samba's net command. Samba needs to be configured ap‐
365 propriately.
366 --use-samba-cmd <command>
368 Use supplied command instead of Samba's net changesecretpw com‐
369 mand. command will be supplied machine account password on stan‐
370 dard input and shall return 0 exit code on success.
371 --check-replication
373 Wait until the password change is reflected in LDAP. By de‐
374 fault, msktutil exits once a password update is successful and
375 the new keytab is written. However, due to replication delays,
376 LDAP queries might still return an older key version number. If
377 --check-replication is given, msktutil waits until the key ver‐
378 sion number is updated on the queried LDAP server as well. Note
379 that this is just a sanity check: The new password is supposed
380 to be accepted on all domain controllers once the update suc‐
381 ceeds, even if LDAP is not yet in sync. Turning on this option
382 might substantially increase the runtime of msktutil in some en‐
383 vironments due to replication delays (eg. 15 to 30 minutes for
384 common AD configurations). The default is not to check LDAP
385 replication.
386 CLEANUP OPTIONS
388 --remove-old <number>
389 Removes entries from the keytab that are older than <number>
390 days. The newest keytab entries will be kept to prevent a total
391 cleanup. I.e. it is not possible to produce an empty keytab with
392 the --remove-old option.
393 --remove-enctype <enctype>
395 Removes entries from the keytab with given encryption type.
396 Warning: it is possible to produce empty keytabs with the --re‐
397 move-empty option by successively removing all encryption types.
398 Supported enctype strings are: des-cbc-crc,des-cbc-md5, arcfour,
399 aes128 and aes256.
400
402 PASSWORD EXPIRY
403 Be aware that Windows machines will, by default, automatically change
404 their account password every 30 days, and thus many domains have a
405 90-day password expiry window, after which your keytab will stop work‐
406 ing. There are two ways to deal with this:
407 a) (Preferred): Make sure you're running a daily cron job to run msktu‐
409 til auto-update, which will change the password automatically 30 days
410 after it was last changed and update the keytab.
411 b) (Not preferred): disable password expiry for the account via the
413 --dont-expire-password option (or otherwise setting DONT_EXPIRE_PASS‐
414 WORD flag in userAccountControl in AD).
415 PASSWORD POLICY ISSUES
417 This section only applies to msktutil --use-service-account.
418 While machine account passwords may be changed at any time, service ac‐
420 counts are user accounts and your Active Directory domain may have spe‐
421 cial password policies for those user accounts. E.g., "minimum pass‐
422 word age" is typically set to 1 day, which means that you will have to
423 wait for that time to pass until you may invoke msktutil update --use-
424 service-account.
425 OTHER NOTES
427 Unlike other kerberos implementations, Active Directory has only a sin‐
428 gle key for all of the principals associated with an account. So, if
429 you create a HTTP/hostname service principal, it will share the same
430 key as the host/hostname principal. If you want to isolate (security-
431 wise) different service principals, you may want to create a dedicated
432 service account for them (with --use-service-account) and a separate
433 keytab file (with --keytab).
434 Also note: kinit -k 'host/computername' *will not work*, by default,
436 even when that is a valid service principal existing in your keytab.
437 Active Directory does not allow you to authenticate as a service prin‐
438 cipal, so do not use that as a test of whether the service principal is
439 working. If you actually want to authenticate as the computer account
440 user, kinit -k 'computername$' instead.
441 If you really need to be able to authenticate as 'host/computername',
443 you can also use the --upn argument to set the userPrincipalName attri‐
444 bute (generally requires administrator credentials, not computer ac‐
445 count credentials). Both 'computername$' and the value of userPrinci‐
446 palName are treated as valid account names to kinit as.
447 msktutil will use kerberized LDAP operations to talk to domain con‐
449 trollers. To obtain a LDAP service ticket, the DNS service will be
450 used to construct the domain controllers LDAP principal name. If DNS
451 is misconfigured, this construction may fail. To work around this is‐
452 sue, you may specify the fully qualified DNS name of your domain con‐
453 troller with the --server option and additionally use the --no-reverse-
454 lookups option.
455 Samba (www.samba.org) provides the net command that can be used to man‐
457 age kerberos keytabs as well. Using msktutil and commands like "net
458 ads join" or "net ads keytab" together can lead to trouble. With the
459 --set-samba-secret option, msktutil can be used as a replacement for
460 net.
461 Active Directory includes authorization data (e.g. information about
463 group memberships) in Kerberos tickets. This information is called PAC
464 and may lead to very large ticket sizes. Especially HTTP services are
465 known to produce failures if that size exceeds the HTTP header size.
466 If your service does not make use of that PAC information (which is
467 true for most Unix/Linux-services) you may just disable it with the
468 --no-pac option.
469
471 For unprivileged users the most common invocations are:
472 msktutil create
474 This will create a computer account in Active Directory with a new
476 password and write out a new keytab.
477 msktutil update --service host --service HTTP
479 This will update a computer account in Active Directory with a new
481 password, write out a new keytab, and ensure that it has both "host"
482 and "HTTP" service principals are on it for the hostname.
483 msktutil update --dont-change-password --service host --service HTTP
485 This will do the same as the last example but without changing the
487 password.
488 msktutil auto-update
490 This is useful in a daily cron job to check and rotate the password au‐
492 tomatically when it's 30 days old.
493 For users with admin privileges in AD, some common uses:
495 msktutil create --service host --service HTTP
497 This will create a computer account in Active Directory with a new
499 password, write out a new keytab, and ensure that it has both "host"
500 and "HTTP" service principals are on it for the hostname.
501 msktutil pre-create --host computer1.example.com
503 This will pre-create an account for computer1 with the default password
505 using your credentials. This can be done on a central host, e.g. to
506 script the addition of many hosts. You can then use msktutil create on
507 the hosts themselves (without special credentials) to join them to the
508 domain.
509 msktutil create --host afs --service afs --enctypes 0x03
511 This will create an afs/cell.name@REALM principal, and associate that
513 principal with a computer account called 'afs'. The principal will be
514 marked as DES-only, which is required for AFS.
515 msktutil create --use-service-account --service HTTP/hostname.example.com --keytab /etc/apache/krb5.keytab --account-name srv-http --no-pac
517 This will create an HTTP/hostname.example.com@REALM principal, and as‐
519 sociate that principal with a service account called 'srv-http'. Cor‐
520 responding Kerberos keys will be written to the keytab file
521 /etc/apache/krb5.keytab. The size of Kerberos tickets for that service
522 will stay small because no PAC information will be included.
523 msktutil create --keytab /etc/krb5/user/10123/client.keytab --use-service-account --account-name johndoe --dont-change-password --old-account-password <John Doe's Password>
525 This will create a keytab for johndoe without changing John Doe's pass‐
527 word
528 msktutil create --service host/hostname --service host/hostname.example.com --set-samba-secret --enctypes 0x4
530 This will create a computer account in Active Directory that is compat‐
532 ible with Samba. The command creates a new password, write out a new
533 keytab, and ensure that it includes both "host/hostname" and
534 "host/hostname.example.com" as service principals (which is equivalent
535 to what setspn.exe -R would do on windows). The new computer password
536 will be stored in Samba's secrets.tdb database to provide interoper‐
537 ability with Samba. As Samba (version 3) only supports arcfour en‐
538 crypted Kerberos tickets the --enctypes option must be used to select
539 only that encryption type.
540 msktutil cleanup --remove-old 10
542 Deletes all entries older than 10 days, keeping at least the last en‐
544 try.
545
547 MSKTUTIL_LDAP_BASE
548 Specifies a relative LDAP base when creating a new account (see
549 --base),
550 MSKTUTIL_KEYTAB
552 Specifies the keytab. Default: /etc/krb5.keytab (see
553 --keytab),
554 MSKTUTIL_SERVER
556 Specifies the domain controller (see --server).
557 MSKTUTIL_DELEGATION
559 Enables the account to be trusted for delegation (see --delega‐
560 tion).
561 MSKTUTIL_NO_PAC
563 Specifies that service tickets for this account should not con‐
564 tain a PAC (see --no-pac).
565 MSKTUTIL_SAMBA_CMD
567 Specifies the command to be used to locally set the machine ac‐
568 count password in Samba's secrets.tdb.
569
571 (C) 2004-2006 Dan Perry <dperry at pppl.gov>
572 (C) 2006 Brian Elliott Finley (finley at anl.gov)
574 (C) 2009-2010 Doug Engert (deengert at anl.gov)
576 (C) 2010 James Knight <foom at fuhm.net>
578 (C) 2010-2013 Ken Dreyer <ktdreyer at ktdreyer.com>
580 (C) 2012-2017 Mark Proehl <mark at mproehl.net>
582 (C) 2012-2017 Olaf Flebbe <of at oflebbe.de>
584 (C) 2013-2017 Daniel Kobras <d.kobras at science-computing.de>
586 1.2 msktutil(1)