Provided by: msktutil_1.2.1-2_amd64 bug

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 Directory 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 Kerberos client libraries are properly installed and
       configured to use Active Directory as a realm.

       Whenever  a  principal  is  added  or  a  keytab  is  updated, the secret password for the
       corresponding account is changed.  By default, the password is not stored, so it needs  to
       be  reset each time msktutil is executed.  All entries in the keytab will be automatically
       updated whenever 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 account 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 password  is
       not  specified  with  the  option  --old-account-password,  msktutil  will use the default
       machine password.  It will then change the password 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 created object and select "Reset account" to set the password to
       the default 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 setspn.exe to set the desired servicePrincipalName(s).  You
       may also select "must change password at next logon".

MODES

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

       update Forces a password change and updates all related service principal 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 account
              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 rotated regularly.

       pre-create
              Pre-create (or update) an account for the given host with default  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 service account.

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

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 default 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 computer account name  and
              the  SAM  Account  Name.  Note that a '$' will be automatically appended to the SAM
              Account Name.  Defaults 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 hostname 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 appended to the  SAM  Account  Name  when
              using service accounts.

       --old-account-password <password>
              Use  supplied  account  password  for authentication.  This is useful 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  performing  keytab
              updates  or  the old password when creating a new keytab. This is useful for adding
              new SPNs to a machine or service 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  authenticate  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 relevant 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 affects 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 Address Translation,
              KRB-PRIV messages fail validation.  This is because the IP address in the encrypted
              part  of  the  message cannot be rewritten in the NAT process.  This option ignores
              the resulting error for the password change process, allowing systems  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 reverse 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  modify  certain attributes that require
              Administrator credentials (description, userAccountControl, userPrincipalName, in a
              default AD setup).

       --auto-update-interval <days>
              Number  of  <days>  when  msktutil  auto-update  will  change the account 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 accounts.

       --delegation
              Enables the account to be trusted for delegation.  This option can also be  enabled
              by  setting  the  MSKTUTIL_DELEGATION  environment  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 credentials.

       --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  userAccountControl  attribute.   Generally requires
              administrator credentials.

       --dont-expire-password
              Sets the DONT_EXPIRE_PASSSWORD  bit  in  the  userAccountControl  attribute,  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  administrator credentials), using this
              option will avoid constraint violation warning.

       --enable
              Unsets the UF_ACCOUNT_DISABLE flag in the  userAccountControl  attribute.   When  a
              computer  leaves  the  domain  this  flag  is  normally  set.   Generally  requires
              administrator credentials.

       --enctypes <integer>
              Sets the supported encryption types in the msDs-supportedEncryptionTypes 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  equivalent  to  MIT's
              krb5.conf parameter allow_weak_crypto.

       --no-pac
              Specifies  that  service  tickets  for this account should not contain 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   environment   variable.    Generally    requires    administrator
              credentials.

       -s, --service <principal>
              Specifies  a  service  principal  to  add  to  the  account  (and  thus  keytab, if
              appropriate).  The service is of the form <service>/<hostname>.  If the hostname is
              omitted,  assumes current hostname.  May be specified multiple times. When creating
              machine accounts, entries for the host  service  are  created  by  default,  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/hostname.

       --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  sAMAccountName  (e.g.
              computername$ for computer accounts) for kinit.

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

              This operation requires administrator privileges.

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

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

       --check-replication
              Wait until the password change is reflected in LDAP.  By  default,  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 version 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 succeeds, even if LDAP is not yet in sync.  Turning  on  this  option  might
              substantially  increase  the  runtime  of  msktutil  in  some  environments  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 --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 working.  There are two ways to deal with this:

       a) (Preferred): Make sure you're running a daily cron job  to  run  msktutil  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_PASSWORD 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 accounts are user
       accounts and your Active Directory domain may have special  password  policies  for  those
       user  accounts.   E.g., "minimum password 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 single 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 principal, 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 attribute (generally requires administrator
       credentials, not computer account credentials).  Both 'computername$'  and  the  value  of
       userPrincipalName are treated as valid account names to kinit as.

       msktutil  will  use kerberized LDAP operations to talk to domain controllers.  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
       issue,  you may specify the fully qualified DNS name of your domain  controller  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 manage 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 automatically 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  associate  that
       principal with a service account called 'srv-http'.  Corresponding 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 password

       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  compatible  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 interoperability with Samba.   As  Samba
       (version 3) only supports arcfour encrypted 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 entry.

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

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

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

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-2021 Olaf Flebbe <of at oflebbe.de>

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

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

       (C) 2017-2022 Michael Osipov <michael.osipov at siemens.com>

       (C) 2018-2022 Daniel Kobras <kobras at puzzle-itc.de>

                                              1.2.1                                   msktutil(1)