resolv.conf is the configuration file of the DNS stub resolver in Linux and other Unix-like systems, located at /etc/resolv.conf, that tells applications which DNS servers to query, which search domains to append to short host names and which resolver options to use. In Linux networking, it is the point where name resolution settings from DHCP, NetworkManager, systemd-resolved or manual configuration finally take effect for most programs.
The file is read by the resolver library in the C standard library, typically glibc or musl, when a program calls functions such as getaddrinfo. It does not run a service by itself; it only describes how the library should ask DNS servers for answers.
How the resolver uses the file
When an application needs an IP address, the C library first consults the Name Service Switch configuration in /etc/nsswitch.conf, which typically checks /etc/hosts before DNS. If DNS is needed, the resolver reads resolv.conf and sends a query over UDP port 53, falling back to TCP for large responses, to the first listed nameserver.
If the first server does not answer within the timeout, the resolver tries the next server, cycling through the list for a set number of attempts. Servers are tried in order, not in parallel, so a dead first entry slows down every lookup on the system, which is one of the most common causes of mysteriously slow logins and connections.
| Step | Component | What happens |
|---|---|---|
| Lookup order | /etc/nsswitch.conf | Decides whether files or DNS are checked first |
| Local file check | /etc/hosts | Static mappings are returned immediately |
| Name expansion | search and ndots settings | Short names get search domains appended |
| Query | nameserver entries | UDP query sent to the first server |
| Retry and fallback | timeout and attempts options | Next server tried after a timeout |
Directives and options
The file has a small, line-oriented syntax. Each line begins with a keyword followed by values, and lines starting with # or ; are comments. Only a handful of directives are in common use.
| Directive | Purpose | Limits and defaults |
|---|---|---|
| nameserver | IP address of a DNS server | Up to 3 used by glibc, extra lines ignored |
| search | Domains appended to short names | Several domains, last search or domain line wins |
| domain | Single local domain name | Older form, superseded by search |
| options | Resolver behavior flags | Several options on one line |
| sortlist | Preferred address ranges for answers | Rarely used today |
The options line controls timing and name handling. The defaults are conservative, and tuning them is a common step in containers and high-volume services.
| Option | Effect | Default in glibc |
|---|---|---|
| timeout:n | Seconds to wait for each server | 5 seconds |
| attempts:n | Rounds through the server list | 2 attempts |
| ndots:n | Dots needed before a name is tried as absolute first | 1 |
| rotate | Spread queries across servers round-robin | Off |
| edns0 | Enable larger UDP responses | Off |
| single-request | Send A and AAAA queries sequentially | Off |
Who manages resolv.conf on modern systems
On current distributions the file is rarely edited by hand, because several network tools generate it automatically. Manual edits are often silently overwritten at the next DHCP renewal or network change, so identifying the owner of the file is the first step in any DNS troubleshooting.
| Manager | How the file looks | Where to change settings |
|---|---|---|
| systemd-resolved | Symlink with nameserver 127.0.0.53 | resolved.conf, network units or nmcli |
| NetworkManager | Generated file with a header comment | Connection profiles via nmcli |
| Netplan | Settings passed to the backend renderer | YAML files under /etc/netplan |
| resolvconf or openresolv | Assembled from interface fragments | Interface configuration or hooks |
| DHCP client alone | Rewritten on lease renewal | DHCP client configuration |
| Container runtime | Generated per container | Runtime or orchestrator DNS settings |
With systemd-resolved, the file usually points applications to a local stub listener at 127.0.0.53, which then forwards queries to the real upstream servers, caches results and handles per-interface DNS for VPNs. Running ls -l /etc/resolv.conf shows whether it is a symlink and to which file, and resolvectl status shows the actual upstream servers.
Pitfalls and troubleshooting
- Manual edits disappear: a network manager regenerates the file, so settings must be made in the manager’s own configuration.
- High ndots values in Kubernetes: with
ndots:5, external names are first tried with every search domain, multiplying DNS queries. - A dead first nameserver adds a delay of the full timeout to every lookup.
- Copying 127.0.0.53 into containers breaks resolution, because that address refers to the host’s loopback, not the container’s.
- Making the file immutable with
chattr +ihides the real configuration problem and confuses later administrators.
For diagnosis, getent hosts name tests resolution exactly as applications see it, including nsswitch and search domains, while dig and nslookup query DNS servers directly and can bypass parts of the resolver logic. Comparing both quickly shows whether a problem lies in resolv.conf settings or in the DNS servers themselves.
Inside containers and Kubernetes pods, the file is generated by the runtime for each container, so changes belong in the pod or runtime DNS policy rather than in the image. Inspecting the file from inside a running container with cat /etc/resolv.conf remains the quickest way to confirm which nameserver, search list and ndots value the workload actually uses, because these often differ from the host.
In everyday language
Computers find websites by number, not by name, so they need a phone book service called DNS. The resolv.conf file is a short note telling the computer which phone book services to call.
It lists up to three services to try in order. It can also say which family name to add when someone gives only a first name, such as turning “printer” into a full office address. If the note lists a service that never answers, every lookup has to wait before trying the next one.
Seen in the real world
A developer notices that SSH logins and package downloads on an Ubuntu server take about five seconds longer than they should. getent hosts shows the delay, while dig against the company DNS server answers instantly.
Inspecting /etc/resolv.conf reveals that it was edited by hand to list an old DNS server that was decommissioned last month, and that the edit survived because systemd-resolved had been disabled. The administrator restores the symlink to the systemd-resolved stub file, configures the correct DNS servers in the Netplan YAML file and applies the change. Lookups return to a few milliseconds, and a new configuration management rule now checks the symlink on every server to stop the problem from returning.