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 ou>
Specifies an LDAP base OU when creating a new account. Unless
the given string ends with the domain's base DN, it is assume to
be a relative path: 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 MSKTUTIL_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 (a 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.

-m, --sasl-mechanisms <mechanisms list>
A space-separated list of candidate SASL mechanisms to use when
performing the LDAP bind. The first mechanism in the list that
is supported by both the client (the host running msktutil) and
the server (Active Directory) will be used. If providing more
than one candidate mechanism, make sure to quote the list to
protect the whitespace from the shell. Default: "GSS-SPNEGO
GSSAPI".

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. When creating ma-
chine accounts, entries for the host service are created by de-
fault, unless --service is given. Unqualified service names
(without a '/' component) are qualified with the full and the
short hostnames, eg. host/hostname.example.com and host/host-
name.

--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.

--use-samba-cmd <command>
Use supplied command instead of Samba's net changesecretpw com-
mand. command will be supplied machine account password on stan-
dard input and shall return 0 exit code on success.

--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 <enctype>
Removes entries from the keytab with given encryption type.
Warning: it is possible to produce empty keytabs with the --re-
move-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 at-
tribute (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).

MSKTUTIL_SAMBA_CMD
Specifies the command to be used to locally set the machine ac-
count password in Samba's secrets.tdb.

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

1.2.2 msktutil(1)

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

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages