apache/hadoop · critical · RuntimeException

Must start privileged NFS server with 'nfs.registration.port

Error message

Must start privileged NFS server with 'nfs.registration.port' configured to a privileged port.

What it means

PrivilegedNfsGatewayStarter is the jsvc (commons-daemon) bootstrap that binds the NFS registration socket as root. It requires nfs.registration.port to be a privileged port (1-1023) so the gateway can perform privileged NFS registration; the default value is unprivileged, so if the key is unset or set to >=1024, init() throws this RuntimeException and jsvc exits.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-nfs/src/main/java/org/apache/hadoop/hdfs/nfs/nfs3/PrivilegedNfsGatewayStarter.java:53

 * Red Hat: https://bugzilla.redhat.com/show_bug.cgi?id=731542
 * SLES: https://bugzilla.novell.com/show_bug.cgi?id=823364
 * Debian: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594880
 */
public class PrivilegedNfsGatewayStarter implements Daemon {
  static final Logger LOG =
      LoggerFactory.getLogger(PrivilegedNfsGatewayStarter.class);
  private String[] args = null;
  private DatagramSocket registrationSocket = null;
  private Nfs3 nfs3Server = null;

  @Override
  public void init(DaemonContext context) throws Exception {
    System.err.println("Initializing privileged NFS client socket...");
    NfsConfiguration conf = new NfsConfiguration();
    int clientPort = conf.getInt(NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_KEY,
        NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_DEFAULT);
    if (clientPort < 1 || clientPort > 1023) {
      throw new RuntimeException("Must start privileged NFS server with '" +
          NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_KEY + "' configured to a " +
          "privileged port.");
    }

    try {
      InetSocketAddress socketAddress =
                new InetSocketAddress("localhost", clientPort);
      registrationSocket = new DatagramSocket(null);
      registrationSocket.setReuseAddress(true);
      registrationSocket.bind(socketAddress);
    } catch (SocketException e) {
      LOG.error("Init failed for port=" + clientPort, e);
      throw e;
    }
    args = context.getArguments();
  }

  @Override

View on GitHub (pinned to 2add963021)

Solutions

Set nfs.registration.port to an unused port in 1-1023 (e.g. a dedicated port agreed with your admins) in nfssite-site.xml or core-site.xml on the gateway host.
Ensure jsvc starts the process as root (privileged bind) — the starter exists exactly for that.
Alternatively run the unprivileged gateway (hadoop nfs3 / portmap-free setup) if privileged registration is not required.

Example fix

# before: nfssite-site.xml — key missing, init throws
# after
<property>
  <name>nfs.registration.port</name>
  <value>1246</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

/* check config before installing/starting the privileged daemon */
NfsConfiguration conf = new NfsConfiguration();
int port = conf.getInt(NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_KEY,
                       NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_DEFAULT);
if (port < 1 || port > 1023) {
    throw new IllegalArgumentException(
        "nfs.registration.port must be in 1..1023 for the privileged starter, got " + port);
}

Try / catch

try {
    starter.init(context);
} catch (RuntimeException e) {
    // deterministic config error at daemon init: read the message, set
    // nfs.registration.port to a free privileged port, restart jsvc.
    // No retry is useful until the config changes.
}

Prevention

Template the NFS gateway config so nfs.registration.port is always set for jsvc deployments (value in 1-1023).
Add a pre-start script that validates the port range and fails with a clear message before jsvc runs.
Reserve the chosen privileged port with your infra/firewall team so nothing else binds it.
If privileged registration is unnecessary, use the unprivileged gateway path instead of jsvc.

When it happens

Trigger: Starting the NFS gateway via jsvc without nfs.registration.port in the configuration, or with it configured to a value like 2049 or the 22024 default — anything outside 1..1023 fails the explicit range check at init().

Common situations: First-time privileged gateway setup following the Hadoop NFS docs but skipping the nfssite-site.xml port configuration; port values copied from the non-privileged (unsecured) deployment; firewall/team conventions pushing ports above 1024.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/2028b77190bfe739. Report an issue: GitHub.