The evolution of FreeNAS has been both subtle and revolutionary over its decade-long history, and the next generation of FreeNAS is poised to introduce the biggest changes yet to the world’s most popular software-defined storage OS. This clean-slate rewrite adds something unheard of in open source storage: An intuitive command-line interface or CLI for short that allows you to control every aspect of FreeNAS, including exciting new features like object storage and virtualization. Enterprise users familiar with the Cisco and Vyatta CLIs will feel right at home with the FreeNAS CLI, but new users should have no trouble navigating it thanks to its purpose-built design and built-in help. Beyond simply being intuitive, the FreeNAS CLI is also highly-scriptable, allowing you to configure a local or remote FreeNAS system in seconds.

Getting Started

The FreeNAS CLI is only available in FreeNAS 10 ALPHA nightly builds which can be downloaded from download.freenas.org/10/MASTER/.
While FreeNAS 9.3 and 10 ALPHA differ in countless ways, they do share the same installation procedures that use a hybrid CD-ROM/USB key bootable installer image. The FreeNAS 9.3 Documentation will walk you through the process on real or virtual hardware. Upgrades from FreeNAS 9.3 are not supported at this time and understand that FreeNAS 10 ALPHA is not yet ready for production use with critical data.

Orientation

On first boot, you will be greeted by Suraj’s sacred cow who advises you to “Type 'help' to get started.” You should also see a DHCP-acquired IP address that you can ssh to as root and type ‘cli‘.
The CLI prompt will look like this, with “unix” indicating that you are connected via the local unix-domain socket:

 _________________________________________

/ Welcome to the FreeNAS CLI! Type 'help' \

\ to get started.                         /

 -----------------------------------------

        \   ^__^

         \  (**)\_______

            (__)\       )\/\

             U  ||----w |

                ||     ||

You may try the following URLs to access the web user interface:

          URLs (url)

http://192.168.1.4

http://fe80::3e97:eff:fe77:a435

unix::>

A question mark “?” will show you the available items in any given namespace and from there “help” and “show” are your primary discovery commands:

unix::>?

Global commands:

-   ?      dump  help     pending   setenv   showurls  unalias  whoami

..  alias  echo  history  printenv  shell    source    vars

/   clear  exit  login    saveenv   showips  top       wait

Filtering commands:

exclude  less  limit  more  newer_than  older_than  search  select  sort

Current namespace items:

account  calendar          log          service    statistic  update

alert    directoryservice  network      share      system     vm

boot     disk              replication  simulator  task       volume

unix::>help disk

Command   Description

show      Lists disks

The disk namespace lists the disks recognized by the system.

Type 'show' for more details about the disks.

Type the disk's name to manage that disk and type

'help properties' for help on the available properties.

unix::>disk show

Path      Name       Size       Online   Empty   Allocation

/dev/da0    da0    7.22 GiB       yes      no      boot device

/dev/ada0   ada0   223.57 GiB     yes      no      unallocated

/dev/ada1   ada1   223.57 GiB     yes      no      unallocated

Knowing that we have disks ada0 and ada1 available for use, using them to create a mirrored volume is simply a matter of providing a volume name plus the disks:

unix::>volume create myvolume disks=ada0,ada1

Task #5 submitted

unix::>

unix::>volume show

Volume name   Encrypted   Providers   Status    Mount point

myvolume      no          none        ONLINE   /mnt/myvolume

The [1] before the prompt indicated that a task, in this case “volume create” is pending execution. You can display pending and executing tasks and subtasks with “pending”:

[1] unix::>pending

ID   Description     Started at    Finished at     State          Status

Task ID      Task description         Task status

10       Create volume myvolume   50% (Executing...)

Sharing Setup

With your volume configured, you can now follow the familiar FreeNAS steps of creating a user and an SMB share, enabling the SMB service, and assigning ownership of the share to the user:

unix::>account user create myuser password=123

unix::>share smb create myshare parent=myvolume

Task #15 submitted

Share 'myshare' has been created but the service 'smb' is not currently running,

please enable the service with '/ service smb config set enable=yes'

unix::>/ service smb config set enable=yes

Task #20 submitted

unix::>service smb show

Property   Description     Value    Editable

name       Service name   smb       no

state      State          RUNNING   no

pid        Process ID     1389      no

unix::>share smb myshare set owner=myuser

New to FreeNAS 10 is the ability to manually start and stop services, rather than only enabling and disabling them: “/ service smb start”
With the share configured, you can test it over the LAN or at the FreeBSD command line invoked with  “shell” and the included  “smbclient” utility:

unix::>shell

# smbclient -U myuser \\\\localhost\\myshare

...

Enter myuser’s password:

Domain=[WORKGROUP] OS=[Windows 6.1] Server=[Samba 4.3.4-UNKNOWN]

smb: \> dir

.                                   D        0  Tue Feb 16 00:14:59 2016

..                                  D        0  Tue Feb 16 00:13:36 2016

.config-smb-myshare.json            H     1801  Tue Feb 16 00:14:59 2016

223477658 blocks of size 1024. 223477638 blocks available

smb: \> exit

# exit

unix::>

Success!

Five commands are all it takes to create a volume and share it to a dedicated user. The power of this approach becomes clear when you consider that the same five commands can reside in a script. Rather than executing the commands one by one, you can type “shell” and create the following script “/root/create_share” with your editor of choice:

volume create myvolume disks=ada0,ada1; wait

account user create myuser password=123; wait

share smb create myshare parent=myvolume; wait

service smb config set enable=yes

share smb myshare set owner=myuser

FreeNAS CLI Scripting

From the CLI you can type “source create_share” to run the script to have your volume, user and share created in seconds. This opens the door for remotely configuring multiple FreeNAS systems from either one another, or from any computer with the FreeNAS CLI installed. Here are two examples of locally and remotely running our script in the FreeBSD shell:

cli -f /root/create_share

cli -f /root/create_share ssh://root@192.168.1.4

This crash course only scratches the surface of the FreeNAS CLI and its potential to change the way you look at storage and system management. New scripting features are arriving every week and the FreeNAS CLI promises to become a standard tool in your administrative toolkit.
Michael Dexter
Senior Analyst