Skip to content

Mounting NFSv4 Gateways#

What is a NFSv4 Gateway#

An Oak gateway is a private virtual server, hosted in the SRCF datacenter (where Oak is hosted), which provides an NFSv4 protocol, authenticated through Kerberos, that is compatible with many Linux-based OS distributions.

Oak users may request a private NFSv4 for a specific Oak space. You can mount your Oak space on (up to) 16 different workstations/servers per gateway. Private Oak gateways are connected to the Stanford Research Network at 25Gb/s (theoretical). The service is billed monthly, just like Oak storage, so you can cancel at any monthly interval.

Ordering a NFSv4 Gateway#

To order an Oak Oak NFSv4 gateway for your Oak space, please send us an email at srcc-support@stanford.edu including the following:

  • The directory you would like to be exported ( e.g., /oak/stanford/groups/ruthm )

  • The list of servers or IPs where you want the Oak directory to be mounted

  • A valid PTA to use for billing

Before You Begin:#

  • The person configuring the client system must be an administrator of your machine, both locally (sudo/root) and in its NetDB record. If you are unsure about your specific machine, please reach out to your local IT support group.
  • Please note that while we can provide instructions and general guidance to configure this protocol, it your responsibility to manage the configuration of your workstation or server. Should any problems arise, we will ensure that your gateway is perfoming optimally, but we cannot provide in-depth troubleshooting of systems that we do not directly administer.
  • Kerberos authentication requires the use of Kerberos tickets. The max lifetime of these tickets is 25 hours, renewable for up to 7 days. These limits are set Stanford-wide and cannot be overidden by Stanford Research Computing. Users will be required to manually re-authenticate for a kerberos ticket at least every seven days.

Naming Conventions#

The hostname for your NFSv4 gateways may vary from these instructions. Generally speaking, the naming scheme is as follows:

Oak Space Type Example Path Hostname Format
Group /oak/stanford/groups/$PI_SUNET nfs-$PI_SUNET.oak.stanford.edu
Project /oak/stanford/projects/$PROJECT_NAME nfs-p-$PROJECT_NAME.oak.stanford.edu
School /oak/stanford/schools/$SCHOOL_NAME nfs-s-$SCHOOL_NAME.oak.stanford.edu
Org /oak/stanford/orgs/$ORG_NAME nfs-o-$ORG_NAME.oak.stanford.edu

If you're unsure of the hostname for your NFSv4 gateway, please send us an email at srcc-support@stanford.edu.

For the purposes of this documentation, we will assume that a gateway for an Oak group space, so we'll use $PI_SUNET in our gateway hostname.

Preparing Your Workstation#

Your NFS server's hostname is nfs-$PI_SUNET.oak.stanford.edu. The NFS protocol 4.x is supported. Supported security models include krb5, krb5i or krb5p (We recommend krb5p, which uses full encryption)

Please perform the following steps on each NFS client machine.

  • Check that the client's hostname is fully qualified using “hostname -f”, it should always have a .stanford.edu domain. If it is not correct, you may need to edit your /etc/hostname.

  • Create a local group named oak_$PI_SUNET on the client (the GID number is not relevant). This is optional and cosmetic to avoid using an unknown local group, but we find it helps to maintain a consistent look and feel for permissions when listing directory contents.

  • Copy Stanford’s /etc/krb5.conf to /etc/krb5.conf on your local machine with permissions 0644

  • Install a Kerberos keytab, example for “$HOSTNAME.stanford.edu”, replace by your client host name. You need to be administrator of your machine, both locally and in its NetDB record. You will also need “wallet” installed. For more info, please see the service page for Wallet at Stanford. 

$ kinit $SUNET_ID
$ wallet -f keytab get $HOSTNAME.keytab host/$HOSTNAME.stanford.edu

Then install the keytab as /etc/krb5.keytab owned by root with permissions 0600

  • Finalize the NFS client configuration

Depending on your chosen OS distribution, you might need to install the nfs-kernel-server package.

A Kerberos keytab file contains a list of keys that are analogous to user passwords.

It is important to protect your Kerberos keytab files by storing them on the local disk.

  • The krb5.conf file permission must be 0644, which means that the owner (usually root) can read and write the file; however, members of the group that the file belongs to, and all others can only read the file.
  • The krb5.keytab file permission must be 0600, which means that the owner (usually root) can read and write the file; however, members of the group that the file belongs to, and all others cannot access the file.

Mounting your NFS4 Oak Gateway#

Info

We highly recommended to creating a local mount point that uses the same canonical direcotry path of /oak/stanford/$SPACE_TYPE/$SPACE_NAME to keep a consistent experience whether you access Oak from your NFS client, Sherlock, a data transfer node, or Globus. In this example, we're assuming this gateway will be for an Oak group space called ruthm

Mounting Automatically at Boot Time:#

Append an adaptation of the following line to your /etc/fstab: 

nfs-$PI_SUNET.oak.stanford.edu:/groups/$PI_SUNET    /oak/stanford/groups/$PI_SUNET    nfs    rw,vers=4.2,sec=krb5p,_netdev 0 0

Alternatively, you can adapt this series of commands to help you through the process.

#! /usr/bin/env bash
# Define the mount point details. Make sure to update the PI_SUNET variable from the `ruthm` placeholder!
PI_SUNET='ruthm'
MOUNT_LINE="nfs-$PI_SUNET.oak.stanford.edu:/groups/$PI_SUNET /oak/stanford/groups/$PI_SUNET nfs rw,vers=4.2,sec=krb5p,_netdev 0 0"

# Check if the mount line exists in `/etc/fstab` and append it if it doesn't
grep -qxF "$MOUNT_LINE" /etc/fstab || echo "$MOUNT_LINE" | sudo tee -a /etc/fstab > /dev/null

Manually (Useful for testing purposes)#

$ PI_SUNET='ruthm' 
$ mkdir -p /oak/stanford/groups/$PI_SUNET
$ mount -o vers=4.2,sec=krb5p nfs-$PI_SUNET.oak.stanford.edu:/groups/$PI_SUNET /oak/stanford/groups/$PI_SUNET

Test Your Gateway Mount Connection#

Note: The SUNet ID provided must be a member of the oak:$PI_SUNET workgroup

$ kinit $YOUR_SUNET_ID@stanford.edu
$ ls -l /oak/stanford/groups/$PI_SUNET

Troubleshooting#

UID/GID mapping: usually it is not needed to configure /etc/idmapd.conf as the default will pick the stanford.edu domain which is the correct one. If you prefer, you may want to enforce the following:

Domain = stanford.edu
Local-Realms = stanford.edu

In case of UID/GID mapping issues (esp. at the beginning), you can clear the NFS idmap cache with the following command:

$ nfsidmap -c

Getting Support#

For questions about your gateway or these instructions, please send us an email at srcc-support@stanford.edu