nuttx/Documentation/guides/nfs.rst

=================
NFS Client How-To
=================

Adding NFS to the NuttX Configuration
=====================================

The NFS client is easily added to your configuration: You simply need to
add ``CONFIG_NFS`` to your ``nuttx/.config`` file. There are, however, a
few dependencies on other system settings:

First, there are things that you must configure in order to be able to
use any file system:

  -  ``CONFIG_DISABLE_MOUNTPOINT=n``. You must include support for mount
     points in the pseudo-file system.

And there are several dependencies on the networking configuration. At a
minimum, you need to have the following selections:

  -  ``CONFIG_NET=y``. General networking support.
  -  ``CONFIG_NET_UDP=y``. Support for UDP.

Mount Interface
===============

A low-level, C-callable interface is provided to mount a file system.
That interface is called ``mount()`` and is mentioned in the
porting guide and is prototyped in the header file ``include/sys/mount.h``:

.. c:function:: int mount(const char *source, const char *target, const char *filesystemtype, unsigned long mountflags, const void *data)

  ``mount()`` attaches the filesystem specified by the
  ``source`` block device name into the root file system at the path
  specified by ``target``.

  :param source: A null-terminated string providing the fill path to a
     block driver in the NuttX pseudo-file system.
  :param target: The location in the NuttX pseudo-file system where the
     volume will be mounted.
  :param filesystemtype: A string identifying the type of file system to
     use.
  :param mountflags: Various flags that can be used to qualify how the
     file system is mounted.
  :param data: Opaque data that is passed to the file system with the
     mount occurs.

  :return: Zero is returned on success; -1 is returned on an
    error and ``errno`` is set appropriately:

    -  ``EACCES``. A component of a path was not searchable or mounting a
       read-only filesystem was attempted without giving the ``MS_RDONLY``
       flag.
    -  ``EBUSY``. ``source`` is already mounted.
    -  ``EFAULT``. One of the pointer arguments points outside the user
       address space.
    -  ``EINVAL``. ``source`` had an invalid superblock.
    -  ``ENODEV``. ``filesystemtype`` not configured
    -  ``ENOENT``. A pathname was empty or had a nonexistent component.
    -  ``ENOMEM``. Could not allocate a memory to copy filenames or data
       into.
    -  ``ENOTBLK``. ``source`` is not a block device

This same interface can be used to mount a remote, NFS file system using
some special parameters. The NFS mount differs from the *normal* file
system mount in that: (1) there is no block driver for the NFS file
system, and (2) special parameters must be passed as ``data`` to
describe the remote NFS server. Thus the following code snippet might
represent how an NFS file system is mounted:

.. code-block:: c

  #include <sys/mount.h>
  #include <nuttx/fs/nfs.h>

  struct nfs_args data;
  char *mountpoint;

  ret = mount(NULL, mountpoint, string "nfs", 0, (FAR void *)&data);

NOTE that: (1) the block driver parameter is ``NULL``. The ``mount()``
is smart enough to know that no block driver is needed with the NFS file
system. (2) The NFS file system is identified with the simple string
"nfs" (3) A reference to ``struct nfs_args`` is passed as an
NFS-specific argument.

The NFS-specific interface is described in the file
``include/nuttx/fs/nfs.h``. There you can see that ``struct nfs_args``
is defined as:

.. code-block:: c

  struct nfs_args
  {
    uint8_t  addrlen;               /* Length of address */
    uint8_t  sotype;                /* Socket type */
    uint8_t  flags;                 /* Flags, determines if following are valid: */
    uint8_t  timeo;                 /* Time value in deciseconds (with NFSMNT_TIMEO) */
    uint8_t  retrans;               /* Times to retry send (with NFSMNT_RETRANS) */
    uint16_t wsize;                 /* Write size in bytes (with NFSMNT_WSIZE) */
    uint16_t rsize;                 /* Read size in bytes (with NFSMNT_RSIZE) */
    uint16_t readdirsize;           /* readdir size in bytes (with NFSMNT_READDIRSIZE) */
    char    *path;                  /* Server's path of the directory being mount */
    struct   sockaddr_storage addr; /* File server address (requires 32-bit alignment) */
  };

NFS Mount Command
=================

The :ref:`NuttShell (NSH) <nsh>` also supports a command called
``nfsmount`` that can be used to mount a remote file system via the NSH
command line.

**Command Syntax:**

.. code-block::

  nfsmount <server-address> <mount-point> <remote-path> [udp]

**Synopsis**. The ``nfsmount`` command mounts a network file system in
the NuttX pseudo filesystem. The ``nfsmount`` will use NFSv3 UDP
protocol to mount the remote file system.

