Subcommands

The following subcommand descriptions assume the administration server is using the standard MIT Kerberos database for the registry. Other database implementations may not support all of the subcommand options and attributes.

The following subcommands are supported:
help [subcommand]
The help subcommand displays the command syntax for the specified subcommand. If no subcommand name is specified, the available subcommands are displayed.
get_privs
The get_privs (also known as getprivs) subcommand lists the administrative privileges for the authenticated client. Additional authorization checking may be performed for a specific administration function depending upon the function and the database implementation.
list_principals [expression]
The list_principals (also known as listprincs) subcommand lists all of the principals in the Kerberos database that match the specified search expression. If no search expression is provided, all principals are listed. You must have LIST authority.

The search expression can include the “*” and “?” wild cards where “*” represents zero or more characters and “?” represents a single character. For example, the expression */admin@* returns all principal names that end with /admin, the expression rwh* returns all principal names that begin with rwh, and the expression test_client?@* returns principal names such as test_client1, test_client2, and so forth.

The search string can also contain paired “[“and “]” characters with one or more characters between the brackets. A match occurs if a name contains one of the characters between the brackets. For example, the expression */[ad]* returns all names containing /a and /d, while the expression [ckr]* returns all names beginning with c, k, or r.

get_principal name
The get_principal (also known as getprinc) subcommand displays information for a single principal entry. You must have GET authority, or the principal entry must be your own entry.
The following principal attributes can be displayed by the get_principal subcommand. The attributes that are supported by the administration server are dependent upon the Kerberos database implementation.
DISALLOW_DUP_SKEY
Specifies that a service ticket cannot be encrypted using the session key of an existing ticket.
DISALLOW_FORWARDABLE
Specifies that forwardable tickets are not allowed.
DISALLOW_POSTDATED
Specifies that postdated tickets are not allowed.
DISALLOW_PROXIABLE
Specifies that proxiable tickets are not allowed.
DISALLOW_RENEWABLE
Specifies that renewable tickets are not allowed.
DISALLOW_SVR
Specifies that service tickets cannot be obtained for this principal.
DISALLOW_TGT_BASED
Specifies that service tickets cannot be obtained using a ticket-granting ticket.
DISALLOW_ALL_TIX
Specifies that tickets cannot be obtained for this principal.
REQUIRES_PWCHANGE
Specifies that the password must be changed.
PWCHANGE_SERVICE
Specifies that this is a password-changing service. The KDC grants an initial ticket to a password-changing service even if the current password is expired.
REQUIRES_HW_AUTH
Specifies that hardware authentication must be used when requesting a ticket. When requesting an initial ticket, hardware authentication must be used, and when requesting a service ticket, the ticket-granting ticket must indicate hardware authentication.
Note: z/OS does not support hardware authentication for an initial ticket but it will grant a service ticket when hardware authentication is requested if the ticket-granting ticket is from a foreign realm where hardware authentication is supported and used.
REQUIRES_PRE_AUTH
Specifies that preauthentication must be used when requesting a ticket. When requesting an initial ticket, preauthentication data must be provided, and when requesting a service ticket, the ticket-granting ticket must indicate preauthentication.
SUPPORT_DESMD5
Specifies that ENCTYPE_DES_CBC_MD5 keys are supported for this principal.
add_principal [options] [attributes] name
The add_principal (also known as addprinc) subcommand adds a new principal entry to the Kerberos database. The options and attributes may be specified before or after the principal name and may be entered in any order. You must have ADD authority.
The following options are supported for the add_principal subcommand:
-clearpolicy
Specifies that no policy is to be associated with the principal entry. The default policy is used if neither -policy nor -clearpolicy is specified and a policy named default exists. This option is mutually exclusive with the -policy option.
-e key types
Specifies the key types to be generated. All available key types are generated if this option is not specified. Entries in the list are separated by commas. Each entry consists of an encryption type and a salt type, separated by a colon. The salt type can be omitted and defaults to normal. Similar encryption types are ignored when processing the list. For example, encryption types des-cbc-crc and des-cbc-md5 use the same DES key, so only one of these encryption types needs to be specified to cause a DES key to be generated.
-expire date
Specifies the expiration date for the principal entry. If this option is not specified, the entry does not expire.
-kvno version
Specifies the key version number for the encryption keys generated by this command. If this option is not specified, the initial key version number is set to 1. A key version of 0 is not allowed.
-maxlife interval
Specifies the maximum ticket lifetime. If this option is not specified, the maximum ticket lifetime is obtained from the KDC policy.
-maxrenewlife interval
Specifies the maximum renewable ticket lifetime. If this option is not specified, the maximum renewable ticket lifetime is obtained from the KDC policy.
-policy name
Specifies the policy associated with the principal. The default policy is used if neither -policy nor -clearpolicy is specified and a policy named default exists. This option is mutually exclusive with the -clearpolicy option.
-pw password
Specifies the password for the principal entry. The user is prompted to enter the password in non-display mode if neither -pw nor -randkey is specified. This option is mutually exclusive with the -randkey option.
-pwexpire date
Specifies the expiration date for the password. If this option is not specified, the password lifetime from the effective policy is used to set the password expiration date.
-randkey
Specifies that a random key is to be generated for this principal. This option is mutually exclusive with the -pw option. If neither -pw nor -randkey is specified, the user is prompted to enter the password in non-display mode.
The following attributes are supported for the add_principal subcommand. The attributes that are supported by the administration server are dependent upon the Kerberos database implementation.
+allow_dup_skey
Specifies that a service ticket can be encrypted using the session key of an existing ticket. This is the default.
-allow_dup_skey
Specifies that a service ticket cannot be encrypted using the session key of an existing ticket.
+allow_forwardable
Specifies that forwardable tickets are allowed. This is the default.
-allow_forwardable
Specifies that forwardable tickets are not allowed.
+allow_postdated
Specifies that postdated tickets are allowed. This is the default.
-allow_postdated
Specifies that postdated tickets are not allowed.
+allow_proxiable
Specifies that proxiable tickets are allowed. This is the default.
-allow_proxiable
Specifies that proxiable tickets are not allowed.
+allow_renewable
Specifies that renewable tickets are allowed. This is the default.
-allow_renewable
Specifies that renewable tickets are not allowed.
+allow_svr
Specifies that service tickets can be obtained for this principal. This is the default.
-allow_svr
Specifies that service tickets cannot be obtained for this principal.
+allow_tgs_req
Specifies that service tickets can be obtained using a ticket-granting ticket. This is the default.
-allow_tgs_req
Specifies that service tickets cannot be obtained using a ticket-granting ticket.
+allow_tix
Specifies that tickets can be obtained for this principal. This is the default.
-allow_tix
Specifies that tickets cannot be obtained for this principal.
+needchange
Specifies that the password must be changed.
-needchange
Specifies that the password does not need to be changed. This is the default.
+password_changing_service
Specifies that this is a password changing service. The KDC grants an initial ticket to a password changing service even if the current password is expired.
-password_changing_service
Specifies that this is not a password changing service. This is the default.
+requires_hwauth
Specifies that hardware authentication must be used when requesting a ticket. Hardware authentication must be used when requesting an initial ticket, and the ticket-granting ticket must indicate hardware authentication when requesting a service ticket.
Note: z/OS does not support hardware authentication for an initial ticket but it will grant a service ticket when hardware authentication is requested if the ticket-granting ticket is from a foreign realm where hardware authentication is supported and used.
-requires_hwauth
Specifies that hardware authentication is not required. This is the default.
+requires_preauth
Specifies that preauthentication must be used when requesting a ticket. Preauthentication data must be provided when requesting an initial ticket, and the ticket-granting ticket must indicate preauthentication when requesting a service ticket.

