Add and Verify an RPC Program Name in /etc/rpc

Add one local name and alias for an RPC program number to /etc/rpc, then prove that libc and getent can resolve it in both directions. This file is a small name database, not a service configuration: changing it never starts an RPC server, allocates a port, or makes anything listen. Allow about fifteen minutes, including a careful rollback check.

You need a shell, the getent command from the standard system utilities, and sudo access if you are changing the system file. The examples use the installed Linux man-pages 6.7 documentation. On this machine, manpages is package version 6.7-2, while /etc/rpc is supplied by the netbase package.

1. Understand the record before editing

/etc/rpc holds one RPC program per logical line. The first field is the canonical server name, the second its numeric program identifier, and any later fields are aliases. Spaces and tabs separate fields. A hash character starts a comment, and everything after it on that line is ignored by routines that search the database.

example-service 123456 example-alias

Use a program number that belongs to the application or vendor you are integrating. Do not copy an existing number just because it is convenient: the name database does not reserve numbers or detect a conflict with a running service. A duplicate number can make a lookup return the wrong entry, and a misleading alias makes diagnostics harder to trust.

First inspect the current file and confirm your proposed names are not already taken:

$ grep -nE '(^|[[:space:]])example-service([[:space:]]|$)' /etc/rpc || echo 'canonical name is unused'
$ grep -nE '(^|[[:space:]])example-alias([[:space:]]|$)' /etc/rpc || echo 'alias is unused'

2. Back up the system file

Editing this file needs elevated privileges. Make a dated backup in a root-readable location first. The command below reads the original and writes a separate copy; it does not touch /etc/rpc itself:

$ backup="/etc/rpc.backup.$(date +%Y%m%d-%H%M%S)"
$ sudo cp --preserve=mode,ownership,timestamps /etc/rpc "$backup"
$ sudo test -s "$backup" && echo "backup written to $backup"

Do not put the backup in a directory managed by an automated cleanup job unless that is deliberate. Record the printed path: if the edit goes wrong, that path is your recovery copy.

3. Add the entry as one complete line

Open the file with an editor as root:

$ sudoedit /etc/rpc

Add a line near related entries, replacing every placeholder with values approved for your environment:

example-service 123456 example-alias

Keep the canonical name, number and aliases separated by ordinary spaces or tabs; punctuation does not work as a field separator. Keep comments on their own line while testing, because an accidental hash before the number turns the rest of the line into a comment. Do not delete existing records to make room: the file is normally short enough that a new line is clearer and safer.

Save the file and leave the editor. No daemon restart is normally needed for a new lookup, but a long-running process may hold a cached database handle. Restart only the application that needs the new name, and only through that application's own procedure.

4. Verify the name and number lookups

getent exercises the system's RPC database lookup path. Query the canonical name, then the number:

$ getent rpc example-service
example-service 123456 example-alias
$ getent rpc 123456
example-service 123456 example-alias

Both commands should print the same record. Query the alias too, as a third check:

$ getent rpc example-alias
example-service 123456 example-alias

Looking up by number and by name are separate useful checks. The underlying getrpcbyname() and getrpcbynumber() routines search the RPC database from the start for a matching name or number. A successful result proves the record is parseable and visible through the local lookup interface; it proves nothing about a server actually running or reachable.

For a status suitable for a script, use a conditional rather than parsing output:

if getent rpc example-service >/dev/null; then
    printf '%s\n' 'RPC name is available'
else
    printf '%s\n' 'RPC name was not found' >&2
    exit 1
fi

Keep the expected number in the application configuration too. /etc/rpc gives you a human-readable mapping; it does not validate that a service actually uses that number.

5. Diagnose a failed lookup

If getent rpc example-service prints nothing, inspect the exact line without changing it:

$ sudo grep -nF 'example-service' /etc/rpc
$ sudo sed -n '1,12p' /etc/rpc

Work through the common traps in order:

• Canonical name is the first field. An alias cannot stand in for it.
• The number is the second field. No punctuation, no trailing comment marker.
• A hash comments out the rest of the line. Check nothing accidental sits before your entry.
• Tabs and spaces separate fields; commas do not. A comma-separated line will not parse the way you expect.
• A clean edit is not proof of a matching query. Double-check you queried the same spelling or number you wrote.

Compare the file and lookup output with diff if the result still surprises you. Do not restart unrelated RPC services to fix a text lookup: the problem is usually a spelling, field order or comment error.

6. Roll back without guessing

Do not restore a backup blindly if another administrator or a package update has touched /etc/rpc since you made it. Inspect the current file against the backup first:

$ sudo diff -u /etc/rpc /etc/rpc.backup.YYYYMMDD-HHMMSS

If the only difference is your new record, remove that line with sudoedit and verify the lookup is gone. If you must restore the backup, preserve its ownership and permissions:

$ sudo cp --preserve=mode,ownership,timestamps /etc/rpc /etc/rpc.before-restore
$ sudo cp --preserve=mode,ownership,timestamps /etc/rpc.backup.YYYYMMDD-HHMMSS /etc/rpc
$ getent rpc example-service || echo 'entry is absent after restore'

The first command makes a second recovery copy. Keep it until the RPC-dependent application has been checked. Removing old backups is a separate, irreversible cleanup decision: never fold it into a repair command.