**Command Line Arguments**. The ``nfsmount`` takes three arguments:

  #. The ``<server-address>`` is the IP address of the server exporting
     the file system you wish to mount. This implementation of NFS for the
     NuttX RTOS is only for a local area network, so the server and client
     must be in the same network.
  #. The ``<mount-point >`` is the location in the NuttX pseudo filesystem
     where the mounted volume will appear. This mount point can only
     reside in the NuttX pseudo filesystem. By convention, this mount
     point is a subdirectory under ``/mnt``. The mount command will create
     whatever pseudo directories that may be needed to complete the full
     path (but the full path must not already exist).
  #. The ``<remote-path>`` is the file system ``/`` directory being
     exported from server. This ``/`` directory must have been configured
     for exportation on the server before when the NFS server was set up.

After the volume has been mounted in the NuttX pseudo filesystem, it may
be access in the same way as other objects in the file system.

**Example**. Suppose that the NFS server has been configured to export
the directory ``/export/shared``. The the following command would mount
that file system (assuming that the target also has privileges to mount
the file system).

.. code-block:: fish

  NuttShell (NSH)
  nsh> ls /mnt
  /mnt:
  nsh: ls: no such directory: /mnt
  nsh> nfsmount 10.0.0.1 /mnt/nfs /export/shared
  nsh> ls -l /mnt/nfs
  /mnt/nfs:
   drwxrwxrwx   4096 ..
   drwxrwxrwx   4096 testdir/
   -rw-rw-rw-      6 ctest.txt
   -rw-r--r--     15 btest.txt
   drwxrwxrwx   4096 .
  nsh> echo "This is a test" >/mnt/nfs/testdir/testfile.txt
  nsh> ls -l /mnt/nfs/testdir
  /mnt/nfs/testdir:
   -rw-rw-rw-     21 another.txt
   drwxrwxrwx   4096 ..
   drwxrwxrwx   4096 .
   -rw-rw-rw-     16 testfile.txt
  nsh> cat /mnt/nfs/testdir/testfile.txt
  This is a test

Configuring the NFS server (Ubuntu)
===================================

Setting up the server will be done in two steps: First, setting up the
configuration file for NFS, and then starting the NFS services. But
first, you need to install the nfs server on Ubuntu with these two
commands:

.. code-block:: console

  $ sudo apt-get install nfs-common
  $ sudo apt-get install nfs-kernel-server

After that, we need to make or choose the directory we want to export
from the NFS server. In our case, we are going to make a new directory
called ``/export``.

.. code-block:: console

  # sudo mkdir /export

It is important that ``/export`` directory allow access to everyone (777
permissions) as we will be accessing the NFS share from the client with
no authentication.

.. code-block:: console

  # sudo chmod 777 /export

When all this is done, we will need to edit the configuration file to
set up an NFS server: ``/etc/exports``. This file contains a list of
entries; each entry indicates a volume that is shared and how it is
shared. For more information for a complete description of all the setup
options for this file you can check in the man pages (``man export``).

An entry in ``/etc/exports`` will typically look like this:

.. code-block::

  directory machine1(option11,option12)

So for our example we export ``/export`` to the client 10.0.0.2 add the
entry:

.. code-block::

  /export 10.0.0.2(rw)

In our case we are using all the default options except for the ``ro``
that we replaced with ``rw`` so that our client will have read and write
access to the directory that we are exporting.

After we do all the require configurations, we are ready to start the
server with the next command:

.. code-block:: console

  # sudo /etc/init.d/nfs-kernel-server start

Note: If you later decide to add more NFS exports to the /etc/exports
file, you will need to either restart NFS daemon or run command
exportfs.

.. code-block:: console

  # sudo /etc/init.d/nfs-kernel-server start

Or

.. code-block:: console

  # exportfs -ra

Now we can check if the export directory and our mount point is properly
set up.

.. code-block:: console

  # sudo showmount -e
  # sudo showmount -a

And also we can verify if NFS is running in the system with:

.. code-block:: console

    # rpcinfo –p
    program vers proto   port
       100000   2   tcp    111  portmapper
       100000   2   udp    111  portmapper
       100011   1   udp   749  rquotad
       100011   2   udp   749  rquotad
       100005   1   udp    759  mountd
       100005   1   tcp    761  mountd
       100005   2   udp    764  mountd
       100005   2   tcp    766  mountd
       100005   3   udp    769  mountd
       100005   3   tcp    771  mountd
       100003   2   udp   2049  nfs
       100003   3   udp   2049  nfs
       300019   1   tcp    830  amd
       300019   1   udp    831  amd
       100024   1   udp    944  status
       100024   1   tcp    946  status
       100021   1   udp   1042  nlockmgr
       100021   3   udp   1042  nlockmgr
       100021   4   udp   1042  nlockmgr
       100021   1   tcp   1629  nlockmgr
       100021   3   tcp   1629  nlockmgr
       100021   4   tcp   1629  nlockmgr

Now your NFS sever is sharing ``/export`` directory to be accessed.