Linux /etc/hosts File: Local Hostname Resolution

Learn how to use Linux /etc/hosts for local hostname-to-IP mappings, validate entries, understand NSS and DNS lookup order, and troubleshoot common problems.

The Linux /etc/hosts file is a local, plain-text name-resolution database. It maps human-readable hostnames to IP addresses without requiring a DNS lookup. A hostname is a name such as webserver or webserver.lab.example; an IP address is a numeric network address such as 192.168.198.140 or 2001:db8::140.

Each mapping applies only to the machine whose /etc/hosts file contains it. Editing the file on one workstation does not update other computers, DNS servers, containers, or virtual machines.

What /etc/hosts Does

Name resolution is the process of finding the IP address associated with a hostname. When an application connects to webserver, the operating system must resolve that name before it can usually open a network connection.

The hosts file provides a static, local answer. For example, this entry tells the machine that webserver is at 192.168.198.140:

192.168.198.140 webserver

Applications can then use webserver instead of the numeric address. The mapping does not prove that the address is reachable or that a service is listening there; it only supplies an address for the name.

Location and Permissions

The standard Linux path is /etc/hosts. Reading it is generally unrestricted, but modifying it requires administrative privileges because it is part of the system configuration.

cat /etc/hosts

Use a privilege-safe editor workflow rather than changing permissions on the file:

sudoedit /etc/hosts

sudoedit opens an editor with a temporary copy and installs the saved result with the appropriate administrative privileges. Before editing, make a backup:

sudo cp /etc/hosts /etc/hosts.bak

Hosts File Syntax

A hosts-file line contains an IP address first, followed by a canonical hostname and optional aliases. Fields are separated by spaces or tabs. A comment begins with # and continues to the end of the line.

IP-address canonical-hostname optional-alias-1 optional-alias-2 # comment

One line represents one IP-address mapping. Multiple names on that line resolve to the same address.

192.168.198.140 webserver.lab.example webserver lab-web

Both IPv4 and IPv6 addresses are supported:

192.168.198.140 webserver
2001:db8::140 webserver-v6

A fully qualified domain name, or FQDN, is a complete hostname such as webserver.lab.example. A short name such as webserver is an additional hostname or alias.

Common /etc/hosts Entry Forms

Purpose | Example entry | Explanation

IPv4 localhost | 127.0.0.1 localhost | The conventional IPv4 name for the current machine.

IPv6 localhost | ::1 localhost | The conventional IPv6 name for the current machine.

Single custom hostname | 192.168.198.140 webserver | Maps a private IPv4 address to one short hostname.

FQDN with short alias | 192.168.198.140 webserver.lab.example webserver | Both names resolve to the same address.

Commented entry | # 192.168.198.140 old-server | Ignored because the line begins with a comment marker.

Default Loopback Entries

Loopback means that traffic is sent back to the same computer rather than to another device. The usual loopback addresses are:

  • 127.0.0.1 for IPv4.
  • ::1 for IPv6.

localhost is the conventional hostname for these local paths. A typical file includes both mappings:

127.0.0.1 localhost
::1 localhost

Do not casually delete or change standard localhost entries. Local applications may try IPv4, IPv6, or both, and may depend on these names resolving correctly.

Adding a Custom Hostname Mapping

A local mapping is useful for development, lab systems, temporary testing, or a small isolated network where a centralized DNS change would be unnecessary.

Short hostname

To map a private-network web server:

192.168.198.140 webserver

After saving the file, applications on this machine can use webserver.

FQDN and alias

To provide both a complete lab name and a convenient short name:

192.168.198.140 webserver.lab.example webserver

The FQDN and the alias are names for the same address on the edited machine.

Temporary service testing

A workstation can temporarily direct a test hostname to a replacement service:

203.0.113.25 app.example.test

This changes name resolution only on that workstation. It does not modify shared DNS or other clients.

A command-line append can be used for automation, but inspect the file first and avoid creating duplicates:

printf '%s\n' '192.168.198.140 webserver' | sudo tee -a /etc/hosts

Using and Verifying Mapped Names

Use getent to test resolution through the system's configured Name Service Switch sources:

getent hosts webserver
getent ahosts webserver

getent hosts displays a resolver result, while getent ahosts can show address records and address families returned through NSS.

You can test a network client with the hostname:

ping -c 3 webserver
curl http://webserver/

ping tests ICMP reachability when ICMP is permitted. curl tests an HTTP request if an HTTP service is listening. Neither command is a pure name-resolution test, so use getent to separate name problems from network or service problems.

Resolution Order: /etc/hosts and DNS

Linux uses NSS, or Name Service Switch, to select lookup sources and their order. The configuration is commonly found in /etc/nsswitch.conf.

grep '^hosts:' /etc/nsswitch.conf

