Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
msktutil(1)		    General Commands Manual		   msktutil(1)

NAME
       msktutil	 - fetches and manages kerberos	keytabs	in an Active Directory
       environment

SYNOPSIS
       msktutil	[mode] [parameter 1] [parameter	2] ...

DESCRIPTION
       msktutil	is a Unix/Linux	keytab utility for Microsoft Active  Directory
       environments.   This  program is	capable	of creating accounts in	Active
       Directory, adding service principals to those  accounts,	 and  creating
       local  keytab files so that kerberizied services	can utilize Active Di-
       rectory as a Kerberos infrastructure.  msktutil will create and	manage
       machine	accounts  by  default.	 The --use-service-account option lets
       msktutil	operate	on service accounts.  msktutil requires	that the  Ker-
       beros client libraries are properly installed and configured to use Ac-
       tive Directory as a realm.

       Whenever	a principal is added or	a keytab is updated, the secret	 pass-
       word  for  the corresponding account is changed.	 By default, the pass-
       word is not stored, so it needs to be reset each	time msktutil is  exe-
       cuted.	All  entries in	the keytab will	be automatically updated when-
       ever the	password is reset.  The	previous entries will be left  in  the
       keytab,	so sessions using the older key	versions will not break.  This
       behavior	is similar to the way Windows hosts  handle  machine  password
       changes.

CREDENTIALS
       There  are  two	common methods of using	this program.  The first is to
       "kinit" with Administrator-like credentials which  have	permission  to
       create computer objects in your Active Directory	server.	 If you	invoke
       the program with	such credentials, you can create a  new	 computer  ac-
       count or	service	account	from scratch.

       The  second  is	to  pre-create the accounts with such credentials, and
       then invoke msktutil on a  machine  without  any	 special  permissions.
       When  the  computer account or service account exists already, msktutil
       will attempt to authenticate as that account using either the  existing
       keytab,	or if that fails, a default password.  When that default pass-
       word is not specified with the option --old-account-password,  msktutil
       will  use  the default machine password.	 It will then change the pass-
       word and	update the keytab appropriately.  This	is  usually  the  more
       convenient option when joining many computers to	the domain.

       To  pre-create  a  computer  account,  you may use the Active Directory
       Users and Computers GUI,	select "new computer"  from  the  right	 click
       menu,  and  type	the short DNS name, then right click on	the newly cre-
       ated object and select "Reset account" to set the password to  the  de-
       fault  value.  Another alternative is to	run msktutil in	the pre-create
       mode.  Both methods accomplish the same thing.

       To pre-create a service account,	you may	use the	Active Directory Users
       and Computers GUI, select "new user" from the right click menu, fill in
       all required data, set the password to a	specific value	and  use  set-
       spn.exe	to  set	the desired servicePrincipalName(s).  You may also se-
       lect "must change password at next logon".

MODES
       create Creates a	keytab for the current host or	a  given  service  ac-
	      count.  Equivalent to update --service host.

       update Forces a password	change and updates all related service princi-
	      pal entries from the servicePrincipalName	and  userPrincipalName
	      attributes.  Updates dNSHostName for machine accounts and	always
	      updates msDS-supportedEncryptionTypes  attributes	 with  current
	      values, and applies other	changes	as specified.

       auto-update
	      Checks  if the password is at least 30 days old (from pwdLastSet
	      attribute), and that the account does not	have  password	expiry
	      disabled.	  If those conditions are met, acts just like msktutil
	      update. Will also	update if the keytab  failed  to  authenticate
	      but the default password did work	(e.g.  after resetting the ac-
	      count in AD).  Otherwise,	exits without doing anything (even  if
	      attribute	modifying options are given).  This option is intended
	      for use from a daily crontab to ensure that the password is  ro-
	      tated regularly.

       pre-create
	      Pre-create  (or  update)	an account for the given host with de-
	      fault password.  Does not	use or update local keytab.   Requires
	      -h  or  --computer-name  argument.   Implies  --user-creds-only.
	      Generally	requires administrator credentials.

       flush  Flushes out principals for  the  current	accountname  from  the
	      keytab,  and  makes corresponding	changes	to the machine or ser-
	      vice account.

       cleanup
	      Deletes entries from the	keytab	that  are  no  longer  needed.
	      delete  Deletes  the  host or service account from Active	Direc-
	      tory.

