When adding Powershell hosts to vRealize Orchestrator using Kerberos Authentication, one has to create the krb5.conf file. There are various articles on that and the best one I’ve seen is “this one”, so I am not going to repeat all that information here. However, I thought to write something up about what’s important to remember while writing the configuration sections and explain what those sections are about so that informed decisions can be made while writing the file. Please note that there are many other types of section that this file can contain and also many other options for each one of them. I am just explaining the sections and options used for this particular use case.
[libdefaults]
This is typically the first section in the file and it contains the various defaults values that can be used from the Kerberos V5 library. For the purpose of this post, we use “default_realm”, which is pretty self-explanatory in that it defines the Kerberos realm that is used by default. One typically points it to the main Active Directory domain as the Kerberos realm but there can be others. Note that the realm is defined in UPPERCASE. This is “by convention” and carries throughout the file. Kerberos realms are defined that way in the file and it’s important to keep this case convention.
The second option used in this file is: udp_preference_limit = 1. Contrary to popular belief, the “1” is there NOT to switch on the option. The value is actually in bytes and is simply a way to force TCP to be used in preference to UDP. If there is a higher value and the message size is smaller than that in bytes, then UDP would be tried first. That said, both protocols will be used in case of failure regardless. As you can see, setting it at 1, makes all messages bigger and hence, TCP is given priority.
[realms]
This section is where there are one or more subsections, defining the Kerberos realms and their Kerberos servers, with designated roles. It can also contain other realm-specific information. “kdc” here is the most important one and defines the server(s) acting as the KDC. In an Active Directory domain based scenario, the KDC service is running on it so one just points it to one or more domain controllers. It’s actually supposed to be used only if DNS is not advertising the service but it ensures that the DCs can be used regardless.
Then there is the “admin_server” option. It is used to point any administrative operations towards a particular server. If there are more than one, pick the one that is preferred.
There is also a “default_domain” option. This option maps the default domain all these Kerberos servers are in. Also, this is actually required for any V4 instances where principal names don’t contain a domain name.
As you can also see in my example screenshot, if you have multiple domains and want to add hosts from there too, you can have more than one subsection with the relevant entries.
[domain_realm]
First thing to note is that it’s NOT “domain_realms” i.e. it’s not plural! Considering you can define multiple realm mappings in there, it doesn’t seem surprising that many people make this typo. It also doesn’t help when VMware’s own documentation contains the error. The section won’t be found because of the typo but everything still works because if no mapping is found, domain part of the hostname is accepted as the Kerberos realm (in uppercase, of course) and they’re typically the same so it’s not a problem. However, it can cause issues if the domain part of the hostname doesn’t match the Kerberos realm, which can be the case in certain environments.
Anyway, getting back to the entries. This section maps a hostname or domain to a Kerberos realm. The first pair of entries in the example screenshot, maps all hosts under the domain “domain.local” and the domain itself, to DOMAIN.LOCAL Kerberos realm, respectively. As with the previous section, similar mappings can be made for multiple domains here.
[logging]
In my example screenshot, I don’t have the logging section as it’s not required and is also not in VMware’s recipe. However, I thought I should write about that as well, for the sake of completeness. As they’re absent from my screenshot, here is what people typically use:
kdc = FILE:/var/log/krb5/krb_kdc.log
admin_server = FILE:/var/log/krb5/kadmin.log
default = SYSLOG:NOTICE:DAEMON
First two are easy to explain as they both log kdc and admin server activity into files specified in the path. That said, make note of the : (colon) after FILE. This is important as it allows the file to be appended. Replacing it with = by mistake, would result in the file being overwritten.
The “default” entry defines what to do in absence of any specific instructions. In the case above, it defines that all “NOTICE” level messages from the “DAEMON” should go to the system log. There are other options also available e.g. ERR, WARNING, INFO, DEBUG etc. for the former and KERN, USER, MAIL etc. for the latter, being popular choices.
Hope this post will be helpful in understanding what these options mean and their effect. It’s always good to know what you’re doing when writing a configuration file!
This is typically the first section in the file and it contains the various defaults values that can be used from the Kerberos V5 library. For the purpose of this post, we use “default_realm”, which is pretty self-explanatory in that it defines the Kerberos realm that is used by default. One typically points it to the main Active Directory domain as the Kerberos realm but there can be others. Note that the realm is defined in UPPERCASE. This is “by convention” and carries throughout the file. Kerberos realms are defined that way in the file and it’s important to keep this case convention.
The second option used in this file is: udp_preference_limit = 1. Contrary to popular belief, the “1” is there NOT to switch on the option. The value is actually in bytes and is simply a way to force TCP to be used in preference to UDP. If there is a higher value and the message size is smaller than that in bytes, then UDP would be tried first. That said, both protocols will be used in case of failure regardless. As you can see, setting it at 1, makes all messages bigger and hence, TCP is given priority.
[realms]
This section is where there are one or more subsections, defining the Kerberos realms and their Kerberos servers, with designated roles. It can also contain other realm-specific information. “kdc” here is the most important one and defines the server(s) acting as the KDC. In an Active Directory domain based scenario, the KDC service is running on it so one just points it to one or more domain controllers. It’s actually supposed to be used only if DNS is not advertising the service but it ensures that the DCs can be used regardless.
Then there is the “admin_server” option. It is used to point any administrative operations towards a particular server. If there are more than one, pick the one that is preferred.
There is also a “default_domain” option. This option maps the default domain all these Kerberos servers are in. Also, this is actually required for any V4 instances where principal names don’t contain a domain name.
As you can also see in my example screenshot, if you have multiple domains and want to add hosts from there too, you can have more than one subsection with the relevant entries.
[domain_realm]
First thing to note is that it’s NOT “domain_realms” i.e. it’s not plural! Considering you can define multiple realm mappings in there, it doesn’t seem surprising that many people make this typo. It also doesn’t help when VMware’s own documentation contains the error. The section won’t be found because of the typo but everything still works because if no mapping is found, domain part of the hostname is accepted as the Kerberos realm (in uppercase, of course) and they’re typically the same so it’s not a problem. However, it can cause issues if the domain part of the hostname doesn’t match the Kerberos realm, which can be the case in certain environments.
Anyway, getting back to the entries. This section maps a hostname or domain to a Kerberos realm. The first pair of entries in the example screenshot, maps all hosts under the domain “domain.local” and the domain itself, to DOMAIN.LOCAL Kerberos realm, respectively. As with the previous section, similar mappings can be made for multiple domains here.
[logging]
In my example screenshot, I don’t have the logging section as it’s not required and is also not in VMware’s recipe. However, I thought I should write about that as well, for the sake of completeness. As they’re absent from my screenshot, here is what people typically use:
kdc = FILE:/var/log/krb5/krb_kdc.log
admin_server = FILE:/var/log/krb5/kadmin.log
default = SYSLOG:NOTICE:DAEMON
First two are easy to explain as they both log kdc and admin server activity into files specified in the path. That said, make note of the : (colon) after FILE. This is important as it allows the file to be appended. Replacing it with = by mistake, would result in the file being overwritten.
The “default” entry defines what to do in absence of any specific instructions. In the case above, it defines that all “NOTICE” level messages from the “DAEMON” should go to the system log. There are other options also available e.g. ERR, WARNING, INFO, DEBUG etc. for the former and KERN, USER, MAIL etc. for the latter, being popular choices.
Hope this post will be helpful in understanding what these options mean and their effect. It’s always good to know what you’re doing when writing a configuration file!
Is this supposed to be plural?
udp_preferences_limit = 1
Should there be no “s” ?
http://web.mit.edu/Kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html
Thanks David,
You are absolutely right! It seems I made the typo when taking the screenshot (as the text explanation below is correct). Let’s see when I get the chance to fix it!
Nice spot! 🙂
Ather