Sunday, September 04, 2005

Mac OS X as an NFS Server

This covers the steps necessary to export filesystems on Mac OS X via NFS. This was originally written in the 10.1 days, but is still applicable as of 10.4.2 (non-server versions).
Like setting up a client, configuring OS X to be a server involves updating NetInfo. For a server, there are several Unix daemons which need to run (one of which needs to be notified if it is already running).
The example filesystem to be exported in this document will be /external/path; obviously change this to something useful.
The steps are to add a new directory to NetInfo, called /exports, and add directories to that which are to be exported.

NetInfo Changes, via Graphical Interface

  1. To accomplish this in Aqua, run NetInfo Manager (located in /Applications/Utilities) and authenticate as an administrator (the little lock at the bottom of the window).
    Authenticate lock
    Authenticate lock

  2. We need to create a new directory, so click on the left-most directory (called simply, /), and create a new directory (through the button, menu option, or shortcut Cmd-N).
    This will create a new directory called new_directory, which we need to rename.
    root in the directory browser
    root in the directory browser

    Ways to create a directory
    Ways to create a directory

  3. In the bottom-part of the window, double-click on new_directory in the Value(s) column, which will highlight new_directory and place the insertion point there. Simply type exports to rename it, then save changes (Cmd-S or Domain menu, and select Save) to update the browser portion of the window.
    Renaming the newly-created directory
    Renaming the newly-created directory

    Now renamed, but not saved
    Now renamed, but not saved

    Now renamed and saved
    Now renamed and saved

    All exported filesystems will be listed under this new directory. Let's add one.

  4. Click on exports in the browser, and create a new directory. The value of the name property for each subdirectory in exports specifies the local filesystem to be exported (in our example, /external/path).
    Double-click new_directory in Value(s), and enter /external/path (make sure there is no trailing slash on this). This specifies the local path to export to clients, but nothing about which clients should be allowed access, or what options to use. For that, we need to add two more properties.

  5. Under the Directory menu is a command, New Property, which is what we will use to add the properties. Select this command twice, as we'll be specifying the clients who will be allowed access, and the export options.
    Two new properties added
    Two new properties added

  6. Double-click the first new_property and rename it to opts; set the value of this property to ro to export this filesystem as read-only (see the manpage for exports for the options which can be used). Change the second new_property to clients, and set the value to a blank (delete what is currently there), which means export to all clients (see the note about default entry, below).
    Properties are now set
    Properties are now set

  7. Save changes. All required information is now in NetInfo for the system to export filesystems via NFS. What's left is to notify or start the NFS server-related daemons.

You can repeat this procedure for any other directories you wish to export (but be sure to read the note about default entry, below, if you export several directories to empty clients properties).

NetInfo Changes, Command Line
Adding NFS export information to NetInfo from a command line involves running a few simple commands: one to create the entry, and two more to add the necessary options.

  1. To create the new entry, run

    sudo nicl . -create /exports/\\/external\\/path

    Since NetInfo uses the / to separate path components, and we have / characters in the entry we want to create, those / have to be escaped. This is done with the backslash, \, and since we are running in a shell, we need to double them up. After the shell is done examining the command, the string \\/ becomes \/ which is what we need to pass to nicl. If we don't use any backslashes, nicl will end up creating an entry /exports/external which has a subdirectory path. This is definitely not what we want.
    Basically, double-backslash the forward slashes in the path to export (/external/path), but not the NetInfo path (/exports/). Note also the part /\\/ as the path we are exporting is /external/path which includes the leading /.
    If you added /exports/external\\/path then the path exported would be external/path which is a relative path, but relative to what?
    Make sure to not put in a trailing slash on the path.

  2. Now we need to add the two properties which specify the allowed clients and any options we need. These properties are clients which we'll set to an empty string (which means all clients, but read the note on default entry, below); and opts, set to ro so the directory is mounted read-only (see the manpage for exports for the options which can be used). The commands to accomplish this are:

    sudo nicl . -append /exports/\\/external\\/path clients ""
    sudo nicl . -append /exports/\\/external\\/path opts ro