OPTIONS
   COMMON OPTIONS
       -v, --version
	      Displays version information

       --help Displays a help message

       --verbose
	      Enables verbose status messages.	May  be	 specified  more  then
	      once to get LDAP debugging.

   CONNECTION/SETUP OPTIONS
       -b, --base <base>
	      Specifies	a relative LDAP	base when creating a new account.  For
	      example, specifying '-b OU=Unix' for a computer named SERVER  in
	      an  Active  Directory domain example.com would create a computer
	      account in the LDAP  path:  CN=SERVER,OU=Unix,DC=EXAMPLE,DC=COM.
	      This  option  can	 also  be  specified  by  setting  the	MSKTU-
	      TIL_LDAP_BASE environment	variable to the	desired	value.

	      If not specified,	the default value is read from AD (and the de-
	      fault  there,  unless  modified by an admin, is CN=Computers for
	      machine accounts and CN=Users for	service	accounts).

       --computer-name <name>
	      Specifies	that the new account should use	<name>	for  the  com-
	      puter  account  name  and	the SAM	Account	Name.  Note that a '$'
	      will be automatically appended to	the  SAM  Account  Name.   De-
	      faults to	the machine's hostname,	excluding the realm, with dots
	      replaced with dashes.

	      That is: if the  realm  is  EXAMPLE.COM,	and  the  hostname  is
	      FOO.EXAMPLE.COM, the default computer name is FOO.  If the host-
	      name is FOO.BAR.EXAMPLE.COM, the default computer	name  is  FOO-
	      BAR.

       --account-name <name>
	      An  alias	for --computer-name that can be	used when operating on
	      service accounts.	 Note that a '$' will not be automatically ap-
	      pended to	the SAM	Account	Name when using	service	accounts.

       --old-account-password <password>
	      Use  supplied account password for authentication.  This is use-
	      ful if the keytab	does not yet exist but	the  password  of  the
	      computer	account	 is  known.   This password will be changed by
	      msktutil in order	to create or update the	keytab

       --password <new_password>
	      Specify the new account password instead of generating a	random
	      one.  Consider  the  password  policy settings when defining the
	      string.

       --dont-change-password
	      Do not create a new password. Try	to use existing	keys when per-
	      forming  keytab  updates or the old password when	creating a new
	      keytab. This is useful for adding	new SPNs to a machine or  ser-
	      vice  account. This option is only available in update or	create
	      mode. In create mode the old password needs to be	specified with
	      --old-account-password

       -h, --hostname <name>
	      Overrides	the current hostname to	be used	to be <name>.  If this
	      is not specified,	the local host name will be used.   Note  that
	      the  local  name	lookup	service	will be	to qualify and resolve
	      names into fully-qualified names,	including a domain  extension.
	      This  affects  the default hostname for other arguments, and the
	      default computer-name.  The hostname is also  used  to  set  the
	      dNSHostName attribute.

       -k, --keytab <file>
	      Specifies	to use <file> for the keytab.  This option can also be
	      specified	by setting the MSKTUTIL_KEYTAB environment variable to
	      the  name	 of the	desired	keytab file.  This keytab is both read
	      from, in order to	authenticate as	the given account, and written
	      to,    after    updating	 the   account	 password.    Default:
	      /etc/krb5.keytab

       --keytab-auth-as	<name>
	      Specifies	which principal	name we	should try to use, when	we au-
	      thenticate from a	keytab.	Normally, msktutil will	try to use the
	      account name or the host principal for the current host. If this
	      option  is specified, instead msktutil will try to use the given
	      principal	name first, and	only fall back to the default behavior
	      if  we fail to authenticate with the given name. This option can
	      be useful	if you do not know the current password	for the	 rele-
	      vant  account,  do not have a keytab with	the account principal,
	      but you do have a	keytab with  a	service	 principal  associated
	      with that	account.

       --server	<server>
	      Specifies	 to  use  <server> as the domain controller.  This af-
	      fects both kerberos and ldap operations.	The server can also be
	      specified	 by  setting the MSKTUTIL_SERVER environment variable.
	      Default: looked up in DNS	from the realm name.

       --server-behind-nat
	      When the server is behind	a firewall that	performs  Network  Ad-
	      dress  Translation,  KRB-PRIV messages fail validation.  This is
	      because the IP address in	the encrypted part of the message can-
	      not  be  rewritten  in the NAT process.  This option ignores the
	      resulting	error for the password change process,	allowing  sys-
	      tems  outside  the  NAT  firewall	 to join the domain managed by
	      servers inside the NAT firewall.

       --realm <realm>
	      Specifies	to use <realm> as kerberos realm.   Default:  use  the
	      default_realm from [libdefaults] section of krb5.conf.

       --site <site>
	      Find  and	use domain controller in specific AD site. This	option
	      is ignored if option --server is used.

       -N, --no-reverse-lookups
	      Do not attempt to	canonicalize the name of the domain controller
	      via DNS reverse lookups.	You may	need to	do this	if your	client
	      cannot resolve the PTR records for a domain controller  or  your
	      DNS  servers  store incorrect PTR	records.  Default: Use DNS re-
	      verse lookups to canonicalize DC names.

       -n, --no-canonical-name
	      Do not attempt to	canonicalize the hostname while	creating names
	      of kerberos principals.  Instead use supplied hostname. This may
	      be needed	for systems where forward and reverse DNS  lookups  do
	      not  return  the	same  (an dynamic dns system for example where
	      lookup for myhost.mydomain returns IP X.Y.Z.W , but  lookup  for
	      IP X.Y.Z.W returns a name	different than myhost.mydomain).

       --user-creds-only
	      Don't  attempt  to  authenticate	with a keytab: only use	user's
	      credentials (from	e.g. kinit).  You may need to do this to  mod-
	      ify  certain  attributes	that require Administrator credentials
	      (description, userAccountControl,	userPrincipalName,  in	a  de-
	      fault AD setup).

       --auto-update-interval <days>
	      Number  of  <days> when msktutil auto-update will	change the ac-
	      count password. Defaults to 30 days.

   OBJECT TYPE/ATTRIBUTE-SETTING OPTIONS
       --use-service-account
	      Create and maintain service  accounts  instead  of  machine  ac-
	      counts.

       --delegation
	      Enables  the  account to be trusted for delegation.  This	option
	      can also be enabled by setting the MSKTUTIL_DELEGATION  environ-
	      ment  variable.  This modifies the userAccountControl attribute.
	      Generally	requires administrator credentials.

       --description <text>
	      Sets the account's description attribute to the given  text  (or
	      removes  if  text	is '').	 Generally requires administrator cre-
	      dentials.

       --disable-delegation
	      Disables the account from	being trusted  for  delegation.	  This
	      modifies	the  userAccountControl	attribute.  Generally requires
	      administrator credentials.

       --disable-no-pac
	      Unsets the flag that disables the	KDC's including	of  a  PAC  in
	      the  machine's  service tickets.	This modifies the userAccount-
	      Control attribute.   Generally  requires	administrator  creden-
	      tials.

       --dont-expire-password
	      Sets the DONT_EXPIRE_PASSSWORD bit in the	userAccountControl at-
	      tribute, which disables password expiry for  this	 account.   If
	      you  don't run a cron job	to periodically	rotate the keytab, you
	      will want	to set this flag.   Generally  requires	 administrator
	      credentials.

       --do-expire-password
	      Unsets  the  DONT_EXPIRE_PASSWORD	flag in	the userAccountControl
	      attribute.  Generally requires administrator credentials.

       --dont-update-dnshostname
	      Do not update dnsHostName	attribute. In  some  AD	 installations
	      modification  of this attribute is not allowed (unless using ad-
	      ministrator credentials),	using  this  option  will  avoid  con-
	      straint violation	warning.

       --enable
	      Unsets the UF_ACCOUNT_DISABLE flag in the	userAccountControl at-
	      tribute.	When a computer	leaves the domain this	flag  is  nor-
	      mally set.  Generally requires administrator credentials.

       --enctypes <integer>
	      Sets the supported encryption types in the msDs-supportedEncryp-
	      tionTypes	field.

	      You may OR together the following	values:
		0x1=des-cbc-crc
		0x2=des-cbc-md5
		0x4=rc4-hmac-md5
		0x8=aes128-cts-hmac-sha1
		0x10=aes256-cts-hmac-sha1

	      This value is used to determine which encryption types  AD  will
	      offer to use, and	which encryption types to put in the keytab.

	      If the value is set to 0x3 (that is: only	the two	DES types), it
	      also attempts to set the DES-only	flag in	userAccountControl.

	      Note: Windows 2008R2 refuses to use DES  by  default;  you  thus
	      cannot  use DES-only keys	unless you have	enabled	DES encryption
	      for your domain first.  Recent versions of MIT kerberos  clients
	      similarly	refuse to use DES by default.

	      Default: sets the	value to 0x1C: that is,	use anything but DES.

       --allow-weak-crypto
	      Enables the usage	of DES keys for	authentication.	This is	equiv-
	      alent to MIT's krb5.conf parameter allow_weak_crypto.

       --no-pac
	      Specifies	that service tickets for this account should not  con-
	      tain  a  PAC.   This  modifies the userAccountControl attribute.
	      See Microsoft Knowledge Base article #832575 for details.	  This
	      option  can also be specified by setting the MSKTUTIL_NO_PAC en-
	      vironment	variable.  Generally  requires	administrator  creden-
	      tials.

       -s, --service <principal>
	      Specifies	 a  service  principal to add to the account (and thus
	      keytab, if appropriate).	The  service  is  of  the  form	 <ser-
	      vice>/<hostname>.	  If  the hostname is omitted, assumes current
	      hostname.	 May be	specified multiple times.

       --remove-service	<principal>
	      Specifies	a service principal to remove from  the	 account  (and
	      keytab if	appropriate).

       --upn <principal>
	      Sets  the	userPrincipalName attribute of the computer account or
	      service account to be <principal>.

	      The userPrincipalName can	be used	in addition to the sAMAccount-
	      Name (e.g. computername$ for computer accounts) for kinit.

	      <principal>  can	be  provided  in  short	 form (e.g. host/host-
	      name.example.com)	or  in	long  form  (e.g.  host/hostname.exam-
	      ple.com@EXAMPLE.COM). In short form the default realm will auto-
	      matically	be appended.

	      This operation requires administrator privileges.

       --set-samba-secret
	      Use Samba's net changesecretpw command to	locally	 set  the  ma-
	      chine  account  password	in Samba's secrets.tdb.	 $PATH need to
	      include Samba's net command.  Samba needs	to be  configured  ap-
	      propriately.

       --check-replication
	      Wait  until  the	password  change is reflected in LDAP.	By de-
	      fault, msktutil exits once a password update is  successful  and
	      the  new keytab is written.  However, due	to replication delays,
	      LDAP queries might still return an older key version number.  If
	      --check-replication  is given, msktutil waits until the key ver-
	      sion number is updated on	the queried LDAP server	as well.  Note
	      that  this  is just a sanity check: The new password is supposed
	      to be accepted on	all domain controllers once  the  update  suc-
	      ceeds,  even if LDAP is not yet in sync.	Turning	on this	option
	      might substantially increase the runtime of msktutil in some en-
	      vironments  due  to replication delays (eg. 15 to	30 minutes for
	      common AD	configurations).  The default is  not  to  check  LDAP
	      replication.

   CLEANUP OPTIONS
       --remove-old <number>
	      Removes  entries	from  the  keytab that are older than <number>
	      days. The	newest keytab entries will be kept to prevent a	 total
	      cleanup. I.e. it is not possible to produce an empty keytab with
	      the --remove-old option.

       --remove-enctype	<int>
	      Removes entries from the keytab with given encryption type. (See
	      --enctypes for supported encryption types.)  Warning: it is pos-
	      sible to produce empty keytabs with the --remove-empty option by
	      successively  removing  all  encryption types. Supported enctype
	      strings  are:  des-cbc-crc,des-cbc-md5,  arcfour,	  aes128   and
	      aes256.

