With the start of the New Year, I have been auditing my homelab, trying to identify areas where I can optimize its current loadout. Out of this audit, I noticed that I had accumulated a lot of files that were taking up valuable local NVME storage on my Proxmox server. These were files like iso images for installing new VMs, backups, container templates- all things that just didn't necessarily need to be kept in hot storage. Wouldn't it be nice to be able to free up valuable NVME drive space by shifting those files to a more centralized file storage server? In today's tutorial, we will be discussing how to add CIFS storage to Proxmox.

What is CIFS/SMB/Samba Storage?

CIFS/SMB allows you to reach out from your server and access network attached storage (commonly known as a Samba share) just as if it were local storage. The protocol is extremely common, even in consumer equipment, and is the protocol commonly used to allow file sharing over a network by Synology, QNAP, and WD's MyCloud NAS devices. While there technically is a difference between CIFS/Samba, I will be using CIFS/SMB/Samba interchangeably throughout this article.

Why Should I Add CIFS/Samba Storage to Proxmox?

The most important part of learning any new tool is knowing when to use it and when not to. SMB storage is no different.

When Should I Use CIFS Storage?

The advantage of the network attached storage that CIFS offers is that it gives a centralized place for bulk file storage. From a cost perspective, that means you can use more economical storage media (i.e. regular hard drives) to store those large, bulk files.

From a maintenance perspective it has even more advantages: not only do you only have to maintain one centralized server, but you can also focus on making sure that centralized storage server better protects its valuable files; Think: RAID HDD configuration, automatic offsite backups, etc.

CIFS is ideal for storage of files that you may still need access to but don't necessarily need as quickly as local NVME storage. Therefore, I classify CIFS/SMB/Samba shares as "warm storage"- it's not as hot as local, but it's certainly not cold storage either. It's great for stuff that take up a lot of room on Proxmox, like installation media and backup images. Log files are also nicely handled by CIFS storage. Its performance is so good that you can even directly use mounted SMB shares for the source files being transcoded by Handbrake:

When Shouldn't I Use CIFS?

The answer to this is that you shouldn't use CIFS when you need your most performant storage. i.e. I wouldn't use a Samba share for my scratch disk in machine learning. I also wouldn't try to mount my gaming VM's primary storage on an SMB share.

That being said, I don't want you to take away from this guide that SMB shares are inherently bad. That's far from the case. As with everything else, context plays a large role. CIFS will easily saturate the gigabit network connection found in your typical homelab which is a pretty darn good speed, especially when you consider that your typical HDD has a read/write speed right in this same range at 125-150 MB/s; I would argue that it's a perfectly balanced connection. I have observed these speeds in my own network when my backups are transferred from Proxmox to unRAID.

If you're only running Linux in your homelab, the only additional note I will make here is that you might consider NFS as opposed to CIFS. I will be doing a future tutorial on that but since Samba shares are by the far the most common, I decided to do this CIFS guide first.

How to Add CIFS Storage To Proxmox:

Now that you have the background, let's get to work on setting up SMB shares in Proxmox. You're going to laugh when you see how easy this is.

Prerequisites:

SMB/CIFS/Samba Share - To keep the length of this guide manageable, I will assume you have already set up an SMB share and are broadcasting it from your file server.

Open up the Proxmox webGUI and navigate to 1) Datacenter > 2) Storage > 3) Add > 4) CIFS:

How to Add CIFS Storage to Proxmox

You'll then be prompted to create your new CIFS storage pool. This includes the following:

ID: The name of your new storage pool. I chose "unraid" since this storage is being provided by an unRAID server.

The name of your new storage pool. I chose "unraid" since this storage is being provided by an unRAID server. Server: IP address of the CIFS server. In my case 10.0.30.5 is the IP address of my unRAID server.

IP address of the CIFS server. In my case 10.0.30.5 is the IP address of my unRAID server. Username: Login username needed to authenticate into the SMB share. If you aren't using authentication to protect your share you can just leave the generic guest user that Proxmox initially defaults in.

Login username needed to authenticate into the SMB share. If you aren't using authentication to protect your share you can just leave the generic guest user that Proxmox initially defaults in. Password: Password for above username.

Password for above username. Share: Select the specific Samba share being broadcast by your file server. In my case, I have created a share named "proxmox" on my unRAID server.

Select the specific Samba share being broadcast by your file server. In my case, I have created a share named "proxmox" on my unRAID server. Max Backups: This feature determines how many backups of an individual VM Proxmox will keep on the storage pool before automatically deleting the oldest ones first. It's a handy feature that keeps your backups from proliferating indefinitely. I suggest you use two here to start. Note: You'll only have this option available if you select "VZDump Backup File" in the Content field below it.

This feature determines how many backups of an individual VM Proxmox will keep on the storage pool before automatically deleting the oldest ones first. It's a handy feature that keeps your backups from proliferating indefinitely. I suggest you use two here to start. Note: You'll only have this option available if you select "VZDump Backup File" in the Content field below it. Content: This is a multiselect menu used to determine what kind of files can be stored on this Proxmox store. As we discussed in "When Should I Use CIFS Storage?", I recommend allowing this storage pool to store disk images, ISO images, container templates, and VZDump backup files.

CIFS Storage Menu in Proxmox

Once you click "Add", you'll then see your new CIFS storage pool available in the Proxmox webGUI:

Congratulations! You're now live with a CIFS storage pool on Proxmox!

Troubleshooting

Rarely, you may come across the following error when you navigate to the CIFS store in the Proxmox webGUI:

unable to activate storage '<Store Name Here>' - directory '/mnt/pve/<CIFS Storage ID>' does not exist (500)

If you open up an SSH connection into the server and ls this directory, you'll likely also see the following message:

cannot open directory '.': Stale file handle

First of all, you should know that this error is usually relatively benign in the sense that when you write to the share (as when you write a backup file), chances are that the file did actually make it to the share. Obviously, it's still not great though.

It should also be noted that this a problem that can happen with any network-attached storage (NAS) protocol including NFS, and is not unique to CIFS. Referencing Mike Eisler's Managing NFS and NIS, re: a stale file handle:

A filehandle becomes stale whenever the file or directory referenced by the handle is removed by another host, while your client still holds an active reference to the object. A typical example occurs when the current directory of a process, running on your client, is removed on the server (either by a process running on the server or on another client).

Source: Managing NFS and NIS

This problem can be resolved with the following commands:

First, unmount the CIFS file systems with:

umount -f -a -t cifs -l

Whenever you run a command you should know what it's doing. umount detaches file systems. The -f option forces umount, -a removes all filesystems, which is why it is VITALLY IMPORTANT that you add the -t option followed by cifs which will only unmount cifs-type mounts. The -l option makes it a lazy unmount so that it does it now. This is okay since we're going to remount it immediately with:

mount -t cifs

With that command your problem should now be resolved. I have a theory about what causes this and how the incidence of this problem can be reduced, but I haven't yet had a chance to take a deeper dive into it. When I do, I will update you.

That concludes this article. I hope you found it useful. Let me know how you are using NAS storage with Proxmox in the comments below. If you run into any trouble let me know and I'll do my best to help. Chances are that others have run into the same problem so your question may help others out.

If you wish to subscribe to be notified of future articles, be sure to check out the The Engineer's Workshop Forums and sign up! It's also a great community for discussions and questions related to homelabs, self-hosting, and electronics.