You can repeat this procedure for any other directories you wish to export (but be sure to read the note about default entry, below, if you export several directories to empty clients properties).

Starting Daemons or Notifying mountd
For serving NFS, Mac OS X has three daemons which need to be running: portmap which tells clients how to contact the NFS daemons, mountd which handles mounting of NFS filesystems, and nfsd which handles all the rest of serving NFS. See the respective man pages for more information on these.
The first thing to know is, if a machine has no exports listed, these daemons will not be started when the OS starts. portmap is started by /System/Library/StartupItems/Portmap/Portmap (prior to 10.4, and by launchd in 10.4 and later), and both mountd and nfsd are started by /System/Library/StartupItems/NFS/NFS. If you're curious, a look at these scripts will show where they check for exports before starting the respective daemons. The NFS script also starts the NFS client daemons, FYI.
The point of this information is, if this is the first time you add NFS exports, these daemons have to be started before anything works. If this is the case, you'll need to start the daemons (mentioned below). If they are already running, you merely need to notify mountd of export changes (also below).

Starting Daemons
If the daemons aren't running yet (ie, you just added your first exports), you can either start them up by hand, or simply reboot. To start them, run (don't start portmap if you're running on 10.4 or later):

cd /
sudo /usr/sbin/portmap
sudo /usr/sbin/mountd
sudo /sbin/nfsd -t -u -n 6

The order is important. The arguments given to nfsd are the default; if you've added your own to NetInfo's /config/nfsd, use those instead. Once they are started, you're ready to test them.

Notifying mountd
If the daemons are already running, modifying /exports requires a notification be sent to only mountd. This can be done simply by running:

sudo kill -1 `cat /var/run/`

Note those are backticks, not single quotes.

Testing The Exports
To see what mountd is offering, you can run:

showmount -e

This shows the exported filesystems on your machine. You can also run this against another machine as:

showmount -e nfsserver

The output from showmount should look like:

Exports list on localhost:
/external/path Everyone

This indicates the exports are setup properly and mountd is aware of them. The next test is to actually attempt to mount the filesystem. This is accomplished by running:

sudo mount localhost:/external/path /private/mnt

This mounts the exported filesystem into /private/mnt, so an ls of /private/mnt should show the same files as under /external/path.
Once this is verified, unmount it by running

sudo umount /private/mnt

The only testing left is to try mounting the filesystem on a different machine. If that doesn't work, you'll have to consult further documentation, as a full NFS troubleshooting discussion is beyond the scope of this document.