NOTES
   PASSWORD EXPIRY
       Be  aware  that Windows machines	will, by default, automatically	change
       their account password every 30 days, and  thus	many  domains  have  a
       90-day  password	expiry window, after which your	keytab will stop work-
       ing.  There are two ways	to deal	with this:

       a) (Preferred): Make sure you're	running	a daily	cron job to run	msktu-
       til  auto-update,  which	will change the	password automatically 30 days
       after it	was last changed and update the	keytab.

       b) (Not preferred): disable password expiry for	the  account  via  the
       --dont-expire-password  option  (or otherwise setting DONT_EXPIRE_PASS-
       WORD flag in userAccountControl in AD).

   PASSWORD POLICY ISSUES
       This section only applies to msktutil --use-service-account.

       While machine account passwords may be changed at any time, service ac-
       counts are user accounts	and your Active	Directory domain may have spe-
       cial password policies for those	user accounts.	E.g.,  "minimum	 pass-
       word  age" is typically set to 1	day, which means that you will have to
       wait for	that time to pass until	you may	invoke msktutil	update	--use-
       service-account.

   OTHER NOTES
       Unlike other kerberos implementations, Active Directory has only	a sin-
       gle key for all of the principals associated with an account.   So,  if
       you  create  a  HTTP/hostname service principal,	it will	share the same
       key as the host/hostname	principal.  If you want	to isolate  (security-
       wise)  different	service	principals, you	may want to create a dedicated
       service account for them	(with --use-service-account)  and  a  separate
       keytab file (with --keytab).

       Also  note:  kinit  -k 'host/computername' *will	not work*, by default,
       even when that is a valid service principal existing  in	 your  keytab.
       Active  Directory does not allow	you to authenticate as a service prin-
       cipal, so do not	use that as a test of whether the service principal is
       working.	  If you actually want to authenticate as the computer account
       user, kinit -k 'computername$' instead.

       If you really need to be	able to	authenticate  as  'host/computername',
       you can also use	the --upn argument to set the userPrincipalName	attri-
       bute (generally requires	administrator credentials,  not	 computer  ac-
       count  credentials).  Both 'computername$' and the value	of userPrinci-
       palName are treated as valid account names to kinit as.

       msktutil	will use kerberized LDAP operations to	talk  to  domain  con-
       trollers.   To  obtain  a  LDAP service ticket, the DNS service will be
       used to construct the domain controllers	LDAP principal name.   If  DNS
       is  misconfigured, this construction may	fail.  To work around this is-
       sue,  you may specify the fully qualified DNS name of your domain  con-
       troller with the	--server option	and additionally use the --no-reverse-
       lookups option.

       Samba (www.samba.org) provides the net command that can be used to man-
       age  kerberos  keytabs  as well.	 Using msktutil	and commands like "net
       ads join" or "net ads keytab" together can lead to trouble.   With  the
       --set-samba-secret  option,  msktutil  can be used as a replacement for
       net.

       Active Directory	includes authorization data  (e.g.  information	 about
       group memberships) in Kerberos tickets.	This information is called PAC
       and may lead to very large ticket sizes.	 Especially HTTP services  are
       known  to  produce  failures if that size exceeds the HTTP header size.
       If your service does not	make use of that  PAC  information  (which  is
       true  for  most	Unix/Linux-services)  you may just disable it with the
       --no-pac	option.

