{"record":{"id":"2028b77190bfe739","repo":"apache/hadoop","slug":"must-start-privileged-nfs-server-with-nfs-registr","errorCode":null,"errorMessage":"Must start privileged NFS server with 'nfs.registration.port' configured to a privileged port.","messagePattern":"Must start privileged NFS server with 'nfs\\.registration\\.port' configured to a privileged port\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs-nfs/src/main/java/org/apache/hadoop/hdfs/nfs/nfs3/PrivilegedNfsGatewayStarter.java","lineNumber":53,"sourceCode":" * Red Hat: https://bugzilla.redhat.com/show_bug.cgi?id=731542\n * SLES: https://bugzilla.novell.com/show_bug.cgi?id=823364\n * Debian: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594880\n */\npublic class PrivilegedNfsGatewayStarter implements Daemon {\n  static final Logger LOG =\n      LoggerFactory.getLogger(PrivilegedNfsGatewayStarter.class);\n  private String[] args = null;\n  private DatagramSocket registrationSocket = null;\n  private Nfs3 nfs3Server = null;\n\n  @Override\n  public void init(DaemonContext context) throws Exception {\n    System.err.println(\"Initializing privileged NFS client socket...\");\n    NfsConfiguration conf = new NfsConfiguration();\n    int clientPort = conf.getInt(NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_KEY,\n        NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_DEFAULT);\n    if (clientPort < 1 || clientPort > 1023) {\n      throw new RuntimeException(\"Must start privileged NFS server with '\" +\n          NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_KEY + \"' configured to a \" +\n          \"privileged port.\");\n    }\n\n    try {\n      InetSocketAddress socketAddress =\n                new InetSocketAddress(\"localhost\", clientPort);\n      registrationSocket = new DatagramSocket(null);\n      registrationSocket.setReuseAddress(true);\n      registrationSocket.bind(socketAddress);\n    } catch (SocketException e) {\n      LOG.error(\"Init failed for port=\" + clientPort, e);\n      throw e;\n    }\n    args = context.getArguments();\n  }\n\n  @Override","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-nfs/src/main/java/org/apache/hadoop/hdfs/nfs/nfs3/PrivilegedNfsGatewayStarter.java#L35-L71","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","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."],"exampleFix":"# before: nfssite-site.xml — key missing, init throws\n# after\n<property>\n  <name>nfs.registration.port</name>\n  <value>1246</value>\n</property>","handlingStrategy":"validation","validationCode":"/* check config before installing/starting the privileged daemon */\nNfsConfiguration conf = new NfsConfiguration();\nint port = conf.getInt(NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_KEY,\n                       NfsConfigKeys.DFS_NFS_REGISTRATION_PORT_DEFAULT);\nif (port < 1 || port > 1023) {\n    throw new IllegalArgumentException(\n        \"nfs.registration.port must be in 1..1023 for the privileged starter, got \" + port);\n}","typeGuard":null,"tryCatchPattern":"try {\n    starter.init(context);\n} catch (RuntimeException e) {\n    // deterministic config error at daemon init: read the message, set\n    // nfs.registration.port to a free privileged port, restart jsvc.\n    // No retry is useful until the config changes.\n}","preventionTips":["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."],"tags":["nfs-gateway","hadoop","configuration","privileged-port","startup","jsvc","daemon"],"backgroundTag":"privileged-port-required","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}