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