A common configuration is:

hosts: files dns

Here, files means the local hosts file is checked before dns. If a matching entry exists in /etc/hosts, that local result can override the DNS answer for this machine. If there is no local match, the resolver may continue to DNS, depending on the configured sources and their rules.

Other source names may appear in the hosts: rule:

  • files: local files, normally including /etc/hosts.
  • dns: DNS servers configured for the system.
  • myhostname: a local hostname resolver commonly associated with systemd.
  • mdns: multicast DNS for local-network discovery.
  • resolve: a system resolver service, commonly systemd-resolved.
  • nis: Network Information Service, where an organization still uses it.

Exact behavior differs across distributions, releases, resolver services, VPNs, containers, and local configuration. Do not assume that every Linux system uses the same rule or the same caching behavior.

Hosts File Compared with DNS

Characteristic | /etc/hosts | DNS

Scope | One machine | Many clients through shared DNS infrastructure

Administration | Edit each client separately | Manage records centrally or through delegated DNS administration

Update effort | Manual or configuration-management updates on every client | One authoritative change can serve many clients

Best use cases | Development, labs, temporary overrides, isolated networks | Organization-wide and production name management

Scalability | Poor when many machines or records are involved | Designed for distributed, large-scale name service

Effect of address changes | Every affected file can become stale | Central records can be updated for all clients

Typical precedence | Often checked before DNS when NSS uses files dns | Queried after earlier configured sources

Hosts-file administration does not scale because every client requires a separate update. Static entries can also become stale when DHCP assignments, cloud instances, or server addresses change. Centralized DNS is generally the better choice for organization-wide or production naming.

Operational Risks

  • An accidental entry can redirect a production hostname to the wrong server.
  • A local override can hide an intended DNS change, routing policy, failover target, or load-balancing result.
  • Old test records can remain after a service moves and cause confusing failures.
  • Different machines may resolve the same name differently because their files are not synchronized.

Use distinctive test names where possible, document temporary changes, and remove entries when testing ends.

Safe Editing and Validation Workflow

  1. Inspect the current file with cat /etc/hosts or a line-numbered command such as grep -n '' /etc/hosts.
  2. Create a backup with sudo cp /etc/hosts /etc/hosts.bak.
  3. Use sudoedit /etc/hosts to make the change.
  4. Put the IP address first, followed by the canonical hostname and any aliases.
  5. Check for misspellings, duplicate names, conflicting addresses, and accidentally commented entries.
  6. Confirm the effective result with getent hosts name and, when useful, getent ahosts name.
  7. Test the intended application separately with a suitable client such as curl.

Most standard resolver lookups read the hosts file immediately after it is saved. However, applications and local caching services may retain an earlier result. If the file is correct but one program still behaves differently, restart that program or clear its relevant cache. Browsers, language runtimes, VPN clients, containers, and separate network namespaces may also have distinct resolution behavior.

Troubleshooting

The name resolves to the DNS address instead of the local address

  • Confirm that the entry exists, is not misspelled, and is not commented out.
  • Run getent hosts hostname.
  • Inspect the NSS order with grep '^hosts:' /etc/nsswitch.conf.
  • If dns appears before files, DNS may be selected first.
  • Retry with a newly started application if a cached result is suspected.

getent returns no result

  • Ensure the address is first and the hostname follows it.
  • Check for hidden formatting or syntax problems by inspecting the exact line with line numbers.
  • Query the exact hostname or alias written in the file.
  • Check that the entry was saved to the correct machine's /etc/hosts.

The name resolves but the connection fails

  • Confirm the selected address with getent.
  • Check routing and target reachability.
  • Verify that the expected service is running and listening on the expected port.
  • Check firewalls and confirm that the mapping is not outdated.

localhost no longer works

Check that conventional mappings remain present:

127.0.0.1 localhost
::1 localhost

Also determine whether the application is attempting IPv4, IPv6, or both. A missing address-family entry can affect applications that prefer one protocol.

Different applications produce different results

Use getent as the operating-system-level reference, then consider application caches, browser caches, container or VPN configuration, and separate network namespaces. Restart the affected application when appropriate and verify that it is using the same hosts file and network environment.

Exam-Relevant Notes

  • /etc/hosts is a local static mapping database, not a DNS server.
  • The standard format is IP address hostname aliases.
  • # starts a comment.
  • 127.0.0.1 is IPv4 loopback; ::1 is IPv6 loopback.
  • /etc/nsswitch.conf controls host lookup sources and ordering through the hosts: rule.
  • With hosts: files dns, a matching hosts-file entry normally takes precedence over DNS on that machine.
  • Hosts-file changes are local and do not scale like centralized DNS.
  • Name resolution success and service reachability are separate tests.

For related material, see Linux hostname resolution with /etc/hosts.