1msktutil(1)                 General Commands Manual                msktutil(1)
2
3
4

NAME

6       msktutil  - fetches and manages kerberos keytabs in an Active Directory
7       environment
8

SYNOPSIS

10       msktutil [mode] [parameter 1] [parameter 2] ...
11

DESCRIPTION

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

CREDENTIALS

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

MODES

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

OPTIONS

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

NOTES

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

EXAMPLES

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

ENVIRONMENT

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

AUTHORS

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)
Impressum