EXAMPLES
       For unprivileged	users the most common invocations are:

       msktutil	create

       This will create	a computer account in  Active  Directory  with	a  new
       password	and write out a	new keytab.

       msktutil	update --service host --service	HTTP

       This  will  update  a  computer	account	in Active Directory with a new
       password, write out a new keytab, and ensure that it  has  both	"host"
       and "HTTP" service principals are on it for the hostname.

       msktutil	update	--dont-change-password --service host --service	HTTP

       This  will  do  the  same  as the last example but without changing the
       password.

       msktutil	auto-update

       This is useful in a daily cron job to check and rotate the password au-
       tomatically when	it's 30	days old.

       For users with admin privileges in AD, some common uses:

       msktutil	create --service host --service	HTTP

       This  will  create  a  computer	account	in Active Directory with a new
       password, write out a new keytab, and ensure that it  has  both	"host"
       and "HTTP" service principals are on it for the hostname.

       msktutil	pre-create --host computer1.example.com

       This will pre-create an account for computer1 with the default password
       using your credentials.	This can be done on a central  host,  e.g.  to
       script the addition of many hosts.  You can then	use msktutil create on
       the hosts themselves (without special credentials) to join them to  the
       domain.

       msktutil	create --host afs --service afs	--enctypes 0x03

       This  will  create an afs/cell.name@REALM principal, and	associate that
       principal with a	computer account called	'afs'.	The principal will  be
       marked as DES-only, which is required for AFS.

       msktutil	create --use-service-account --service HTTP/hostname.example.com --keytab /etc/apache/krb5.keytab --account-name srv-http --no-pac

       This  will create an HTTP/hostname.example.com@REALM principal, and as-
       sociate that principal with a service account called 'srv-http'.	  Cor-
       responding   Kerberos   keys   will  be	written	 to  the  keytab  file
       /etc/apache/krb5.keytab.	 The size of Kerberos tickets for that service
       will stay small because no PAC information will be included.

       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>

       This will create	a keytab for johndoe without changing John Doe's pass-
       word

       msktutil	create --service host/hostname --service host/hostname.example.com --set-samba-secret --enctypes 0x4

       This will create	a computer account in Active Directory that is compat-
       ible  with  Samba.  The command creates a new password, write out a new
       keytab,	and  ensure  that  it  includes	  both	 "host/hostname"   and
       "host/hostname.example.com"  as service principals (which is equivalent
       to what setspn.exe -R would do on windows).  The	new computer  password
       will  be	 stored	 in Samba's secrets.tdb	database to provide interoper-
       ability with Samba.  As Samba (version 3)  only	supports  arcfour  en-
       crypted	Kerberos  tickets the --enctypes option	must be	used to	select
       only that encryption type.

       msktutil	cleanup	--remove-old 10

       Deletes all entries older than 10 days, keeping at least	the  last  en-
       try.