Note that a z/OS KDC always requires preauthentication when requesting an initial ticket, even if this attribute is not set. This is done to improve the security of the Kerberos secret keys.

-requires_preauth
Specifies that preauthentication is not required. This is the default.
+support_desmd5
Specifies that ENCTYPE_DES_CBC_MD5 keys are supported for this principal.
-support_desmd5
Specifies that ENCTYPE_DES_CBC_MD5 keys are not supported for this principal. This is the default.
delete_principal name
The delete_principal (also known as delprinc) subcommand deletes a principal entry from the Kerberos database. You must have DELETE authority.
modify_principal [options] [attributes] name
The modify_principal (also known as modprinc) subcommand modifies an existing principal entry in the Kerberos database. The options and attributes may be specified before or after the principal name and may be entered in any order. You must have MODIFY authority.
The following options are supported for the modify_principal subcommand. The attributes that are supported by the administration server are dependent upon the Kerberos database implementation.
-clearpolicy
Specifies that no policy is to be associated with the principal entry. This option is mutually exclusive with the -policy option.
-expire date
Specifies the expiration date for the principal entry.
-kvno version
Specifies the key version number for the principal.
-maxlife interval
Specifies the maximum ticket lifetime.
-maxrenewlife interval
Specifies the maximum renewable ticket lifetime.
-policy name
Specifies the policy associated with the principal. This option is mutually exclusive with the -clearpolicy option.
-pwexpire date
Specifies the expiration date for the password.
The following attributes are supported for the modify_principal subcommand:
+allow_dup_skey
Specifies that a service ticket can be encrypted using the session key of an existing ticket. Resets the DISALLOW_DUP_SKEY attribute.
-allow_dup_skey
Specifies that a service ticket cannot be encrypted using the session key of an existing ticket. Sets the DISALLOW_DUP_SKEY attribute.
+allow_forwardable
Specifies that forwardable tickets are allowed. Resets the DISALLOW_FORWARDABLE attribute.
-allow_forwardable
Specifies that forwardable tickets are not allowed. Sets the DISALLOW_FORWARDABLE attribute.
+allow_postdated
Specifies that postdated tickets are allowed. Resets the DISALLOW_POSTDATED attribute.
-allow_postdated
Specifies that postdated tickets are not allowed. Sets the DISALLOW_POSTDATED attribute.
+allow_proxiable
Specifies that proxiable tickets are allowed. Resets the DISALLOW_PROXIABLE attribute.
-allow_proxiable
Specifies that proxiable tickets are not allowed. Sets the DISALLOW_PROXIABLE attribute.
+allow_renewable
Specifies that renewable tickets are allowed. Resets the DISALLOW_RENEWABLE attribute.
-allow_renewable
Specifies that renewable tickets are not allowed. Sets the DISALLOW_RENEWABLE attribute.
+allow_svr
Specifies that service tickets can be obtained for this principal. Resets the DISALLOW_SVR attribute.
-allow_svr
Specifies that service tickets cannot be obtained for this principal. Sets the DISALLOW_SVR attribute.
+allow_tgs_req
Specifies that service tickets can be obtained using a ticket-granting ticket. Resets the DISALLOW_TGT_BASED attribute.
-allow_tgs_req
Specifies that service tickets cannot be obtained using a ticket-granting ticket. Sets the DISALLOW_TGT_BASED attribute.
+allow_tix
Specifies that tickets can be obtained for this principal. Resets the DISALLOW_TIX attribute.
-allow_tix
Specifies that tickets cannot be obtained for this principal. Sets the DISALLOW_TIX attribute.
+needchange
Specifies that the password must be changed. Sets the REQUIRES_PWCHANGE attribute.
-needchange
Specifies that the password does not need to be changed. Resets the REQUIRES_PWCHANGE attribute.
+password_changing_service
Specifies that this is a password changing service. The KDC grants an initial ticket to a password changing service even if the current password is expired. Sets the PWCHANGE_SERVICE attribute.
-password_changing_service
Specifies that this is not a password changing service. Resets the PWCHANGE_SERVICE attribute.
+requires_hwauth
Specifies that hardware authentication must be used when requesting a ticket. Hardware authentication must be used when requesting an initial ticket, and the ticket-granting ticket must indicate hardware authentication when requesting a service ticket. Sets the REQUIRES_HW_AUTH attribute.
Note: z/OS does not support hardware authentication for an initial ticket but it will grant a service ticket when hardware authentication is requested if the ticket-granting ticket is from a foreign realm where hardware authentication is supported and used.
-requires_hwauth
Specifies that hardware authentication is not required. Resets the REQUIRES_HW_AUTH attribute.
+requires_preauth
Specifies that preauthentication must be used when requesting a ticket. Preauthentication data must be provided when requesting an initial ticket, and the ticket-granting ticket must indicate preauthentication when requesting a service ticket. Sets the REQUIRES_PRE_AUTH attribute.
-requires_preauth
Specifies that preauthentication is not required. Resets the REQUIRES_PRE_AUTH attribute.

