NFS

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

NFS Namespace

The nfs namespace has five command(s), and is based on share creation and management functions found in the SCALE API and web UI. It provides access to NFS share methods through the nfs commands.

NFS Commands

The following nfs commands allow you to create new shares, manage existing shares, get information on NFS shares on the system

You can enter commands from the main CLI prompt or from the sharing namespace prompt.

Interactive Argument Editor (TUI)

Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).

Click for more information

The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.

Optional properties, indicated by the # symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.

To configure required properties, enter a space after the colon then add the value.

To enable optional properties, delete # from the corresponding line.

Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.

Press F2 or click Save to save the modified file.

Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.

Create Command

The create command adds a new NFS share.

It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
Using the Create Command

Description

The create has one required property, path. The Create Command Optional Properties section below lists the 12 optional properties. Enter a property argument using the = delimiter to separate property and value. Enter a string value enclosed in double quotes.

Enter the command string, then press Enter.

create returns an empty line. Use the query command to verify the share was created and to view details of the share.

Create Command Optional Properties

These optional properties are also used with the update command.

CommandDescriptionSyntax Example
aliasesThis option is a Work in Progress.
commentEnter a description for the share. Enclose the string in double quotes.comment="For read only access"
networksSpecify a list of network IP addresses with CIDR notation allowed to access this share. Leave empty to allow all. Enter the network values enclosed in square brackets []. Enclose each IP address/CIDR value in double quotes and separate multiple network values with a comma and space.networks=["1.2.3.0/24", “1.2.2.2/21”]
hostsSpecify a list of network IP addresses with CIDR notation or hostnames allowed to access this share. Leave empty to allow all. Enter the network values enclosed in square brackets []. Enclose each IP address/CIDR or hostname value in double quotes and separate multiple network values with a comma and space.networks=["1.2.3.0/24", “truenas.com”]
roSet to true to prohibit writing to the share or false to allow writing to the share.ro=true or ro=false
quietDo not use.
maproot_userEnter a username to limit the root user to the permissions of that user.maproot_user=admin
maproot_groupEnter a group name to limit the root user to the permissions of that group.mapgroup=admin
mapall_userEnter a username set all clients to use the specified permissions of that user.mapall_user=admin
mapall_groupEnter a group name set all clients to use the specified permissions of that group.mapall_group=admin
securitySets the security for the share to one of four options:
  • SYS to set the share to use locally acquired UID and GID permissions.
  • KRB5 to set the share to use Kerberos V5 user authentication.
  • KRB5i to set the share to use Kerberos V5i for user authentication and perform integrity checking of NFS operations using secure checksums to prevent data tampering.
  • KRB5P to set the share to use Kerberos V5 user authentication and integrity checking that encrypts NFS traffic to prevent traffic sniffing.
  • security=SYS
    enabledSet to true to enable this share or false to disable the share without deleting it.enable=true or enable=false

    Usage

    From the CLI prompt, enter:

    sharing nfs create path="/mnt/tank/shares/nfs2"

    Where mnt/tank/shares/nfs2 is the path to the dataset created for the share.

    If using optional property arguments, for example, to set networks and read only access, enter:

    sharing nfs create path="/mnt/tank/shares/nfs2" networks=10.123.12.1/24 10.123.11.2/23 ro=true

    Where:

    • mnt/tank/shares/nfs2 is the path to the dataset created for the share.
    • 10.123.12.1/24 10.123.11.2/23 are the space-separated IP addresses with CIDR notation for each network you allow to connect to the share.
    • true sets the share to read only or false to allow write access to the share.

    Command Example
    sharing nfs create path=/mnt/tank/shares/nfs2
    

    Delete Command

    The delete command deletes an NFS share.

    Using the Delete Command

    Description

    The delete command has one required property, id. Enter a property argument using the = delimiter to separate property and value and enclose the value in double quotes. Enter the command string, then press Enter.

    delete returns an empty line.

    Usage

    From the CLI prompt, enter:

    sharing nfs delete id="4"

    Where 4 is the ID assigned to the share.

    Command Example
    sharing nfs delete id=4
    

    Get_Instance Command

    The get_instance command retrieves information for an NFS share matching the id entered in the command string. Use to verify properties for the configured share.

    Using the Get_Instance Command

    Description

    The get_instance command has one required property, id. Enter the command, then press Enter. get_instance returns a table (dictionary) of properties for the ID entered. The dictionary includes the share ID, path, aliases, comment, networks, hosts entered, the read only, quiet, and locked status as true or false, value for maproot and mapall users and groups, security applied, and the enabled status as true or false.

    Use the query command to locate the ID number for the share.

    Usage

    From the CLI prompt, enter:

    sharing nfs get_instance id=1

    Where 1 is the ID number for the share.

    Command Example
    sharing nfs get_instance id=1 
    +---------------+-----------------------+
    |            id | 1                     |
    |          path | /mnt/tank/shares/nfs  |
    |       aliases | <empty list>          |
    |       comment |                       |
    |         hosts | <empty list>          |
    |            ro | false                 |
    |         quiet | false                 |
    |  maproot_user | <null>                |
    | maproot_group | <null>                |
    |   mapall_user | <null>                |
    |  mapall_group | <null>                |
    |      security | <empty list>          |
    |       enabled | true                  |
    |      networks | <empty list>          |
    |        locked | false                 |
    +---------------+-----------------------+
    

    Query Command

    The query command returns a table (dictionary) of all NFS shares on the system. Use to locate the share ID number and other configuration information.

    Using the Query Command

    Description

    The query does not require entering property arguments. Enter the command, then press Enter. The query returns a table (dictionary) of all NFS shares configured on the system. Information includes the ID, path, aliases, any comments, networks hosts, read only status, maproot user and group, mapall user and group, security, enabled, and locked status.

    Usage

    From the CLI prompt, enter:

    `sharing nfs query'

    Command Example
    sharing nfs query
    +----+-----------------------+--------------+------------+-------+-------+--------------+---------------+-------------+--------------+--------------+---------+--------------+-------+
    | id | path                  | aliases      | comment    | ro    | quiet | maproot_user | maproot_group | mapall_user | mapall_group | security     | enabled | networks     | Locked |
    | 1  | /mnt/tank/shares/nfs  | <empty list> | test share | false | false |              |               |             |              | <empty list> | true    | <empty list> | false |
    | 2  | /mnt/tank/shares/nfs2 | <empty list> |            | false | false | <null>       | <null>        | <null>      | <null>       | <empty list> | true    | <empty list> | false |
    +----+-----------------------+--------------+------------+-------+-------+--------------+---------------+-------------+--------------+--------------+---------+--------------+-------+
    

    Update Command

    The update command returns a table (dictionary) of all NFS shares on the system. Use to locate the share ID number and other configuration information.

    Using the Update Command

    Description

    The update has one required property, id. This command uses the optional share properties listed in Create Command Optional Properties found in the Create Command section. Follow the syntax examples provided for each property. Enter the command string, then press Enter. update returns an empty line.

    Usage

    To add or change a comment for a share, from the CLI prompt, enter:

    sharing nfs update id=4 comment="test share"

    Where

    • 4 is the ID number assigned to the share to update.
    • test share is the comment to add to the share.

    Command Example
    sharing nfs update id=4 comment="test share"