Published on 19 September 2013 by

Puppet Enterprise relies on having working name resolution available. Most commonly this is provided via a local hosts file, or organizational DNS servers. If you’ve installed Puppet Enterprise on a machine or two, and you find yourself staring at some alarming pink text (as shown below), you probably have an issue with name resolution in your environment.

Screenshot of error message indicating DNS issue

Fortunately, there are good tools and procedures you can use to investigate name resolution problems.

When faced with resolution errors, I first like to test to see if they’re limited to the particular host I’m trying to reach, or symptomatic of a more general issue.

If you’re making use of the hosts file (e.g. /etc/hosts in most Linuxes) to locally define the mappings between the names of your machines and their IP addresses, you can very simply test whether that’s working as expected by trying to ping your master by name and seeing if the expected IP is used by the utility. If not, usually it’s an error in one of two places: the hosts file, or the configuration file that determines where your system will look for domain name mappings (e.g. /etc/nsswitch.conf in most Linuxes).

If you’re using DNS, you’ll need to break out some more interesting tools. In this example, I’ve used the dig utility to perform lookups of two fully qualified domain names (keep in mind that dig only performs lookups against name servers — it won’t use information from your hosts file). One is, a known good name that should resolve successfully. The other is my Puppet master, puppet.ipa.vm. resolves successfully, but puppet.ipa.vm returns an “NXDOMAIN” status, indicating the request could not be resolved because the name does not exist.

Screenshot of using dig to look up domain names

This tells me I should double check my configuration and ensure I’m using the correct name for my Puppet server. If that checks out, the DNS server configuration needs to be examined to see if there is a bad or absent entry for the host.

Another possibility is receiving output like what you see below when testing resolution of a name.

Screenshot of what it looks like when dig cannot contact the configured DNS servers.

This indicates that dig was unable to contact the configured DNS servers for some reason. The culprit in this case could be a number of things. We might have no network connectivity at all, or there could be something blocking the traffic. The locally configured DNS servers (found in /etc/resolv.conf on many Linuxes) might be incorrect, or be down.

The instructions above will point you in the right direction to remedy the most common name resolution issues we’ve seen. Once you’ve resolved yours, it’s time to get started with Puppet Enterprise. Here, too, there are just a few very common issues we often help people with. Ruth Linehan, a developer here at Puppet Labs, tells you which logs to check if something goes sideways.

Photo of Ken Johnson, Puppet Labs support engineerKen Johnson is a support engineer at Puppet Labs. When he's not helping people with a remarkable range of technical issues, he's fixing vintage arcade games or cars. Follow Ken on Twitter (@kjpdx) or connect with him on Google+.

Learn More

Share via:
Posted in:

Re: your G+ post "You can't use #Puppet Enterprise unless your DNS services are working. Support engineer +Ken Johnson offers help with troubleshooting #DNS issues. " linking here?

Why say that "Puppet Enterprise relies on having working DNS services" at the top of this post. then later say that /etc/hosts files can work perfectly well, when /etc/hosts files can obviate the need for DNS services? Which is easier to manage, and has the greater security impact, varies with the environment.

For example, if I have a reliable means of pushing /etc/hosts, I can save networking round-trips to DNS (you don't want to do DNS in conjunction with Netfilter, AKA iptables), and I may need no highly-sensitive 'keys-to-the-kingdom' DNS server. Which might require defining and enforcing a closely-controlled security posture. For other security reasons, a user might accept this OPEX and CAPEX in order to do reverse-DNS lookups, for entirely valid reasons.

I think you may be adding to DNS confustion, and there is already enough of that to go around..

Greg Metcalfe

Quite correct Greg, I should have said it requires correctly functioning name resolution of some sort, not necessarily DNS based. I'll revise to reflect that distinction.

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.