Prefer IPv4 Safely with /etc/gai.conf

You will edit /etc/gai.conf so glibc prefers IPv4-mapped addresses over unusable IPv6 routes. This changes glibc's destination-address sorting while keeping a copy of the original configuration and a clear way back. It is useful when applications try an unusable IPv6 path before IPv4 and appear to hang. Allow about 15 minutes, including a small verification test. You need a shell and root access only for the final file change.

1. Confirm the scope of the change

gai.conf is read by the glibc implementation of getaddrinfo(3). It controls the order of addresses returned to applications; it does not disable IPv6, change DNS records, alter routing, or force every program to use IPv4. Applications that implement their own resolver or connection policy may not follow it.

This guide describes Linux man-pages 6.7 and glibc 2.39, the versions installed here. The file has been supported since glibc 2.5. The documented rules are based on RFC 3484 address sorting, while the local example file also describes RFC 6724 scope handling. Check your installed manual if a different glibc release is in use.

$ getconf GNU_LIBC_VERSION
glibc 2.39
$ man gai.conf

Checkpoint: if the command reports a different glibc version, keep the installed man gai.conf open while reviewing the syntax below.

2. Inspect the current file before editing

The configuration is /etc/gai.conf. A missing file means glibc uses its built-in defaults. Read the file without elevating privileges:

$ ls -l /etc/gai.conf
$ sed -n '1,220p' /etc/gai.conf

Look especially for existing label and precedence lines. A common trap is that one active line of either kind replaces the corresponding default table; it does not merely add one entry to the defaults. If you customise precedence, copy every default entry you intend to retain.

The installed example commonly contains this IPv4-preference line commented out:

#precedence ::ffff:0:0/96  100

The ::ffff:0:0/96 network represents IPv4-mapped IPv6 addresses in the sorting table. The value 100 is a precedence value, not an address or a timeout.

3. Make a recoverable backup

Back up the file before changing it. This is a state-changing step, but it does not restart services or modify the network:

$ sudo cp --preserve=mode,ownership,timestamps /etc/gai.conf /etc/gai.conf.before-ipv4
$ sudo ls -l /etc/gai.conf /etc/gai.conf.before-ipv4

If /etc/gai.conf does not exist, create the backup only after you have decided which complete table you want to install. Do not overwrite an existing backup blindly; choose another name such as /etc/gai.conf.before-ipv4-2026-09-23.

Checkpoint: both paths should refer to readable files with the same size before you edit. If the copy fails, stop and fix the permission or filesystem problem first.

4. Install a complete precedence table

Because an active precedence line suppresses the default precedence table, add the full table rather than only the IPv4 line. The following is the default table documented by gai.conf(5), with the IPv4-mapped entry changed from 10 to 100:

precedence  ::1/128       50
precedence  ::/0          40
precedence  2002::/16     30
precedence  ::/96          20
precedence  ::ffff:0:0/96  100

Use your normal privileged editor to add or replace that table in /etc/gai.conf. For example:

$ sudoedit /etc/gai.conf

Leave unrelated comments and label or scopev4 rules alone unless you understand their effect. Do not add reload yes as a shortcut for testing. The manual warns that checking for changes on every getaddrinfo(3) call can cause problems in multithreaded applications; the default is reload no.

5. Verify syntax and application behaviour

There is no separate gai.conf compiler or validation command documented by the manpage. Check the installed file directly, then use a resolver client that calls glibc:

$ sed -n '/^[[:space:]]*precedence/p' /etc/gai.conf
$ getent ahosts example.com

The first command should show the five active precedence lines. The second may print different addresses, or fail, depending on your DNS and network. It is a useful smoke test, not a guarantee about every application. Compare it with the saved output from before the change if you need evidence that ordering changed.

For a local, deterministic check of the resolver's address families, use:

$ getent ahosts localhost
127.0.0.1       STREAM localhost
127.0.0.1       DGRAM
127.0.0.1       RAW

Do not expect this localhost result to prove the IPv4 preference: local name data and available addresses constrain it. A real dual-stack name is a better test, and a failed lookup can reflect DNS or connectivity rather than a malformed configuration.

6. Undo the change if connections regress

If applications now fail or take longer to connect, restore the backup. This replaces the configuration file, so check the target before running the command:

$ sudo test -f /etc/gai.conf.before-ipv4
$ sudo cp --preserve=mode,ownership,timestamps /etc/gai.conf.before-ipv4 /etc/gai.conf
$ sed -n '/^[[:space:]]*precedence/p' /etc/gai.conf

glibc normally reads the file once per process with reload no. Restart the affected application after restoring the file, using that application's ordinary service procedure. Do not reboot merely to make a configuration-file rollback take effect.

If you need the original built-in behaviour and there was no file before the experiment, move the new file aside rather than deleting it immediately:

$ sudo mv /etc/gai.conf /etc/gai.conf.disabled
$ sudo test ! -e /etc/gai.conf && echo 'gai.conf absent; glibc defaults apply'

Keep the moved file until the change has been assessed. Removing it later is irreversible, so do that only when you have retained the configuration elsewhere.