configure XSAN 4.1 (& 5.0)


This guide should help you to connect a OS/X 10.11 and up based client to a StorNext® 5 & 6 based MetaData Controller (MDC) or a Xcellis Workflow Director. There are 2 ways to connect a fresh Xsan 4.1 or 5 based client to your Controller/ Director. Here is the full compatibility list from Apple:


You have an Xcellis Workflow Director and since StorNext  5.3.2 you would need officially Xsan 5.  You never used Xsan on that client before and updating to OS/X 10.12 is a piece of cake. Voila, your client is now fully compatible with SNFS 5.3.2 and up. But where are the darn configuration files. Nothing is where it was and the usual directories are empty. No online manual from Apple? I’d say as usual, let others figure it out.

Another thing with doesn’t really line up is that the compatibility matrix from Apple and Quantum took over 6 month to be released. El-Capitan was released before StorNext 5 has been official released, which means El-Capitan’s version was already future proofed?


XSAN since version 2.3 comes embedded within the OS and doesn’t require a dedicated license anymore. The surprising part here is still the lack of documentation. While Apple keeps changing the configuration quite frequently, the Xsan pane which some users may have used in previous OSX releases is gone, everything will be configured with configuration profiles.


Continuing with XSAN 4 which is the current version, this blog entry follows the idea to have a complete collection of all the XSAN versions covered beginning with XSAN 1.4 over XSAN 2.3 & 3.0 and XSAN 4.

Some basics upfront:

A metadada network should always be separated (dedicated) to have a low latency communication between the clients and the SNFS/XSAN server. Usually you’d chose a different class C network and have a dedicated NIC installed on your client.

The basic commands you need to verify if the client setup should work are ping, cvadmin and cvlabel.

ping – the simple test if you have a valid IP connection
cvadmin – to verify the connection to the MDC
cvlabel – to assure that you see all the LUN’s you need to mount a volume

My MDC reports back at and my client has the metadata IP assigned.

XSAN 1.x – 1.4.1

The downloadable XSAN Administration Guide shows actually what needs to be done, therefore it would be redundant to write it down.

XSAN 1.4.2 – 2.x
XSAN 2.3 – 3.x (OSX 10.7 – 10.9)
XSAN 4 – Yosemite
XSAN 5 – Sierra

XSAN 5.1 – Sierra


This version of XSAN comes with the OS and is doesn’t require any further installation or serial number. With other words, it’s free.


Option a: (The keyboard warrior way)

You might perform a quick ping test to the MDC to avoid troubleshooting later.

If you have an existing XSAN 3 configuration, you can simply copy the /Library/Preferenes/Xsan folder to the new client.

  1. Configure the metadata network on a free NIC
  2. Start a terminal window and gain root access
    sudo –s
  3. Use your favorite CLI editor (nano, vi …) and create the nameservers file
    vi /Library/Preferences/Xsan/fsnameservers
  4. Enter the IP of the MDC:
  5. Save the file and quit the editor
  6. Create the main configuration file for the client and change the bold sections to match your environment.
    vi /Library/Preferences/Xsan/config.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
  <plist version="1.0">
  1. Restart Xsan either by rebooting the client or issuing the commands:
    launchctl unload /System/Library/LaunchDaemons/
    launchctl load –w -F /System/Library/LaunchDaemons/

Option b: (you need access to the MDC)
  1. SSH into the MDC and navigate into /usr/cvfs/config
  2. Create a profile with following command:
    ../lib/make_profile san_profile
  3. Copy the new profile back to your macOS: scp san_profile user@
  4. On your macOS client, clear existing profiles if there are any:
    sudo for i in `profiles list | grep | awk ‘{print $NF}’` ; do profiles -R  -p $i ; done
  5. Import the new profile:
    sudo profiles -I -f /tmp/san_profile
    (The configuration will be imported into /Library/Preferences/Xsan/config.plist and /Library/Preferences/Xsan/fsnameservers )
  1. Restart Xsan either by rebooting the client or issuing the commands:
    launchctl unload /System/Library/LaunchDaemons/
    launchctl load –w -F /System/Library/LaunchDaemons/

Note: You can’t skip the “–w –F” after the any longer as the daemon won’t launch successfully.

  1. After Xsan has restarted, from a terminal run the command: /usr/sbin/cvadmin
    You should see something like:
Xsan Administrator
Enter command(s)
For command help, enter "help" or "?".
List FSS
File System Services (* indicates service is in control of FS):

1>*san-1[0] located on (pid 10442)
2>*san-2[1] located on (pid 10487)

Select FSM "none"
Xsanadmin >

The above shows there are is a connection to the MDC ( with two volumes: san-1 and san-2

Mounting a volume:
  1. Mount all volumes manually to test the installation
  2. mkdir /Volumes/san-1
    2. mount -t acfs san-1 /Volumes/san-1
    3. repeat as necessary, changing san-1 to the appropriate volume name
    4. run a df command to see if the StorNext volumes have been successfully mounted on the client.
  3. Configure the volumes to mount automatically
  4. Mounts in XSAN 2.3 and above are handled in the /Library/Preferences/Xsan/ automount.plist file

The following shows an example to auto mount the volume san-1:

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
 <plist version="1.0">

Volumes will automatically be mounted to /Volumes/VolumeName

After saving the file, reboot the client to see if the volumes successfully mount after boot. SAN volumes should appear as desktop icons, usually a minute or so after startup

Stopping and starting XSAN from the command line:

launchctl unload /System/Library/LaunchDaemons/
launchctl load /System/Library/LaunchDaemons/


  • A common point of failure for mounts is the existence of /Library/Preferences/Xsan/.auth_secret If this file exists, delete it. This is a leftover if the client has been part of a XSAN MDC cluster.
  • If you are missing the config.plist or the automount.plist, /var/log/system.log may show an error of the form:

Configuration files are for an old version of Xsan; no Xsan volumes will be mounted

  • Verify if you see all required labels for a volume you want to mount.:

/usr/sbin/cvlabel –c | sort

It is acknowledged by anyone who chooses to utilize this procedure that all risks taken in performing these steps are performed on your own and that I am not reliable for any damage.

Leave a Reply

Your email address will not be published. Required fields are marked *