1msktutil(1) General Commands Manual msktutil(1)
2
3
4
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
17 Directory as a Kerberos infrastructure. msktutil will create and man‐
18 age 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
21 Active Directory as a realm.
22
23 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
37 account or service account from scratch.
38
39 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
49 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
53 default value. Another alternative is to run msktutil in the pre-cre‐
54 ate mode. Both methods accomplish the same thing.
55
56 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
60 select "must change password at next logon".
61
63 create Creates a keytab for the current host or a given service
64 account. Equivalent to update --service host.
65
66 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
72 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
78 account in AD). Otherwise, exits without doing anything (even
79 if attribute modifying options are given). This option is
80 intended for use from a daily crontab to ensure that the pass‐
81 word is rotated regularly.
82
83 pre-create
84 Pre-create (or update) an account for the given host with
85 default password. Does not use or update local keytab.
86 Requires -h or --computer-name argument. Implies --user-creds-
87 only. Generally requires administrator credentials.
88
89 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
93 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
103 --help Displays a help message
104
105 --verbose
106 Enables verbose status messages. May be specified more then
107 once to get LDAP debugging.
108
109 CONNECTION/SETUP OPTIONS
110 -b, --base <base>
111 Specifies a relative LDAP base when creating a new account. For
112 example, specifying '-b OU=Unix' for a computer named SERVER in
113 an Active Directory domain example.com would create a computer
114 account in the LDAP path: CN=SERVER,OU=Unix,DC=EXAMPLE,DC=COM.
115 This option can also be specified by setting the MSKTU‐
116 TIL_LDAP_BASE environment variable to the desired value.
117
118 If not specified, the default value is read from AD (and the
119 default there, unless modified by an admin, is CN=Computers for
120 machine accounts and CN=Users for service accounts).
121
122 --computer-name <name>
123 Specifies that the new account should use <name> for the com‐
124 puter account name and the SAM Account Name. Note that a '$'
125 will be automatically appended to the SAM Account Name.
126 Defaults to the machine's hostname, excluding the realm, with
127 dots replaced with dashes.
128
129 That is: if the realm is EXAMPLE.COM, and the hostname is
130 FOO.EXAMPLE.COM, the default computer name is FOO. If the host‐
131 name is FOO.BAR.EXAMPLE.COM, the default computer name is FOO-
132 BAR.
133
134 --account-name <name>
135 An alias for --computer-name that can be used when operating on
136 service accounts. Note that a '$' will not be automatically
137 appended to the SAM Account Name when using service accounts.
138
139 --old-account-password <password>
140 Use supplied account password for authentication. This is use‐
141 ful if the keytab does not yet exist but the password of the
142 computer account is known. This password will be changed by
143 msktutil in order to create or update the keytab
144
145 --password <new_password>
146 Specify the new account password instead of generating a random
147 one. Consider the password policy settings when defining the
148 string.
149
150 --dont-change-password
151 Do not create a new password. Try to use existing keys when per‐
152 forming keytab updates or the old password when creating a new
153 keytab. This is useful for adding new SPNs to a machine or ser‐
154 vice account. This option is only available in update or create
155 mode. In create mode the old password needs to be specified with
156 --old-account-password
157
158 -h, --hostname <name>
159 Overrides the current hostname to be used to be <name>. If this
160 is not specified, the local host name will be used. Note that
161 the local name lookup service will be to qualify and resolve
162 names into fully-qualified names, including a domain extension.
163 This affects the default hostname for other arguments, and the
164 default computer-name. The hostname is also used to set the
165 dNSHostName attribute.
166
167 -k, --keytab <file>
168 Specifies to use <file> for the keytab. This option can also be
169 specified by setting the MSKTUTIL_KEYTAB environment variable to
170 the name of the desired keytab file. This keytab is both read
171 from, in order to authenticate as the given account, and written
172 to, after updating the account password. Default:
173 /etc/krb5.keytab
174
175 --keytab-auth-as <name>
176 Specifies which principal name we should try to use, when we
177 authenticate from a keytab. Normally, msktutil will try to use
178 the account name or the host principal for the current host. If
179 this option is specified, instead msktutil will try to use the
180 given principal name first, and only fall back to the default
181 behavior if we fail to authenticate with the given name. This
182 option can be useful if you do not know the current password for
183 the relevant account, do not have a keytab with the account
184 principal, but you do have a keytab with a service principal
185 associated with that account.
186
187 --server <server>
188 Specifies to use <server> as the domain controller. This
189 affects both kerberos and ldap operations. The server can also
190 be specified by setting the MSKTUTIL_SERVER environment vari‐
191 able. Default: looked up in DNS from the realm name.
192
193 --server-behind-nat
194 When the server is behind a firewall that performs Network
195 Address Translation, KRB-PRIV messages fail validation. This is
196 because the IP address in the encrypted part of the message can‐
197 not be rewritten in the NAT process. This option ignores the
198 resulting error for the password change process, allowing sys‐
199 tems outside the NAT firewall to join the domain managed by
200 servers inside the NAT firewall.
201
202 --realm <realm>
203 Specifies to use <realm> as kerberos realm. Default: use the
204 default_realm from [libdefaults] section of krb5.conf.
205
206 --site <site>
207 Find and use domain controller in specific AD site. This option
208 is ignored if option --server is used.
209
210 -N, --no-reverse-lookups
211 Do not attempt to canonicalize the name of the domain controller
212 via DNS reverse lookups. You may need to do this if your client
213 cannot resolve the PTR records for a domain controller or your
214 DNS servers store incorrect PTR records. Default: Use DNS
215 reverse lookups to canonicalize DC names.
216
217 -n, --no-canonical-name
218 Do not attempt to canonicalize the hostname while creating names
219 of kerberos principals. Instead use supplied hostname. This may
220 be needed for systems where forward and reverse DNS lookups do
221 not return the same (an dynamic dns system for example where
222 lookup for myhost.mydomain returns IP X.Y.Z.W , but lookup for
223 IP X.Y.Z.W returns a name different than myhost.mydomain).
224
225 --user-creds-only
226 Don't attempt to authenticate with a keytab: only use user's
227 credentials (from e.g. kinit). You may need to do this to mod‐
228 ify certain attributes that require Administrator credentials
229 (description, userAccountControl, userPrincipalName, in a
230 default AD setup).
231
232 --auto-update-interval <days>
233 Number of <days> when msktutil auto-update will change the
234 account password. Defaults to 30 days.
235
236 OBJECT TYPE/ATTRIBUTE-SETTING OPTIONS
237 --use-service-account
238 Create and maintain service accounts instead of machine
239 accounts.
240
241 --delegation
242 Enables the account to be trusted for delegation. This option
243 can also be enabled by setting the MSKTUTIL_DELEGATION environ‐
244 ment variable. This modifies the userAccountControl attribute.
245 Generally requires administrator credentials.
246
247 --description <text>
248 Sets the account's description attribute to the given text (or
249 removes if text is ''). Generally requires administrator cre‐
250 dentials.
251
252 --disable-delegation
253 Disables the account from being trusted for delegation. This
254 modifies the userAccountControl attribute. Generally requires
255 administrator credentials.
256
257 --disable-no-pac
258 Unsets the flag that disables the KDC's including of a PAC in
259 the machine's service tickets. This modifies the userAccount‐
260 Control attribute. Generally requires administrator creden‐
261 tials.
262
263 --dont-expire-password
264 Sets the DONT_EXPIRE_PASSSWORD bit in the userAccountControl
265 attribute, which disables password expiry for this account. If
266 you don't run a cron job to periodically rotate the keytab, you
267 will want to set this flag. Generally requires administrator
268 credentials.
269
270 --do-expire-password
271 Unsets the DONT_EXPIRE_PASSWORD flag in the userAccountControl
272 attribute. Generally requires administrator credentials.
273
274 --dont-update-dnshostname
275 Do not update dnsHostName attribute. In some AD installations
276 modification of this attribute is not allowed (unless using
277 administrator credentials), using this option will avoid con‐
278 straint violation warning.
279
280 --enable
281 Unsets the UF_ACCOUNT_DISABLE flag in the userAccountControl
282 attribute. When a computer leaves the domain this flag is nor‐
283 mally set. Generally requires administrator credentials.
284
285 --enctypes <integer>
286 Sets the supported encryption types in the msDs-supportedEncryp‐
287 tionTypes field.
288
289 You may OR together the following values:
290 0x1=des-cbc-crc
291 0x2=des-cbc-md5
292 0x4=rc4-hmac-md5
293 0x8=aes128-cts-hmac-sha1
294 0x10=aes256-cts-hmac-sha1
295
296 This value is used to determine which encryption types AD will
297 offer to use, and which encryption types to put in the keytab.
298
299 If the value is set to 0x3 (that is: only the two DES types), it
300 also attempts to set the DES-only flag in userAccountControl.
301
302 Note: Windows 2008R2 refuses to use DES by default; you thus
303 cannot use DES-only keys unless you have enabled DES encryption
304 for your domain first. Recent versions of MIT kerberos clients
305 similarly refuse to use DES by default.
306
307 Default: sets the value to 0x1C: that is, use anything but DES.
308
309 --allow-weak-crypto
310 Enables the usage of DES keys for authentication. This is equiv‐
311 alent to MIT's krb5.conf parameter allow_weak_crypto.
312
313 --no-pac
314 Specifies that service tickets for this account should not con‐
315 tain a PAC. This modifies the userAccountControl attribute.
316 See Microsoft Knowledge Base article #832575 for details. This
317 option can also be specified by setting the MSKTUTIL_NO_PAC
318 environment variable. Generally requires administrator creden‐
319 tials.
320
321 -s, --service <principal>
322 Specifies a service principal to add to the account (and thus
323 keytab, if appropriate). The service is of the form <ser‐
324 vice>/<hostname>. If the hostname is omitted, assumes current
325 hostname. May be specified multiple times.
326
327 --remove-service <principal>
328 Specifies a service principal to remove from the account (and
329 keytab if appropriate).
330
331 --upn <principal>
332 Sets the userPrincipalName attribute of the computer account or
333 service account to be <principal>.
334
335 The userPrincipalName can be used in addition to the sAMAccount‐
336 Name (e.g. computername$ for computer accounts) for kinit.
337
338 <principal> can be provided in short form (e.g. host/host‐
339 name.example.com) or in long form (e.g. host/hostname.exam‐
340 ple.com@EXAMPLE.COM). In short form the default realm will auto‐
341 matically be appended.
342
343 This operation requires administrator privileges.
344
345 --set-samba-secret
346 Use Samba's net changesecretpw command to locally set the
347 machine account password in Samba's secrets.tdb. $PATH need to
348 include Samba's net command. Samba needs to be configured
349 appropriately.
350
351 --check-replication
352 Wait until the password change is reflected in LDAP. By
353 default, msktutil exits once a password update is successful and
354 the new keytab is written. However, due to replication delays,
355 LDAP queries might still return an older key version number. If
356 --check-replication is given, msktutil waits until the key ver‐
357 sion number is updated on the queried LDAP server as well. Note
358 that this is just a sanity check: The new password is supposed
359 to be accepted on all domain controllers once the update suc‐
360 ceeds, even if LDAP is not yet in sync. Turning on this option
361 might substantially increase the runtime of msktutil in some
362 environments due to replication delays (eg. 15 to 30 minutes for
363 common AD configurations). The default is not to check LDAP
364 replication.
365
366 CLEANUP OPTIONS
367 --remove-old <number>
368 Removes entries from the keytab that are older than <number>
369 days. The newest keytab entries will be kept to prevent a total
370 cleanup. I.e. it is not possible to produce an empty keytab with
371 the --remove-old option.
372
373 --remove-enctype <int>
374 Removes entries from the keytab with given encryption type. (See
375 --enctypes for supported encryption types.) Warning: it is pos‐
376 sible to produce empty keytabs with the --remove-empty option by
377 successively removing all encryption types. Supported enctype
378 strings are: des-cbc-crc,des-cbc-md5, arcfour, aes128 and
379 aes256.
380
382 PASSWORD EXPIRY
383 Be aware that Windows machines will, by default, automatically change
384 their account password every 30 days, and thus many domains have a
385 90-day password expiry window, after which your keytab will stop work‐
386 ing. There are two ways to deal with this:
387
388 a) (Preferred): Make sure you're running a daily cron job to run msktu‐
389 til auto-update, which will change the password automatically 30 days
390 after it was last changed and update the keytab.
391
392 b) (Not preferred): disable password expiry for the account via the
393 --dont-expire-password option (or otherwise setting DONT_EXPIRE_PASS‐
394 WORD flag in userAccountControl in AD).
395
396 PASSWORD POLICY ISSUES
397 This section only applies to msktutil --use-service-account.
398
399 While machine account passwords may be changed at any time, service
400 accounts are user accounts and your Active Directory domain may have
401 special password policies for those user accounts. E.g., "minimum
402 password age" is typically set to 1 day, which means that you will have
403 to wait for that time to pass until you may invoke msktutil update
404 --use-service-account.
405
406 OTHER NOTES
407 Unlike other kerberos implementations, Active Directory has only a sin‐
408 gle key for all of the principals associated with an account. So, if
409 you create a HTTP/hostname service principal, it will share the same
410 key as the host/hostname principal. If you want to isolate (security-
411 wise) different service principals, you may want to create a dedicated
412 service account for them (with --use-service-account) and a separate
413 keytab file (with --keytab).
414
415 Also note: kinit -k 'host/computername' *will not work*, by default,
416 even when that is a valid service principal existing in your keytab.
417 Active Directory does not allow you to authenticate as a service prin‐
418 cipal, so do not use that as a test of whether the service principal is
419 working. If you actually want to authenticate as the computer account
420 user, kinit -k 'computername$' instead.
421
422 If you really need to be able to authenticate as 'host/computername',
423 you can also use the --upn argument to set the userPrincipalName
424 attribute (generally requires administrator credentials, not computer
425 account credentials). Both 'computername$' and the value of userPrin‐
426 cipalName are treated as valid account names to kinit as.
427
428 msktutil will use kerberized LDAP operations to talk to domain con‐
429 trollers. To obtain a LDAP service ticket, the DNS service will be
430 used to construct the domain controllers LDAP principal name. If DNS
431 is misconfigured, this construction may fail. To work around this
432 issue, you may specify the fully qualified DNS name of your domain
433 controller with the --server option and additionally use the --no-
434 reverse-lookups option.
435
436 Samba (www.samba.org) provides the net command that can be used to man‐
437 age kerberos keytabs as well. Using msktutil and commands like "net
438 ads join" or "net ads keytab" together can lead to trouble. With the
439 --set-samba-secret option, msktutil can be used as a replacement for
440 net.
441
442 Active Directory includes authorization data (e.g. information about
443 group memberships) in Kerberos tickets. This information is called PAC
444 and may lead to very large ticket sizes. Especially HTTP services are
445 known to produce failures if that size exceeds the HTTP header size.
446 If your service does not make use of that PAC information (which is
447 true for most Unix/Linux-services) you may just disable it with the
448 --no-pac option.
449
451 For unprivileged users the most common invocations are:
452
453 msktutil create
454
455 This will create a computer account in Active Directory with a new
456 password and write out a new keytab.
457
458 msktutil update --service host --service HTTP
459
460 This will update a computer account in Active Directory with a new
461 password, write out a new keytab, and ensure that it has both "host"
462 and "HTTP" service principals are on it for the hostname.
463
464 msktutil update --dont-change-password --service host --service HTTP
465
466 This will do the same as the last example but without changing the
467 password.
468
469 msktutil auto-update
470
471 This is useful in a daily cron job to check and rotate the password
472 automatically when it's 30 days old.
473
474 For users with admin privileges in AD, some common uses:
475
476 msktutil create --service host --service HTTP
477
478 This will create a computer account in Active Directory with a new
479 password, write out a new keytab, and ensure that it has both "host"
480 and "HTTP" service principals are on it for the hostname.
481
482 msktutil pre-create --host computer1.example.com
483
484 This will pre-create an account for computer1 with the default password
485 using your credentials. This can be done on a central host, e.g. to
486 script the addition of many hosts. You can then use msktutil create on
487 the hosts themselves (without special credentials) to join them to the
488 domain.
489
490 msktutil create --host afs --service afs --enctypes 0x03
491
492 This will create an afs/cell.name@REALM principal, and associate that
493 principal with a computer account called 'afs'. The principal will be
494 marked as DES-only, which is required for AFS.
495
496 msktutil create --use-service-account --service HTTP/hostname.example.com --keytab /etc/apache/krb5.keytab --account-name srv-http --no-pac
497
498 This will create an HTTP/hostname.example.com@REALM principal, and as‐
499 sociate that principal with a service account called 'srv-http'. Cor‐
500 responding Kerberos keys will be written to the keytab file
501 /etc/apache/krb5.keytab. The size of Kerberos tickets for that service
502 will stay small because no PAC information will be included.
503
504 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>
505
506 This will create a keytab for johndoe without changing John Doe's pass‐
507 word
508
509 msktutil create --service host/hostname --service host/hostname.example.com --set-samba-secret --enctypes 0x4
510
511 This will create a computer account in Active Directory that is compat‐
512 ible with Samba. The command creates a new password, write out a new
513 keytab, and ensure that it includes both "host/hostname" and
514 "host/hostname.example.com" as service principals (which is equivalent
515 to what setspn.exe -R would do on windows). The new computer password
516 will be stored in Samba's secrets.tdb database to provide interoper‐
517 ability with Samba. As Samba (version 3) only supports arcfour
518 encrypted Kerberos tickets the --enctypes option must be used to select
519 only that encryption type.
520
521 msktutil cleanup --remove-old 10
522
523 Deletes all entries older than 10 days, keeping at least the last
524 entry.
525
527 MSKTUTIL_LDAP_BASE
528 Specifies a relative LDAP base when creating a new account (see
529 --base),
530
531 MSKTUTIL_KEYTAB
532 Specifies the keytab. Default: /etc/krb5.keytab (see
533 --keytab),
534
535 MSKTUTIL_SERVER
536 Specifies the domain controller (see --server).
537
538 MSKTUTIL_DELEGATION
539 Enables the account to be trusted for delegation (see --delega‐
540 tion).
541
542 MSKTUTIL_NO_PAC
543 Specifies that service tickets for this account should not con‐
544 tain a PAC (see --no-pac).
545
547 (C) 2004-2006 Dan Perry <dperry at pppl.gov>
548
549 (C) 2006 Brian Elliott Finley (finley at anl.gov)
550
551 (C) 2009-2010 Doug Engert (deengert at anl.gov)
552
553 (C) 2010 James Knight <foom at fuhm.net>
554
555 (C) 2010-2013 Ken Dreyer <ktdreyer at ktdreyer.com>
556
557 (C) 2012-2017 Mark Proehl <mark at mproehl.net>
558
559 (C) 2012-2017 Olaf Flebbe <of at oflebbe.de>
560
561 (C) 2013-2017 Daniel Kobras <d.kobras at science-computing.de>
562
563
564
565 1.1 msktutil(1)