Notes About Being an NFS Server

  • default entry
    One big issue is where you try to export more than one directory on the same filesystem to a blank clients property. The first one is picked up, labeled as the "default entry" for that filesystem, and any other directory on that same filesystem with a blank clients list will not in fact be exported. This is covered in the manpage for exports, but the wording is quite vague.
    The fix for this is to add the additional directories to the name property of the first one you add. For example, if you want to export /Users/user1 and /Users/user2 to everybody and both directories are on the same filesystem, you would set it up as follows,

    sudo nicl . -create /exports/\\/Users\\/user1
    sudo nicl . -append /exports/\\/Users\\/user1 name /Users/user2
    sudo nicl . -append /exports/\\/Users\\/user1 clients ""
    sudo nicl . -append /exports/\\/Users\\/user1 opts ro

    This then causes both /Users/user1 and /Users/user2 to be the default entry.

  • Security Information
    One note about security. Be very careful with exports which use an empty clients property, as that means any machine can see the exported files. Whenever possible, only specify machines which need to access the exported filesystem. Also, whenever possible, export filesystems read-only (an opts value of ro).

  • Viewing /exports from the command line
    If you want to look at what's currently in /exports from the command line, run

    nidump -r /exports .

    This will dump out the information recursively (what's in /exports, and all the information pertaining to it). It should look something like

    "name" = ( "exports" );
    CHILDREN = (
    "name" = ( "/external/path" );
    "clients" = ( "" );
    "opts" = ( "ro" );


  • Cette page est bien faite et m'a permis de rétablir un export qui avait disparu après mon passage à 10.4

    quelques remarques malgrès tout
    1) L'exemple /external/path est trompeur car il laisse à penser que "external" est obligatoire en plus du path.

    2) l'exemple d'option "ro" n'est pas assez documenté, il faudrait dire que ce champ peut être laissé vide ce qui veut dire que l'export est "read-write". J'ai mis "rw" et l'export ne fonctionnait pas.

    By Anonymous Anonymous, at November 17, 2005 at 7:50 AM  

  • I've followed the directions as listed (changing filenames to suit my system.)

    'showount' shows nothing
    'showmount -e' shows nothing

    'nidump -r exports .' shows the full (equivalent) listing.

    when trying to do

    'sudo mount localhost:/path-to-export /path-to-mount'

    I get: mount_nfs: can't access /path-to-export: Permission denied

    Any tips? I've successfully mounted NFS exports as a client, but can't get the server to cooperate.

    I'm using 10.3.9


    By Anonymous Anonymous, at January 11, 2006 at 4:57 PM  

  • When showmount -e doesn't show the associated path, an attempt at mounting it is pretty much guaranteed to fail.

    When nidump shows the information correctly, but showmount -e shows nothing, this usually means mountd doesn't know about it. Make sure mountd has been notified (the bit about Notifying mountd above).

    By Anonymous Anonymous, at January 12, 2006 at 1:47 AM  

  • HUPing mountd using either of the methods listed (in full) still leaves me with 'showmount -e' returning an empty list.

    I'm stumped


    By Anonymous Anonymous, at January 12, 2006 at 6:52 PM  

  • Okay, I've now followed your directions _exactly_, and still get exactly the same result (showmount -e shows nothing)


    By Anonymous Anonymous, at January 12, 2006 at 7:31 PM  

  • Interesting. After a reboot, 'showmount -e' is now showing the version I created using the CLI version of your instructions. This didn't happen after HUPing using either method. Still no sign of the version created using the Netinfo GUI.

    It's a start. It also confirms my suspicions that Netinfo Manager is slightly broken under Panther (at least on this old machine).

    Thanks for your informative page. I can now experiment and see what happens.


    By Anonymous Anonymous, at January 13, 2006 at 3:04 PM  

  • Odd that HUPing mountd didn't work, perhaps simply restarting that one process could have done the job instead of a full reboot?

    As far as NetInfo Manager issues, if nidump does not show what is seen in Manager, something weird is definitely going on.

    By Anonymous Anonymous, at January 14, 2006 at 3:00 PM  

  • I appear to have two separate problems now:

    1) NFS is really slow. It takes about 3 minutes to process a "showmount -e" from a different machine, and the same timeframe to connect to. After connection is established, it seems to be fine (although I haven't done any benchmarking)

    2) I can't work out how to pass in options to change it from a read-only filesystem to a read-write. I've come from a linux background, so I thought it would be as simple as changing 'opts ro' to 'opts rw' then adding in more like 'sync' and 'root_squash', but these seem to crash the server. As does changing the client list to individual machine names or IP's (assuming that is what "client" means - or does it mean the _type_ of nfs client like "linux" and "macos"?)

    On a separate issue: I haven't tested this thoroughly, but it seems that the NFS server isn't starting until _after_ a login. Ideally, I need it to start during the booting process without logging in (i.e remote server)

    Can you recommend a source of further information on OS X/BSD NFS that will point me in the right direction.


    By Anonymous Anonymous, at January 15, 2006 at 9:54 PM  

  • The first problem (initial connect is slow, but things are fine after) usual say to me that name resolution is timing out; check DNS/lookupd stuff on machine names (and possibly reverse lookups).

    When you want to change from read-only to writable, simply remove ro from opts; the other options you list aren't available for the Mac's NFS server (at least on client) -- see the exports manpage for workable options.

    The server should be starting at startup (since it uses a system-level startup item); not sure why it wouldn't be working until a user logs in. Since this is using the automounter, client mounts won't be actually mounted until accessed...

    The FreeBSD handbook section on NFS may (or may not) be helpful on generic BSD issues.

    By Anonymous Anonymous, at January 17, 2006 at 2:21 AM  

  • I was really having a lot of trouble setting up the NFS until I saw the (non-server) condition. I've been piling through documentation, but I can't find a solution. Undoubtedly just my unfamiliarity with OS X, but do you know of another way to set up a network file system on OS X server?

    By Anonymous Anonymous, at April 26, 2006 at 5:45 PM  

  • I was having the same problem as the guy above, with showexports -e not working. This was because I'd earlier created an /etc/exports file and mountd was picking that up. Killing mountd, removing the file and restarting mountd solved the problem

    By Anonymous Anonymous, at May 6, 2006 at 2:24 PM  

  • I too followed the instructions exactly, and showmount returned nothing.. My solution was to (obviously) create the directory that I was exporting, once I did this, it showed up fine.

    By Anonymous Anonymous, at June 11, 2006 at 12:23 PM  

  • Very slow NFS can be that portmap isn't running...

    By Anonymous Anonymous, at October 9, 2006 at 5:29 AM  

  • Under "Starting Daemons" you say:
    To start them, run (don't start portmap if you're running on 10.4 or later):

    Why shouldn't I start portmap on Tiger 10.4?
    Does mountd or nfsd do that?

    By Anonymous Anonymous, at October 15, 2006 at 12:25 PM  

  • I am using 10.4.8 and the NetInfo method.
    showmount -e showed the correct path that I set. But, when I tried

    sudo mount localhost:/external/path /private/mnt

    I got the error:
    NFS Portmap: RPC: Program not registered

    and no prompt (had to ctrl-c)

    By Anonymous Anonymous, at December 15, 2006 at 10:23 AM  

  • I am using 10.4.8. "showmount" shows nothing and "nidump" shows the entries.

    I have noticed that the /etc/exports file, when properly populated, will allow NFS services to work. It seems to ignore the NetInfo manager information entirely. I wonder why?

    I have also noted that Webmin will manage NFS exports okay, but I cannot set up an export that has a space in the name. (e.g. "/Volumes/External Drive") Any ideas on how to overcome that? (adding \ in front of the space doesn't help either.)

    By Anonymous Anonymous, at January 7, 2007 at 7:01 PM  

  • When I type
    >sudo nicl . -append /exports/\\/external\\/Users/admin/Desktop clients ""

    I keep getting "invalid path"..

    By Anonymous Anonymous, at January 31, 2007 at 7:19 AM  

  • When I run showmount -e

    my export list on localhost shows no exports, and I did export the directory /Users/admin/Desktop.....

    By Anonymous Anonymous, at January 31, 2007 at 7:26 AM  

  • I have been having the same problem as ttfn, however I recieve nothing from "nidump -r exports ." as well....

    Sonambulant Evocation..

    By Anonymous Anonymous, at January 31, 2007 at 7:30 AM  

  • create /etc/exports and fill it in as the man page (man exports) suggest. reboot.

    if you edit /etc/exports you can refresh by "kill -HUP `cat /var/run/`" as the man page suggests.

    By Anonymous Anonymous, at February 6, 2007 at 8:35 AM  

  • I did all the nicl stuff (and fiddled with Netinfo Manager too) but couldn't get the equivalent of no_root_squash (on Linux) enabled.

    I had no problems with nicl other than this one difficulty, and found that I could get it to work properly by creating /etc/exports and using the -maproot=root option (explained in the exports man page).


    By Anonymous Anonymous, at February 20, 2007 at 2:58 AM  

  • In response to the comment for Mac OS 10.4.8, stating:

    "I got the error:
    NFS Portmap: RPC: Program not registered"

    I received this error on one of my systems - it turned out that the nfs server had its Firewall turned on.

    I suggest checking the server (export machine), turning off the Firewall, attempt the mount from the client machine. (Firewall settings in the Sharing System Preferences Pane, on the Firewall tab).

    If the mount works, and you then want to play around with turning Firewall protection, have at it. However, I believe the portmapper service on Mac OS X changes the port it uses from instance to instance, in a non-standard Unix manner. This makes it difficult to open up one port through a firewall....

    good luck,

    By Anonymous Anonymous, at February 22, 2007 at 2:44 PM  

  • I too had no luck with putting the info in the Netinfo database. I put it in but nothing was exported.

    So I did it the old-fashioned way with /etc/exports and it works!

    By Anonymous Anonymous, at March 28, 2007 at 8:44 PM  

  • It wasn't working for me because I had a symlink as the export.
    As soon as I export a real directory it worked.

    By Blogger n0b0d3, at May 1, 2007 at 9:20 AM  

  • Great tutorial, this worked well for me. Like the prior comment, I was confused that "opts rw" was not accepted, perhaps you could describe this in the main body.

    Thank you very much

    By Blogger Brian, at May 11, 2007 at 1:01 AM  

  • The following tutorial works much better.

    How to Share Directories over NFS


    Using these instructions and the additional -maproot=root option (to be able to read and write when mounting as route) I was able to get it all working pretty easily. The patch makes NFS much smarter on Mac OSX.

    By Anonymous Anonymous, at June 24, 2007 at 5:33 PM  

  • Hello everyone!

    I really appreciate this tutorial because I have successfully mounted my Debian NFS client to my Mac OS X NFS server by following this tutorial!

    Now, I wanted to have a read-write permission to /external/path so I changed opts value from "ro" to "rw". Then I executed the commands found in "Starting Daemons" section of this article to notify NFS server about the changes.

    The problem is, /external/path doesn't appear anymore when executing "showount -e" command. It appears again only when I reset the opts value back to "ro".

    How can I export a directory in Mac OS X server over NFS? Please help me. Thanks!

    By Anonymous Anonymous, at May 19, 2008 at 3:05 AM  

  • I am sorry but a correction to the previous comment,


    This tutorial only showed exporting a directory with a read-only permission. Changing opts to rw doesn't work.

    Please help. Thanks!

    By Anonymous Anonymous, at May 19, 2008 at 7:41 PM  

  • Hi again everyone!

    I have finally found the solution to my previous question. Just in case there would be anyone who would also want to export a directory with a read-write permission, here is what I did:

    1. Give a write permission to all using chmod:
    sudo chmod -R a+w /external/path
    2. Changed opt value from ro to
    3. restart portmap, mountd, and nfsd.
    sudo /usr/sbin/portmap
    sudo /usr/sbin/mountd
    sudo /sbin/nfsd -t -u -n 6

    Hope this could be helpful! :)

    By Anonymous Anonymous, at May 20, 2008 at 4:15 AM  

  • Hi. I've done what is said here and can get showmount -e provide the correct exports list. However, when I enter

    sudo mount localhost:/exported/dir /private/mnt

    I get the error

    mount_nfs: can't access /Volumes/cassava1/data: Permission denied

    What sort of permissions do I need to check. The exported disk is ro so your instructions should be fine. The only thing I changed was to provide a list of clients.


    By Anonymous Anonymous, at November 25, 2008 at 10:35 AM  

  • Sorry, I should say that I am running 10.4.11. Also the /exports/dir is /Volumes/cassava1/data


    By Anonymous Anonymous, at November 25, 2008 at 10:38 AM  

  • Hi,
    i am a new mac user. Have a question:
    I bought a Patriot Media Player thinking that I intent on connecting with my mac so that I can stream movies from my mac to the Patriot. Can you please recommend how I would go about this.
    Appreciate your help and time.

    By Blogger Unknown, at July 12, 2010 at 7:50 PM  

Post a Comment

<< Home