Note that a z/OS KDC always requires preauthentication when requesting an initial ticket, even if this attribute is not set. This is done to improve the security of the Kerberos secret keys.

+support_desmd5
Specifies that ENCTYPE_DES_CBC_MD5 keys are supported for this principal. Sets the SUPPORT_DESMD5 attribute.
-support_desmd5
Specifies that ENCTYPE_DES_CBC_MD5 keys are not supported for this principal. Resets the SUPPORT_DESMD5 attribute.
change_password [-randkey | -pw password] [-keepold] [-e keytypes] name
The change_password (also known as cpw) subcommand changes the password for a principal. You must have CHANGEPW authority, or the principal entry must be your own entry.

A random key is generated if the -randkey option is specified. Otherwise, you are prompted to enter the new password unless the -pw option is specified.

Any existing encryption keys are discarded unless the -keepold option is specified. The number of retained keys is dependent upon the Kerberos database implementation.

All available key types are generated unless the -e option is specified. Entries in the key types list are separated by commas. Each entry consists of an encryption type and a salt type, separated by a colon. The salt type can be omitted and defaults to normal. Similar encryption types are ignored when processing the list. For example, encryption types des-cbc-crc and des-cbc-md5 use the same DES key, so only one of these encryption types needs to be specified to cause a DES key to be generated.