ENVIRONMENT
       MSKTUTIL_LDAP_BASE
	      Specifies	 a relative LDAP base when creating a new account (see
	      --base),

       MSKTUTIL_KEYTAB
		Specifies   the	  keytab.   Default:   /etc/krb5.keytab	  (see
	      --keytab),

       MSKTUTIL_SERVER
	      Specifies	the domain controller (see --server).

       MSKTUTIL_DELEGATION
	      Enables  the account to be trusted for delegation	(see --delega-
	      tion).

       MSKTUTIL_NO_PAC
	      Specifies	that service tickets for this account should not  con-
	      tain a PAC (see --no-pac).

AUTHORS
       (C) 2004-2006 Dan Perry <dperry at pppl.gov>

       (C) 2006	Brian Elliott Finley (finley at	anl.gov)

       (C) 2009-2010 Doug Engert (deengert at anl.gov)

       (C) 2010	James Knight <foom at fuhm.net>

       (C) 2010-2013 Ken Dreyer	<ktdreyer at ktdreyer.com>

       (C) 2012-2017 Mark Proehl <mark at mproehl.net>

       (C) 2012-2017 Olaf Flebbe <of at	oflebbe.de>

       (C) 2013-2017 Daniel Kobras <d.kobras at	science-computing.de>

				      1.1			   msktutil(1)

NAME | SYNOPSIS | DESCRIPTION | CREDENTIALS | MODES | OPTIONS | NOTES | EXAMPLES | ENVIRONMENT | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=msktutil&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help