Sev1: OCI File Storage mounts hang or fail — security rules, export options and stale NFS handles

#Symptoms

• mount.nfs: Connection timed out or access denied by server while mounting.
• df -h hangs; processes stuck in uninterruptible D state on the mount.
• Stale file handle after a file system or export was recreated.

#1. Check the network ports

File Storage needs these from the client subnet to the mount target subnet:

Also allow the return traffic (stateful rules do this automatically).

# from the client
nc -zvw3 10.0.3.10 111
nc -zvw3 10.0.3.10 2049
rpcinfo -p 10.0.3.10

If ports fail, check the security list on both subnets and any NSG on the mount target:

oci fs mount-target get --mount-target-id $MT --query 'data.{ip:"private-ip-ids", nsg:"nsg-ids", subnet:"subnet-id"}'
oci network nsg rules list --nsg-id $MT_NSG --direction INGRESS --output table

#2. Check the export and its options

oci fs export list --compartment-id $COMP --file-system-id $FS \
  --query 'data[].{id:id, path:path, state:"lifecycle-state"}' --output table
oci fs export get --export-id $EXPORT --query 'data."export-options"'

Export options control which source CIDRs can mount and with what access:

Fix by updating the export options (this call replaces the list, so include every source you need):

oci fs export update --export-id $EXPORT --force --export-options \
  '[{"source":"10.0.2.0/24","access":"READ_WRITE","identitySquash":"NONE","requirePrivilegedSourcePort":false}]'

#3. Mount with the right options

sudo mount -t nfs -o vers=3,nosuid,resvport,hard,timeo=600 10.0.3.10:/shared /mnt/shared

/etc/fstab entry with nofail and _netdev so boot doesn't hang if the mount target is unreachable:

10.0.3.10:/shared  /mnt/shared  nfs  vers=3,hard,timeo=600,_netdev,nofail  0 0

#4. Clear hung or stale mounts

sudo umount -f /mnt/shared || sudo umount -l /mnt/shared
sudo mount /mnt/shared

Warning

hard mounts protect data: writes wait instead of failing silently. Do not switch to soft just to stop hangs; you risk silent data loss on writes. Fix the network path instead.

Stale file handle means the export or file system behind the path changed. Unmount and mount again; apps holding open files must be restarted.

#5. Performance that looks like a hang

File Storage throughput scales with the amount of data stored (check the current documentation for limits). A small file system with heavy workload can feel hung. Spread load across several file systems, mount targets and clients, and use nconnect where supported by the client kernel.

#Prevent it next time

• Put mount target rules in an NSG managed with the file system in Terraform.
• Use _netdev,nofail in fstab on every client.
• Take File Storage snapshots on a schedule (snapshot policies) so accidental deletes are recoverable.
• Monitor the mount from a synthetic check that writes and reads a small file.