rename_principal oldname newname
The rename_principal (also known as renprinc) subcommand changes the name of a principal entry in the Kerberos database. You must have both ADD and DELETE authority.

Since the principal name is often used as part of the password salt, you should change the password for the principal after the entry is renamed. Some implementations of the Kerberos administration server do not allow a principal to be renamed if the principal name is used in the password salt. In this case, you must delete the existing principal entry using the delete_principal subcommand and then add the new principal entry using the add_principal subcommand.

list_policies [expression]
The list_policies (also known as listpols) subcommand lists all of the policies in the Kerberos database that match the specified search expression. All policies are listed if no search expression is provided. You must have LIST authority.

The search expression can include the “*” and “?” wild cards where “*” represents zero or more characters and “?” represents a single character. For example, the expression *_local returns all policy names that end with _local, the expression def* returns all policy names that begin with def, and the expression test_policy? returns policy names such as test_policy1, test_policy2, and so forth.

The search string can also contain paired “[“ and “]” characters with one or more characters between the brackets. A match occurs if a name contains one of the characters between the brackets. For example, the expression [adh]* returns all names beginning with a,d, or h.

get_policy name
The get_policy (also known as getpol) subcommand displays information for a single policy entry. You must have GET authority or the policy must be associated with your own principal entry.
add_policy [options] name
The add_policy (also known as addpol) subcommand adds a new policy to the Kerberos database. The options may be specified before or after the policy name and may be specified in any order. You must have ADD authority.
The following options are supported for the add_policy subcommand:
-maxlife interval
Specifies the maximum password lifetime. The password must be changed after this interval has elapsed.
-minlife interval
Specifies the minimum password lifetime. A new password cannot be changed until this interval has elapsed.
-minlength number
Specifies the minimum password length.
-minclasses number
Specifies the minimum number of character classes in the password.
-history number
Specifies the number of passwords in the password history. A new password cannot match any of the remembered passwords.
modify_policy [options] name
The modify_policy (also known as modpol) subcommand modifies an existing policy in the Kerberos database. The options may be specified before or after the policy name and may be specified in any order. You must have MODIFY authority.
The following options are supported for the modify_policy subcommand:
-maxlife interval
Specifies the maximum password lifetime. The password must be changed after this interval has elapsed.
-minlife interval
Specifies the minimum password lifetime. A new password cannot be changed until this interval has elapsed.
-minlength number
Specifies the minimum password length.
-minclasses number
Specifies the minimum number of character classes in the password.
-history number
Specifies the number of passwords in the password history. A new password cannot match any of the remembered passwords.
delete_policy name
The delete_policy (also known as delpol) subcommand deletes a policy entry from the Kerberos database. You must have DELETE authority.
add_key [[-keytab | -k] keytab_name] [-keepold] [-e keytypes] principal_name
The add_key (also known as ktadd) subcommand generates a set of random encryption keys for the named principal and then adds the generated keys to the specified key table. You must have CHANGEPW authority or the principal entry must be your own entry.

The default key table is used if the -keytab option is not specified. A key table name prefix of “FILE:” is changed to “WRFILE:” because the add_key subcommand must update the key table.

Any existing encryption keys are discarded unless the -keepold option is specified. The number of retained keys is dependent upon the Kerberos database implementation.

All available key types are generated unless the -e option is specified. Entries in the key types list are separated by commas. Each entry consists of an encryption type and a salt type, separated by a colon. The salt type can be omitted and defaults to normal. Similar encryption types are ignored when processing the list. For example, encryption types des-cbc-crc and des-cbc-md5 use the same DES key, so only one of these encryption types needs to be specified to cause a DES key to be generated.