Stale file handle ошибка

NFS Stale File Handles can be one of the most frustrating problems when it comes to network-attached storage (NAS). In this guide, we’ll talk about methods you can use to equip your NFS clients to recover automatically from stale file handle errors.

What is an NFS filehandle?

Basically, an NFS filehandle is a pointer on the NFS server to the actual file (or directory). In most instances, this pointer is an amalgamation of an inode, disk device, and inode generation of the referenced file on the server. As such, the filehandle is essentially meaningless to the NFS client that has an NFS share mounted.

What does «NFS Stale File Handle» error mean?

Again, filehandles are essentially meaningless to the client that is mounting an NFS share. Even if the client could decode the filehandle, the client doesn’t have direct access to the file system or disks on the NFS server and therefore that filehandle with its inode, disk, and inode generation data mean nothing to it. More importantly, an NFS client has no idea what other operations are going on with the files/directories it has mounted, so when a filehandle becomes invalid (or «stale»), the NFS server returns a «stale file handle» error in response to the client.

What causes an NFS «stale file handle» error?

We’ve established that a filehandle (which represents a file on a NFS server) contains information about the file’s inode, disk device, and inode generation on the NFS server. We’ve also established that a «stale file handle» error means that this reference is out-of-date or otherwise invalid.

So what could cause this reference to go out of date and no longer be valid? I.e. What causes an NFS stale file handle error?

The answer is any change in the mounted file’s underlying inode, disk device, or inode generation on the NFS server causes an NFS stale filehandle.

How To Automatically Fix NFS Stale File Handle Errors

When it comes to NFS stale file handle errors, an «ounce of prevention is worth a pound of cure». It’s always best to understand how your NFS shares are being used, but that’s another topic for another time. Besides, unfortunately, these errors can’t always be prevented.

So here’s how to better equip your NFS clients to automatically resolve stale file handle errors when they happen (and they will).

First, if you’re here for just a one-off fix, you can resolve the issue with:

umount -l /path/to/NFS/mount/here

But let’s say you don’t to want to have to actively seek out stale NFS mounts and want your Linux NFS client to just handle it automatically. Here’s what to do.

1. Create a new script:

nano /home/engineer/Desktop/staleHandleDestroyer

1. Copy and paste the following:

#! /bin/bash
list=$(df 2>&1 | grep 'Stale file handle' | awk '{print ""$2"" }' | tr -d :)
for directory in $list
do
	umount -l "$directory"
	mount -a
done

It’s hard to create a one-size-fits-all script because a lot of it depends on how the client is accessing the NFS share, but this should work for the majority of Linux/Ubuntu/Debian installations. If you want to discuss your specific use case, please comment below!

1. Make it executable:

sudo chmod +x /home/engineer/Desktop/staleHandleDestroyer

1. Add it as a root cron job:

sudo crontab -e

*/5 * * * * /home/engineer/Desktop/staleHandleDestroyer

The above cron job will run every five minutes, searching for stale file handles. If it finds a stale file handle, it will automatically unmount them (lazy umount is safest, so that’s what I use above) and then attempt to remount. If five minutes is too long for you, then you can use * * * * * /home/engineer/Desktop/staleHandleDestroyer instead which will run q1m (every minute).

If that’s still too long for you, then we should talk about preventing this from happening in the first place…

Additional Resources

• Managing NFS and NIS by Mike Eisler

The most complete and definitive resource on understanding the Network File System (NFS) anywhere. Covers everything from networking fundamentals, NFS theory (including design and operation), security, and NFS troubleshooting and performance. Definitely worth buying and having on hand.

• Setting Up and Securing an unRAID NFS Server
• Forum Topics on NFS

And as always, if you need any help or want to discuss your specific NFS deployment, drop a comment below!

And if you have a question or want to discuss anything else, be sure to check out The Engineer’s Workshop forums!