FreeNAS® 11.0-U4 User Guide

FreeNAS® 11.0-U4 User Guide
September 2017 Edition
FreeNAS® is © 2011-2017 iXsystems
FreeNAS® and the FreeNAS® logo are registered trademarks of iXsystems
FreeBSD® is a registered trademark of the FreeBSD Foundation
Written by users of the FreeNAS® network-attached storage operating system.
Version 11.0
Copyright © 2011-2017 iXsystems (https://www.ixsystems.com/)
CONTENTS
Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
2
1 Introduction
1.1 New Features in 11.0 . . . . . . . . .
1.2 Changes Since 11.0 . . . . . . . . . .
1.2.1 U1 . . . . . . . . . . . . . . .
1.2.2 U2 . . . . . . . . . . . . . . .
1.2.3 U3 . . . . . . . . . . . . . . .
1.2.4 U4 . . . . . . . . . . . . . . .
1.3 Path and Name Lengths . . . . . . .
1.4 Hardware Recommendations . . . .
1.4.1 RAM . . . . . . . . . . . . . .
1.4.2 The Operating System Device
1.4.3 Storage Disks and Controllers
1.4.4 Network Interfaces . . . . . .
1.5 Getting Started with ZFS . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
4
5
5
5
5
5
6
6
7
8
9
9
2 Installing and Upgrading
2.1 Getting FreeNAS® . . . . . . . . .
2.2 Preparing the Media . . . . . . .
2.2.1 On FreeBSD or Linux . . .
2.2.2 On Windows . . . . . . .
2.2.3 On OS X . . . . . . . . . .
2.3 Performing the Installation . . . .
2.4 Installation Troubleshooting . . .
2.5 Upgrading . . . . . . . . . . . . .
2.5.1 Caveats . . . . . . . . . .
2.5.2 Initial Preparation . . . .
2.5.3 Upgrading Using the ISO .
2.5.4 Upgrading From the GUI .
2.5.5 If Something Goes Wrong
2.5.6 Upgrading a ZFS Pool . .
2.6 Virtualization . . . . . . . . . . . .
2.6.1 VirtualBox . . . . . . . . .
2.6.2 VMware ESXi . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10
10
11
11
12
12
13
19
20
20
21
21
24
24
25
27
27
36
3 Booting
3.1 Obtaining an IP Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Initial Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
44
45
46
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
i
4 Account
4.1 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
47
50
5 System
5.1 Information . . . . . . . . . . . .
5.2 General . . . . . . . . . . . . . . .
5.3 Boot . . . . . . . . . . . . . . . . .
5.3.1 Mirroring the Boot Device
5.4 Advanced . . . . . . . . . . . . . .
5.4.1 Autotune . . . . . . . . .
5.5 Email . . . . . . . . . . . . . . . .
5.6 System Dataset . . . . . . . . . .
5.7 Tunables . . . . . . . . . . . . . .
5.8 Update . . . . . . . . . . . . . . .
5.8.1 Preparing for Updates . .
5.8.2 Updates and Trains . . . .
5.8.3 Checking for Updates . .
5.8.4 Applying Updates . . . . .
5.8.5 Manual Updates . . . . .
5.9 Alert Services . . . . . . . . . . .
5.9.1 How it Works . . . . . . .
5.10 CAs . . . . . . . . . . . . . . . . .
5.11 Certificates . . . . . . . . . . . . .
5.12 Support . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
54
54
55
58
61
62
64
65
66
67
69
69
70
71
72
72
73
74
74
77
80
6 Tasks
6.1 Cron Jobs . . . . . . . . . . . .
6.2 Init/Shutdown Scripts . . . . .
6.3 Rsync Tasks . . . . . . . . . .
6.3.1 Rsync Module Mode .
6.3.2 Rsync over SSH Mode
6.4 S.M.A.R.T. Tests . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
83
83
85
86
89
90
92
7 Network
7.1 Global Configuration . . . . . . . .
7.2 Interfaces . . . . . . . . . . . . . .
7.3 IPMI . . . . . . . . . . . . . . . . . .
7.4 Link Aggregations . . . . . . . . . .
7.4.1 LACP, MPIO, NFS, and ESXi .
7.4.2 Creating a Link Aggregation
7.5 Network Summary . . . . . . . . .
7.6 Static Routes . . . . . . . . . . . . .
7.7 VLANs . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
95
95
96
98
100
100
101
105
105
106
8 Storage
8.1 Volumes . . . . . . . . . . . .
8.1.1 Volume Manager . . .
Encryption . . . . . . .
Manual Setup . . . . . .
Extending a ZFS Volume
8.1.2 Change Permissions .
8.1.3 Create Dataset . . . .
Deduplication . . . . .
Compression . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
108
108
108
110
111
112
113
115
117
118
ii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8.1.4
8.1.5
8.1.6
8.2
8.3
8.4
8.5
8.6
Create zvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Import Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Import Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Importing an Encrypted Pool . . . . . . . . . . . . . . . . . . . . . . .
8.1.7 View Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.8 Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Encrypted Volumes . . . . . . . . . . . . . . . . . . . . . .
8.1.9 View Multipaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.10 Replacing a Failed Drive . . . . . . . . . . . . . . . . . . . . . . . . .
Replacing an Encrypted Drive . . . . . . . . . . . . . . . . . . . . . . .
Removing a Log or Cache Device . . . . . . . . . . . . . . . . . . . . .
8.1.11 Replacing Drives to Grow a ZFS Pool . . . . . . . . . . . . . . . . . .
Periodic Snapshot Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replication Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.1 Examples: Common Configuration . . . . . . . . . . . . . . . . . . .
Alpha (Source) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Beta (Destination) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.2 Example: FreeNAS® to FreeNAS® Semi-Automatic Setup . . . . . .
8.3.3 Example: FreeNAS® to FreeNAS® Dedicated User Replication . . . .
8.3.4 Example: FreeNAS® to FreeNAS® or Other Systems, Manual Setup
Encryption Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.5 Replication Options . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.6 Replication Encryption . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.7 Limiting Replication Times . . . . . . . . . . . . . . . . . . . . . . . .
8.3.8 Troubleshooting Replication . . . . . . . . . . . . . . . . . . . . . .
SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Manual Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scrubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VMware-Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9 Directory Services
9.1 Active Directory . . . . . . . . . . . . . . . . .
9.1.1 Troubleshooting Tips . . . . . . . . . .
9.1.2 If the System Will not Join the Domain
9.2 LDAP . . . . . . . . . . . . . . . . . . . . . . .
9.3 NIS . . . . . . . . . . . . . . . . . . . . . . . .
9.4 Kerberos Realms . . . . . . . . . . . . . . . .
9.5 Kerberos Keytabs . . . . . . . . . . . . . . . .
9.6 Kerberos Settings . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
118
120
121
122
122
124
127
131
131
133
133
133
134
136
136
136
137
137
139
141
141
144
145
145
145
146
146
146
147
148
150
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
152
152
157
157
158
161
162
163
163
10 Sharing
10.1 Apple (AFP) Shares . . . . . . . . . . . . . . . . . . . . . .
10.1.1 Creating AFP Guest Shares . . . . . . . . . . . . .
10.1.2 Creating Authenticated and Time Machine Shares
10.2 Unix (NFS) Shares . . . . . . . . . . . . . . . . . . . . . . .
10.2.1 Example Configuration . . . . . . . . . . . . . . . .
10.2.2 Connecting to the Share . . . . . . . . . . . . . . .
From BSD or Linux . . . . . . . . . . . . . . . . . . .
From Microsoft . . . . . . . . . . . . . . . . . . . . .
From Mac OS X . . . . . . . . . . . . . . . . . . . . .
10.2.3 Troubleshooting NFS . . . . . . . . . . . . . . . . .
10.3 WebDAV Shares . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
165
166
168
170
174
178
178
178
179
179
181
182
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
iii
10.4 Windows (SMB) Shares . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4.1 Configuring Unauthenticated Access . . . . . . . . . . . . . . . .
10.4.2 Configuring Authenticated Access Without a Domain Controller
10.4.3 Configuring Shadow Copies . . . . . . . . . . . . . . . . . . . . .
10.5 Block (iSCSI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.1 Target Global Configuration . . . . . . . . . . . . . . . . . . . . .
10.5.2 Portals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.3 Initiators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.4 Authorized Accesses . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.5 Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.6 Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.7 Target/Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.8 Connecting to iSCSI . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.9 Growing LUNs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Zvol Based LUN . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Extent Based LUN . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
183
189
190
193
195
196
197
199
200
202
203
206
207
208
208
209
11 Services
11.1 Control Services . . . . . . . . . . . . . . .
11.2 AFP . . . . . . . . . . . . . . . . . . . . . .
11.2.1 Troubleshooting AFP . . . . . . . .
11.3 Domain Controller . . . . . . . . . . . . .
11.3.1 Samba Domain Controller Backup
11.4 Dynamic DNS . . . . . . . . . . . . . . . .
11.5 FTP . . . . . . . . . . . . . . . . . . . . . .
11.5.1 Anonymous FTP . . . . . . . . . .
11.5.2 FTP in chroot . . . . . . . . . . . .
11.5.3 Encrypting FTP . . . . . . . . . . .
11.5.4 Troubleshooting FTP . . . . . . . .
11.6 iSCSI . . . . . . . . . . . . . . . . . . . . .
11.7 LLDP . . . . . . . . . . . . . . . . . . . . .
11.8 NFS . . . . . . . . . . . . . . . . . . . . . .
11.9 Rsync . . . . . . . . . . . . . . . . . . . . .
11.9.1 Configure Rsyncd . . . . . . . . . .
11.9.2 Rsync Modules . . . . . . . . . . .
11.10S3 . . . . . . . . . . . . . . . . . . . . . . .
11.11S.M.A.R.T. . . . . . . . . . . . . . . . . . . .
11.12SMB . . . . . . . . . . . . . . . . . . . . . .
11.12.1 Troubleshooting SMB . . . . . . .
11.13SNMP . . . . . . . . . . . . . . . . . . . . .
11.14SSH . . . . . . . . . . . . . . . . . . . . . .
11.14.1 SCP Only . . . . . . . . . . . . . . .
11.14.2 Troubleshooting SSH . . . . . . . .
11.15TFTP . . . . . . . . . . . . . . . . . . . . . .
11.16UPS . . . . . . . . . . . . . . . . . . . . . .
11.16.1 Multiple Computers with One UPS
11.17WebDAV . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
210
210
212
214
214
216
216
217
220
221
222
223
223
223
224
225
226
226
228
229
230
234
236
237
239
239
240
241
244
244
12 Plugins
12.1 Installing Plugins
12.2 Updating Plugins
12.3 Uploading Plugins
12.4 Deleting Plugins .
12.5 Available Plugins
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
246
246
250
250
251
251
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13 Jails
13.1 Jails Configuration . . . . . . . . . .
13.2 Adding Jails . . . . . . . . . . . . . .
13.2.1 Managing Jails . . . . . . . .
Accessing a Jail Using SSH . .
Add Storage . . . . . . . . . .
13.2.2 Installing FreeBSD Packages
13.2.3 Compiling FreeBSD Ports .
13.2.4 Starting Installed Software
13.3 Managing Jail Templates . . . . . .
13.4 Using iocage . . . . . . . . . . . . .
13.4.1 Managing iocage Jails . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
253
254
255
258
259
260
262
264
266
268
270
270
14 VMs
272
14.1 Creating VMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
14.2 Adding Devices to a VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
14.3 Running VMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
15 Reporting
278
16 Wizard
280
17 Display System Processes
287
18 Shell
288
19 Log Out
290
20 Reboot
291
21 Shutdown
292
22 Support Icon
293
23 Guide
294
24 Alert
295
25 Support Resources
25.1 Website and Social Media
25.2 Forums . . . . . . . . . . .
25.3 IRC . . . . . . . . . . . . .
25.4 Mailing Lists . . . . . . . .
25.5 Videos . . . . . . . . . . .
25.6 Professional Support . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
297
297
297
299
300
300
301
26 Command Line Utilities
26.1 Iperf . . . . . . . . .
26.2 Netperf . . . . . . .
26.3 IOzone . . . . . . .
26.4 arcstat . . . . . . .
26.5 tw_cli . . . . . . . .
26.6 MegaCli . . . . . . .
26.7 freenas-debug . . .
26.8 tmux . . . . . . . .
26.9 Dmidecode . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
302
302
305
306
309
314
316
316
317
318
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
v
27 Contributing to FreeNAS®
319
27.1 Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
28 ZFS Primer
29 VAAI
29.1 VAAI for iSCSI
323
327
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
30 Using the API
328
30.1 A Simple API Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
30.2 A More Complex Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Index
vi
332
Welcome
This Guide covers the installation and use of FreeNAS® 11.0.
The FreeNAS® User Guide is a work in progress and relies on the contributions of many individuals. If you are interested in helping us to improve the Guide, read the instructions in the README
(https://github.com/freenas/freenas-docs/blob/master/README.md). IRC Freenode users are welcome to
join the #freenas channel where you will find other FreeNAS® users.
The FreeNAS® User Guide is freely available for sharing and redistribution under the terms of the Creative
Commons Attribution License (https://creativecommons.org/licenses/by/3.0/). This means that you have
permission to copy, distribute, translate, and adapt the work as long as you attribute iXsystems as the
original source of the Guide.
FreeNAS® and the FreeNAS® logo are registered trademarks of iXsystems.
Active Directory® is a registered trademark or trademark of Microsoft Corporation in the United States
and/or other countries.
Apple, Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries.
Avago is a trademark of Avago Technologies.
Broadcom is a trademark of Broadcom Corporation.
Chelsio® is a registered trademark of Chelsio Communications.
Cisco® is a registered trademark or trademark of Cisco Systems, Inc. and/or its affiliates in the United States
and certain other countries.
Django® is a registered trademark of Django Software Foundation.
Facebook® is a registered trademark of Facebook Inc.
FreeBSD® and the FreeBSD® logo are registered trademarks of the FreeBSD Foundation® .
Fusion-io is a trademark or registered trademark of Fusion-io, Inc.
Intel, the Intel logo, Pentium Inside, and Pentium are trademarks of Intel Corporation in the U.S. and/or
other countries.
LinkedIn® is a registered trademark of LinkedIn Corporation.
Linux® is a registered trademark of Linus Torvalds.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Twitter is a trademark of Twitter, Inc. in the United States and other countries.
UNIX® is a registered trademark of The Open Group.
VirtualBox® is a registered trademark of Oracle.
VMware® is a registered trademark of VMware, Inc.
Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit organization.
Windows® is a registered trademark of Microsoft Corporation in the United States and other countries.
1
Typographic Conventions
Typographic Conventions
The FreeNAS® 11.0 User Guide uses these typographic conventions:
Table 1: Text Format Examples
Item
Graphical elements: buttons, icons, fields, columns, and boxes
Menu selections
Commands
File names and volume and dataset names
Keyboard keys
Important points
Values entered into fields, or device names
2
Visual Example
Click the Import CA button.
Select System → Information.
Use the scp command.
Locate the /etc/rc.conf file.
Press the Enter key.
This is important.
Enter 127.0.0.1 in the address field.
CHAPTER
ONE
INTRODUCTION
FreeNAS® is an embedded open source network-attached storage (NAS) operating system based on
FreeBSD and released under a 2-clause BSD license (https://opensource.org/licenses/BSD-2-Clause). A NAS
has an operating system optimized for file storage and sharing.
FreeNAS® provides a browser-based, graphical configuration interface. The built-in networking protocols
provide storage access to multiple operating systems. A plugin system is provided for extending the built-in
features by installing additional software.
1.1 New Features in 11.0
• The base operating system has been updated to FreeBSD 11-STABLE. This brings in many significant
features (https://www.freebsd.org/releases/11.0R/relnotes.html), including important speed improvements for 40/100GigE networking.
• An updated version of ZFS includes new pool Feature Flags (http://open-zfs.org/wiki/Feature_Flags),
the skein and SHA512 hash functions.
• The Ports version of SSH has been updated to 7.4p1 to address CVE-2016-10012
(https://nvd.nist.gov/vuln/detail/CVE-2016-10012).
Please use the /usr/local/bin/ssh and
/usr/local/bin/sshd binaries.
• Python has been updated to version 3.6.1.
• The sas3flash firmware upgrade tool for LSI/Avago/Broadcom 9305-8i, 9305-16i, and 9305-24i host
adapters has been updated to the latest version.
• The Zerotier (https://www.zerotier.com/) distributed network hypervisor has been added.
• The mrsas(4) (https://www.freebsd.org/cgi/man.cgi?query=mrsas) driver is loaded by default for the Dell PERC H330, Dell PERC H730, and other controllers which are supported by both the mrsas(4) (https://www.freebsd.org/cgi/man.cgi?query=mrsas) and mfi(4)
(https://www.freebsd.org/cgi/man.cgi?query=mfi) drivers.
• Drivers for PMC Adaptec host bus adapters have been added with the pmspcv(4)
driver
(https://www.freebsd.org/cgi/man.cgi?query=pmspcv&manpath=FreeBSD+11.0RELEASE+and+Ports).
• The installer (page 13) can now be run through a serial port for systems without directly-connected
keyboards or monitors.
• The login dialog (page 45) now has a link to try a preliminary version of the new Angular-based
(https://angular.io/) GUI. Click on Demo our upcoming UI! to try it.
• An option to save the encryption seed has been added to the System (page 54) Save Config button.
3
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Email notices about available updates are only sent once instead of once per day.
• A new Alert Services (page 73) section in System → Alert Services makes it possible to send important alerts through external services, including AWS-SNS (https://aws.amazon.com/sns/), Hipchat
(https://www.hipchat.com/), InfluxDB (https://www.influxdata.com/), Slack (https://slack.com/),
Mattermost (https://about.mattermost.com/), OpsGenie (https://www.opsgenie.com/), PagerDuty
(https://www.pagerduty.com/), and VictorOps (https://victorops.com/).
• Encrypted volumes now use the AES-256 cipher.
• An experimental Active Directory (page 152) Enable Monitoring option has been added. When enabled,
this restarts the Active Directory service after a temporary loss of communications with an Active
Directory server. Previously, a loss of communications with the AD server would stop the Active Directory service, requiring a manual restart. At present, this experimental feature is recommended only
for testing in non-production environments. Please submit bug reports at https://bugs.freenas.org if
any problems are encountered.
• An enhanced Services (page 210) screen adds a checkbox to directly set which services start at boot.
• Plugin
and
jail
templates
have
been
updated
to
address
(https://www.freebsd.org/security/advisories/FreeBSD-SA-16:17.openssl.asc).
CVE-2016-2107
• A new VMs (page 272) (Virtual Machines) feature has been added.
Based on bhyve(8)
(https://www.freebsd.org/cgi/man.cgi?query=bhyve), it offers support for BSDs (FreeBSD, OpenBSD,
NetBSD), Linux (including CentOS, Debian, Fedora, OpenSUSE, Ubuntu), SmartOS, Windows, and Windows Server. Future versions will include additional features like VM templates, hardware passthrough, and UEFI screen resolution adjustment.
• Netatalk has been updated to version 3.1.11 (http://netatalk.sourceforge.net/3.1/ReleaseNotes3.1.11.html).
• Samba has been updated to version 4.6.5 (https://www.samba.org/samba/history/samba-4.6.5.html).
• The new S3 (page 228) service has been added, allowing the FreeNAS® system to provide S3 file sharing.
• The Mosh mobile shell (https://mosh.org/) has been added.
• Pipe Viewer, a utility for monitoring the progress of data through a pipeline
(http://www.ivarch.com/programs/pv.shtml), has been added. This can be useful for monitoring
zfs send | zfs recv commands.
• The Unison file synchronization tool (http://www.cis.upenn.edu/~bcpierce/unison/) has been added.
• The Alert (page 295) about mismatching driver and firmware versions for Avago disk controllers has
been removed as unnecessary. Driver and firmware versions no longer correspond.
1.2 Changes Since 11.0
FreeNAS® uses a “rolling release” model instead of point releases. The Update (page 69) mechanism makes
it easy to keep up-to-date with the latest security fixes, bug fixes, and new features. Some updates affect
the user interface, so this section lists any functional changes that have occurred since 11.0 was released.
Note: The screenshots in this documentation assume that the system has been fully updated to the latest
STABLE version of FreeNAS® 11.0-U4. If a screen on the system is not the same as shown in this guide, make
sure that all updates have been applied.
4
Chapter 1. Introduction
FreeNAS® 11.0-U4 User Guide, Release 11.0
1.2.1 U1
• The Read only
Templates.
checkbox has been removed from Jails → Templates → Add Jail
• The NT4 option has been removed from Directory Services (page 152) as it is no longer supported by
Samba.
1.2.2 U2
• Samba
has
been
patched
to
bin/cvename.cgi?name=CVE-2017-11103).
address
CVE-2017-11103
(https://cve.mitre.org/cgi-
• The
system
has
been
patched
to
address
FreeBSD-SA-17:05.heimdal
(https://www.freebsd.org/security/advisories/FreeBSD-SA-17:05.heimdal.asc).
• The Active Directory (page 152) Enable Monitoring option is no longer considered experimental.
1.2.3 U3
• The boot volume Automatic scrub interval (page 58) has been changed to 7 days for earlier detection
of problems with boot devices.
1.2.4 U4
• The
system
has
been
patched
to
address
FreeBSD-SA-17:06.openssh.asc
(https://www.freebsd.org/security/advisories/FreeBSD-SA-17:06.openssh.asc).
• Samba has been updated to 4.6.8 (https://www.samba.org/samba/history/samba-4.6.8.html) to address the most recent CVEs.
1.3 Path and Name Lengths
Names of files, directories, and devices are subject to some limits imposed by the FreeBSD operating system. The limits shown here are for names using plain-text characters that each occupy one byte of space.
Some UTF-8 characters take more than a single byte of space, and using those characters reduces these
limits proportionally. System overhead can also reduce the length of these limits by one or more bytes.
1.3. Path and Name Lengths
5
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 1.1: Path and Name Lengths
Type
File Paths
File and Directory
Names
Mounted Filesystem
Paths
Device Filesystem Paths
Maximum
Length
1024
bytes
255 bytes
88 bytes
63 bytes
Description
Total file path length (PATH_MAX). The full path includes directory separator slash characters, subdirectory names,
and the name of the file itself. For example, the path
/mnt/tank/mydataset/mydirectory/myfile.txt is 42
bytes long.
Using very long file or directory names can be problematic. A
complete path with long directory and file names can exceed
the 1024-byte limit, preventing direct access to that file until the
directory names or filename are shortened or the file is moved
into a directory with a shorter total path length.
Individual directory or file name length (NAME_MAX).
Mounted filesystem path length (MNAMELEN). Longer paths can
prevent a device from being mounted.
devfs(8) (https://www.freebsd.org/cgi/man.cgi?query=devfs&sektion=8)
device path lengths (SPECNAMELEN). Longer paths can prevent a
device from being created.
1.4 Hardware Recommendations
FreeNAS® 11.0 is based on FreeBSD 11 and supports the same hardware found in the FreeBSD Hardware Compatibility List (http://www.freebsd.org/releases/11.0R/hardware.html). Supported processors are
listed in section 2.1 amd64 (https://www.freebsd.org/releases/11.0R/hardware.html#proc). FreeNAS® is
only available for 64-bit processors. This architecture is called amd64 by AMD and Intel 64 by Intel.
Note: FreeNAS® boots from a GPT partition. This means that the system BIOS must be able to boot using
either the legacy BIOS firmware interface or EFI.
Actual hardware requirements vary depending on the usage of the FreeNAS® system.
This section provides some starter guidelines.
The FreeNAS® Hardware Forum
(https://forums.freenas.org/index.php?forums/hardware.18/) has performance tips from FreeNAS® users
and is a place to post questions regarding the hardware best suited to meet specific requirements. Hardware Recommendations (https://forums.freenas.org/index.php?resources/hardware-recommendationsguide.12/) gives detailed recommendations for system components, with the FreeNAS® Quick Hardware
Guide (https://forums.freenas.org/index.php?resources/freenas-quick-hardware-guide.7) providing short
lists of components for various configurations. Building, Burn-In, and Testing your FreeNAS® system
(https://forums.freenas.org/index.php?threads/building-burn-in-and-testing-your-freenas-system.17750/)
has detailed instructions on testing new hardware.
1.4.1 RAM
The best way to get the most out of a FreeNAS® system is to install as much RAM as possible. The recommended minimum is 8 GB of RAM. The more RAM, the better the performance, and the FreeNAS® Forums
(https://forums.freenas.org/index.php) provide anecdotal evidence from users on how much performance
is gained by adding more RAM.
6
Chapter 1. Introduction
FreeNAS® 11.0-U4 User Guide, Release 11.0
Depending upon the use case, your system may require more RAM. Here are some general rules of thumb:
• To use Active Directory with many users, add an additional 2 GB of RAM for winbind’s internal cache.
• For iSCSI, install at least 16 GB of RAM if performance is not critical, or at least 32 GB of RAM if good
performance is a requirement.
• When installing FreeNAS® on a headless system, disable the shared memory settings for the video
card in the BIOS.
• To use ZFS deduplication, ensure the system has at least 5 GB of RAM per TB of storage to be deduplicated.
If the hardware supports it and the budget allows for it, install ECC RAM. While more expensive,
ECC RAM is highly recommended as it prevents in-flight corruption of data before the error-correcting
properties of ZFS come into play, thus providing consistency for the checksumming and parity calculations performed by ZFS. If you consider your data important, use ECC RAM. This Case Study
(http://research.cs.wisc.edu/adsl/Publications/zfs-corruption-fast10.pdf) describes the risks associated with
memory corruption.
Unless the system has at least 8 GB of RAM, consider adding RAM before using FreeNAS® to store data.
Many users expect FreeNAS® to function with less memory, just at reduced performance. The bottom line
is that these minimums are based on feedback from many users. Requests for help in the forums or IRC are
sometimes ignored when the installed system does not have at least 8 GB of RAM because of the abundance
of information that FreeNAS® may not behave properly with less memory.
1.4.2 The Operating System Device
The FreeNAS® operating system is installed to at least one device that is separate from the storage disks.
The device can be a USB stick, SSD, compact flash, or DOM (Disk on Module). Installation to a hard drive is
discouraged as that drive is then not available for data storage.
Note: To write the installation file to a USB stick, two USB ports are needed, each with an inserted USB
device. One USB stick contains the installer. The other USB stick is the destination for the FreeNAS® installation. Take care to select the correct USB device for the FreeNAS® installation. It is not possible to install
FreeNAS® onto the same USB stick containing the installer. After installation, remove the installer USB stick.
It might also be necessary to adjust the BIOS configuration to boot from the new FreeNAS® USB stick.
When determining the type and size of the target device where FreeNAS® will be installed, keep these points
in mind:
• the bare minimum size is 8 GB. This provides room for the operating system and several boot environments. Since each update creates a boot environment, this is the recommended minimum. 32 GB
provides room for more boot environments.
• if you plan to make your own boot environments, budget about 1 GB of storage per boot environment. Consider deleting older boot environments after making sure they are no longer needed. Boot
environments can be created and deleted using System → Boot.
• use quality, name-brand USB sticks, as ZFS will quickly reveal errors on cheap, poorly-made sticks.
• for a more reliable boot disk, use two identical devices and select them both during the installation.
This will create a mirrored boot device.
1.4. Hardware Recommendations
7
FreeNAS® 11.0-U4 User Guide, Release 11.0
1.4.3 Storage Disks and Controllers
The Disk section (http://www.freebsd.org/releases/11.0R/hardware.html#DISK) of the FreeBSD Hardware
List lists the supported disk controllers. In addition, support for 3ware 6 Gbps RAID controllers has been
added along with the CLI utility tw_cli for managing 3ware RAID controllers.
FreeNAS® supports hot pluggable drives. Using this feature requires enabling AHCI in the BIOS.
Reliable disk alerting and immediate reporting of a failed drive can be obtained by using an HBA such as an
Avago MegaRAID controller or a 3Ware twa-compatible controller.
Note: Upgrading the firmware of Avago SAS HBAs to the latest version is recommended.
Some Highpoint RAID controllers do not support pass-through of S.M.A.R.T. data or other disk information,
potentially including disk serial numbers. It is best to use a different disk controller with FreeNAS® .
Note: The system is configured to prefer the mrsas(4) (https://www.freebsd.org/cgi/man.cgi?query=mrsas)
driver for controller cards like the Dell PERC H330 and H730 which are supported by several drivers. Although not recommended, the mfi(4) (https://www.freebsd.org/cgi/man.cgi?query=mfi) driver can be used
instead by removing the loader Tunable (page 67): hw.mfi.mrsas_enable or setting the Value to 0.
Suggestions for testing disks before adding them to a RAID array can be found in this forum post
(https://forums.freenas.org/index.php?threads/checking-new-hdds-in-raid.12082/#post-55936). Additionally, badblocks (https://linux.die.net/man/8/badblocks) is installed with FreeNAS® for testing disks.
If the budget allows optimization of the disk subsystem, consider the read/write needs and RAID requirements:
• For steady, non-contiguous writes, use disks with low seek times. Examples are 10K or 15K SAS drives
which cost about $1/GB. An example configuration would be six 600 GB 15K SAS drives in a RAID 10
which would yield 1.8 TB of usable space, or eight 600 GB 15K SAS drives in a RAID 10 which would
yield 2.4 TB of usable space.
When high performance is a key requirement and budget permits, consider a Fusion-I/O card
(http://www.fusionio.com/products/) which is optimized for massive random access. These cards are expensive and are suited for high-end systems that demand performance. A Fusion-I/O card can be formatted
with a filesystem and used as direct storage; when used this way, it does not have the write issues typically
associated with a flash device. A Fusion-I/O card can also be used as a cache device when your ZFS dataset
size is bigger than your RAM. Due to the increased throughput, systems running these cards typically use
multiple 10 GigE network interfaces.
For ZFS, Disk Space Requirements for ZFS Storage Pools (http://docs.oracle.com/cd/E19253-01/8195461/6n7ht6r12/index.html) recommends a minimum of 16 GB of disk space. Due to the way that ZFS
creates swap, it is not possible to format less than 3 GB of space with ZFS. However, on a drive that is
below the minimum recommended size, a fair amount of storage space is lost to swap: for example, on a 4
GB drive, 2 GB will be reserved for swap.
Users new to ZFS who are purchasing hardware should read through ZFS Storage Pools Recommendations
(https://web.archive.org/web/20161028084224/http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide#
first.
ZFS vdevs, groups of disks that act like a single device, can be created using disks of different sizes. However,
the capacity available on each disk is limited to the same capacity as the smallest disk in the group. For
example, a vdev with one 2 TB and two 4 TB disks will only be able to use 2 TB of space on each disk. In
general, use disks that are the same size for the best space usage and performance.
8
Chapter 1. Introduction
FreeNAS® 11.0-U4 User Guide, Release 11.0
The ZFS Drive Size and Cost Comparison spreadsheet (https://forums.freenas.org/index.php?threads/zfsdrive-size-and-cost-comparison-spreadsheet.38092/) is available to compare usable space provided by different quantities and sizes of disks.
1.4.4 Network Interfaces
The Ethernet section (http://www.freebsd.org/releases/11.0R/hardware.html#ethernet) of the FreeBSD
Hardware Notes indicates which interfaces are supported by each driver. While many interfaces are supported, FreeNAS® users have seen the best performance from Intel and Chelsio interfaces, so consider
these brands when purchasing a new NIC. Realtek cards often perform poorly under CPU load as interfaces
with these chipsets do not provide their own processors.
At a minimum, a GigE interface is recommended. While GigE interfaces and switches are affordable for
home use, modern disks can easily saturate their 110 MB/s throughput. For higher network throughput,
multiple GigE cards can be bonded together using the LACP type of Link Aggregations (page 100). The Ethernet switch must support LACP, which means a more expensive managed switch is required.
When network performance is a requirement and there is some money to spend, use 10 GigE interfaces and a managed switch. Managed switches with support for LACP and jumbo frames are preferred, as both can be used to increase network throughput. Refer to the 10 Gig Networking Primer
(https://forums.freenas.org/index.php?threads/10-gig-networking-primer.25749/) for more information.
Note: At present, these are not supported: InfiniBand, FibreChannel over Ethernet, or wireless interfaces.
Both hardware and the type of shares can affect network performance.
On the
same hardware, SMB is slower than FTP or NFS because Samba is single-threaded
(https://www.samba.org/samba/docs/man/Samba-Developers-Guide/architecture.html). So a fast CPU
can help with SMB performance.
Wake on LAN (WOL) support depends on the FreeBSD driver for the interface. If the driver supports WOL, it
can be enabled using ifconfig(8) (http://www.freebsd.org/cgi/man.cgi?query=ifconfig). To determine if WOL
is supported on a particular interface, use the interface name with the following command. In this example,
the capabilities line indicates that WOL is supported for the re0 interface:
ifconfig -m re0
re0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> metric 0 mtu 1500
options=42098<VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,WOL_MAGIC,VLAN_HWTSO>
capabilities=5399b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4,WOL_
˓→UCAST,WOL_MCAST, WOL_MAGIC,VLAN_HWFILTER,VLAN_H WTSO>
If WOL support is shown but not working for a particular interface, create a bug report using the instructions
in Support (page 80).
1.5 Getting Started with ZFS
Readers new to ZFS should take a moment to read the ZFS Primer (page 323).
1.5. Getting Started with ZFS
9
CHAPTER
TWO
INSTALLING AND UPGRADING
Please note that the FreeNAS® operating system must be installed on a separate device from the drives
which hold the storage data. In other words, with only one disk drive, the FreeNAS® graphical interface is
available, but there is no place to store any data. And storing data is, after all, the whole point of a NAS
system. Home users experimenting with FreeNAS® can install FreeNAS® on an inexpensive USB thumb
drive and use the computer’s disks for storage.
This section describes:
• Getting FreeNAS® (page 10)
• Preparing the Media (page 11)
• Performing the Installation (page 13)
• Installation Troubleshooting (page 19)
• Upgrading (page 20)
• Virtualization (page 27)
2.1 Getting FreeNAS®
The latest STABLE version of FreeNAS® 11.0 can be downloaded from http://download.freenas.org/11/
latest/x64/. Release notes and other information is at http://download.freenas.org/11/latest/.
Note: FreeNAS® requires 64-bit hardware.
The download page contains these types of files:
• .iso: this is a bootable installer that can be written to either a CD or USB flash as described in Preparing
the Media (page 11).
• .GUI_Upgrade.txz: this is a compressed firmware upgrade image. To upgrade FreeNAS® , download
this file and see the section on Upgrading (page 20).
Each file has an associated sha256.txt file which should be used to verify the integrity of the downloaded
file. The command to verify the checksum varies by operating system:
• on a BSD system use the command sha256 name_of_file
• on a Linux system use the command sha256sum name_of_file
• on a Mac system use the command shasum -a 256 name_of_file
10
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Windows
or
Mac
users
can
install
additional
utilities
like
HashCalc
(http://www.slavasoft.com/hashcalc/) or HashTab (http://implbits.com/products/hashtab/)
The value produced by running the command must match the value shown in the sha256.txt file. Checksum values that do not match indicate a corrupted installer file that should not be used.
2.2 Preparing the Media
The FreeNAS® installer can run from either a CD or a USB memory stick.
A CD burning utility is needed to write the .iso file to a CD.
The .iso file can also be written to a USB memory stick or Compact Flash card. The method used to write
the file depends on the operating system. Examples for several common operating systems are shown
below.
Note: To install from a USB stick to another USB stick, two USB ports are needed, each with an inserted
USB device. One USB stick contains the installer. The other USB stick is the destination for the FreeNAS®
installation. Take care to select the correct USB device for the FreeNAS® installation. It is not possible to
install FreeNAS® onto the same USB stick containing the installer. After installation, remove the installer
USB stick. It might also be necessary to adjust the BIOS configuration to boot from the new FreeNAS® USB
stick.
Make sure that the boot device order in the BIOS is set to boot from the device containing the FreeNAS®
installer media, then boot the system to start the installation.
2.2.1 On FreeBSD or Linux
On a FreeBSD or Linux system, the dd command can be used to write the .iso file to an inserted USB
thumb drive or Compact Flash device. Example: Writing the .iso file to a USB Thumb Drive (page ??) demonstrates writing the image to the first USB device (/dev/da0) on a FreeBSD system. Substitute the filename of
the .iso file and the device name representing the device to write to on your system.
Warning: The dd command is very powerful and can destroy any existing data on the specified device.
Make absolutely sure of the device name to write to and do not mistype the device name when using
dd! If you are uncomfortable using this command, write the .iso file to a CD instead.
Writing the .iso file to a USB Thumb Drive
dd if=FreeNAS-9.10-RELEASE-x64.iso of=/dev/da0 bs=64k
6117+0 records in
6117+0 records out
400883712 bytes transferred in 88.706398 secs (4519220 bytes/sec)
When using the dd command:
• if= refers to the input file, or the name of the file to write to the device.
• of= refers to the output file; in this case, the device name of the flash card or removable USB drive.
Note that USB device numbers are dynamic, and the target device might be da1 or da2 or another
2.2. Preparing the Media
11
FreeNAS® 11.0-U4 User Guide, Release 11.0
name depending on which devices are attached. Before attaching the target USB drive, use ls
/dev/da*. Then attach the target USB drive, wait ten seconds, and run ls /dev/da* again to
see the new device name and number of the target USB drive. On Linux, use /dev/sdX , where X
refers to the letter of the USB device.
• bs= refers to the block size, the amount of data to write at a time. The larger 64K block size shown
here helps speed up writes to the USB drive.
2.2.2 On Windows
Microsoft provides the USB/DVD Download Tool to create a USB bootable image from an .iso file. Follow these instructions (https://www.microsoft.com/en-us/download/windows-usb-dvd-download-tool), but
enter the name of the downloaded .iso into the SOURCE FILE box.
Image Writer (https://launchpad.net/win32-image-writer/) and Rufus (http://rufus.akeo.ie/) are alternate
programs for writing images to USB sticks on a computer running Windows.
2.2.3 On OS X
Insert the USB thumb drive. In the Finder, go to Applications → Utilities → Disk Utility.
Unmount any mounted partitions on the USB thumb drive. Check that the USB thumb drive has only one
partition, or partition table errors will be shown on boot. If needed, use Disk Utility to set up one partition
on the USB drive. Selecting Free space when creating the partition works fine.
Determine the device name of the inserted USB thumb drive. From TERMINAL, navigate to the Desktop,
then type this command:
diskutil list
/dev/disk0
#:
0:
1:
2:
3:
TYPE NAME
GUID_partition_scheme
EFI
Apple_HFS Macintosh HD
Apple_Boot Recovery HD
/dev/disk1
#:
TYPE NAME
0:
FDisk_partition_scheme
1:
DOS_FAT_32 UNTITLED
SIZE
*500.1 GB
209.7 MB
499.2 GB
650.0 MB
IDENTIFIER
disk0
disk0s1
disk0s2
disk0s3
SIZE
*8.0 GB
8.0 GB
IDENTIFIER
disk1
disk1s1
This shows which devices are available to the system. Locate the target USB stick and record the path. If you
are not sure which path is the correct one for the USB stick, remove the device, run the command again, and
compare the difference. Once sure of the device name, navigate to the Desktop from TERMINAL, unmount
the USB stick, and use the dd command to write the image to the USB stick. In Example: Using dd on an OS
X System (page ??), the USB thumb drive is /dev/disk1, which is first unmounted. The dd command uses
/dev/rdisk1 (note the extra r) to write to the raw device, which is faster. When running these commands,
substitute the name of the installation file and the correct path to the USB thumb drive.
Example: Using dd on an OS X System
diskutil unmountDisk /dev/disk1
Unmount of all volumes on disk1 was successful
dd if=FreeNAS-9.10-RELEASE-x64.iso of=/dev/rdisk1 bs=64k
12
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
If the error “Resource busy” is shown when the dd command is run, go to Applications →
Utilities → Disk Utility, find the USB thumb drive, and click on its partitions to make sure all
of them are unmounted. If the error “dd: /dev/disk1: Permission denied” is shown, run the dd command by typing sudo dd if=FreeNAS-9.10-RELEASE-x64.iso of=/dev/rdisk1 bs=64k. This
will prompt for your password.
Note:
The dd command can take some minutes to complete. Wait until the prompt returns and a message is
displayed with information about how long it took to write the image to the USB drive.
2.3 Performing the Installation
With the installation media inserted, boot the system from that media. The FreeNAS® installer GRUB menu
is displayed as is shown in Figure 2.1.
Fig. 2.1: Grub Menu
Tip: The Serial Enabled option is useful on systems which do not have a keyboard or monitor, but are
accessed through a serial port, Serial over LAN, or IPMI (page 98).
Note: If the installer does not boot, verify that the installation device is listed first in the boot order in the
BIOS. When booting from a CD, some motherboards may require connecting the CD device to SATA0 (the
first connector) to boot from CD. If the installer stalls during bootup, double-check the SHA256 hash of the
2.3. Performing the Installation
13
FreeNAS® 11.0-U4 User Guide, Release 11.0
.iso file. If the hash does not match, re-download the file. If the hash is correct, burn the CD again at a
lower speed or write the file to a different USB stick.
The installer will start automatically after a few seconds, or an option can be chosen by moving the highlight
bar to it with the up and down arrow keys and pressing Enter. After booting, the console setup menu is
displayed as shown in Figure 2.2.
Fig. 2.2: Console Setup
Press Enter to select the default option, 1 Install/Upgrade. The next menu, shown in Figure 2.3, lists all
available drives. This includes any inserted USB thumb drives, which have names beginning with da.
In this example, the user is performing a test installation using VirtualBox and has created a 16 GB virtual
disk to hold the operating system.
14
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.3: Selecting the Install Drive
Use the arrow keys to highlight the destination USB drive, SSD, DOM (Disk on Module), Compact Flash
device, or virtual disk. Press the spacebar to select it. To mirror the boot device, move to the second
device and press spacebar to select it also. After making these selections, press Enter. The warning
shown in Figure 2.4 is displayed, a reminder not to install the operating system on a drive that is meant for
storage. Press Enter to continue on to the screen shown in Figure 2.6.
2.3. Performing the Installation
15
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.4: Installation Warning
Note: A minimum of 8 GB of space on the boot device is required. However, 32 GB is recommended to
provide room for future additions and boot environments. When using mirrored boot devices, it is best to
use devices of the same size. If the device sizes are different, the mirror is limited to the size of the smaller
device.
The installer recognizes existing installations of previous versions of FreeNAS® 8.x or 9.x. When an existing
installation is present, the menu shown in Figure 2.5 is displayed. To overwrite an existing installation, use
the arrows to move to Fresh Install and press Enter twice to continue to the screen shown in Figure 2.6.
16
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.5: Performing a Fresh Install
The screen shown in Figure 2.6 prompts for the root password which is used to log in to the administrative
graphical interface.
Fig. 2.6: Set the Root Password
2.3. Performing the Installation
17
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting a password is mandatory and the password cannot be blank. Since this password provides access
to the administrative GUI, it should be hard to guess. Enter the password, press the down arrow key, and
confirm the password. Then press Enter to continue with the installation.
Note: For security reasons, the SSH service and root SSH logins are disabled by default. Unless these are
set, the only way to access a shell as root is to gain physical access to the console menu or to access the web
shell within the administrative GUI. This means that the FreeNAS® system should be kept physically secure
and that the administrative GUI should be behind a properly configured firewall and protected by a secure
password.
FreeNAS® can be configured to boot with the standard BIOS boot mechanism or UEFI booting as shown
Figure 2.7. BIOS booting is recommended for legacy and enterprise hardware. UEFI is used on newer
consumer motherboards.
Fig. 2.7: Choose UEFI or BIOS Booting
Note: Most UEFI systems can also boot in BIOS mode if CSM (Compatibility Support Module) is enabled in
the UEFI setup screens.
The message in Figure 2.8 is shown after the installation is complete.
18
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.8: Installation Complete
Press Enter to return to the first menu, shown in Figure 2.1. Highlight 3 Reboot System and press Enter. If
booting from CD, remove the CDROM. As the system reboots, make sure that the device where FreeNAS®
was installed is listed as the first boot entry in the BIOS so the system will boot from it. FreeNAS® boots into
the Console Setup menu described in Booting (page 43).
2.4 Installation Troubleshooting
If the system does not boot into FreeNAS® , there are several things that can be checked to resolve the
situation.
Check the system BIOS and see if there is an option to change the USB emulation from CD/DVD/floppy to
hard drive. If it still will not boot, check to see if the card/drive is UDMA compliant.
If the system BIOS does not support EFI with BIOS emulation, see if it has an option to boot using legacy
BIOS mode.
When the system starts to boot but hangs with this repeated error message:
run_interrupt_driven_hooks: still waiting after 60 seconds for xpt_config
go into the system BIOS and look for an onboard device configuration for a 1394 Controller. If present,
disable that device and try booting again.
If the system starts to boot but hangs at a mountroot> prompt, follow the instructions in Workaround/SemiFix for Mountroot Issues with 9.3 (https://forums.freenas.org/index.php?threads/workaround-semi-fix-formountroot-issues-with-9-3.26071/).
If the burned image fails to boot and the image was burned using a Windows system, wipe the USB stick
before trying a second burn using a utility such as Active@ KillDisk (http://how-to-erase-hard-drive.com/).
2.4. Installation Troubleshooting
19
FreeNAS® 11.0-U4 User Guide, Release 11.0
Otherwise, the second burn attempt will fail as Windows does not understand the partition which was
written from the image file. Be very careful to specify the correct USB stick when using a wipe utility!
2.5 Upgrading
FreeNAS® provides flexibility for keeping the operating system up-to-date:
1. Upgrades to major releases, for example from version 9.3 to 9.10, can still be performed using either
an ISO or the graphical administrative interface. Unless the Release Notes for the new major release
indicate that the current version requires an ISO upgrade, either upgrade method can be used.
2. Minor releases have been replaced with signed updates. This means that it is not necessary to wait for
a minor release to update the system with a system update or newer versions of drivers and features.
It is also no longer necessary to manually download an upgrade file and its associated checksum to
update the system.
3. The updater automatically creates a boot environment, making updates a low-risk operation. Boot environments provide the option to return to the previous version of the operating system by rebooting
the system and selecting the previous boot environment from the boot menu.
This section describes how to perform an upgrade from an earlier version of FreeNAS® to 11.0. After 11.0
has been installed, use the instructions in Update (page 69) to keep the system updated.
2.5.1 Caveats
Be aware of these caveats before attempting an upgrade to 11.0:
• Warning: upgrading the ZFS pool can make it impossible to go back to a previous version.
For this reason, the update process does not automatically upgrade the ZFS pool, though the Alert
(page 295) system shows when newer feature flags are available for a pool. Unless a new feature flag
is needed, it is safe to leave the pool at the current version and uncheck the alert. If the pool is upgraded, it will not be possible to boot into a previous version that does not support the newer feature
flags.
• The Wizard (page 280) does not recognize an encrypted ZFS pool. If the ZFS pool is GELI-encrypted and
the Wizard (page 280) starts after the upgrade, cancel the Wizard (page 280) and use the instructions
in Importing an Encrypted Pool (page 122) to import the encrypted volume. The Wizard (page 280) can
be run afterward for post-configuration. It will then recognize that the volume has been imported and
not prompt to reformat the disks.
• Upgrading the firmware of Avago SAS HBAs to the latest version is recommended.
• If upgrading from 9.3.x,
please read the FAQ: Updating from 9.3 to
(https://forums.freenas.org/index.php?threads/faq-updating-from-9-3-to-9-10.54260/) first.
9.10
• Upgrades from FreeNAS® 0.7x are not supported. The system has no way to import configuration
settings from 0.7x versions of FreeNAS® . The configuration must be manually recreated. If supported,
the FreeNAS® 0.7x volumes or disks must be manually imported.
• Upgrades on 32-bit hardware are not supported. However, if the system is currently running a 32bit version of FreeNAS® and the hardware supports 64-bit, the system can be upgraded. Any archived
reporting graphs will be lost during the upgrade.
• UFS is no longer supported. If your data currently resides on one UFS-formatted disk, create a ZFS
volume using other disks after the upgrade, then use the instructions in Import Disk (page 120) to
mount the UFS-formatted disk and copy the data to the ZFS volume. With only one disk, back up its
data to another system or media before the upgrade, format the disk as ZFS after the upgrade, then
20
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
restore the backup. If the data currently resides on a UFS RAID of disks, it is not possible to directly
import that data to the ZFS volume. Instead, back up the data before the upgrade, create a ZFS volume
after the upgrade, then restore the data from the backup.
• The VMware Tools VMXNET3 drivers are no longer supported. Configure and use the vmx(4)
(https://www.freebsd.org/cgi/man.cgi?query=vmx) driver instead.
2.5.2 Initial Preparation
Before upgrading the operating system, perform the following steps:
1. Back up the FreeNAS® configuration in System → General → Save Config.
2. If any volumes are encrypted, make sure that you have set the passphrase and have a copy of the
encryption key and the latest recovery key. After the upgrade is complete, use the instructions in
Importing an Encrypted Pool (page 122) to import the encrypted volume.
3. Warn users that the FreeNAS® shares will be unavailable during the upgrade; you should schedule the
upgrade for a time that will least impact users.
4. Stop all services in Services → Control Services.
2.5.3 Upgrading Using the ISO
To perform an upgrade using this method, download (http://download.freenas.org/latest/) the .iso to the
computer that will be used to prepare the installation media. Burn the downloaded .iso file to a CD or
USB thumb drive using the instructions in Preparing the Media (page 11).
Insert the prepared media into the system and boot from it. After the media finishes booting into the
installation menu, press Enter to select the default option of 1 Install/Upgrade. The installer presents a
screen showing all available drives.
Warning: All drives are shown, including boot drives and storage drives. Only choose boot drives when
upgrading. Choosing the wrong drives to upgrade or install will cause loss of data. If unsure about which
drives contain the FreeNAS® operating system, reboot and remove the install media. In the FreeNAS®
GUI, use System → Boot to identify the boot drives. More than one drive is shown when a mirror has
been used.
Move to the drive where FreeNAS® is installed and press the Spacebar to mark it with a star. If a mirror
has been used for the operating system, mark all of the drives where the FreeNAS® operating system is
installed. Press Enter when done.
The installer recognizes earlier versions of FreeNAS® installed on the boot drive or drives and presents the
message shown in Figure 2.9.
2.5. Upgrading
21
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.9: Upgrading a FreeNAS® Installation
Note: If you choose a Fresh Install, the backup of your configuration data must be restored using System
→ General → Upload Config after booting into the new operating system.
To perform an upgrade, press Enter to accept the default of Upgrade Install. Again, the installer will remind
you that the operating system should be installed on a disk that is not used for storage.
22
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.10: Install in New Boot Environment or Format
The updated system can be installed in a new boot environment, or the entire boot device can be formatted
to start fresh. Installing into a new boot environment preserves the old code, allowing a roll-back to previous
versions if necessary. Formatting the boot device is usually not necessary but can reclaim space. User data
and settings are preserved when installing to a new boot environment and also when formatting the boot
device. Move the highlight to one of the options and press Enter to start the upgrade.
The installer unpacks the new image and displays the menu shown in Figure 2.11. The database file that is
preserved and migrated contains your FreeNAS® configuration settings.
2.5. Upgrading
23
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.11: Preserve and Migrate Settings
Press Enter. FreeNAS® indicates that the upgrade is complete and a reboot is required. Press OK, highlight
3 Reboot System, then press Enter to reboot the system. If the upgrade installer was booted from CD,
remove the CD.
During the reboot there may be a conversion of the previous configuration database to the new version of
the database. This happens during the “Applying database schema changes” line in the reboot cycle. This
conversion can take a long time to finish, sometimes fifteen minutes or more, and might have to reboot the
system again afterwards. Please be patient and the system will start normally. If database errors are shown
but the graphical administrative interface is accessible, go to Settings → General and use the Upload
Config button to upload the configuration that you saved before starting the upgrade.
2.5.4 Upgrading From the GUI
To perform an upgrade using this method, go to System → Update.
After the update is complete, you will temporarily lose your connection as the FreeNAS® system reboots into
the new version of the operating system. The FreeNAS® system will normally receive the same IP address
from the DHCP server. Refresh your browser after a moment to see if you can access the system.
2.5.5 If Something Goes Wrong
If an update fails, an alert is issued and the details are written to /data/update.failed.
To return to a previous version of the operating system, physical or IPMI access to the FreeNAS® console
is needed. Reboot the system and watch for the boot menu. In the example shown in Figure 2.12, the
first boot menu entry, FreeNAS (default), refers to the initial installation, before the update was applied.
The second boot entry, FreeNAS-1415259326, refers to the current version of the operating system, after
the update was applied. This second entry is highlighted and begins with a star, indicating that this is the
24
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
environment the system will boot unless another entry is manually selected. Both entries include a date
and timestamp showing when that boot environment was created.
Fig. 2.12: Boot Menu
To boot into the previous version of the operating system, use the up or down arrow to select it and press
Enter.
If a boot device fails and the system no longer boots, don’t panic. The data is still on the disks and there is
still a copy of the saved configuration. The system can be recovered with a few steps:
1. Perform a fresh installation on a new boot device.
2. Import the volumes in Storage → Auto Import Volume.
3. Restore the configuration in System → General → Upload Config.
Note: It is not possible to restore a saved configuration that is newer than the installed version. For
example, if you reboot into an older version of the operating system, you cannot restore a configuration
that was created in a later version.
2.5.6 Upgrading a ZFS Pool
In FreeNAS® , ZFS pools can be upgraded from the graphical administrative interface.
Before upgrading an existing ZFS pool, be aware of these caveats first:
2.5. Upgrading
25
FreeNAS® 11.0-U4 User Guide, Release 11.0
• the pool upgrade is a one-way street, meaning that if you change your mind you cannot go back to
an earlier ZFS version or downgrade to an earlier version of the software that does not support
those feature flags.
• before performing any operation that may affect the data on a storage disk, always back up all data
first and verify the integrity of the backup. While it is unlikely that the pool upgrade will affect the
data, it is always better to be safe than sorry.
• upgrading a ZFS pool is optional. Do not upgrade the pool if the the possibility of reverting to an
earlier version of FreeNAS® or repurposing the disks in another operating system that supports ZFS
is desired. It is not necessary to upgrade the pool unless newer ZFS feature flags are required. If a
pool is upgraded to the latest feature flags, it will not be possible to import that pool into another
operating system that does not yet support those feature flags.
To perform the ZFS pool upgrade, go to Storage → Volumes → View Volumes and highlight the volume (ZFS pool) to upgrade. Click the Upgrade button as shown in Figure 2.13.
Note: If the Upgrade button does not appear, the pool is already at the latest feature flags and does not
need to be upgraded.
Fig. 2.13: Upgrading a ZFS Pool
The warning serves as a reminder that a pool upgrade is not reversible. Click OK to proceed with the
upgrade.
The upgrade itself only takes a few seconds and is non-disruptive. It is not necessary to stop any sharing
services to upgrade the pool. However, it is best to upgrade when the pool is not being heavily used. The
upgrade process will suspend I/O for a short period, but is nearly instantaneous on a quiet pool.
26
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
2.6 Virtualization
FreeNAS® can be run inside a virtual environment for development, experimentation, and educational purposes. Please note that running FreeNAS® in production as a virtual machine is not recommended (https://forums.freenas.org/index.php?threads/please-do-not-run-freenas-in-production-as-avirtual-machine.12484/).
If you decide to use FreeNAS® within a virtual environment, read this
post first (https://forums.freenas.org/index.php?threads/absolutely-must-virtualize-freenas-a-guide-to-notcompletely-losing-your-data.12714/) as it contains useful guidelines for minimizing the risk of losing data.
To install or run FreeNAS® within a virtual environment, create a virtual machine that meets these minimum
requirements:
• at least 8192 MB (8 GB) base memory size
• a virtual disk at least 8 GB in size to hold the operating system and boot environments
• at least one additional virtual disk at least 4 GB in size to be used as data storage
• a bridged network adapter
This section demonstrates how to create and access a virtual machine within VirtualBox and VMware ESXi
environments.
2.6.1 VirtualBox
VirtualBox (https://www.virtualbox.org/) is an open source virtualization program originally created by Sun
Microsystems. VirtualBox runs on Windows, BSD, Linux, Macintosh, and OpenSolaris. It can be configured to
use a downloaded FreeNAS® .iso file, and makes a good testing environment for practicing configurations
or learning how to use the features provided by FreeNAS® .
To create the virtual machine, start VirtualBox and click the New button, shown in Figure 2.14, to start the
new virtual machine wizard.
Fig. 2.14: Initial VirtualBox Screen
2.6. Virtualization
27
FreeNAS® 11.0-U4 User Guide, Release 11.0
Click the Next button to see the screen in Figure 2.15. Enter a name for the virtual machine, click the
Operating System drop-down menu and select BSD, and select FreeBSD (64-bit) from the Version dropdown.
Fig. 2.15: Type in a Name and Select the Operating System for the New Virtual Machine
Click Next to see the screen in Figure 2.16. The base memory size must be changed to at least 8192 MB.
When finished, click Next to see the screen in Figure 2.17.
28
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.16: Select the Amount of Memory Reserved for the Virtual Machine
Fig. 2.17: Select Existing or Create a New Virtual Hard Drive
Click Create to launch the Create Virtual Hard Drive Wizard shown in Figure 2.18.
2.6. Virtualization
29
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.18: Create New Virtual Hard Drive Wizard
Select VDI and click the Next button to see the screen in Figure 2.19.
30
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.19: Select Storage Type for Virtual Disk
Choose either Dynamically allocated or Fixed-size storage. The first option uses disk space as needed until it
reaches the maximum size that is set in the next screen. The second option creates a disk the full amount
of disk space, whether it is used or not. Choose the first option to conserve disk space; otherwise, choose
the second option, as it allows VirtualBox to run slightly faster. After selecting Next, the screen in Figure 2.20
is shown.
2.6. Virtualization
31
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.20: Select File Name and Size of Virtual Disk
This screen is used to set the size (or upper limit) of the virtual disk. Increase the default size to 8 GB. Use
the folder icon to browse to a directory on disk with sufficient space to hold the virtual disk files. Remember
that there will be a system disk of at least 8 GB and at least one data storage disk of at least 4 GB.
After making a selection and pressing Next, a summary of the configuration options chosen is shown. Use
the Back button to return to a previous screen if any values need to be modified. Otherwise, click Finish to
complete the wizard. The new virtual machine is listed in the left frame, as shown in the example in Figure
2.21.
32
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.21: The New Virtual Machine
Create the virtual disks to be used for storage. Click the Storage hyperlink in the right frame to access the
storage screen seen in Figure 2.22.
2.6. Virtualization
33
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.22: Storage Settings of the Virtual Machine
Click the Add Attachment button, select Add Hard Disk from the pop-up menu, then click the Create New Disk
button. This launches the Create New Virtual Hard Drive Wizard (seen in Figure 2.18 and 2.19). This disk
will be used for storage, so create a size appropriate to your needs, making sure that it is at least 4 GB. To
practice with RAID configurations, create as many virtual disks as needed. Two disks can be created on each
IDE controller. For additional disks, click the Add Controller button to create another controller for attaching
additional disks.
Create a device for the installation media. Highlight the word “Empty”, then click the CD icon as shown in
Figure 2.23.
34
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.23: Configuring ISO Installation Media
Click Choose a virtual CD/DVD disk file... to browse to the location of the .iso file. If the .iso was burned to
CD, select the detected Host Drive.
Depending on the extensions available in the host CPU, it might not be possible to boot the VM from .iso.
If “your CPU does not support long mode” is shown when trying to boot the .iso, the host CPU either does
not have the required extension or AMD-V/VT-x is disabled in the system BIOS.
Note: If you receive a kernel panic when booting into the ISO, stop the virtual machine. Then, go to System
and check the box Enable IO APIC.
To configure the network adapter, go to Settings → Network. In the Attached to drop-down menu
select Bridged Adapter, then choose the name of the physical interface from the Name drop-down menu. In
the example shown in Figure 2.24, the Intel Pro/1000 Ethernet card is attached to the network and has a
device name of em0.
2.6. Virtualization
35
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.24: Configuring a Bridged Adapter in VirtualBox
After configuration is complete, click the Start arrow and install FreeNAS® as described in Performing the
Installation (page 13). Once FreeNAS® is installed, press F12 when the VM starts to boot to access the boot
menu. Select the primary hard disk as the boot option. You can permanently boot from disk by removing
the CD/DVD device in Storage or by unchecking CD/DVD-ROM in the Boot Order section of System.
2.6.2 VMware ESXi
Before using ESXi, read this post (https://forums.freenas.org/index.php?threads/sync-writes-or-why-is-myesxi-nfs-so-slow-and-why-is-iscsi-faster.12506/) for an explanation of why iSCSI will be faster than NFS.
ESXi is a bare-metal hypervisor architecture created by VMware Inc. Commercial and free versions
of the VMware vSphere Hypervisor operating system (ESXi) are available from the VMware website
(http://www.vmware.com/products/esxi-and-esx/overview). After the operating system is installed on supported hardware, use a web browser to connect to its IP address. The welcome screen provides a link to
download the VMware vSphere client which is used to create and manage virtual machines.
Once the VMware vSphere client is installed, use it to connect to the ESXi server. To create a new virtual machine, click File → New → Virtual Machine. The New Virtual Machine Wizard will launch as shown
in Figure 2.25.
36
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.25: New Virtual Machine Wizard
Click Next and enter a name for the virtual machine. Click Next and highlight a datastore. An example is
shown in Figure 2.26. Click Next. In the screen shown in Figure 2.27, click Other, then select a FreeBSD 64-bit
architecture.
2.6. Virtualization
37
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.26: Select Datastore
38
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.27: Select Operating System
Click Next and create a virtual disk file of 8 GB to hold the FreeNAS® operating system, as shown in Figure
2.28.
2.6. Virtualization
39
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.28: Create Disk for the Operating System
Click Next and Finish. The new virtual machine is listed in the left frame. Right-click the virtual machine and
select Edit Settings to access the screen shown in Figure 2.29.
40
Chapter 2. Installing and Upgrading
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.29: Virtual Machine Settings
Increase the Memory Configuration to at least 8192 MB.
To create a storage disk, click Hard disk 1 → Add. In the Device Type menu, highlight Hard Disk and click
Next. Select Create a new virtual disk and click Next. In the screen shown in Figure 2.30, select the size of
the disk. To dynamically allocate space as needed, check the box Allocate and commit space on demand (Thin
Provisioning). Click Next, then Next, then Finish to create the disk. Repeat to create the amount of storage
disks needed to meet your requirements.
2.6. Virtualization
41
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 2.30: Creating a Storage Disk
For ESX 5.0, Workstation 8.0, or Fusion 4.0 or higher, additional configuration is needed so that the virtual
HPET setting does not prevent the virtual machine from booting.
If you are running ESX, while in Edit Settings, click Options → Advanced → General →
Configuration Parameters. Change hpet0.present from true to false, then click OK twice to save the
setting.
For Workstation or Player, while in Edit Settings, click Options → Advanced → File Locations. Locate the path for the Configuration file named filename.vmx. Open that file in a text editor, change
hpet0.present from true to false, and save the change.
42
Chapter 2. Installing and Upgrading
CHAPTER
THREE
BOOTING
The Console Setup menu, shown in Figure 3.1, appears at the end of the boot process. If the FreeNAS®
system has a keyboard and monitor, this Console Setup menu can be used to administer the system.
Note: When connecting to the FreeNAS® system with SSH or the web Shell (page 288), the Console Setup
menu is not shown by default. It can be started by the root user or another user with root permissions by
typing /etc/netcli.
The Console Setup menu can be disabled by unchecking Enable Console Menu in System → Settings
→ Advanced.
Fig. 3.1: Console Setup Menu
The menu provides these options:
1) Configure Network Interfaces provides a configuration wizard to set up the system’s network interfaces.
2) Configure Link Aggregation is for creating or deleting link aggregations.
3) Configure VLAN Interface is used to create or delete VLAN interfaces.
43
FreeNAS® 11.0-U4 User Guide, Release 11.0
4) Configure Default Route is used to set the IPv4 or IPv6 default gateway. When prompted, enter the IP
address of the default gateway.
5) Configure Static Routes prompts for the destination network and gateway IP address. Re-enter this
option for each static route needed.
6) Configure DNS prompts for the name of the DNS domain and the IP address of the first DNS server.
When adding multiple DNS servers, press Enter to enter the next one. Press Enter twice to leave this
option.
7) Reset Root Password is used to reset a lost or forgotten root password. Select this option and follow the
prompts to set the password.
8) Reset to Factory Defaults Caution! This option deletes all of the configuration settings made in the
administrative GUI and is used to reset a FreeNAS® system back to defaults. Before selecting this option,
make a full backup of all data and make sure all encryption keys and passphrases are known! After
this option is selected, the configuration is cleared and the system reboots. Storage → Volumes →
Import Volume can be used to re-import volumes.
9) Shell starts a shell for running FreeBSD commands. To leave the shell, type exit.
10) System Update checks for system updates. If any new updates are available, they are automatically
downloaded and applied. This is a simplified version of the Update (page 69) option available in the web
interface. Updates are applied immediately for the currently selected train and access to the GUI is not
required. For more advanced update options like switching trains, use Update (page 69).
11) Reboot reboots the system.
12) Shut Down halts the system.
3.1 Obtaining an IP Address
During boot, FreeNAS® automatically attempts to connect to a DHCP server from all live network interfaces.
If it successfully receives an IP address, the address is displayed so it can be used to access the graphical
user interface. The example in Figure 3.1 shows a FreeNAS® system that is accessible at http://192.168.1.119.
Some FreeNAS® systems are set up without a monitor, making it challenging to determine which IP address
has been assigned. On networks that support Multicast DNS (mDNS), the hostname and domain can be
entered into the address bar of a browser. By default, this value is freenas.local.
If the FreeNAS® server is not connected to a network with a DHCP server, use the console network configuration menu to manually configure the interface as seen in Example: Manually Setting an IP Address from the
Console Menu (page ??). In this example, the FreeNAS® system has one network interface, em0.
Manually Setting an IP Address from the Console Menu
Enter an option from 1-14: 1
1) em0
Select an interface (q to quit): 1
Reset network configuration (y/n) n
Configure interface for DHCP? (y/n) n
Configure IPv4? (y/n) y
Interface name: (press enter as can be blank)
Several input formats are supported
Example 1 CIDR Notation: 192.168.1.1/24
Example 2 IP and Netmask separate:
IP: 192.168.1.1
Netmask: 255.255.255.0, or /24 or 24
IPv4 Address: 192.168.1.108/24
Saving interface configuration: Ok
Configure IPv6? (y/n) n
44
Restarting network: ok
You may try the following URLs to access the web user interface:
http://192.168.1.108
Chapter 3. Booting
FreeNAS® 11.0-U4 User Guide, Release 11.0
After the system has an IP address, enter that address into a graphical web browser from a computer
connected to the same network as the FreeNAS® system.
3.2 Logging In
The password for the root user is requested as shown in Figure 3.2.
Fig. 3.2: Enter the Root Password
Enter the password chosen during the installation. The administrative GUI is displayed as shown in Figure
3.3.
Fig. 3.3: FreeNAS® Graphical Configuration Menu
If the FreeNAS® system does not respond to the IP address or mDNS name entered in a browser:
• If proxy settings are enabled in the browser configuration, disable them and try connecting again.
3.2. Logging In
45
FreeNAS® 11.0-U4 User Guide, Release 11.0
• If the page does not load, check whether the FreeNAS® system’s IP address responds to a ping from
another computer on the same network. If the FreeNAS® IP address is in a private IP address range,
it can only be accessed from within that private network.
• If the user interface loads but is unresponsive or seems to be missing menu items, try a different web
browser. IE9 has known issues and does not display the graphical administrative interface correctly if
compatibility mode is turned on. Firefox (https://www.mozilla.org/en-US/firefox/all/) is recommended.
• If An error occurred! messages are shown when attempting to configure an item in the GUI, make sure
that the browser is set to allow cookies from the FreeNAS® system.
This blog post (http://fortysomethinggeek.blogspot.com/2012/10/ipad-iphone-connect-with-freenas-orany.html) describes some applications which can be used to access the FreeNAS® system from an iPad
or iPhone.
3.3 Initial Configuration
The first time the FreeNAS® GUI is accessed, the Wizard (page 280) starts automatically to help configure
the FreeNAS® device quickly and easily.
46
Chapter 3. Booting
CHAPTER
FOUR
ACCOUNT
The Account Configuration section of the administrative GUI describes how to manually create and manage
users and groups. This section contains these entries:
• Groups (page 47): used to manage UNIX-style groups on the FreeNAS® system.
• Users (page 50): used to manage UNIX-style accounts on the FreeNAS® system.
Each entry is described in more detail in this section.
4.1 Groups
The Groups interface provides management of UNIX-style groups on the FreeNAS® system.
Note: If a directory service is running on the network, it is not necessary to recreate the network’s users
or groups. Instead, import the existing account information into FreeNAS® . Refer to Directory Services
(page 152) for details.
This section describes how to create a group and assign user accounts to it. The next section, Users (page 50),
describes creating user accounts.
Click Groups → View Groups to see a screen like Figure 4.1.
47
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 4.1: Group Management
All groups that came with the operating system will be listed. Each group has an entry indicating the group
ID, group name, whether or not it is a built-in group which was installed with FreeNAS® , and whether or not
the group members are allowed to use sudo. Clicking a group entry causes a Members button to appear.
Click the button to view and modify the group membership.
The Add Group button opens the screen shown in Figure 4.2. Table 4.1 summarizes the available options
when creating a group.
Fig. 4.2: Creating a New Group
48
Chapter 4. Account
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 4.1: Group Creation Options
Setting
Group ID
Value
string
Group Name
Permit Sudo
string
checkbox
Allow repeated GIDs
checkbox
Description
the next available group ID will be suggested for you; by convention, UNIX groups containing user accounts have an ID greater
than 1000 and groups required by a service have an ID equal
to the default port number used by the service (e.g. the sshd
group has an ID of 22)
mandatory
if checked, members of the group have permission to use
sudo (http://www.sudo.ws/); when using sudo, a user will be
prompted for their own password
allows multiple groups to share the same group id (GID); this is
useful when a GID is already associated with the UNIX permissions for existing data
After a group and users are created, users can be made members of a group. Highlight the group where
users will be assigned, then click the Members button. Highlight the user in the Member users list (which
shows all user accounts on the system) and click >> to move that user to the right frame. The user accounts
which appear in the right frame are added as members of the group.
In the example shown in Figure 4.3, the data1 group has been created and the user1 user account has been
created with a primary group of user1. The Members button for the data1 group has been selected and user1
has been added as a member of the group.
Fig. 4.3: Assigning a User to a Group
The Delete Group button deletes a group. The pop-up message asks whether all members of that group
should also be deleted. Note that the built-in groups do not provide a Delete Group button.
4.1. Groups
49
FreeNAS® 11.0-U4 User Guide, Release 11.0
4.2 Users
FreeNAS® supports users, groups, and permissions, allowing great flexibility in configuring which users
have access to the data stored on FreeNAS® . To assign permissions to shares, one of the following must
be done:
1. Create a guest account that all users will use or create a user account for every user in the network
where the name of each account is the same as a logon name used on a computer. For example, if
a Windows system has a login name of bobsmith, create a user account with the name bobsmith on
FreeNAS® . A common strategy is to create groups with different sets of permissions on shares, then
assign users to those groups.
2. If your network uses a directory service, import the existing account information using the instructions
in Directory Services (page 152).
Account → Users → View Users provides a listing of all of the system accounts that were installed
with the FreeNAS® operating system, as shown in Figure 4.4.
Fig. 4.4: Managing User Accounts
Each account entry indicates the user ID, username, primary group ID, home directory, default shell, full
name, whether it is a built-in user that came with the FreeNAS® installation, the email address, whether
logins are disabled, whether the user account is locked, whether the user is allowed to use sudo, and if the
user connects from a Windows 8 or higher system. To reorder the list, click the desired column name. An
arrow indicates which column controls the view sort order. Click the arrow to reverse the sort order.
Click a user account to cause these buttons to appear:
• Modify User: used to modify the account’s settings, as listed in Table 4.2.
• Change E-mail: used to change the email address associated with the account.
Note: It is important to set the email address for the built-in root user account as important system
messages are sent to the root user. For security reasons, password logins are disabled for the root account
and changing this setting is highly discouraged.
Except for the root user, the accounts that come with FreeNAS® are system accounts. Each system account
is used by a service and should not be used as a login account. For this reason, the default shell on system
50
Chapter 4. Account
FreeNAS® 11.0-U4 User Guide, Release 11.0
accounts is nologin(8) (http://www.freebsd.org/cgi/man.cgi?query=nologin). For security reasons, and to
prevent breakage of system services, do not modify the system accounts.
The Add User button opens the screen shown in Figure 4.5. Some settings are only available in Advanced
Mode. To see these settings, either click the Advanced Mode button or configure the system to always display
these settings by checking the box Show advanced fields by default in System → Advanced. Table 4.2
summarizes the options which are available when user accounts are created or modified.
Warning: When using Active Directory (page 152), Windows user passwords must be set from within
Windows.
Fig. 4.5: Adding or Editing a User Account
Table 4.2: User Account Configuration
Setting
Value
User ID
integer
4.2. Users
Advanced
Mode
Description
grayed out if user already created; when creating an
account, the next numeric ID will be suggested; by
convention, user accounts have an ID greater than
1000 and system accounts have an ID equal to the default port number used by the service
Continued on next page
51
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 4.2 – continued from previous page
Advanced Description
Mode
grayed out if user already created; maximum 16 characters though a maximum of 8 is recommended for
interoperability; cannot begin with a hyphen, if a $ is
used it can only be the last character, and it cannot
contain a space, tab, or the characters ,: + & # %
Setting
Value
Username
string
Create a new primary group
checkbox
Primary Group
drop-down
menu
Create Home Directory In
Home Directory
Mode
Shell
browse button
checkboxes
Full Name
E-mail
Password
drop-down
menu
string
string
string
Password confirmation
Disable password
login
string
Lock user
checkbox
Permit Sudo
checkbox
Microsoft Account
checkbox
SSH Public Key
string
Auxiliary groups
mouse selection
checkbox
X
^ & ( ) ! @ ~ * ? < > =
by default, a primary group with the same name as
the user will be created; uncheck this box to select a
different primary group name
must uncheck Create a new primary group to access
this menu; for security reasons, FreeBSD will not give a
user su permissions if wheel is their primary group; to
give a user su access, add them to the wheel group in
Auxiliary groups
browse to the name of an existing volume or dataset
that the user will be assigned permission to access
sets default Unix permissions of user’s home directory; read-only for built-in users
select shell to use for local and SSH logins; see Table
4.3 for an overview of available shells
mandatory, may contain spaces
email address associated with the account
mandatory unless check box Disable password login;
cannot contain a ?
must match the value of Password
when checked, disables password logins and authentication to SMB shares; to undo this setting, set a password for the user using the Modify User button for the
user in View Users; checking this box grays out Lock
user and Permit Sudo, which are mutually exclusive
a checked box prevents user from logging in until the
account is unlocked (box is unchecked); checking this
box will gray out Disable password login which is mutually exclusive
if checked, members of the group have permission to
use sudo (http://www.sudo.ws/); when using sudo, a
user will be prompted for their own password
check this box if the user will be connecting from a
Windows 8 or higher system
paste the user’s public SSH key to be used for keybased authentication (do not paste the private key!)
highlight the groups to which the user is to be added;
click the >> button to add the user to the highlighted
groups
Note: Some fields cannot be changed for built-in users and will be grayed out.
52
Chapter 4. Account
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 4.3: Available Shells
Shell
netcli.sh
csh
sh
tcsh
nologin
bash
ksh93
mksh
rbash
rzsh
scponly
zsh
git-shell
Description
user is shown the Console Setup menu (Figure 3.1) on connection, even if it is disabled in System → Advanced → Enable
Console Menu; the user must be root or have root permissions
(effective user ID 0, like toor)
C shell (https://en.wikipedia.org/wiki/C_shell)
Bourne shell (https://en.wikipedia.org/wiki/Bourne_shell)
Enhanced C shell (https://en.wikipedia.org/wiki/Tcsh)
use when creating a system account or to create a user account
that can authenticate with shares but which cannot login to the
FreeNAS system using ssh
Bourne Again shell (https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29)
Korn shell (http://www.kornshell.com/)
mirBSD Korn shell (https://www.mirbsd.org/mksh.htm)
Restricted bash (http://www.gnu.org/software/bash/manual/html_node/TheRestricted-Shell.html)
Restricted zsh (http://www.csse.uwa.edu.au/programming/linux/zshdoc/zsh_14.html)
select scponly (https://github.com/scponly/scponly/wiki) to restrict
the user’s SSH usage to only the scp and sftp commands
Z shell (http://www.zsh.org/)
restricted git shell (http://git-scm.com/docs/git-shell)
Built-in user accounts needed by the system cannot be removed. A Remove User button appears for custom
users that have been added by the system administrator. If the user to be removed is the last user in a
custom group, an option is presented to delete the group as well.
4.2. Users
53
CHAPTER
FIVE
SYSTEM
The System section of the administrative GUI contains these entries:
• Information (page 54) provides general FreeNAS® system information such as hostname, operating
system version, platform, and uptime
• General (page 55) configures general settings such as HTTPS access, the language, and the timezone
• Boot (page 58) creates, renames, and deletes boot environments
• Advanced (page 62) configures advanced settings such as the serial console, swap space, and console
messages
• Email (page 65) configures the email address to receive notifications
• System Dataset (page 66) configures the location where logs and reporting graphs are stored
• Tunables (page 67) provides a front-end for tuning in real-time and to load additional kernel modules
at boot time
• Update (page 69) performs upgrades and checks for system updates
• Alert Services (page 73) configures services used to notify the administrator about system events.
• CAs (page 74): import or create internal or intermediate CAs (Certificate Authorities)
• Certificates (page 77): import existing certificates or create self-signed certificates
• Support (page 80): report a bug or request a new feature.
Each of these is described in more detail in this section.
5.1 Information
System → Information displays general information about the FreeNAS® system. An example is seen
in Figure 5.1.
The information includes the hostname, the build version, type of CPU (platform), the amount of memory,
the current system time, the system’s uptime, the number of users connected at the console or by serial,
telnet, or SSH connections, and the current load average. On servers supplied or certified by iXsystems, an
additional Serial Number field showing the hardware serial number is displayed.
To change the system’s hostname, click the Edit button, type in the new hostname, and click OK. The hostname must include the domain name. If the network does not use a domain name, add .local after the
hostname.
54
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.1: System Information Tab
5.2 General
System → General is shown in Figure 5.2.
Fig. 5.2: General Screen
5.2. General
55
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 5.1 summarizes the settings that can be configured using the General tab:
Table 5.1: General Configuration Settings
Setting
Protocol
Value
dropdown
menu
Certificate
dropdown
menu
dropdown
menu
WebGUI IPv4 Address
WebGUI IPv6 Address
dropdown
menu
WebGUI HTTP Port
integer
WebGUI HTTPS Port
integer
WebGUI HTTP –>
HTTPS Redirect
checkbox
Language
dropdown
menu
dropdown
menu
dropdown
menu
dropdown
menu
string
Console Keyboard Map
Timezone
Syslog level
Syslog server
Description
protocol to use when connecting to the administrative GUI from
a browser; if modified from the default of HTTP to HTTPS or to
HTTP+HTTPS, select the certificate to use in Certificate; if you do
not have a certificate, first create a CA (in CAs (page 74)), then
the certificate itself (in Certificates (page 77))
required for HTTPS; browse to the location of the certificate to
use for encrypted connections
choose from a list of recent IP addresses to limit the one to use
when accessing the administrative GUI; the built-in HTTP server
will automatically bind to the wildcard address of 0.0.0.0 (any
address) and will issue an alert if the specified address becomes
unavailable
choose from a list of recent IPv6 addresses to limit the one to
use when accessing the administrative GUI; the built-in HTTP
server will automatically bind to any address and will issue an
alert if the specified address becomes unavailable
allows configuring a non-standard port for accessing
the administrative GUI over HTTP; changing this setting
might also require changing a Firefox configuration setting
(http://www.redbrick.dcu.ie/%7Ed_fens/articles/Firefox:_This_Address_is_Restricted
allows configuring a non-standard port for accessing the administrative GUI over HTTPS
when this box is checked, HTTP connections are automatically
redirected to HTTPS if HTTPS is selected in Protocol, otherwise
such connections will fail
select the localization from the drop-down menu and reload the
browser; view the status of localization at pootle.freenas.org
(http://pootle.freenas.org/)
select the keyboard layout
select the timezone from the drop-down menu
when Syslog server is defined, only logs matching this level are
sent
IP address_or_hostname:optional_port_number of remote syslog
server to send logs to; once set, log entries are written to both
the console and the remote server
After making any changes, click the Save button.
This screen also contains these buttons:
Factory Restore: reset the configuration database to the default base version. However, this does not
delete user SSH keys or any other data stored in a user’s home directory. Since any configuration changes
stored in the configuration database will be erased, this option is useful when a mistake has been made or
56
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
to return a test system to the original configuration.
Save Config: save a backup copy of the current configuration database in the format hostname-versionarchitecture to the computer accessing the administrative interface. Saving the configuration after making
any configuration changes is highly recommended. FreeNAS® automatically backs up the configuration
database to the system dataset every morning at 3:45. However, this backup does not occur if the system
is shut down at that time. If the system dataset is stored on the boot pool and the boot pool becomes
unavailable, the backup will also not be available. The location of the system dataset can be viewed or set
using System → System Dataset.
Note: SSH (page 237) keys are not stored in the configuration database and must be backed up separately.
There are two types of passwords. User account passwords for the base operating system are stored as
hashed values, do not need to be encrypted to be secure, and are saved in the system configuration backup.
Other passwords, like iSCSI CHAP passwords or Active Directory bind credentials, are stored in an encrypted
form to prevent them from being visible as plain text in the saved system configuration. The key or seed
for this encryption is normally stored only on the boot device. When Save Config is chosen, a dialog gives
the option to Export Password Secret Seed with the saved configuration, allowing the configuration file to be
restored to a different boot device where the decryption seed is not already present. Configuration backups containing the seed must be physically secured to prevent decryption of passwords and unauthorized
access.
Warning: The Export Password Secret Seed option is off by default and should only be used when making
a configuration backup that will be stored securely. After moving a configuration to new hardware, media
containing a configuration backup with a decryption seed should be securely erased before reuse.
Upload Config: allows browsing to the location of a previously saved configuration file to restore that
configuration. The screen turns red as an indication that the system will need to reboot to load the restored
configuration.
NTP Servers: The network time protocol (NTP) is used to synchronize the time on the computers in a
network. Accurate time is necessary for the successful operation of time sensitive applications such as
Active Directory or other directory services. By default, FreeNAS® is pre-configured to use three public
NTP servers. If your network is using a directory service, ensure that the FreeNAS® system and the server
running the directory service have been configured to use the same NTP servers.
Available NTP servers can be found at https://support.ntp.org/bin/view/Servers/NTPPoolServers. For time
accuracy, choose NTP servers that are geographically close to the FreeNAS® system’s physical location.
NTP servers are added by clicking on NTP Servers → Add NTP Server to open the screen shown
in Figure 5.3. Table 5.2 summarizes the options available when adding an NTP server. ntp.conf(5)
(http://www.freebsd.org/cgi/man.cgi?query=ntp.conf) explains these options in more detail.
5.2. General
57
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.3: Add an NTP Server
Table 5.2: NTP Servers Configuration Options
Setting
Address
Burst
Value
string
checkbox
IBurst
Prefer
checkbox
checkbox
Min. Poll
integer
Max. Poll
integer
Force
checkbox
Description
name of NTP server
recommended when Max. Poll is greater than 10; only use on
your own servers i.e. do not use with a public NTP server
speeds the initial synchronization (seconds instead of minutes)
should only be used for NTP servers that are known to be highly
accurate, such as those with time monitoring hardware
power of 2 in seconds; cannot be lower than 4 or higher than
Max. Poll
power of 2 in seconds; cannot be higher than 17 or lower than
Min. Poll
forces the addition of the NTP server, even if it is currently unreachable
5.3 Boot
FreeNAS® supports a ZFS feature known as multiple boot environments. With multiple boot environments,
the process of updating the operating system becomes a low-risk operation. The updater automatically
creates a snapshot of the current boot environment and adds it to the boot menu before applying the
update. If the update fails, reboot the system and select the previous boot environment from the boot
menu to instruct the system to go back to that system state.
Note: Boot environments are separate from the configuration database. Boot environments are a snap-
58
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
shot of the operating system at a specified time. When a FreeNAS® system boots, it loads the specified
boot environment, or operating system, then reads the configuration database in order to load the current
configuration values. If the intent is to make configuration changes rather than operating system changes,
make a backup of the configuration database first using System → General → Save Config.
As seen in Figure 5.4, two boot environments are created when FreeNAS® is installed. The system will boot
into the default boot environment and users can make their changes and update from this version. The
other boot environment, named Initial-Install can be booted into if the system needs to be returned to a
pristine, non-configured version of the installation.
If the Wizard (page 280) was used, a third boot environment called Wizard-date is also created, indicating
the date and time the Wizard (page 280) was run.
Fig. 5.4: Viewing Boot Environments
Each boot environment entry contains this information:
• Name: the name of the boot entry as it will appear in the boot menu.
• Active: indicates which entry will boot by default if the user does not select another entry in the boot
menu.
• Created: indicates the date and time the boot entry was created.
• Keep: indicates whether or not this boot environment can be pruned if an update does not have
enough space to proceed. Click the entry’s Keep button if that boot environment should not be automatically pruned.
Highlight an entry to view its configuration buttons. These configuration buttons are shown:
• Rename: used to change the name of the boot environment.
• Keep/Unkeep: used to toggle whether or not the updater can prune (automatically delete) this boot
environment if there is not enough space to proceed with the update.
• Clone: used to create a copy of the highlighted boot environment.
• Delete: used to delete the highlighted entry, which also removes that entry from the boot menu.
Since you cannot delete an entry that has been activated, this button will not appear for the active
boot environment. If you need to delete an entry that is currently activated, first activate another
entry, which will clear the On reboot field of the currently activated entry. Note that this button will not
be displayed for the default boot environment as this entry is needed in order to return the system to
the original installation state.
• Activate: only appears on entries which are not currently set to Active. Changes the selected entry
to the default boot entry on next boot. Its status changes to On Reboot and the current Active entry
changes from On Reboot, Now to Now, indicating that it was used on the last boot but will not be used
on the next boot.
The buttons above the boot entries can be used to:
5.3. Boot
59
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Create: a manual boot environment. A pop-up menu will prompt you to input a “Name” for the boot
environment. When entering the name, only alphanumeric characters, underscores, and dashes are
allowed.
• Scrub Boot: can be used to perform a manual scrub of the boot devices. By default, the boot device
is scrubbed every 7 days. To change the default interval, change the number in the Automatic scrub
interval (in days) field. The date and results of the last scrub are also listed in this screen. The condition
of the boot device should be listed as HEALTHY.
• Status: click this button to see the status of the boot devices. Figure 5.5, shows only one boot device,
which is ONLINE.
Fig. 5.5: Viewing the Status of the Boot Device
If the system has a mirrored boot device and one of the boot devices has an OFFLINE Status, click the device
to replace, then click Replace to rebuild the boot mirror.
Note that you cannot replace the boot device if it is the only boot device as it contains the operating
system itself.
Figure 5.6 shows a sample boot menu.
60
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.6: Boot Environments in Boot Menu
The first entry is the active boot environment, or the one that the system has been configured to boot into.
To boot into a different boot environment, press the spacebar to pause this screen, use the down arrow
to select Boot Environment Menu, and press Enter. A menu displays the other available boot environments.
Use the up/down arrows to select the desired boot environment and press Enter to boot into it. To always
boot into that boot environment, go to System → Boot, highlight that entry, and click the Activate button.
5.3.1 Mirroring the Boot Device
If the system is currently booting from one device, you can add another device to create a mirrored boot
device. This way, if one device fails, the system still has a copy of the boot file system and can be configured
to boot from the remaining device in the mirror.
Note: When adding another boot device, it must be the same size (or larger) as the existing boot device.
Different models of USB devices which advertise the same size may not necessarily be the same size. For
this reason, it is recommended to use the same model of USB drive.
In the example shown in Figure 5.7, the user has clicked System → Boot → Status to display the
current status of the boot device. The example indicates that there is currently one device, ada0p2, its status
is ONLINE, and it is currently the only boot device as indicated by the word stripe. To create a mirrored boot
device, click either the entry called freenas-boot or stripe, then click the Attach button. If another device is
available, it appears in the Member disk drop-down menu. Select the desired device, then click Attach Disk.
5.3. Boot
61
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.7: Mirroring a Boot Device
Once the mirror is created, the Status screen indicates that it is now a mirror. The number of devices in the
mirror are shown, as seen in the example in Figure 5.8.
Fig. 5.8: Viewing the Status of a Mirrored Boot Device
5.4 Advanced
System → Advanced is shown in Figure 5.9. The configurable settings are summarized in Table 5.3.
62
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.9: Advanced Screen
Table 5.3: Advanced Configuration Settings
Setting
Enable Console Menu
Value
checkbox
Use Serial Console
Serial Port Address
Serial Port Speed
checkbox
string
dropdown
menu
checkbox
checkbox
Enable screen saver
Enable powerd (Power
Saving Daemon)
Swap size
Show console messages in the footer
5.4. Advanced
non-zero
integer
representing
GB
checkbox
Description
unchecking this box removes the console menu shown in Figure
3.1
do not check this box if the serial port is disabled
serial port address in hex
select the speed used by the serial port
enable or disable the console screen saver
powerd(8) (http://www.freebsd.org/cgi/man.cgi?query=powerd)
monitors the system state and sets the CPU frequency accordingly
by default, all data disks are created with this amount of swap;
this setting does not affect log or cache devices as they are created without swap
display console messages in real time at bottom of browser;
click the console to bring up a scrollable screen; check the
Stop refresh box in the scrollable screen to pause updating and
uncheck the box to continue to watch the messages as they occur
Continued on next page
63
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Show tracebacks in
case of fatal errors
Show advanced fields
by default
Enable autotune
Enable debug kernel
Enable automatic upload of kernel crash
dumps and daily
telemetry
MOTD banner
Periodic Notification
User
Remote Graphite
Server hostname
Use FQDN for logging
Table 5.3 – continued from previous page
Value
Description
checkbox
provides a pop-up of diagnostic information when a fatal error
occurs
checkbox
several GUI menus provide an Advanced Mode button to access
additional features; enabling this shows these features by default
checkbox
enables Autotune (page 64) which attempts to optimize the system depending upon the hardware which is installed
checkbox
when checked, next boot uses a debug version of the kernel
checkbox
when checked, kernel crash dumps and telemetry (some system
stats, collectd RRDs, and select syslog messages) are automatically sent to the development team for diagnosis
string
dropdown
menu
string
checkbox
message to be shown when a user logs in with SSH
user to receive security output emails; this output runs nightly
but only sends an email when the system reboots or encounters
an error
IP address or hostname of a remote server running Graphite
(http://graphite.wikidot.com/)
when checked, include the Fully-Qualified Domain Name in logs
to precisely identify systems with similar hostnames
Click the Save button after making any changes.
This tab also contains this button:
Save Debug: used to generate a text file of diagnostic information. After the debug data is collected, the
system prompts for a location to save the generated ASCII text file.
5.4.1 Autotune
FreeNAS® provides an autotune script which optimizes the system depending on the installed hardware.
For example, if a ZFS volume exists on a system with limited RAM, the autotune script automatically adjusts
some ZFS sysctl values in an attempt to minimize ZFS memory starvation issues. It should only be used as
a temporary measure on a system that hangs until the underlying hardware issue is addressed by adding
more RAM. Autotune will always slow such a system, as it caps the ARC.
The Enable autotune checkbox in System → Advanced is unchecked by default. Check this box to run the
autotuner at boot time. If you would like the script to run immediately, the system must be rebooted.
If the autotune script adjusts any settings, the changed values appear in System → Tunables. These
values can be modified and overridden. Note that deleting tunables that were created by autotune only
affects the current session, as autotune-set tunables are recreated at boot.
When attempting to increase the performance of the FreeNAS® system, and particularly when the current
hardware may be limiting performance, try enabling autotune.
For those who wish to see which checks are performed, the autotune script is located in
/usr/local/bin/autotune.
64
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
5.5 Email
An automatic script sends a nightly email to the root user account containing important information such
as the health of the disks. Alert (page 295) events are also emailed to the root user account. Problems with
Scrubs (page 147) are reported separately in an email sent at 03:00AM.
Note: S.M.A.R.T. (page 229) reports are mailed separately to the address configured in that service.
The administrator typically does not read email directly on the FreeNAS® system. Instead, these emails are
usually sent to an external email address where they can be read more conveniently. It is important to
configure the system so it can send these emails to the administrator’s remote email account so they are
aware of problems or status changes.
The first step is to set the remote address where email will be sent. Select Users → View Users, click
on root to highlight that user, then click Change E-mail. Enter the email address on the remote system where
email is to be sent, like admin@example.com.
Additional configuration is performed with System → Email, shown in Figure 5.10.
Fig. 5.10: Email Screen
Table 5.4: Email Configuration Settings
Setting
From email
Value
string
Outgoing mail
server
Port to connect to
string or IP address
integer
TLS/SSL
drop-down menu
5.5. Email
Description
the envelope From address shown in the email; this can be
set to assist with filtering mail on the receiving system
hostname or IP address of SMTP server to use for sending
this email
SMTP port number, typically 25, 465 (secure SMTP), or 587
(submission)
encryption type; choices are Plain, SSL, or TLS
Continued on next page
65
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Use SMTP Authentication
Value
checkbox
Username
string
Password
string
Password Confirmation
string
Table 5.4 – continued from previous page
Description
enable/disable SMTP AUTH
(http://en.wikipedia.org/wiki/SMTP_Authentication) using PLAIN SASL; if checked, enter the required Username and
Password
enter the username if the SMTP server requires authentication
enter the password if the SMTP server requires authentication
enter the same password again for confirmation
Click the Send Test Mail button to verify that the configured email settings are working. If the test email
fails, double-check the destination email address by clicking the Change E-mail button for the root account
in Account → Users → View Users. Test mail cannot be sent unless the root email address has been
set.
Configuring email for TLS/SSL email providers is described in Are you having trouble getting FreeNAS
to email you in Gmail? (https://forums.freenas.org/index.php?threads/are-you-having-trouble-gettingfreenas-to-email-you-in-gmail.22517/).
5.6 System Dataset
System → System Dataset, shown in Figure 5.11, is used to select the pool which will contain the
persistent system dataset. The system dataset stores debugging core files and Samba4 metadata such as
the user/group cache and share level permissions. If the FreeNAS® system is configured to be a Domain
Controller, all of the domain controller state is stored there as well, including domain controller users and
groups.
Note: When the system dataset is moved, a new dataset is created and set active. The old dataset is
intentionally not deleted by the system because the move might be transient or the information in the old
dataset might be useful for later recovery.
Fig. 5.11: System Dataset Screen
Note: Encrypted volumes are not displayed in the System dataset pool drop-down menu.
66
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
The system dataset can optionally be configured to also store the system log and Reporting (page 278)
information. If there are lots of log entries or reporting information, moving these to the system dataset
will prevent /var/ on the device holding the operating system from filling up as /var/ has limited space.
Use the drop-down menu to select the ZFS volume (pool) to contain the system dataset. Whenever the location of the system dataset is changed, a pop-up warning indicates that the SMB service must be restarted,
causing a temporary outage of any active SMB connections.
To store the system log on the system dataset, check the Syslog box.
To store the reporting information on the system dataset, check the Reporting Database box.
If you make any changes, click the Save button to save them.
If you change the pool storing the system dataset at a later time, FreeNAS® will automatically migrate the
existing data in the system dataset to the new location.
Note: Depending on configuration, the system dataset can occupy a large amount of space and receive
frequent writes. Do not put the system dataset on a flash drive or other media with limited space or write
life.
5.7 Tunables
System → Tunables can be used to manage the following:
1. FreeBSD sysctls: a sysctl(8) (http://www.freebsd.org/cgi/man.cgi?query=sysctl) makes changes to the
FreeBSD kernel running on a FreeNAS® system and can be used to tune the system.
2. FreeBSD loaders: a loader is only loaded when a FreeBSD-based system boots and can be used to
pass a parameter to the kernel or to load an additional kernel module such as a FreeBSD hardware
driver.
3. FreeBSD rc.conf options: rc.conf(5) (https://www.freebsd.org/cgi/man.cgi?query=rc.conf&manpath=FreeBSD+11.0RELEASE) is used to pass system configuration options to the system startup scripts as the system
boots. Since FreeNAS® has been optimized for storage, not all of the services mentioned in rc.conf(5)
are available for configuration. Note that in FreeNAS® , customized rc.conf options are stored in
/tmp/rc.conf.freenas.
Warning: Adding a sysctl, loader, or rc.conf option is an advanced feature. A sysctl immediately
affects the kernel running the FreeNAS® system and a loader could adversely affect the ability of the
FreeNAS® system to successfully boot. Do not create a tunable on a production system unless you
understand and have tested the ramifications of that change.
Since sysctl, loader, and rc.conf values are specific to the kernel parameter to be tuned, the driver to be
loaded, or the service to configure, descriptions and suggested values can be found in the man page for the
specific driver and in many sections of the FreeBSD Handbook (http://www.freebsd.org/handbook).
To add a loader, sysctl, or rc.conf option, go to System → Tunables → Add Tunable, to access the
screen shown in seen in Figure 5.12.
5.7. Tunables
67
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.12: Adding a Tunable
Table 5.5 summarizes the options when adding a tunable.
Table 5.5: Adding a Tunable
Setting
Variable
Value
string
Value
integer or string
Type
Comment
drop-down menu
string
Enabled
checkbox
Description
typically the name of the sysctl or driver to load, as indicated by
its man page
value to associate with Variable; typically this is set to YES to enable the sysctl or driver specified by the “Variable”
choices are Loader, rc.conf, or Sysctl
optional, but a useful reminder for the reason behind adding this
tunable
uncheck if you would like to disable the tunable without deleting
it
Note: As soon as a Sysctl is added or edited, the running kernel changes that variable to the value specified.
However, when a Loader or rc.conf value is changed, it does not take effect until the system is rebooted.
Regardless of the type of tunable, changes persist at each boot and across upgrades unless the tunable is
deleted or its Enabled checkbox is unchecked.
Any added tunables are listed in System → Tunables. To change the value of an existing tunable, click
its Edit button. To remove a tunable, click its Delete button.
Restarting the FreeNAS® system after making sysctl changes is recommended. Some sysctls only take effect
at system startup, and restarting the system guarantees that the setting values correspond with what is
being used by the running system.
The GUI does not display the sysctls that are pre-set when FreeNAS® is installed. FreeNAS® 11.0 ships with
the following sysctls set:
kern.metadelay=3
kern.dirdelay=4
kern.filedelay=5
kern.coredump=1
kern.sugid_coredump=1
68
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
vfs.timestamp_precision=3
net.link.lagg.lacp.default_strict_mode=0
vfs.zfs.min_auto_ashift=12
Do not add or edit these default sysctls as doing so may render the system unusable.
The GUI does not display the loaders that are pre-set when FreeNAS® is installed. FreeNAS® 11.0 ships with
these loaders set:
autoboot_delay="2"
loader_logo="freenas"
loader_menu_title="Welcome to FreeNAS"
loader_brand="freenas-brand"
loader_version=" "
kern.cam.boot_delay="30000"
debug.debugger_on_panic=1
debug.ddb.textdump.pending=1
hw.hptrr.attach_generic=0
vfs.mountroot.timeout="30"
ispfw_load="YES"
hint.isp.0.role=2
hint.isp.1.role=2
hint.isp.2.role=2
hint.isp.3.role=2
module_path="/boot/kernel;/boot/modules;/usr/local/modules"
net.inet6.ip6.auto_linklocal="0"
vfs.zfs.vol.mode=2
kern.geom.label.disk_ident.enable="0"
hint.ahciem.0.disabled="1"
hint.ahciem.1.disabled="1"
kern.msgbufsize="524288"
hw.usb.no_shutdown_wait=1
Do not add or edit the default tunables as doing so might make the system unusable.
The ZFS version used in 11.0 deprecates these tunables:
vfs.zfs.write_limit_override
vfs.zfs.write_limit_inflated
vfs.zfs.write_limit_max
vfs.zfs.write_limit_min
vfs.zfs.write_limit_shift
vfs.zfs.no_write_throttle
After upgrading from an earlier version of FreeNAS® , these tunables are automatically deleted. Please do
not manually add them back.
5.8 Update
FreeNAS® has an integrated update system to make it easy to keep up to date.
5.8.1 Preparing for Updates
It is best to perform updates at times the FreeNAS® system is idle, with no clients connected and no scrubs
or other disk activity going on. A reboot is required after most updates, so they are often planned for
5.8. Update
69
FreeNAS® 11.0-U4 User Guide, Release 11.0
scheduled maintenance times to avoid disrupting user activities.
The update process will not proceed unless there is enough free space in the boot pool for the new update
files. If a space warning is shown, use Boot (page 58) to remove unneeded boot environments.
5.8.2 Updates and Trains
FreeNAS® is updated with signed update files. This provides flexibility in deciding when to upgrade the system with patches, new drivers, or new features. It also allows “test driving” an upcoming release. Combined
with boot environments, new features or system patches can be tested while still being able to revert to a
previous version of the operating system (see If Something Goes Wrong (page 24)). Digital signing of update
files eliminates the need to manually download both an upgrade file and the associated checksum to verify
file integrity.
Figure 5.13 shows an example of the System → Update screen.
Fig. 5.13: Update Options
By default, the system automatically checks for updates and issues an alert when a new update becomes
available. The automatic check can be disabled by unchecking Automatically check for updates.
This screen lists the URL of the official update server in case that information is needed in a network with
outbound firewall restrictions. It also shows which software branch, or train, is being tracked for updates.
Several trains are available for updates.
Caution: Only Production trains are recommended for regular usage. Other trains are made
available for pre-production testing and updates to legacy versions. Pre-production testing trains are
provided only to permit testing of new versions before switching to a new branch. Before using a nonproduction train, be prepared to experience bugs or problems. Testers are encouraged to submit bug
reports at https://bugs.freenas.org/.
These trains are available:
70
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
For Production Use
• FreeNAS-11-STABLE (Recommended)
After testing, new fixes and features are added to this train. Selecting this train and applying any
pending updates is recommended.
For Pre-Production Testing
• FreeNAS-11-Nightlies
Do not use this train in production. It is the experimental branch for future versions and is meant
only for testers and developers.
Legacy Versions
• FreeNAS-9.10-STABLE
Maintenance-only updates to the older version of FreeNAS® . Upgrading to FreeNAS-11-STABLE is
recommended to ensure that the system receives bug fixes and new features.
• FreeNAS-9.3-STABLE
Maintenance-only updates to the older version of FreeNAS® . Upgrading to FreeNAS-9.10-STABLE is
recommended to ensure that the system receives bug fixes and new features.
Obsolete Versions
• FreeNAS-9.10-Nightlies
As of May 5, 2017, this train has been replaced by the FreeNAS-11-Nightlies train. Please switch to the
FreeNAS-11-Nightlies train for active support.
To change the train, use the drop-down menu to make a different selection.
Note: The train selector does not allow downgrades. For example, the STABLE train cannot be selected
while booted into a Nightly boot environment, or a 9.3 train cannot be selected while booted into a 9.10
boot environment. To go back to an earlier version after testing or running a more recent version, reboot
and select a boot environment for that earlier version. This screen can then be used to check for updates
that train.
This screen also shows the URL of the official update server. That information can be required when using
a network with outbound firewall restrictions.
The Verify Install button verifies that the operating system files in the current installation do not have any
inconsistencies. If any problems are found, a pop-up menu lists the files with checksum mismatches or
permission errors.
5.8.3 Checking for Updates
Checking for updates by making sure the desired train is selected and clicking the Check Now button. Any
available updates are listed. In the example shown in Figure 5.14, the numbers which begin with a # represent the bug report number from bugs.freenas.org (https://bugs.freenas.org). Numbers which do not begin
with a # represent a git commit. Click the ChangeLog link to open the log of changes in a web browser. Click
the ReleaseNotes link to open the Release Notes in the browser.
5.8. Update
71
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.14: Reviewing Updates
5.8.4 Applying Updates
Make sure the system is in a low-usage state as described above in Preparing for Updates (page 69).
Click the OK button to download and apply the updates. Be aware that some updates automatically reboot
the system after they are applied.
Warning: Each update creates a boot environment. If the update process needs more space, it attempts
to remove old boot environments. Boot environments marked with the Keep attribute as shown in Boot
(page 58) will not be removed. If space for a new boot environment is not available, the upgrade fails.
Space on the boot device can be manually freed using System → Boot. Review the boot environments
and remove the Keep attribute or delete any boot environments that are no longer needed.
Updates can also be downloaded and applied later. To do so, uncheck the Apply updates after downloading
box before pressing OK. In this case, this screen closes after updates are downloaded. Downloaded updates
are listed in the Pending Updates section of the screen shown in Figure 5.13. When ready to apply the
previously downloaded updates, click the Apply Pending Updates button. Remember that the system might
reboot after the updates are applied.
Warning: After updates have completed, reboot the system. Configuration changes made after an
update but before that final reboot will not be saved.
5.8.5 Manual Updates
Updates can be manually downloaded as a file. These updates are then applied with the Manual Update
button. After obtaining the update file, click Manual Update and choose a location to temporarily store the
file on the FreeNAS® system. Use the file browser to locate the update file, then click Apply Update to apply
it.
Manual update files can be identified by their filenames, which end in -manual-update-unsigned.tar.
Manual updates cannot be used to upgrade from older major versions.
72
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
5.9 Alert Services
FreeNAS® can use a number of methods to notify the administrator of system events that require attention.
These events are system Alerts (page 295) marked WARN or CRITICAL.
Currently available alert services:
• AWS-SNS (https://aws.amazon.com/sns/)
• Hipchat (https://www.hipchat.com/)
• InfluxDB (https://www.influxdata.com/)
• Slack (https://slack.com/)
• Mattermost (https://about.mattermost.com/)
• OpsGenie (https://www.opsgenie.com/)
• PagerDuty (https://www.pagerduty.com/)
• VictorOps (https://victorops.com/)
Warning: These alert services might use a third party commercial vendor not directly affiliated with
iXsystems. Please investigate and fully understand that vendor’s pricing policies and services before
using their alert service. iXsystems is not responsible for any charges incurred from the use of third
party vendors with the Alert Services feature.
Select System → Alert Services to go to the Alert Services screen. Click Add Service to display the
dialog shown in Figure 5.15.
Fig. 5.15: Add Alert Service
The Service Name drop-down menu is used to pick a specific alert service. The fields shown in the rest
of the dialog change to those required by that service. Enter the required information, check the Enabled
checkbox, then click OK to save the settings.
System alerts marked WARN or CRITICAL are sent to each alert service that has been configured and enabled.
5.9. Alert Services
73
FreeNAS® 11.0-U4 User Guide, Release 11.0
Alert services can be deleted from this list by clicking them and then clicking the Delete button at the bottom
of the window. To disable an alert service temporarily, click Edit and remove the checkmark from the Enabled
checkbox.
5.9.1 How it Works
A
nas-health
service
is
registered
with
Consul.
This
service
runs
/usr/local/etc/consul-checks/freenas_health.sh periodically, currently every two minutes. If an alert marked WARNING or CRITICAL is found, the nas-health service is marked as “unhealthy”,
triggering consul-alerts to notify configured alert services.
5.10 CAs
FreeNAS® can act as a Certificate Authority (CA). When encrypting SSL or TLS connections to the FreeNAS®
system, either import an existing certificate, or create a CA on the FreeNAS® system, then create a certificate. This certificate will appear in the drop-down menus for services that support SSL or TLS.
For secure LDAP, the public key of an existing CA can be imported with Import CA, or a new CA created on
the FreeNAS® system and used on the LDAP server also.
Figure 5.16 shows the screen after clicking System → CAs.
Fig. 5.16: Initial CA Screen
If your organization already has a CA, the CA’s certificate and key can be imported. Click the Import CA button
to open the configuration screen shown in Figure 5.17. The configurable options are summarized in Table
5.6.
74
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.17: Importing a CA
Table 5.6: Importing a CA Options
Setting
Identifier
Value
string
Certificate
Private Key
string
string
Passphrase
string
Serial
string
Description
mandatory; enter a descriptive name for the CA using only alphanumeric, underscore (_), and dash (-) characters
mandatory; paste in the certificate for the CA
if there is a private key associated with the Certificate, paste it
here
if the Private Key is protected by a passphrase, enter it here and
repeat it in the “Confirm Passphrase” field
mandatory; enter the serial number for the certificate
To instead create a new CA, first decide if it will be the only CA which will sign certificates for internal use or
if the CA will be part of a certificate chain (https://en.wikipedia.org/wiki/Root_certificate).
To create a CA for internal use only, click the Create Internal CA button which will open the screen shown in
Figure 5.18.
5.10. CAs
75
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.18: Creating an Internal CA
The configurable options are described in Table 5.7. When completing the fields for the certificate authority,
supply the information for your organization.
Table 5.7: Internal CA Options
Setting
Identifier
Value
string
Key Length
Digest Algorithm
Lifetime
Country
State
Locality
Organization
Email Address
drop-down menu
drop-down menu
76
integer
drop-down menu
string
string
string
string
Description
required; enter a descriptive name for the CA using only alphanumeric, underscore (_), and dash (-) characters
for security reasons, a minimum of 2048 is recommended
the default is acceptable unless your organization requires a different algorithm
in days
select the country for the organization
required; enter the state or province of the organization
required; enter the location of the organization
required; enter the name of the company or organization
required; enter the email address for the person responsible for
the CA
Continued on next page
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Common
Name
Value
string
Table 5.7 – continued from previous page
Description
required; enter the fully-qualified hostname (FQDN) of the
FreeNAS® system
To instead create an intermediate CA which is part of a certificate chain, click the Create Intermediate CA
button. This screen adds one more option to the screen shown in Figure 5.18:
• Signing Certificate Authority: this drop-down menu is used to specify the root CA in the certificate
chain. This CA must first be imported or created.
Any CAs that you import or create will be added as entries in System → CAs. The columns in this screen
indicate the name of the CA, whether it is an internal CA, whether the issuer is self-signed, the number of
certificates that have been issued by the CA, the distinguished name of the CA, the date and time the CA
was created, and the date and time the CA expires.
Clicking the entry for a CA causes these buttons to become available:
• Export Certificate: prompts to browse to the location to save a copy of the CA’s X.509 certificate on
the computer being used to access the FreeNAS® system.
• Export Private Key: prompts to browse to the location to save a copy of the CA’s private key on the
computer being used to access the FreeNAS® system. This option only appears if the CA has a private
key.
• Delete: prompts for confirmation before deleting the CA.
5.11 Certificates
FreeNAS® can import existing certificates, create new certificates, and issue certificate signing requests so
that created certificates can be signed by the CA which was previously imported or created in CAs (page 74).
Figure 5.19 shows the initial screen after clicking System → Certificates.
Fig. 5.19: Initial Certificates Screen
To import an existing certificate, click the Import Certificate button to open the configuration screen shown in
Figure 5.20. When importing a certificate chain, paste the primary certificate, followed by any intermediate
certificates, followed by the root CA certificate.
The configurable options are summarized in Table 5.8.
5.11. Certificates
77
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.20: Importing a Certificate
Table 5.8: Certificate Import Options
Setting
Identifier
Value
string
Certificate
Private Key
Passphrase
string
string
string
Description
required; enter a descriptive name for the certificate using only
alphanumeric, underscore (_), and dash (-) characters
required; paste the contents of the certificate
required; paste the private key associated with the certificate
if the private key is protected by a passphrase, enter it here and
repeat it in the Confirm Passphrase field
To instead create a new self-signed certificate, click the Create Internal Certificate button to see the screen
shown in Figure 5.21. The configurable options are summarized in Table 5.9. When completing the fields
for the certificate authority, use the information for your organization. Since this is a self-signed certificate,
use the CA that was imported or created with CAs (page 74) as the signing authority.
78
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.21: Creating a New Certificate
Table 5.9: Certificate Creation Options
Setting
Signing Certificate
Authority
Identifier
Value
drop-down menu
Key Length
Digest Algorithm
drop-down menu
drop-down menu
Lifetime
Country
State
Locality
Organization
Email Address
integer
drop-down menu
string
string
string
string
5.11. Certificates
string
Description
required; select the CA which was previously imported or
created using CAs (page 74)
required; enter a descriptive name for the certificate using
only alphanumeric, underscore (_), and dash (-) characters
for security reasons, a minimum of 2048 is recommended
the default is acceptable unless your organization requires a
different algorithm
in days
select the country for the organization
required; enter the state or province for the organization
required; enter the location for the organization
required; enter the name of the company or organization
required; enter the email address for the person responsible
for the CA
Continued on next page
79
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Common Name
Value
string
Table 5.9 – continued from previous page
Description
required; enter the fully-qualified hostname (FQDN) of the
FreeNAS® system
If you need to use a certificate that is signed by an external CA, such as Verisign, instead create a certificate
signing request. To do so, click the Create Certificate Signing Request button. A screen like the one in Figure
5.21 opens, but without the Signing Certificate Authority field.
Certificates that are imported, self-signed, or for which a certificate signing request is created are added
as entries to System → Certificates. In the example shown in Figure 5.22, a self-signed certificate
and a certificate signing request have been created for the fictional organization My Company. The selfsigned certificate was issued by the internal CA named My Company and the administrator has not yet
sent the certificate signing request to Verisign so that it can be signed. Once that certificate is signed and
returned by the external CA, it should be imported using the Import Certificate button so that is available as
a configurable option for encrypting connections.
Fig. 5.22: Managing Certificates
Clicking an entry activates these configuration buttons:
• View: after a certificate is created, it cannot be edited. The Name, Certificate, and Private Key fields can
be viewed. If a certificate must be changed, Delete and recreate it.
• Export Certificate saves a copy of the certificate or certificate signing request to the system being
used to access the FreeNAS® system. For a certificate signing request, send the exported certificate
to the external signing authority so that it can be signed.
• Export Private Key saves a copy of the private key associated with the certificate or certificate signing
request to the system being used to access the FreeNAS® system.
• Delete is used to delete a certificate or certificate signing request.
5.12 Support
The FreeNAS® Support tab, shown in Figure 5.23, provides a built-in ticketing system for generating bug
reports and feature requests.
80
Chapter 5. System
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 5.23: Support Tab
This screen provides a built-in interface to the FreeNAS® bug tracker located at bugs.freenas.org
(https://bugs.freenas.org). If you have not yet used the FreeNAS® bug tracker, you must first go to that
website, click the Register link, fill out the form, and reply to the registration email. This will create a username and password which can be used to create bug reports and receive notifications as the reports are
actioned.
Before creating a bug report or feature request, ensure that an existing report does not already exist at
bugs.freenas.org (https://bugs.freenas.org). If you find a similar issue that is not yet marked as closed or
resolved, add a comment to that issue if you have new information to provide that can assist in resolving the
issue. If you find a similar issue that is marked as closed or resolved, you can create a new issue and refer to
the earlier issue number.
Note: If you are not updated to the latest version of STABLE, do that first to see if it resolves your issue.
To generate a report using the built-in Support screen, complete the following fields:
• Username:
enter the
(https://bugs.freenas.org).
login
name
created
when
registering
at
bugs.freenas.org
• Password: enter the password associated with the registered login name.
• Type: select Bug when reporting an issue or Feature when requesting a new feature.
• Category: this drop-down menu is empty a registered “Username” and “Password” are entered. An
error message is displayed if either value is incorrect. After the Username and Password are validated,
possible categories are populated to the drop-down menu. Select the one that best describes the bug
or feature being reported.
5.12. Support
81
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Attach Debug Info: it is recommended to leave this box checked so that an overview of the system’s
hardware, build string, and configuration is automatically generated and included with the ticket.
• Subject: input a descriptive title for the ticket. A good Subject makes it easy for you and other users
to find similar reports.
• Description: input a 1 to 3 paragraph summary of the issue that describes the problem, and if applicable, what steps one can do to reproduce it.
• Attachments: this is the only optional field. It is useful for including configuration files or screenshots
of any errors or tracebacks.
Once you have finished completing the fields, click the Submit button to automatically generate and upload
the report to bugs.freenas.org (https://bugs.freenas.org). A pop-up menu provides a clickable URL so to
view status or add additional information to the report.
82
Chapter 5. System
CHAPTER
SIX
TASKS
The Tasks section of the administrative GUI is used to configure repetitive tasks:
• Cron Jobs (page 83) schedules a command or script to automatically execute at a specified time
• Init/Shutdown Scripts (page 85) configures a command or script to automatically execute during system
startup or shutdown
• Rsync Tasks (page 86) schedules data synchronization to another system
• S.M.A.R.T. Tests (page 92) schedules disk tests
Each of these tasks is described in more detail in this section.
Note: By default, Scrubs (page 147) are run once a month by an automatically-created task. S.M.A.R.T. Tests
(page 92) and Periodic Snapshot Tasks (page 134) must be set up manually.
6.1 Cron Jobs
cron(8) (http://www.freebsd.org/cgi/man.cgi?query=cron) is a daemon that runs a command or script on a
regular schedule as a specified user.
Figure 6.1 shows the screen that opens after clicking Tasks → Cron Jobs → Add Cron Job.
83
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 6.1: Creating a Cron Job
Table 6.1 lists the configurable options for a cron job.
Table 6.1: Cron Job Options
Setting
User
Value
drop-down menu
Command
string
Short description
Minute
string
Hour
slider or hour selections
slider or month
selections
checkboxes
checkboxes
checkbox
with the slider, the cron job occurs every N minutes; with
minute selections, the cron job occurs at the highlighted minutes
with the slider, the cron job occurs every N hours; with hour
selections, the cron job occurs at the highlighted hours
with the slider, cron job occurs every N days; with day selections, cron job occurs on the highlighted days each month
cron job occurs on the selected months
cron job occurs on the selected days
disables emailing standard output to the root user account
checkbox
disables emailing errors to the root user account
checkbox
uncheck disable the cron job without deleting it
Day of month
Month
Day of week
Redirect Stdout
Redirect
Stderr
Enabled
slider or minute
selections
Description
make sure the selected user has permission to run the specified
command or script
the full path to the command or script to be run; if it is a script,
test it at the command line first to make sure that it works as
expected
optional
Cron jobs are shown in View Cron Jobs. Highlight a cron job entry to display buttons to Edit, guilabel:Delete,
or Run Now.
84
Chapter 6. Tasks
FreeNAS® 11.0-U4 User Guide, Release 11.0
Note: % symbols are automatically escaped and should not be prefixed with backslashes. For example,
use date '+%Y-%m-%d' in a cron job to generate a filename based on the date.
6.2 Init/Shutdown Scripts
FreeNAS® provides the ability to schedule commands or scripts to run at system startup or shutdown.
Figure 6.2 shows the screen that opens after clicking Tasks → Init/Shutdown Scripts → Add
Init/Shutdown Script. Table 6.2 summarizes the options.
When scheduling a command, make sure that the command is in the path or give the full path to the
command. One way to test the path is to type which command_name. If the command is not found, it is
not in your path.
When scheduling a script, make sure that the script is executable and has been fully tested to ensure that it
achieves the desired results.
Fig. 6.2: Add an Init/Shutdown Script
Table 6.2: Options When Adding an Init/Shutdown Script
Setting
Type
Value
drop-down menu
Command
string
When
drop-down menu
6.2. Init/Shutdown Scripts
Description
select from Command (for an executable) or Script (for an executable script)
if Command is selected, input the command plus any desired
options; if Script is selected, browse to the location of the script
select when the command/script will run; choices are Pre Init
(very early in boot process before filesystems are mounted),
Post Init (towards end of boot process before FreeNAS services
are started), or Shutdown
85
FreeNAS® 11.0-U4 User Guide, Release 11.0
6.3 Rsync Tasks
Rsync (http://www.samba.org/ftp/rsync/rsync.html) is a utility that copies specified data from one system
to another over a network. Once the initial data is copied, rsync reduces the amount of data sent over the
network by sending only the differences between the source and destination files. Rsync can be used for
backups, mirroring data on multiple systems, or for copying files between systems.
Rsync is most effective when only a relatively small amount of the data has changed. There are also some
limitations when using Rsync with Windows files (https://forums.freenas.org/index.php?threads/impairedrsync-permissions-support-for-windows-datasets.43973/). For large amounts of data, data that has many
changes from the previous copy, or Windows files, Replication Tasks (page 136) are often the faster and
better solution.
Rsync is single-threaded, so gains little from multiple processor cores. To see whether rsync is currently
running, use pgrep rsync from the Shell (page 288).
Both ends of an rsync connection must be configured:
• the rsync server: this system pulls (receives) the data. This system is referred to as PULL in the
configuration examples.
• the rsync client: this system pushes (sends) the data. This system is referred to as PUSH in the
configuration examples.
FreeNAS® can be configured as either an rsync client or an rsync server. The opposite end of the connection can be another FreeNAS® system or any other system running rsync. In FreeNAS® terminology, an
rysnc task defines which data is synchronized between the two systems. To synchronize data between two
FreeNAS® systems, create the rsync task on the rsync client.
FreeNAS® supports two modes of rsync operation:
• rsync module mode: exports a directory tree, and its configured settings, as a symbolic
name over an unencrypted connection. This mode requires that at least one module be defined on the rsync server. It can be defined in the FreeNAS® GUI under Services → Rsync
→ Rsync Modules.
In other operating systems, the module is defined in rsyncd.conf(5)
(http://www.samba.org/ftp/rsync/rsyncd.conf.html).
• rsync over SSH: synchronizes over an encrypted connection. Requires the configuration of SSH user
and host public keys.
This section summarizes the options when creating an Rsync Task. It then provides a configuration example
between two FreeNAS® systems for each mode of rsync operation.
Note: If there is a firewall between the two systems or if the other system has a built-in firewall, make sure
that TCP port 873 is allowed.
Figure 6.3 shows the screen that appears after selecting Tasks → Rsync Tasks → Add Rsync Task.
Table 6.3 summarizes the options that can be configured when creating an rsync task.
86
Chapter 6. Tasks
FreeNAS® 11.0-U4 User Guide, Release 11.0
6.3. Rsync Tasks
87
Fig. 6.3: Adding an Rsync Task
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 6.3: Rsync Configuration Options
Setting
Path
Value
browse button
User
drop-down menu
Remote Host
string
Remote SSH
Port
Rsync mode
Remote Module Name
integer
Remote Path
string
Validate Remote Path
Direction
Short Description
Minute
checkbox
drop-down menu
string
drop-down menu
string
Month
Day of week
Recursive
slider or minute
selections
slider or hour selections
slider or day selections
checkboxes
checkboxes
checkbox
Times
Compress
checkbox
checkbox
Archive
checkbox
Delete
checkbox
Quiet
Preserve permissions
Preserve extended attributes
checkbox
checkbox
Hour
Day of month
checkbox
Description
browse to the path that to be copied; note that a path length
greater than 255 characters will fail
specified user must have permission to write to the specified
directory on the remote system; due to a limitation in FreeBSD,
the user name cannot contain spaces or exceed 17 characters
IP address or hostname of the remote system that will store the
copy; use the format username@remote_host if the username
differs on the remote host
only available in Rsync over SSH mode; allows specifying an SSH
port other than the default of 22
choices are Rsync module or Rsync over SSH
only appears when using Rsync module mode, at
least one module must be defined in rsyncd.conf(5)
(http://www.samba.org/ftp/rsync/rsyncd.conf.html) of rsync
server or in the Rsync Modules of another system
only appears when using Rsync over SSH mode, enter the existing path on the remote host to sync with (e.g. /mnt/volume);
note that maximum path length is 255 characters
if the Remote Path does not yet exist, check this box to have it
automatically created
choices are Push or Pull; default is to push to a remote host
optional
if use the slider, sync occurs every N minutes; if use minute selections, sync occurs at the highlighted minutes
if use the slider, sync occurs every N hours; if use hour selections, sync occurs at the highlighted hours
if use the slider, sync occurs every N days; if use day selections,
sync occurs on the highlighted days
task occurs on the selected months
task occurs on the selected days of the week
if checked, copy will include all subdirectories of the specified
volume
preserve modification times of files
recommended on slow connections as reduces size of data to
be transmitted
equivalent to -rlptgoD (recursive, copy symlinks as symlinks,
preserve permissions, preserve modification times, preserve
group, preserve owner (super-user only), and preserve device
files (super-user only) and special files)
delete files in destination directory that do not exist in sending
directory
suppresses informational messages from the remote server
preserves original file permissions; useful if User is set to root
both systems must support extended attributes
(http://en.wikipedia.org/wiki/Xattr)
Continued on next page
88
Chapter 6. Tasks
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Delay Updates
Value
checkbox
Extra options
string
Enabled
checkbox
Table 6.3 – continued from previous page
Description
when checked, the temporary file from each updated file is
saved to a holding directory until the end of the transfer, when
all transferred files are renamed into place
rsync(1) (http://rsync.samba.org/ftp/rsync/rsync.html) options
not covered by the GUI; if the * character is used, it must be escaped with a backslash (\*.txt) or used inside single quotes
('*.txt')
uncheck to disable the rsync task without deleting it; note that
when the Rsync (page 225) service is OFF, the rsync task will continue to look for the server unless this checkbox is unchecked
If the rysnc server requires password authentication, enter --password-file=/PATHTO/FILENAME in
the Extra options box, replacing /PATHTO/FILENAME with the appropriate path to the file containing the
password.
Created rsync tasks will be listed in View Rsync Tasks. Highlight the entry for an rsync task to display buttons
for Edit, Delete, or Run Now.
6.3.1 Rsync Module Mode
This configuration example configures rsync module mode between the two following FreeNAS® systems:
• 192.168.2.2 has existing data in /mnt/local/images. It will be the rsync client, meaning that an
rsync task needs to be defined. It will be referred to as PUSH.
• 192.168.2.6 has an existing volume named /mnt/remote. It will be the rsync server, meaning that
it will receive the contents of /mnt/local/images. An rsync module needs to be defined on this
system and the rsyncd service needs to be started. It will be referred to as PULL.
On PUSH, an rsync task is defined in Tasks → Rsync Tasks → Add Rsync Task. In this example:
• the Path points to /usr/local/images, the directory to be copied
• the Remote Host points to 192.168.2.6, the IP address of the rsync server
• the Rsync Mode is Rsync module
• the Remote Module Name is backups; this will need to be defined on the rsync server
• the Direction is Push
• the rsync is scheduled to occur every 15 minutes
• the User is set to root so it has permission to write anywhere
• the Preserve Permissions checkbox is checked so that the original permissions are not overwritten by
the root user
On PULL, an rsync module is defined in Services → Rsync Modules → Add Rsync Module. In this
example:
• the Module Name is backups; this needs to match the setting on the rsync client
• the Path is /mnt/remote; a directory called images will be created to hold the contents of
/usr/local/images
• the User is set to root so it has permission to write anywhere
• Hosts allow is set to 192.168.2.2, the IP address of the rsync client
6.3. Rsync Tasks
89
FreeNAS® 11.0-U4 User Guide, Release 11.0
Descriptions of the configurable options can be found in Rsync Modules.
To finish the configuration, start the rsync service on PULL in Services → Control Services. If the
rsync is successful, the contents of /mnt/local/images/ will be mirrored to /mnt/remote/images/.
6.3.2 Rsync over SSH Mode
SSH replication mode does not require the creation of an rsync module or for the rsync service to be running
on the rsync server. It does require SSH to be configured before creating the rsync task:
• a public/private key pair for the rsync user account (typically root) must be generated on PUSH and the
public key copied to the same user account on PULL
• to mitigate the risk of man-in-the-middle attacks, the public host key of PULL must be copied to PUSH
• the SSH service must be running on PULL
To create the public/private key pair for the rsync user account, open Shell (page 288) on PUSH and run
ssh-keygen. This example generates an RSA type public/private key pair for the root user. When creating
the key pair, do not enter the passphrase as the key is meant to be used for an automated task.
ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Created directory '/root/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
f5:b0:06:d1:33:e4:95:cf:04:aa:bb:6e:a4:b7:2b:df root@freenas.local
The key's randomart image is:
+--[ RSA 2048]----+
|
.o. oo
|
|
o+o. . |
|
. =o +
|
|
+ +
o |
|
S o .
|
|
.o
|
|
o.
|
|
o oo
|
|
|
**oE
|-----------------|
|
|
|-----------------|
FreeNAS® supports RSA keys for SSH. When creating the key, use -t rsa to specify this type of key.
Note: If a different user account is used for the rsync task, use the su - command after mounting the
filesystem but before generating the key. For example, if the rsync task is configured to use the user1 user
account, use this command to become that user:
su - user1
Next, view and copy the contents of the generated public key:
90
Chapter 6. Tasks
FreeNAS® 11.0-U4 User Guide, Release 11.0
more .ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1lBEXRgw1W8y8k+lXPlVR3xsmVSjtsoyIzV/PlQPo
SrWotUQzqILq0SmUpViAAv4Ik3T8NtxXyohKmFNbBczU6tEsVGHo/2BLjvKiSHRPHc/1DX9hofcFti4h
dcD7Y5mvU3MAEeDClt02/xoi5xS/RLxgP0R5dNrakw958Yn001sJS9VMf528fknUmasti00qmDDcp/kO
xT+S6DFNDBy6IYQN4heqmhTPRXqPhXqcD1G+rWr/nZK4H8Ckzy+l9RaEXMRuTyQgqJB/rsRcmJX5fApd
DmNfwrRSxLjDvUzfywnjFHlKk/+TQIT1gg1QQaj21PJD9pnDVF0AiJrWyWnR root@freenas.local
Go to PULL and paste (or append) the copied key into the SSH Public Key field of Account → Users →
View Users → root → Modify User, or the username of the specified rsync user account. The
paste for the above example is shown in Figure 6.4. When pasting the key, ensure that it is pasted as
one long line and, if necessary, remove any extra spaces representing line breaks.
Fig. 6.4: Pasting the User’s SSH Public Key
While on PULL, verify that the SSH service is running in Services → Control Services and start it if
it is not.
Next, copy the host key of PULL using Shell on PUSH. The following command copies the RSA host key of the
PULL server used in our previous example. Be sure to include the double bracket >> to prevent overwriting
any existing entries in the known_hosts file:
ssh-keyscan -t rsa 192.168.2.6 >> /root/.ssh/known_hosts
Note: If PUSH is a Linux system, use this command to copy the RSA key to the Linux system:
6.3. Rsync Tasks
91
FreeNAS® 11.0-U4 User Guide, Release 11.0
cat ~/.ssh/id_rsa.pub | ssh user@192.168.2.6 'cat >> .ssh/authorized_keys'
The rsync task can now be created on PUSH. To configure rsync SSH mode using the systems in our previous
example, the configuration is as follows:
• the Path points to /mnt/local/images, the directory to be copied
• the Remote Host points to 192.168.2.6, the IP address of the rsync server
• the Rsync Mode is Rsync over SSH
• the rsync is scheduled to occur every 15 minutes
• the User is set to root so it has permission to write anywhere; the public key for this user must be
generated on PUSH and copied to PULL
• the Preserve Permissions checkbox is checked so that the original permissions are not overwritten by
the root user
Save the rsync task and the rsync will automatically occur according to the schedule. In this example, the
contents of /mnt/local/images/ will automatically appear in /mnt/remote/images/ after 15 minutes. If the content does not appear, use Shell on PULL to read /var/log/messages. If the message
indicates a n (newline character) in the key, remove the space in the pasted key–it will be after the character
that appears just before the n in the error message.
6.4 S.M.A.R.T. Tests
S.M.A.R.T. (http://en.wikipedia.org/wiki/S.M.A.R.T.) (Self-Monitoring, Analysis and Reporting Technology) is a
monitoring system for computer hard disk drives to detect and report on various indicators of reliability.
When a failure is anticipated by S.M.A.R.T., the drive should be replaced. Most modern ATA, IDE, and SCSI-3
hard drives support S.M.A.R.T.–refer to the drive documentation for confirmation.
Figure 6.5 shows the configuration screen that appears after selecting Tasks → S.M.A.R.T. Tests →
Add S.M.A.R.T. Test. Tests are listed under View S.M.A.R.T. Tests. After creating tests, check the configuration in Services → S.M.A.R.T., then click the slider to ON for the S.M.A.R.T. service in Services
→ Control Services. The S.M.A.R.T. service will not start if there are no volumes.
Note: To prevent problems, do not enable the S.M.A.R.T. service if the disks are controlled by a RAID
controller. It is the job of the controller to monitor S.M.A.R.T. and mark drives as Predictive Failure when
they trip.
92
Chapter 6. Tasks
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 6.5: Adding a S.M.A.R.T. Test
Table 6.4 summarizes the configurable options when creating a S.M.A.R.T. test.
Table 6.4: S.M.A.R.T. Test Options
Setting
Disks
Type
Value
list
drop-down menu
Short description
Hour
string
Description
highlight disks to monitor
select type of test to run; see smartctl(8)
(https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in)
for a description of each type of test (note that some test types
will degrade performance or take disks offline; do not schedule
S.M.A.R.T. tests at the same time as a scrub or during a resilver
operation)
optional
slider or hour selections
slider or day selections
checkboxes
checkboxes
if use the slider, test occurs every N hours; if use hour selections, test occurs at the highlighted hours
if use the slider, test occurs every N days; if use day selections,
test occurs on the highlighted days
select the months for the test to occur
select the days of the week for the test to occur
Day of month
Month
Day of week
An example configuration is to schedule a Short Self-Test once a week and a Long Self-Test once a month.
6.4. S.M.A.R.T. Tests
93
FreeNAS® 11.0-U4 User Guide, Release 11.0
These tests should not have a performance impact, as the disks prioritize normal I/O over the tests. If a disk
fails a test, even if the overall status is Passed, start to think about replacing that disk.
Warning: Some S.M.A.R.T. tests cause heavy disk activity and can drastically reduce disk performance.
Do not schedule S.M.A.R.T. tests to run at the same time as scrub or resilver operations or during other
periods of intense disk activity.
Which tests will run and when can be verified by typing smartd -q showtests within Shell (page 288).
The results of a test can be checked from Shell (page 288) by specifying the name of the drive. For example,
to see the results for disk ada0, type:
smartctl -l selftest /dev/ada0
If an email address is entered in the Email to report field of Services → S.M.A.R.T., the system will
send email to that address when a test fails.
94
Chapter 6. Tasks
CHAPTER
SEVEN
NETWORK
The Network section of the administrative GUI contains these components for viewing and configuring
network settings on the FreeNAS® system:
• Global Configuration (page 95): general network settings.
• Interfaces (page 96): settings for each network interface.
• IPMI (page 98): settings controlling connection to the appliance through the hardware side-band management interface if the graphical user interface becomes unavailable.
• Link Aggregations (page 100): settings for network link aggregation and link failover.
• Network Summary (page 105): display an overview of the current network settings.
• Static Routes (page 105): add static routes.
• VLANs (page 106): configure IEEE 802.1q tagging for virtual LANs.
Each of these is described in more detail in this section.
7.1 Global Configuration
Network → Global Configuration, shown in Figure 7.1, is for general network settings that are not
unique to any particular network interface.
Fig. 7.1: Global Network Configuration
Table 7.1 summarizes the settings on the Global Configuration tab. Hostname and domain fields are prefilled as shown in Figure 7.1, but can be changed to meet requirements of the local network.
95
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 7.1: Global Configuration Settings
Setting
Hostname
Domain
IPv4 Default
Gateway
IPv6 Default
Gateway
Nameserver 1
Nameserver 2
Nameserver 3
HTTP Proxy
Value
string
string
IP address
Enable netwait feature
Netwait IP list
checkbox
Host name
database
string
IP address
IP address
IP address
IP address
string
string
Description
system host name
system domain name
typically not set (see Note below); if set, used instead of default
gateway provided by DHCP
typically not set (see Note below)
primary DNS server (typically in Windows domain)
secondary DNS server
tertiary DNS server
enter the proxy information for the network
in the format http://my.proxy.server:3128 or
http://user@password:my.proxy.server:3128
if enabled, network services are not started at boot until the
interface is able to ping the addresses listed in Netwait IP list
if Enable netwait feature is checked, list of IP addresses to ping;
otherwise, ping the default gateway
used to add one entry per line which will be appended to
/etc/hosts; use the format IP_address space hostname where
multiple hostnames can be used if separated by a space
When Active Directory is being used, set the IP address of the realm’s DNS server in the Nameserver 1 field.
If the network does not have a DNS server, or NFS, SSH, or FTP users are receiving “reverse DNS” or timeout
errors, add an entry for the IP address of the FreeNAS® system in the Host name database field.
Note: In many cases, a FreeNAS® configuration does not include default gateway information as a way to
make it more difficult for a remote attacker to communicate with the server. While this is a reasonable precaution, such a configuration does not restrict inbound traffic from sources within the local network. However, omitting a default gateway will prevent the FreeNAS® system from communicating with DNS servers,
time servers, and mail servers that are located outside of the local network. In this case, it is recommended
to add Static Routes (page 105) to be able to reach external DNS, NTP, and mail servers which are configured
with static IP addresses. When a gateway to the Internet is added, make sure that the FreeNAS® system is
protected by a properly configured firewall.
7.2 Interfaces
Network → Interfaces shows which interfaces have been manually configured and allows adding or
editing a manually configured interface.
Note: Typically, the interface used to access the FreeNAS® administrative GUI is configured by DHCP. This
interface does not appear in this screen, even though it is already dynamically configured and in use.
Figure 7.2 shows the screen that opens on clicking Interfaces → Add Interface. Table 7.2 summarizes the configuration options shown when adding an interface or editing an already configured interface.
Note that if any changes to this screen require a network restart, the screen will turn red when the OK but-
96
Chapter 7. Network
FreeNAS® 11.0-U4 User Guide, Release 11.0
ton is clicked and a pop-up message will point out that network connectivity to the FreeNAS® system will be
interrupted while the changes are applied.
Fig. 7.2: Adding or Editing an Interface
Table 7.2: Interface Configuration Settings
Setting
NIC
Value
drop-down menu
Interface
Name
DHCP
string
IPv4 Address
IPv4 Netmask
Auto configure IPv6
IPv6 Address
IPv6 Prefix
Length
Options
IP address
drop-down menu
checkbox
7.2. Interfaces
checkbox
IPv6 address
drop-down menu
string
Description
the FreeBSD device name of the interface; a read-only field
when editing an interface
description of interface
requires static IPv4 or IPv6 configuration if unchecked; only one
interface can be configured for DHCP
enter a static IP address if DHCP is unchecked
enter a netmask if DHCP is unchecked
only one interface can be configured for this option; if
unchecked, manual configuration is required to use IPv6
must be unique on network
match the prefix used on network
additional parameters from ifconfig(8)
(http://www.freebsd.org/cgi/man.cgi?query=ifconfig), separate multiple parameters with a space; for example: mtu 9000
increases the MTU for interfaces which support jumbo frames
(but see this note (page 104) about MTU and lagg interfaces)
97
FreeNAS® 11.0-U4 User Guide, Release 11.0
This screen also provides for the configuration of IP aliases, making it possible for a single interface to have
multiple IP addresses. To set multiple aliases, click the Add extra alias link for each alias. Aliases are deleted
by clicking the interface in the tree, clicking the Edit button, checking the Delete checkbox below the alias,
then clicking the OK button.
Warning: Aliases are deleted by checking the Delete checkbox in the alias area, then clicking OK for the
interface. Do not click the Delete button at the bottom of this screen, which deletes the entire interface.
Multiple interfaces cannot be members of the same subnet.
See Multiple network interfaces
on a single subnet (https://forums.freenas.org/index.php?threads/multiple-network-interfaces-on-a-singlesubnet.20204/) for more information. Check the subnet mask if an error is shown when setting the IP
addresses on multiple interfaces.
This screen will not allow an interface’s IPv4 and IPv6 addresses to both be set as primary addresses. An
error is shown if both the IPv4 address and IPv6 address fields are filled in. Instead, set only one of these
address fields and create an alias for the other address.
7.3 IPMI
Beginning with version 9.2.1, FreeNAS® provides a graphical screen for configuring an IPMI interface. This
screen will only appear if the system hardware includes a Baseboard Management Controller (BMC).
IPMI provides side-band management if the graphical administrative interface becomes unresponsive. This
allows for a few vital functions, such as checking the log, accessing the BIOS setup, and powering on the
system without requiring physical access to the system. IPMI can also be used to allow another person
remote access to the system to assist with a configuration or troubleshooting issue. Before configuring
IPMI, ensure that the management interface is physically connected to the network. The IPMI device may
share the primary Ethernet interface, or it may be a dedicated separate IPMI interface.
Warning: It is recommended to first ensure that the IPMI has been patched against the Remote Management Vulnerability before enabling IPMI. This article (http://www.ixsystems.com/whats-new/how-tofix-the-ipmi-remote-management-vulnerability/) provides more information about the vulnerability and
how to fix it.
Note: Some IPMI implementations require updates to work with newer versions of Java. See PSA: Java 8
Update 131 breaks ASRock’s IPMI Virtual console (https://forums.freenas.org/index.php?threads/psa-java8-update-131-breaks-asrocks-ipmi-virtual-console.53911/) for more information.
IPMI is configured from Network → IPMI. The IPMI configuration screen, shown in Figure 7.3, provides a
shortcut to the most basic IPMI configuration. Those already familiar with IPMI management tools can use
them instead. Table 7.3 summarizes the options available when configuring IPMI with the FreeNAS® GUI.
98
Chapter 7. Network
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 7.3: IPMI Configuration
Table 7.3: IPMI Options
Setting
Channel
Password
Value
drop-down menu
string
DHCP
IPv4 Address
IPv4 Netmask
IPv4 Default
Gateway
VLAN ID
checkbox
string
drop-down menu
string
string
Description
select the channel to use
enter the password used to connect to the IPMI interface from a
web browser
if left unchecked, the following three fields must be set
IP address used to connect to the IPMI web GUI
subnet mask associated with the IP address
default gateway associated with the IP address
enter the VLAN identifier if the IPMI out-of-band management
interface is not on the same VLAN as management networking
After configuration, the IPMI interface is accessed using a web browser and the IP address specified in the
configuration. The management interface prompts for a username and the configured password. Refer to
the IPMI device’s documentation to determine the default administrative username.
After logging in to the management interface, the default administrative username can be changed, and
additional users created. The appearance of the IPMI utility and the functions that are available vary depending on the hardware.
A command-line utility called ipmitool is available to control many features of the IPMI interface. See How
To: Change IPMI Sensor Thresholds using ipmitool (https://forums.freenas.org/index.php?resources/howto-change-ipmi-sensor-thresholds-using-ipmitool.35/) for some examples.
7.3. IPMI
99
FreeNAS® 11.0-U4 User Guide, Release 11.0
7.4 Link Aggregations
FreeNAS® uses FreeBSD’s lagg(4) (http://www.freebsd.org/cgi/man.cgi?query=lagg) interface to provide link
aggregation and link failover. The lagg interface allows aggregation of multiple network interfaces into a single virtual lagg interface, providing fault-tolerance and high-speed multi-link throughput. The aggregation
protocols supported by lagg determine which ports are used for outgoing traffic and whether a specific port
accepts incoming traffic. The link state of the lagg interface is used to validate whether the port is active.
Aggregation works best on switches supporting LACP, which distributes traffic bi-directionally while responding to failure of individual links. FreeNAS® also supports active/passive failover between pairs of links. The
LACP and load-balance modes select the output interface using a hash that includes the Ethernet source
and destination address, VLAN tag (if available), IP source and destination address, and flow label (IPv6
only). The benefit can only be observed when multiple clients are transferring files from the NAS. The flow
entering into the NAS depends on the Ethernet switch load-balance algorithm.
The lagg driver currently supports several aggregation protocols, although only Failover is recommended on
network switches that do not support LACP:
Failover: the default protocol. Sends traffic only through the active port. If the master port becomes
unavailable, the next active port is used. The first interface added is the master port; any interfaces added
after that are used as failover devices. By default, received traffic is only accepted when received through the
active port. This constraint can be relaxed, which is useful for certain bridged network setups, by creating
a a tunable with a Variable of net.link.lagg.failover_rx_all, a Value of a non-zero integer, and a Type of Sysctl in
System → Tunables → Add Tunable.
LACP: supports the IEEE 802.3ad Link Aggregation Control Protocol (LACP) and the Marker Protocol. LACP
negotiates a set of aggregable links with the peer into one or more link aggregated groups (LAGs). Each LAG
is composed of ports of the same speed, set to full-duplex operation. Traffic is balanced across the ports in
the LAG with the greatest total speed; in most cases there will only be one LAG which contains all ports. In
the event of changes in physical connectivity, link aggregation will quickly converge to a new configuration.
LACP must be configured on the switch, and LACP does not support mixing interfaces of different speeds.
Only interfaces that use the same driver, like two igb ports, are recommended for LACP. Using LACP for iSCSI
is not recommended, as iSCSI has built-in multipath features which are more efficient.
Load Balance: balances outgoing traffic across the active ports based on hashed protocol header information and accepts incoming traffic from any active port. This is a static setup and does not negotiate
aggregation with the peer or exchange frames to monitor the link. The hash includes the Ethernet source
and destination address, VLAN tag (if available), and IP source and destination address. Requires a switch
which supports IEEE 802.3ad static link aggregation.
Round Robin: distributes outgoing traffic using a round-robin scheduler through all active ports and accepts incoming traffic from any active port. This mode can cause unordered packet arrival at the client. This
has a side effect of limiting throughput as reordering packets can be CPU intensive on the client. Requires
a switch which supports IEEE 802.3ad static link aggregation.
None: this protocol disables any traffic without disabling the lagg interface itself.
Note: When using LACP, verify that the switch is configured for active LACP. Passive LACP is not supported.
7.4.1 LACP, MPIO, NFS, and ESXi
LACP bonds Ethernet connections to improve bandwidth. For example, four physical interfaces can be
used to create one mega interface. However, it cannot increase the bandwidth for a single conversation.
It is designed to increase bandwidth when multiple clients are simultaneously accessing the same system.
100
Chapter 7. Network
FreeNAS® 11.0-U4 User Guide, Release 11.0
It also assumes that quality Ethernet hardware is used and it will not make much difference when using
inferior Ethernet chipsets such as a Realtek.
LACP reads the sender and receiver IP addresses and, if they are deemed to belong to the same TCP connection, always sends the packet over the same interface to ensure that TCP does not need to reorder
packets. This makes LACP ideal for load balancing many simultaneous TCP connections, but does nothing
for increasing the speed over one TCP connection.
MPIO operates at the iSCSI protocol level. For example, if four IP addresses are created and there are
four simultaneous TCP connections, MPIO will send the data over all available links. When configuring
MPIO, make sure that the IP addresses on the interfaces are configured to be on separate subnets with
non-overlapping netmasks, or configure static routes to do point-to-point communication. Otherwise, all
packets will pass through one interface.
LACP and other forms of link aggregation generally do not work well with virtualization solutions.
In a virtualized environment, consider the use of iSCSI MPIO through the creation of an iSCSI Portal with at least two network cards on different networks. This allows an iSCSI initiator to recognize multiple links to a target, using them for increased bandwidth or redundancy. This how-to
(https://fojta.wordpress.com/2010/04/13/iscsi-and-esxi-multipathing-and-jumbo-frames/) contains instructions for configuring MPIO on ESXi.
NFS does not understand MPIO. Therefore, one fast interface is needed, since creating an iSCSI portal will
not improve bandwidth when using NFS. LACP does not work well to increase the bandwidth for point-topoint NFS (one server and one client). LACP is a good solution for link redundancy or for one server and
many clients.
7.4.2 Creating a Link Aggregation
Before creating a link aggregation, double-check that no interfaces have been manually configured in
Network → Interfaces → View Interfaces.
If any manually-configured interfaces exist, delete them as lagg creation fails if any interfaces are manually configured.
Note: Creating or editing link aggregations can disconnect clients using the FreeNAS® computer. Please
verify that clients have saved their work and are not connected through the affected networks before making changes.
Figure 7.4 shows the configuration options when adding a lagg interface using Network → Link
Aggregations → Create Link Aggregation.
7.4. Link Aggregations
101
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 7.4: Creating a lagg Interface
Note: If interfaces are installed but do not appear in the Physical NICs list, check that a FreeBSD driver for
the interface exists here (http://www.freebsd.org/releases/11.0R/hardware.html#ETHERNET).
To create a link aggregation, select the desired Protocol Type. LACP is preferred. If the network switch does
not support LACP, choose Failover. Highlight the interfaces to associate with the lagg device, and click the
OK button.
Once the lagg device has been created, click its entry to enable its Edit, Delete, and Edit Members buttons.
Clicking the Edit button for a lagg opens the configuration screen shown in Figure 7.5. Table 7.4 describes
the options in this screen.
If the network interface used to connect to the FreeNAS® web GUI is a member of the lagg, the network
connection will be lost when the new lagg is created. The switch settings might also require changes to
communicate through the new lagg interface.
The IP address of the new lagg can be set with DHCP or manually from the console setup menu. If the IP
address is set manually, it might also be necessary to enter a default gateway to allow access to the GUI
from the new lagg interface.
102
Chapter 7. Network
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 7.5: Editing a lagg
Table 7.4: Configurable Options for a lagg
Setting
NIC
Interface
Name
DHCP
Value
string
string
IPv4 Address
IPv4 Netmask
Auto configure IPv6
IPv6 Address
IPv6 Prefix
Length
Options
string
drop-down menu
checkbox
Description
read-only; automatically assigned the next available numeric ID
by default same as device (NIC) name, can be changed to a
more descriptive value
check if the lagg device will get IP address info from DHCP
server
enter a static IP address if DHCP is left unchecked
enter a netmask if DHCP is left unchecked
check only if DHCP server available to provide IPv6 address info
string
drop-down menu
optional
required if an IPv6 address is entered
string
additional ifconfig(8)
(http://www.freebsd.org/cgi/man.cgi?query=ifconfig) options
checkbox
This screen also allows the configuration of an alias for the lagg interface. Multiple aliases can be added
with the Add extra Alias link.
7.4. Link Aggregations
103
FreeNAS® 11.0-U4 User Guide, Release 11.0
Click the Edit Members button, click the entry for a member, then click its Edit button to see the configuration
screen shown in Figure 7.6. The configurable options are summarized in Table 7.5.
Fig. 7.6: Editing a Member Interface
Table 7.5: Configuring a Member Interface
Setting
LAGG Interface group
LAGG Priority
Number
Value
drop-down menu
Description
select the member interface to configure
integer
LAGG Physical
NIC
Options
drop-down menu
order of selected interface within the lagg; configure a failover
to set the master interface to 0 and the other interfaces to 1, 2,
etc.
physical interface of the selected member
string
additional parameters from ifconfig(8)
(http://www.freebsd.org/cgi/man.cgi?query=ifconfig)
Options can be set at the lagg level using the Edit button, or at the individual parent interface level using
the Edit Members button. Changes are typically made at the lagg level (Figure 7.5) as each interface member
will inherit from the lagg. To configure at the interface level (Figure 7.6) instead, the configuration must be
repeated for each interface within the lagg. Some options can only be set on the parent interfaces and are
inherited by the lagg interface. For example, to set the MTU on a lagg, use Edit Members to set the MTU for
each parent interface.
104
Chapter 7. Network
FreeNAS® 11.0-U4 User Guide, Release 11.0
Note: A reboot is required after changing the MTU to create a jumbo frame lagg.
To see if the link aggregation is properly load balancing, run this command from Shell (page 288):
systat -ifstat
More
information
about
this
command
(http://www.freebsd.org/cgi/man.cgi?query=systat).
can
be
found
at
systat(1)
7.5 Network Summary
Network → Network Summary shows a quick summary of the addressing information of every configured interface. For each interface name, the configured IPv4 and IPv6 addresses, DNS servers, and default
gateway are displayed.
7.6 Static Routes
No static routes are defined on a default FreeNAS® system. If a static route is required to reach portions
of the network, add the route with Network → Static Routes → Add Static Route, shown in
Figure 7.7.
Fig. 7.7: Adding a Static Route
The available options are summarized in Table 7.6.
Table 7.6: Static Route Options
Setting
Destination
network
Gateway
Description
Value
integer
Description
use the format A.B.C.D/E where E is the CIDR mask
integer
string
enter the IP address of the gateway
optional
Added static routes are shown in View Static Routes. Click a route’s entry to access the Edit and Delete buttons.
7.6. Static Routes
105
FreeNAS® 11.0-U4 User Guide, Release 11.0
7.7 VLANs
FreeNAS® uses FreeBSD’s vlan(4) (http://www.freebsd.org/cgi/man.cgi?query=vlan) interface to demultiplex
frames with IEEE 802.1q tags. This allows nodes on different VLANs to communicate through a layer 3 switch
or router. A vlan interface must be assigned a parent interface and a numeric VLAN tag. A single parent can
be assigned to multiple vlan interfaces provided they have different tags.
Note:
VLAN tagging is the only 802.1q feature that is implemented.
Additionally, not
all Ethernet interfaces support full VLAN processing.
See the HARDWARE section of vlan(4)
(http://www.freebsd.org/cgi/man.cgi?query=vlan) for details.
Click Network → VLANs → Add VLAN, to see the screen shown in Figure 7.8.
Fig. 7.8: Adding a VLAN
Table 7.7 summarizes the configurable fields.
Table 7.7: Adding a VLAN
Setting
Virtual Interface
Parent Interface
Value
string
VLAN Tag
integer
Description
string
drop-down menu
Description
use the format vlanX where X is a number representing a vlan
interface not currently being used as a parent
usually an Ethernet card connected to a properly configured
switch port; note that newly created Link Aggregations (page 100)
will not appear in the drop-down until the system is rebooted
number between 1 and 4095 which matches a numeric tag set
up in the switched network
optional
The parent interface of a VLAN must be up, but it can have an IP address or it can be unconfigured, depending upon the requirements of the VLAN configuration. This makes it difficult for the GUI to do the
right thing without trampling the configuration. To remedy this, after adding the VLAN, go to Network →
Interfaces → Add Interface. Select the parent interface from the NIC drop-down menu and in the
Options field, type up. This will bring up the parent interface. If an IP address is required, it can be configured
using the rest of the options in the Add Interface screen.
106
Chapter 7. Network
FreeNAS® 11.0-U4 User Guide, Release 11.0
Warning: Creating a vlan will cause network connectivity to be interrupted. Accordingly, the GUI will
provide a warning and an opportunity to cancel the vlan creation.
7.7. VLANs
107
CHAPTER
EIGHT
STORAGE
The Storage section of the graphical interface allows configuration of these options:
• Volumes (page 108) creates and manages storage volumes.
• Periodic Snapshot Tasks (page 134) schedules automatic creation of filesystem snapshots.
• Replication Tasks (page 136) automates the replication of snapshots to a remote system.
• Scrubs (page 147) schedules scrubs as part of ongoing disk maintenance.
• Snapshots (page 148) manages local snapshots.
• VMware-Snapshot (page 150) coordinates ZFS snapshots with a VMware datastore.
8.1 Volumes
The Volumes section of the FreeNAS® graphical interface can be used to format ZFS pools, import a disk to
copy its data into an existing pool, or import an existing ZFS pool. It can also be used to create ZFS datasets
and zvols and to manage their permissions.
Note: In ZFS terminology, the storage that is managed by ZFS is referred to as a pool. The FreeNAS®
graphical interface uses the term volume to refer to a ZFS pool.
Proper storage design is important for any NAS. Please read through this entire chapter before configuring storage disks. All of the features are described to help make it clear which will be the most
benefit for your uses, and caveats or caveats or hardware restrictions which could limit their use.
8.1.1 Volume Manager
Volume Manager is used to add disks to a ZFS pool. Any old data on added disks is overwritten, so save it
elsewhere before reusing a disk. Please see the ZFS Primer (page 323) for information on ZFS redundancy
with multiple disks before using Volume Manager.
Selecting Storage → Volumes → Volume Manager opens a screen like the example shown in Figure
8.1.
108
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.1: Creating a ZFS Pool Using Volume Manager
Table 8.1 summarizes the configuration options of this screen.
Table 8.1: Options When Creating a ZFS Volume
Setting
Volume name
Value
string
Volume to extend
Encryption
dropdown
menu
checkbox
Available disks
display
Volume layout
drag and
drop
Add Extra Device
button
Manual setup
button
Description
ZFS volumes must conform to these naming conventions (http://docs.oracle.com/cd/E23824_01/html/8211448/gbcpt.html); it is recommended to choose a name that
will stick out in the logs (e.g. not data or freenas)
used to extend an existing ZFS pool; see Extending a ZFS Volume
(page 112) for instructions
read the section on Encryption (page 110) before choosing to
use encryption
displays the number and size of available disks; hover over show
to list the available device names; click the + to add all of the
disks to the pool
click and drag the icon to select the desired number of disks for
a vdev; once at least one disk is selected, the layouts supported
by the selected number of disks will be added to the drop-down
menu
used to configure multiple vdevs or to add log or cache devices
during pool creation
used to create a pool manually (not recommended); see Manual
Setup (page 111) for details
Drag the slider to select the desired number of disks. Volume Manager displays the resulting storage capacity, including taking swap space into account. To change the layout or the number of disks, use the mouse
to drag the slider to the desired volume layout. The Volume layout drop-down menu can also be clicked if a
different level of redundancy is required.
8.1. Volumes
109
FreeNAS® 11.0-U4 User Guide, Release 11.0
Note: For performance and capacity reasons, this screen does not allow creating a volume from disks of
differing sizes. While it is not recommended, it is possible to create a volume in this situation by using the
Manual setup button and following the instructions in Manual Setup (page 111).
Volume Manager only allows choosing a configuration if enough disks have been selected to create that
configuration. These layouts are supported:
• Stripe: requires at least one disk
• Mirror: requires at least two disks
• RAIDZ1: requires at least three disks
• RAIDZ2: requires at least four disks
• RAIDZ3: requires at least five disks
• log device: requires at least one dedicated device, a fast, low-latency, power-protected SSD is recommended
• cache device: requires at least one dedicated device, SSD is recommended
When more than five disks are used, consideration must be given to the optimal layout for the best performance and scalability. An overview of the recommended disk group sizes as well as more information
about log and cache devices can be found in the ZFS Primer (page 323).
The Add Volume button warns that existing data will be cleared. In other words, creating a new volume
reformats the selected disks. If the existing data is meant to be preserved, click the Cancel button and refer
to Import Disk (page 120) and Import Volume (page 121) to see if the existing format is supported. If so,
perform that action instead. If the current storage format is not supported, it is necessary to back up the
data to external media, format the disks, then restore the data to the new volume.
Depending on the size and number of disks, the type of controller, and whether encryption is selected,
creating the volume may take some time. After the volume is created, the screen will refresh and the new
volume is listed in the tree under Storage → Volumes. Click the + next to the volume name to access its
Change Permissions (page 113), Create Dataset (page 115), and Create zvol (page 118) options.
Encryption
FreeNAS® supports GELI (http://www.freebsd.org/cgi/man.cgi?query=geli) full disk encryption for ZFS volumes. It is important to understand the details when considering whether encryption is right for your
FreeNAS® system:
• This is not the encryption method used by Oracle’s version of ZFS. That version is not open source
and is the property of Oracle.
• This is full disk encryption and not per-filesystem encryption. The underlying drives are first encrypted, then the pool is created on top of the encrypted devices.
• This type of encryption is primarily targeted at users who store sensitive data and want to retain the
ability to remove disks from the pool without having to first wipe the disk’s contents.
• This design is only suitable for safe disposal of disks independent of the encryption key. As long as the
key and the disks are intact, the system is vulnerable to being decrypted. The key should be protected
by a strong passphrase and any backups of the key should be securely stored.
• On the other hand, if the key is lost, the data on the disks is inaccessible. Always back up the key!
• The encryption key is per ZFS volume (pool). Multiple pools each have their own encryption key.
110
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
• If the system has a lot of disks, performance will suffer if the CPU does not support AESNI (https://en.wikipedia.org/wiki/AES-NI#Supporting_CPUs) or if no crypto hardware is installed.
Without hardware acceleration, there will be about a 20% performance decrease for a single
disk. Performance degradation increases with more disks. As data is written, it is automatically encrypted. As data is read, it is decrypted on the fly. If the processor supports the
AES-NI instruction set, there is very little, if any, degradation in performance when using encryption. This forum post (https://forums.freenas.org/index.php?threads/encryption-performancebenchmarks.12157/) compares the performance of various CPUs.
• Data in the ARC cache and the contents of RAM are unencrypted.
• Swap is always encrypted, even on unencrypted volumes.
• There is no way to convert an existing, unencrypted volume. Instead, the data must be backed up,
the existing pool destroyed, a new encrypted volume created, and the backup restored to the new
volume.
• Hybrid pools are not supported. In other words, newly created vdevs must match the existing encryption scheme. When extending a volume, Volume Manager automatically encrypts the new vdev being
added to the existing encrypted pool.
• The more drives in an encrypted volume, the more encryption and decryption overhead. Encrypted
volumes composed of more than eight drives can suffer severe performance penalties, even
with AES-NI encryption acceleration. If encryption is desired, please benchmark such volumes
before using them in production.
Note: The encryption facility used by FreeNAS® is designed to protect against physical theft of the disks.
It is not designed to protect against unauthorized software access. Ensure that only authorized users have
access to the administrative GUI and that proper permissions are set on shares if sensitive data is stored
on the system.
To create an encrypted volume, check the Encryption box shown in Figure 8.1. A pop-up message shows a
reminder that it is extremely important to make a backup of the key. Without the key, the data on the
disks is inaccessible. Refer to Managing Encrypted Volumes (page 127) for instructions.
Manual Setup
The Manual Setup button shown in Figure 8.1 can be used to create a ZFS volume manually. While this is not
recommended, it can, for example, be used to create a non-optimal volume containing disks of different
sizes.
Note: The usable space of each disk in a volume is limited to the size of the smallest disk in the volume.
Because of this, creating volumes with disks of the same size through the Volume Manager is recommended.
Figure 8.2 shows the Manual Setup screen. Table 8.2 shows the available options.
8.1. Volumes
111
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.2: Manually Creating a ZFS Volume
Note: Because of the disadvantages of creating volumes with disks of different sizes, the displayed list of
disks is sorted by size.
Table 8.2: Manual Setup Options
Setting
Volume name
Value
string
Encryption
checkbox
Member disks
Deduplication
list
dropdown
menu
bullet
selection
ZFS Extra
Description
ZFS volumes must conform to these naming conventions (http://docs.oracle.com/cd/E19082-01/8172271/gbcpt/index.html) ; it is recommended to choose a name
that will stick out in the logs (e.g. not data or freenas)
read the section on Encryption (page 110) before choosing to
use encryption
highlight desired number of disks from list of available disks
choices are Off, Verify, and On; carefully consider the section on
Deduplication (page 117) before changing this setting
used to specify if disk is used for storage (None), a log device, a
cache device, or a spare
Extending a ZFS Volume
The Volume to extend drop-down menu in Storage → Volumes → Volume Manager, shown in Figure
8.1, can be used to add additional disks to an existing ZFS volume. This drop-down menu will be empty if
no ZFS volume exists.
Note: If the existing volume is encrypted, a warning message will remind you that the operation of ex-
112
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
tending a volume will reset the passphrase and recovery key. After extending the volume, you should
immediately recreate both using the instructions in Managing Encrypted Volumes (page 127).
After an existing volume has been selected from the drop-down menu, drag and drop the desired disks and
select the desired volume layout. For example, disks can be added to increase the capacity of the ZFS pool.
When adding disks to increase the capacity of a volume, ZFS supports the addition of virtual devices, known
as vdevs, to an existing ZFS pool. A vdev can be a single disk, a stripe, a mirror, a RAIDZ1, RAIDZ2, or a
RAIDZ3. After a vdev is created, more drives cannot be added to that vdev; however, you can stripe
a new vdev (and its disks) with another of the same type of existing vdev to increase the overall size of
ZFS the pool. In other words, when you extend a ZFS volume, you are really striping similar vdevs. Here are
some examples:
• to extend a ZFS stripe, add one or more disks. Since there is no redundancy, you do not have to add
the same amount of disks as the existing stripe.
• to extend a ZFS mirror, add the same number of drives. The resulting striped mirror is a RAID 10. For
example, if you have 10 drives, you could start by creating a mirror of two drives, extending this mirror
by creating another mirror of two drives, and repeating three more times until all 10 drives have been
added.
• to extend a three drive RAIDZ1, add three additional drives. The result is a RAIDZ+0, similar to RAID
50 on a hardware controller.
• to extend a RAIDZ2 requires a minimum of four additional drives. The result is a RAIDZ2+0, similar to
RAID 60 on a hardware controller.
If you try to add an incorrect number of disks to the existing vdev, an error message will appear, indicating the number of disks that are needed. You will need to select the correct number of disks in order to
continue.
Adding L2ARC or ZIL Devices
Storage → Volumes → Volume Manager (see Figure 8.1) is also used to add L2ARC or ZIL SSDs to
improve specific types of volume performance. This is described in more detail in the ZFS Primer (page 323).
After the SSDs have been physically installed, click the Volume Manager button and choose the volume from
the Volume to extend drop-down menu. Click the + next to the SSD in the Available disks list. In the Volume
layout drop-down menu, select Cache (L2ARC) to add a cache device, or Log (ZIL) to add a log device. Finally,
click Extend Volume to add the SSD.
8.1.2 Change Permissions
Setting permissions is an important aspect of configuring volumes. The graphical administrative interface is
meant to set the initial permissions for a volume or dataset in order to make it available as a share. Once a
share is available, the client operating system should be used to fine-tune the permissions of the files and
directories that are created by the client.
The chapter on Sharing (page 165) contains configuration examples for several types of permission scenarios. This section provides an overview of the screen that is used to set permissions.
Note: For users and groups to be available, they must either be first created using the instructions in Account (page 47) or imported from a directory service using the instructions in Directory Services (page 152).
8.1. Volumes
113
FreeNAS® 11.0-U4 User Guide, Release 11.0
If more than 50 users or groups are available, the drop-down menus described in this section will automatically truncate their display to 50 for performance reasons. In this case, start to type in the desired user or
group name so that the display narrows its search to matching results.
After a volume or dataset is created, it is listed by its mount point name in Storage → Volumes. Clicking
the Change Permissions icon for a specific volume/dataset displays the screen shown in Figure 8.3. Table 8.3
summarizes the options in this screen.
Fig. 8.3: Changing Permissions on a Volume or Dataset
Table 8.3: Options When Changing Permissions
Setting
Apply Owner (user)
Value
checkbox
Owner (user)
dropdown
menu
checkbox
Apply Owner (group)
Owner (group)
Apply Mode
114
dropdown
menu
checkbox
Description
uncheck to prevent new permission change from being applied
to Owner (user), see Note below
user to control the volume/dataset; users which were manually
created or imported from a directory service will appear in the
drop-down menu
uncheck to prevent new permission change from being applied
to Owner (group), see Note below
group to control the volume/dataset; groups which were manually created or imported from a directory service will appear in
the drop-down menu
uncheck to prevent new permission change from being applied
to Mode, see Note below
Continued on next page
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Mode
Permission Type
Set permission recursively
Table 8.3 – continued from previous page
Value
Description
checkboxes only applies to the Unix or Mac “Permission Type” so will be
grayed out if Windows is selected
bullet
choices are Unix, Mac or Windows; select the type which matches
selection
the type of client accessing the volume/dataset
checkbox
if checked, permissions will also apply to subdirectories of the
volume/dataset; if data already exists on the volume/dataset,
change the permissions on the client side to prevent a performance lag
Note: The Apply Owner (user), Apply Owner (group), and Apply Mode checkboxes allow fine-tuning of the
change permissions behavior. By default, all boxes are checked and FreeNAS® resets the owner, group, and
mode when the Change button is clicked. These checkboxes allow choosing which settings to change. For
example, to change just the Owner (group) setting, uncheck the boxes Apply Owner (user) and Apply Mode.
The Windows Permission Type is used for SMB shares or when the FreeNAS® system is a member of an Active
Directory domain. This adds ACLs to traditional Unix permissions. When the Windows Permission Type is set,
ACLs are set to Windows defaults for new files and directories. A Windows client can be used to further
fine-tune permissions as needed.
The Unix Permission Type is usually used with NFS shares. These permissions are compatible with most network clients and generally work well with a mix of operating systems or clients. However, Unix permissions
do not support Windows ACLs and should not be used with SMB shares.
The Mac Permission Type is used with AFP shares.
After a volume or dataset has been set to Windows, it cannot be changed to Unix permissions because that
would remove extended permissions provided by Windows ACLs.
8.1.3 Create Dataset
An existing ZFS volume can be divided into datasets. Permissions, compression, deduplication, and quotas
can be set on a per-dataset basis, allowing more granular control over access to storage data. A dataset
is similar to a folder in that you can set permissions; it is also similar to a filesystem in that you can set
properties such as quotas and compression as well as create snapshots.
Note: ZFS provides thick provisioning using quotas and thin provisioning using reserved space.
Selecting an existing ZFS volume in the tree and clicking Create Dataset shows the screen in Figure 8.4.
8.1. Volumes
115
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.4: Creating a ZFS Dataset
Table 8.4 summarizes the options available when creating a ZFS dataset. Some settings are only available
in Advanced Mode. To see these settings, either click the Advanced Mode button, or configure the system to
always display these settings by checking the box Show advanced fields by default in System → Advanced.
Most attributes, except for the Dataset Name, Case Sensitivity, and Record Size, can be changed after dataset
creation by highlighting the dataset name and clicking its Edit Options button in Storage → Volumes.
Table 8.4: ZFS Dataset Options
Setting
Dataset Name
Comments
Compression Level
Share type
Case Sensitivity
Enable atime
Quota for this dataset
116
Value
string
string
dropdown
menu
dropdown
menu
dropdown
menu
Inherit,
On, or Off
integer
Description
mandatory; enter a unique name for the dataset
short comments or user notes about this dataset
see the section on Compression (page 118) for a description of
the available algorithms
select the type of share that will be used on the dataset; choices
are UNIX for an NFS share, Windows for a SMB share, or Mac for
an AFP share
choices are sensitive (default, assumes filenames are case sensitive), insensitive (assumes filenames are not case sensitive), or
mixed (understands both types of filenames)
controls whether the access time for files is updated when they
are read; setting this property to Off avoids producing log traffic
when reading files and can result in significant performance
gains
only available in Advanced Mode; default of 0 disables quotas;
specifying a value means to use no more than the specified size
and is suitable for user datasets to prevent users from hogging
available space
Continued on next page
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Quota for this dataset
and all children
Reserved space for this
dataset
Reserved space for this
dataset and all children
ZFS Deduplication
Record Size
Table 8.4 – continued from previous page
Value
Description
integer
only available in Advanced Mode; a specified value applies to
both this dataset and any child datasets
integer
only available in Advanced Mode; default of 0 is unlimited; specifying a value means to keep at least this much space free and
is suitable for datasets containing logs which could take up all
available free space
integer
only available in Advanced Mode; a specified value applies to
both this dataset and any child datasets
dropread the section on Deduplication (page 117) before making a
down
change to this setting
menu
droponly available in Advanced Mode; while ZFS automatically adapts
down
the record size dynamically to adapt to data, if the data has a
menu
fixed size (e.g. a database), matching that size may result in better performance
After a dataset is created, you can click on that dataset and select Create Dataset, thus creating a nested
dataset, or a dataset within a dataset. A zvol can also be created within a dataset. When creating datasets,
double-check that you are using the Create Dataset option for the intended volume or dataset. If you get
confused when creating a dataset on a volume, click all existing datasets to close them–the remaining Create
Dataset will be for the volume.
Deduplication
Deduplication is the process of ZFS transparently reusing a single copy of duplicated data to save space.
Depending on the amount of duplicate data, deduplicaton can improve storage capacity, as less data is
written and stored. However, deduplication is RAM intensive. A general rule of thumb is 5 GB of RAM per
terabyte of deduplicated storage. In most cases, compression provides storage gains comparable to
deduplication with less impact on performance.
In FreeNAS® , deduplication can be enabled during dataset creation. Be forewarned that there is no
way to undedup the data within a dataset once deduplication is enabled, as disabling deduplication has NO EFFECT on existing data. The more data written to a deduplicated dataset, the more RAM
it requires. When the system starts storing the DDTs (dedup tables) on disk because they no longer fit
into RAM, performance craters. Further, importing an unclean pool can require between 3-5 GB of RAM
per terabyte of deduped data, and if the system does not have the needed RAM, it will panic. The only
solution is to add more RAM or recreate the pool. Think carefully before enabling dedup! This article (http://constantin.glez.de/blog/2011/07/zfs-dedupe-or-not-dedupe) provides a good description of the
value versus cost considerations for deduplication.
Unless a lot of RAM and a lot of duplicate data is available, do not change the default deduplication
setting of “Off”. For performance reasons, consider using compression rather than turning this option on.
If deduplication is changed to On, duplicate data blocks are removed synchronously. The result is that only
unique data is stored and common components are shared among files. If deduplication is changed to
Verify, ZFS will do a byte-to-byte comparison when two blocks have the same signature to make sure that
the block contents are identical. Since hash collisions are extremely rare, Verify is usually not worth the
performance hit.
After deduplication is enabled, the only way to disable it is to use the zfs set dedup=off
dataset_name command from Shell (page 288). However, any data that has already been deduplicated
Note:
8.1. Volumes
117
FreeNAS® 11.0-U4 User Guide, Release 11.0
will not be un-deduplicated. Only newly stored data after the property change will not be deduplicated. The
only way to remove existing deduplicated data is to copy all of the data off of the dataset, set the property to
off, then copy the data back in again. Alternately, create a new dataset with ZFS Deduplication left disabled,
copy the data to the new dataset, and destroy the original dataset.
Tip: Deduplication is often considered when using a group of very similar virtual machine images. However,
other features of ZFS can provide dedup-like functionality more efficiently. For example, create a dataset
for a standard VM, then clone that dataset for other VMs. Only the difference between each created VM
and the main dataset are saved, giving the effect of deduplication without the overhead.
Compression
When selecting a compression type, you need to balance performance with the amount of disk space saved
by compression. Compression is transparent to the client and applications as ZFS automatically compresses
data as it is written to a compressed dataset or zvol and automatically decompresses that data as it is read.
These compression algorithms are supported:
• lz4: recommended compression method as it allows compressed datasets to operate at near realtime speed. This algorithm only compresses the files that will benefit from compression. By default,
ZFS pools made using FreeNAS® 9.2.1 or higher use this compression method, meaning that this
algorithm is used if the Compression level is left at Inherit when creating a dataset or zvol.
• gzip: varies from levels 1 to 9 where gzip fastest (level 1) gives the least compression and gzip maximum
(level 9) provides the best compression but is discouraged due to its performance impact.
• zle: fast but simple algorithm to eliminate runs of zeroes.
• lzjb: provides decent data compression, but is considered deprecated as lz4 provides much better
performance.
If you select Off as the Compression level when creating a dataset or zvol, compression will not be used on
the dataset/zvol. This is not recommended as using lz4 has a negligible performance impact and allows for
more storage capacity.
8.1.4 Create zvol
A zvol is a feature of ZFS that creates a raw block device over ZFS. This allows you to use a zvol as an iSCSI
(page 223) device extent.
To create a zvol, select an existing ZFS volume or dataset from the tree then click Create zvol to open the
screen shown in Figure 8.5.
118
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.5: Creating a zvol
The configuration options are described in Table 8.5. Some settings are only available in Advanced Mode. To
see these settings, either click the Advanced Mode button or configure the system to always display these
settings by checking Show advanced fields by default in System → Advanced.
Table 8.5: zvol Configuration Options
Setting
zvol Name
Value
string
Comments
Size for this zvol
string
integer
Force size
checkbox
Compression level
dropdown
menu
Description
mandatory; enter a name for the zvol; note that there is a 63character limit on device path names in devfs, so using long zvol
names can prevent accessing zvols as devices; for example, a
zvol with a 70-character filename or path cannot be used as an
iSCSI extent
short comments or user notes about this zvol
specify size and value such as 10Gib; if the size is more than
80% of the available capacity, the creation will fail with an “out
of space” error unless Force size is checked
by default, the system will not let you create a zvol if that operation will bring the pool to over 80% capacity; while NOT recommended, checking this box will force the creation of the zvol in
this situation
see the section on Compression (page 118) for a description of
the available algorithms
Continued on next page
8.1. Volumes
119
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Sparse volume
Block size
Table 8.5 – continued from previous page
Value
Description
checkbox
used to provide thin provisioning; use with caution for when this
option is selected, writes will fail when the pool is low on space
droponly available in Advanced Mode and by default is based on the
down
number of disks in pool; can be set to match the block size of
menu
the filesystem which will be formatted onto the iSCSI target
8.1.5 Import Disk
The Volume → Import Disk screen, shown in Figure 8.6, is used to import a single disk that has been
formatted with the UFS, NTFS, MSDOS, or EXT2 filesystem. The import is meant to be a temporary measure
to copy the data from a disk to an existing ZFS dataset. Only one disk can be imported at a time.
Note: Imports of EXT3 or EXT4 filesystems are possible in some cases, although neither is fully supported.
EXT3 journaling is not supported, so those filesystems must have an external fsck utility, like the one provided by E2fsprogs utilities (http://e2fsprogs.sourceforge.net/), run on them before import. EXT4 filesystems
with extended attributes or inodes greater than 128 bytes are not supported. EXT4 filesystems with EXT3
journaling must have an fsck run on them before import, as described above.
Fig. 8.6: Importing a Disk
Use the drop-down menu to select the disk to import, select the type of filesystem on the disk, and browse
to the ZFS dataset that will hold the copied data. When you click Import Volume, the disk is mounted,
120
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
its contents are copied to the specified ZFS dataset, and the disk is unmounted after the copy operation
completes.
8.1.6 Import Volume
If you click Storage → Volumes → Import Volume, you can configure FreeNAS® to use an existing
ZFS pool. This action is typically performed when an existing FreeNAS® system is re-installed. Since the
operating system is separate from the storage disks, a new installation does not affect the data on the
disks. However, the new operating system needs to be configured to use the existing volume.
Figure 8.7 shows the initial pop-up window that appears when you import a volume.
Fig. 8.7: Initial Import Volume Screen
If you are importing an unencrypted ZFS pool, select No: Skip to import to open the screen shown in Figure
8.8.
Fig. 8.8: Importing a Non-Encrypted Volume
Existing volumes should be available for selection from the drop-down menu. In the example shown in
Figure 8.8, the FreeNAS® system has an existing, unencrypted ZFS pool. Once the volume is selected, click
the OK button to import the volume.
If an existing ZFS pool does not show in the drop-down menu, run zpool import from Shell (page 288) to
import the pool.
If you plan to physically install ZFS formatted disks from another system, be sure to export the drives on
that system to prevent an “in use by another machine” error during the import.
If you suspect that your hardware is not being detected, run camcontrol devlist from Shell (page 288).
If the disk does not appear in the output, check to see if the controller driver is supported or if it needs to
be loaded using Tunables (page 67).
8.1. Volumes
121
FreeNAS® 11.0-U4 User Guide, Release 11.0
Importing an Encrypted Pool
If you are importing an existing GELI-encrypted ZFS pool, you must decrypt the disks before importing the
pool. In Figure 8.7, select Yes: Decrypt disks to access the screen shown in Figure 8.9.
Fig. 8.9: Decrypting Disks Before Importing a ZFS Pool
Select the disks in the encrypted pool, browse to the location of the saved encryption key, input the
passphrase associated with the key, then click OK to decrypt the disks.
Note: The encryption key is required to decrypt the pool. If the pool cannot be decrypted, it cannot be
re-imported after a failed upgrade or lost configuration. This means that it is very important to save a copy
of the key and to remember the passphrase that was configured for the key. Refer to Managing Encrypted
Volumes (page 127) for instructions on how to manage the keys for encrypted volumes.
Once the pool is decrypted, it will appear in the drop-down menu of Figure 8.8. Click the OK button to finish
the volume import.
8.1.7 View Disks
Storage → Volumes → View Disks shows all of the disks recognized by the FreeNAS® system. An
example is shown in Figure 8.10.
122
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.10: Viewing Disks
The current configuration of each device is displayed. Click a disk entry and the Edit button to change its
configuration. The configurable options are described in Table 8.6.
Table 8.6: Disk Options
Setting
Name
Serial
Description
HDD Standby
Value
string
string
string
dropdown
menu
Advanced Power Management
Enable S.M.A.R.T.
dropdown
menu
dropdown
menu
checkbox
S.M.A.R.T. extra options
string
Acoustic Level
8.1. Volumes
Description
read-only value showing FreeBSD device name for disk
read-only value showing the disk’s serial number
optional
indicates the time of inactivity (in minutes) before the drive enters standby mode in order to conserve energy; this forum post
(https://forums.freenas.org/index.php?threads/how-to-find-outif-a-drive-is-spinning-down-properly.2068/) demonstrates how
to determine if a drive has spun down
default is Disabled, can select a power management profile from
the menu
default is Disabled; can be modified for disks that understand AAM
(https://en.wikipedia.org/wiki/Automatic_acoustic_management)
enabled by default if the disk supports S.M.A.R.T.; unchecking
this box will disable any configured S.M.A.R.T. Tests (page 92) for
the disk
additional smartctl(8)
(https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in)
options
123
FreeNAS® 11.0-U4 User Guide, Release 11.0
Note: If a disk’s serial number is not displayed in this screen, use the smartctl command from Shell
(page 288). For example, to determine the serial number of disk ada0, type smartctl -a /dev/ada0 |
grep Serial.
The Wipe function is provided for when an unused disk is to be discarded.
Warning: Make certain that all data has been backed up and that the disk is no longer in use. Triplecheck that the correct disk is being selected to be wiped, as recovering data from a wiped disk is usually
impossible. If there is any doubt, physically remove the disk, verify that all data is still present on the
FreeNAS® system, and wipe the disk in a separate computer.
Clicking Wipe offers several choices. Quick erases only the partitioning information on a disk, making it easy
to reuse but without clearing other old data. For more security, Full with zeros overwrites the entire disk with
zeros, while Full with random data overwrites the entire disk with random binary data.
Quick wipes take only a few seconds. A Full with zeros wipe of a large disk can take several hours, and a Full
with random data takes longer. A progress bar is displayed during the wipe to track status.
8.1.8 Volumes
Storage → Volumes is used to view and further configure existing ZFS pools, datasets, and zvols. The
example shown in Figure 8.11 shows one ZFS pool (volume1) with two datasets (the one automatically created with the pool, volume1, and dataset1) and one zvol (zvol1).
Note that in this example, there are two datasets named volume1. The first represents the ZFS pool and its
Used and Available entries reflect the total size of the pool, including disk parity. The second represents the
implicit or root dataset and its Used and Available entries indicate the amount of disk space available for
storage.
Buttons are provided for quick access to Volume Manager, Import Disk, Import Volume, and View Disks. If the
system has multipath-capable hardware, an extra button will be added, View Multipaths. For each entry,
the columns indicate the Name, how much disk space is Used, how much disk space is Available, the type
of Compression, the Compression Ratio, the Status, whether it is mounted as read-only, and any Comments
entered for the volume.
Fig. 8.11: Viewing Volumes
Clicking the entry for a pool causes several buttons to appear at the bottom of the screen. The buttons
perform these actions:
124
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Detach Volume: allows you to either export the pool or to delete the contents of the pool, depending upon
the choice you make in the screen shown in Figure 8.12. The Detach Volume screen displays the current
used space and indicates if there are any shares, provides checkboxes to Mark the disks as new (destroy data)
and to Also delete the share’s configuration, asks if you are sure that you want to do this, and the browser
will turn red to alert you that you are about to do something that will make the data inaccessible. If you do
not check the box to mark the disks as new, the volume will be exported. This means that the data
is not destroyed and the volume can be re-imported at a later time. If you will be moving a ZFS pool from
one system to another, perform this export action first as it flushes any unwritten data to disk, writes data
to the disk indicating that the export was done, and removes all knowledge of the pool from the system. If
you do check the box to mark the disks as new, the pool and all the data in its datasets, zvols, and
shares will be destroyed and the underlying disks will be returned to their raw state.
Fig. 8.12: Detach or Delete a Volume
Scrub Volume: scrubs and scheduling them are described in more detail in Scrubs (page 147). This button
allows manually initiating a scrub. Scrubs are I/O intensive and can negatively impact performance. Avoid
initiating a scrub when the system is busy.
A Cancel button is provided to cancel a scrub. When a scrub is cancelled, it is abandoned. The next scrub to
run starts from the beginning, not where the cancelled scrub left off.
The status of a running scrub or the statistics from the last completed scrub can be seen by clicking the
Volume Status button.
Volume Status: as shown in the example in Figure 8.13, this screen shows the device name and status of
8.1. Volumes
125
FreeNAS® 11.0-U4 User Guide, Release 11.0
each disk in the ZFS pool as well as any read, write, or checksum errors. It also indicates the status of the
latest ZFS scrub. Clicking the entry for a device causes buttons to appear to edit the device’s options (shown
in Figure 8.14), offline or online the device, or replace the device (as described in Replacing a Failed Drive
(page 131)).
Upgrade: used to upgrade the pool to the latest ZFS features, as described in Upgrading a ZFS Pool (page 25).
This button does not appear if the pool is running the latest version of feature flags.
Fig. 8.13: Volume Status
Selecting a disk in Volume Status and clicking its Edit Disk button shows the screen in Figure 8.14. Table 8.6
summarizes the configurable options.
126
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.14: Editing a Disk
Note: Versions of FreeNAS® prior to 8.3.1 required a reboot to apply changes to the HDD Standby, Advanced Power Management, and Acoustic Level settings. As of 8.3.1, changes to these settings are applied
immediately.
Clicking a dataset in Storage → Volumes causes buttons to appear at the bottom of the screen, providing these options:
Change Permissions: edit the dataset’s permissions as described in Change Permissions (page 113).
Create Snapshot: create a one-time snapshot. To schedule the regular creation of snapshots, instead use
Periodic Snapshot Tasks (page 134).
Destroy Dataset: clicking the Destroy Dataset button causes the browser window to turn red to indicate
that this is a destructive action. The Destroy Dataset screen forces you to check the box I’m aware this will
destroy all child datasets and snapshots within this dataset before it will perform this action.
Edit Options: edit the volume’s properties described in Table 8.4. Note that it will not allow changing the
dataset’s name.
Create Dataset: used to create a child dataset within this dataset.
Create zvol: create a child zvol within this dataset.
Clicking a zvol in Storage → Volumes causes icons to appear at the bottom of the screen: Create Snapshot, Edit zvol, and Destroy zvol. Similar to datasets, a zvol’s name cannot be changed, and destroying a zvol
requires confirmation.
Managing Encrypted Volumes
If the Encryption box is checked during the creation of a pool, additional buttons appear in the entry for the
volume in Storage → Volumes. An example is shown in Figure 8.15.
8.1. Volumes
127
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.15: Encryption Icons Associated with an Encrypted Volume
These additional encryption buttons are used to:
Create/Change Passphrase: set and confirm a passphrase associated with the GELI encryption key. The
desired passphrase is entered and repeated for verification. A red warning is a reminder to Remember to
add a new recovery key as this action invalidates the previous recovery key. Unlike a password, a passphrase
can contain spaces and is typically a series of words. A good passphrase is easy to remember (like the
line to a song or piece of literature) but hard to guess (people who know you should not be able to guess
the passphrase). Remember this passphrase. An encrypted volume cannot be reimported without
it. In other words, if the passphrase is forgotten, the data on the volume can become inaccessible if it
becomes necessary to reimport the pool. Protect this passphrase, as anyone who knows it could reimport
the encrypted volume, thwarting the reason for encrypting the disks in the first place.
128
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.16: Add or Change a Passphrase to an Encrypted Volume
After the passphrase is set, the name of this button changes to Change Passphrase. After setting or changing
the passphrase, it is important to immediately create a new recovery key by clicking the Add recovery key
button. This way, if the passphrase is forgotten, the associated recovery key can be used instead.
Encrypted volumes with a passphrase display an additional lock button:
Fig. 8.17: Lock Button
These encrypted volumes can be locked. The data is not accessible until the volume is unlocked by suppying
the passphrase or encryption key, and the button changes to an unlock button:
Fig. 8.18: Unlock Button
To unlock the volume, click the unlock button to display the Unlock dialog:
8.1. Volumes
129
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.19: Unlock Locked Volume
Unlock the volume by entering a passphrase or using the Browse button to load the recovery key. If both a
passphrase and a recovery key are entered, only the passphrase is used. By default, the services listed will
restart when the volume is unlocked. This allows them to see the new volume and share or access data on
it. Individual services can be prevented from restarting by unchecking them. However, a service that is not
restarted might not be able to access the unlocked volume.
Download Key: download a backup copy of the GELI encryption key. The encryption key is saved to the
client system, not on the FreeNAS® system. The FreeNAS® administrative password must be entered,
then the directory in which to store the key is chosen. Since the GELI encryption key is separate from
the FreeNAS® configuration database, it is highly recommended to make a backup of the key. If the
key is ever lost or destroyed and there is no backup key, the data on the disks is inaccessible.
Encryption Re-key: generate a new GELI encryption key. Typically this is only performed when the administrator suspects that the current key may be compromised. This action also removes the current passphrase.
Add recovery key: generate a new recovery key. This screen prompts for the FreeNAS® administrative
password and then the directory in which to save the key. Note that the recovery key is saved to the client
system, not on the FreeNAS® system. This recovery key can be used if the passphrase is forgotten. Always
immediately add a recovery key whenever the passphrase is changed.
Remove recovery key: Typically this is only performed when the administrator suspects that the current
recovery key may be compromised. Immediately create a new passphrase and recovery key.
Note: The passphrase, recovery key, and encryption key must be protected. Do not reveal the passphrase
to others. On the system containing the downloaded keys, take care that the system and its backups are
protected. Anyone who has the keys has the ability to re-import the disks if they are discarded or stolen.
Warning: If a re-key fails on a multi-disk system, an alert is generated. Do not ignore this alert as
doing so may result in the loss of data.
130
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
8.1.9 View Multipaths
FreeNAS® uses gmultipath(8) (http://www.freebsd.org/cgi/man.cgi?query=gmultipath) to provide multipath
I/O (https://en.wikipedia.org/wiki/Multipath_I/O) support on systems containing hardware that is capable of
multipath. An example would be a dual SAS expander backplane in the chassis or an external JBOD.
Multipath hardware adds fault tolerance to a NAS as the data is still available even if one disk I/O path has
a failure.
FreeNAS® automatically detects active/active and active/passive multipath-capable hardware.
Any
multipath-capable devices that are detected will be placed in multipath units with the parent devices hidden. The configuration will be displayed in Storage → Volumes → View Multipaths. Note that this
option is not be displayed in the Storage → Volumes tree on systems that do not contain multipathcapable hardware.
8.1.10 Replacing a Failed Drive
With any form of redundant RAID, failed drives must be replaced as soon as possible to repair the degraded
state of the RAID. Depending on the hardware’s capabilities, it might be necessary to reboot to replace the
failed drive. Hardware that supports AHCI does not require a reboot.
Note: Striping (RAID0) does not provide redundancy. If a disk in a stripe fails, the volume will be destroyed
and must be recreated and the data restored from backup.
Note: If the volume is encrypted with GELI, refer to Replacing an Encrypted Drive (page 133) before proceeding.
Before physically removing the failed device, go to Storage → Volumes. Select the volume’s name. At
the bottom of the interface are several icons, one of which is Volume Status. Click the Volume Status icon and
locate the failed disk. Then perform these steps:
1. Click the disk’s entry, then its Offline button to change the disk status to OFFLINE. This step is needed
to properly remove the device from the ZFS pool and to prevent swap issues. If the hardware supports
hot-pluggable disks, click the disk’s Offline button and pull the disk, then skip to step 3. If there is no
Offline button but only a Replace button, the disk is already offlined and this step can be skipped.
Note: If the process of changing the disk’s status to OFFLINE fails with a “disk offline failed - no valid
replicas” message, the ZFS volume must be scrubbed first with the Scrub Volume button in Storage
→ Volumes. After the scrub completes, try to Offline the disk again before proceeding.
2. If the hardware is not AHCI capable, shut down the system to physically replace the disk. When finished, return to the GUI and locate the OFFLINE disk.
3. After the disk has been replaced and is showing as OFFLINE, click the disk again and then click its
Replace button. Select the replacement disk from the drop-down menu and click the Replace Disk
button. After clicking the Replace Disk button, the ZFS pool starts to resilver and the status of the
resilver is displayed.
4. After the drive replacement process is complete, re-add the replaced disk in the S.M.A.R.T. Tests
(page 92) screen.
8.1. Volumes
131
FreeNAS® 11.0-U4 User Guide, Release 11.0
In the example shown in Figure 8.20, a failed disk is being replaced by disk ada5 in the volume named
volume1.
Fig. 8.20: Replacing a Failed Disk
After the resilver is complete, Volume Status shows a Completed resilver status and indicates any errors.
Figure 8.21 indicates that the disk replacement was successful in this example.
Note: A disk that is failing but has not completely failed can be replaced in place, without first removing it.
Whether this is a good idea depends on the overall condition of the failing disk. A disk with a few newly-bad
blocks that is otherwise functional can be left in place during the replacement to provide data redundancy.
A drive that is experiencing continuous errors can actually slow down the replacement. In extreme cases, a
disk with serious problems might spend so much time retrying failures that it could prevent the replacement
resilvering from completing before another drive fails.
132
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.21: Disk Replacement is Complete
Replacing an Encrypted Drive
If the ZFS pool is encrypted, additional steps are needed when replacing a failed drive.
First, make sure that a passphrase has been set using the instructions in Encryption (page 110) before
attempting to replace the failed drive. Then, follow the steps 1 and 2 as described above. During step 3,
you will be prompted to input and confirm the passphrase for the pool. Enter this information then click
the Replace Disk button. Wait until the resilvering is complete.
Next, restore the encryption keys to the pool. If the following additional steps are not performed before
the next reboot, access to the pool might be permanently lost.
1. Highlight the pool that contains the disk that was just replaced and click the Encryption Re-key button
in the GUI. Entry of the root password will be required.
2. Highlight the pool that contains the disk you just replaced and click Create Passphrase and enter the
new passphrase. The old passphrase can be reused if desired.
3. Highlight the pool that contains the disk you just replaced and click the Download Key button to save
the new encryption key. Since the old key will no longer function, any old keys can be safely discarded.
4. Highlight the pool that contains the disk that was just replaced and click the Add Recovery Key button to
save the new recovery key. The old recovery key will no longer function, so it can be safely discarded.
Removing a Log or Cache Device
Added log or cache devices appear in Storage → Volumes → Volume Status. Clicking the device
enables its Replace and Remove buttons.
Log and cache devices can be safely removed or replaced with these buttons. Both types of devices improve
performance, and throughput can be impacted by their removal.
8.1.11 Replacing Drives to Grow a ZFS Pool
The recommended method for expanding the size of a ZFS pool is to pre-plan the number of disks in a vdev
and to stripe additional vdevs using Volume Manager (page 108) as additional capacity is needed.
8.1. Volumes
133
FreeNAS® 11.0-U4 User Guide, Release 11.0
However, this is not an option if there are no open drive ports and a SAS/SATA HBA card cannot be added.
In this case, one disk at a time can be replaced with a larger disk, waiting for the resilvering process to
incorporate the new disk into the pool, then repeating with another disk until all of the original disks have
been replaced.
The safest way to perform this is to use a spare drive port or an eSATA port and a hard drive dock. The
process follows these steps:
1. Shut down the system.
2. Install one new disk.
3. Start up the system.
4. Go to Storage → Volumes, select the pool to expand and click the Volume Status button. Select a
disk and click the Replace button. Choose the new disk as the replacement.
5. The status of the resilver process can be viewed by running zpool status. When the new disk
has resilvered, the old one will be automatically offlined. The system is then shut down to physically
remove the replaced disk. One advantage of this approach is that there is no loss of redundancy
during the resilver.
If a spare drive port is not available, a drive can be replaced with a larger one using the instructions in
Replacing a Failed Drive (page 131). This process is slow and places the system in a degraded state. Since a
failure at this point could be disastrous, do not attempt this method unless the system has a reliable
backup. Replace one drive at a time and wait for the resilver process to complete on the replaced drive
before replacing the next drive. After all the drives are replaced and the final resilver completes, the added
space will appear in the pool.
8.2 Periodic Snapshot Tasks
A periodic snapshot task allows scheduling the creation of read-only versions of ZFS volumes and datasets
at a given point in time. Snapshots can be created quickly and, if little data changes, new snapshots take
up very little space. For example, a snapshot where no files have changed takes 0 MB of storage, but as
changes are made to files, the snapshot size changes to reflect the size of the changes.
Snapshots provide a clever way of keeping a history of files, providing a way to recover an older copy or even
a deleted file. For this reason, many administrators take snapshots often (perhaps every fifteen minutes),
store them for a period of time (possibly a month), and store them on another system (typically using
Replication Tasks (page 136)). Such a strategy allows the administrator to roll the system back to a specific
point in time. If there is a catastrophic loss, an off-site snapshot can be used to restore the system up to
the time of the last snapshot.
An existing ZFS volume is required before creating a snapshot. Creating a volume is described in Volume
Manager (page 108).
To create a periodic snapshot task, click Storage → Periodic Snapshot Tasks → Add Periodic
Snapshot which opens the screen shown in Figure 8.22. Table 8.7 summarizes the fields in this screen.
Note: If only a one-time snapshot is needed, instead use Storage → Volumes and click the Create
Snapshot button for the volume or dataset to snapshot.
134
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.22: Creating a Periodic Snapshot
Table 8.7: Options When Creating a Periodic Snapshot
Setting
Value
Volume/Dataset drop-down menu
Recursive
checkbox
Snapshot Lifetime
integer and dropdown menu
Begin
End
Interval
Weekday
drop-down menu
drop-down menu
drop-down menu
checkboxes
8.2. Periodic Snapshot Tasks
Description
select an existing ZFS volume, dataset, or zvol
select this box to take separate snapshots of the volume/dataset and each of its child datasets; if unchecked, a single snapshot is taken of only the specified volume/dataset, but
not any child datasets
length of time to retain the snapshot on this system; if the snapshot is replicated, it is not removed from the receiving system
when the lifetime expires
do not create snapshots before this time of day
do not create snapshots after this time of day
how often to take snapshot between Begin and End times
which days of the week to take snapshots
Continued on next page
135
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Enabled
Value
checkbox
Table 8.7 – continued from previous page
Description
uncheck to disable the scheduled snapshot task without deleting it
If the Recursive box is checked, child datasets of this dataset are included in the snapshot and there is no
need to create snapshots for each child dataset. The downside is that there is no way to exclude particular
child datasets from a recursive snapshot.
When the OK button is clicked, a snapshot is taken and the task will be repeated according to your settings.
After creating a periodic snapshot task, an entry for the snapshot task will be added to View Periodic Snapshot
Tasks. Click an entry to access its Edit and Delete buttons.
8.3 Replication Tasks
Replication is the duplication of snapshots from one FreeNAS® system to another computer. When a new
snapshot is created on the source computer, it is automatically replicated to the destination computer.
Replication is typically used to keep a copy of files on a separate system, with that system sometimes being
at a different physical location.
The basic configuration requires a source system with the original data and a destination system where the
data will be replicated. The destination system is prepared to receive replicated data, a periodic snapshot
(page 134) of the data on the source system is created, and then a replication task is created. As snapshots
are automatically created on the source computer, they are automatically replicated to the destination
computer.
Note: Replicated data is not visible on the receiving system until the replication task completes.
8.3.1 Examples: Common Configuration
The examples shown here use the same setup of source and destination computers.
Alpha (Source)
Alpha is the source computer with the data to be replicated. It is at IP address 10.0.0.102. A volume (page 108)
named alphavol has already been created, and a dataset (page 115) named alphadata has been created on
that volume. This dataset contains the files which will be snapshotted and replicated onto Beta.
This new dataset has been created for this example, but a new dataset is not required. Most users will
already have datasets containing the data they wish to replicate.
Create a periodic snapshot of the source dataset by selecting Storage → Periodic Snapshot Tasks.
Click the alphavol/alphadata dataset to highlight it. Create a periodic snapshot (page 134) of it by clicking
Periodic Snapshot Tasks, then Add Periodic Snapshot as shown in Figure 8.23.
This example creates a snapshot of the alphavol/alphadata dataset every two hours from Monday through
Friday between the hours of 9:00 and 18:00 (6:00 PM). Snapshots are automatically deleted after their
chosen lifetime of two weeks expires.
136
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.23: Create a Periodic Snapshot for Replication
Beta (Destination)
Beta is the destination computer where the replicated data will be copied. It is at IP address 10.0.0.118. A
volume (page 108) named betavol has already been created.
Snapshots are transferred with SSH (page 237). To allow incoming connections, this service is enabled on
Beta. The service is not required for outgoing connections, and so does not need to be enabled on Alpha.
8.3.2 Example: FreeNAS® to FreeNAS® Semi-Automatic Setup
FreeNAS® offers a special semi-automatic setup mode that simplifies setting up replication. Create the
replication task on Alpha by clicking Replication Tasks and Add Replication. alphavol/alphadata is selected as
the dataset to replicate. betavol is the destination volume where alphadata snapshots are replicated. The
Setup mode dropdown is set to Semi-automatic as shown in Figure 8.24. The IP address of Beta is entered in
the Remote hostname field. A hostname can be entered here if local DNS resolves for that hostname.
Note: If WebGUI HTTP –> HTTPS Redirect has been enabled in System → General on the destination
computer, Remote HTTP/HTTPS Port must be set to the HTTPS port (usually 443) and Remote HTTPS must be
enabled when creating the replication on the source computer.
8.3. Replication Tasks
137
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.24: Add Replication Dialog, Semi-Automatic
The Remote Auth Token field expects a special token from the Beta computer. On Beta, choose Storage
→ Replication Tasks, then click Temporary Auth Token. A dialog showing the temporary authorization
token is shown as in Figure 8.25.
Highlight the temporary authorization token string with the mouse and copy it.
138
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.25: Temporary Authentication Token on Destination
On the Alpha system, paste the copied temporary authorization token string into the Remote Auth Token field
as shown in Figure 8.26.
Fig. 8.26: Temporary Authentication Token Pasted to Source
Finally, click the OK button to create the replication task. After each periodic snapshot is created, a replication task will copy it to the destination system. See Limiting Replication Times (page 145) for information
about restricting when replication is allowed to run.
Note: The temporary authorization token is only valid for a few minutes. If a Token is invalid message is
shown, get a new temporary authorization token from the destination system, clear the Remote Auth Token
field, and paste in the new one.
8.3.3 Example: FreeNAS® to FreeNAS® Dedicated User Replication
A dedicated user can be used for replications rather than the root user. This example shows the process
using the semi-automatic replication setup between two FreeNAS® systems with a dedicated user named
repluser. SSH key authentication is used to allow the user to log in remotely without a password.
In this example, the periodic snapshot task has not been created yet. If the periodic snapshot shown in
the example configuration (page 136) has already been created, go to Storage → Periodic Snapshot
Tasks, click on the task to select it, and click Delete to remove it before continuing.
On Alpha, select Account → Users.
Click the Add User.
Enter repluser for Username, enter
/mnt/alphavol/repluser in the Create Home Directory In field, enter Replication Dedicated User for the Full Name,
and set the Disable password login checkbox. Leave the other fields at their default values, but note the User
ID number. Click OK to create the user.
On Beta, the same dedicated user must be created as was created on the sending computer. Select
Account → Users. Click the Add User. Enter the User ID number from Alpha, repluser for Username,
enter /mnt/betavol/repluser in the Create Home Directory In field, enter Replication Dedicated User for the Full
Name, and set the Disable password login checkbox. Leave the other fields at their default values. Click OK
to create the user.
A dataset with the same name as the original must be created on the destination computer, Beta. Select
Storage → Volumes, click on betavol, then click the Create Dataset icon at the bottom. Enter alphadata
as the Dataset Name, then click Add Dataset.
8.3. Replication Tasks
139
FreeNAS® 11.0-U4 User Guide, Release 11.0
The replication user must be given permissions to the destination dataset. Still on Beta, open a Shell
(page 288) and enter this command:
zfs allow -ldu repluser create,destroy,diff,mount,readonly,receive,release,send,
˓→userprop betavol/alphadata
The destination dataset must also be set to read-only. Enter this command in the Shell (page 288):
zfs set readonly=on betavol/alphadata
Close the Shell (page 288) by typing exit and pressing Enter.
The replication user must also be able to mount datasets. Still on Beta, go to System → Tunables. Click
Add Tunable. Enter vfs.usermount for the Variable, 1 for the Value, and choose Sysctl from the Type drop-down.
Click OK to save the tunable settings.
Back on Alpha, create a periodic snapshot of the source dataset by selecting Storage → Periodic
Snapshot Tasks. Click the alphavol/alphadata dataset to highlight it. Create a periodic snapshot (page 134)
of it by clicking Periodic Snapshot Tasks, then Add Periodic Snapshot as shown in Figure 8.23.
Still on Alpha, create the replication task by clicking Replication Tasks and Add Replication. alphavol/alphadata
is selected as the dataset to replicate. betavol/alphadata is the destination volume and dataset where alphadata snapshots are replicated.
The Setup mode dropdown is set to Semi-automatic as shown in Figure 8.24. The IP address of Beta is entered
in the Remote hostname field. A hostname can be entered here if local DNS resolves for that hostname.
Note: If WebGUI HTTP –> HTTPS Redirect has been enabled in System → General on the destination
computer, Remote HTTP/HTTPS Port must be set to the HTTPS port (usually 443) and Remote HTTPS must be
enabled when creating the replication on the source computer.
The Remote Auth Token field expects a special token from the Beta computer. On Beta, choose Storage
→ Replication Tasks, then click Temporary Auth Token. A dialog showing the temporary authorization
token is shown as in Figure 8.25.
Highlight the temporary authorization token string with the mouse and copy it.
On the Alpha system, paste the copied temporary authorization token string into the Remote Auth Token field
as shown in Figure 8.26.
Set the Dedicated User checkbox. Choose repluser in the Dedicated User drop-down.
Click the OK button to create the replication task.
Note: The temporary authorization token is only valid for a few minutes. If a Token is invalid message is
shown, get a new temporary authorization token from the destination system, clear the Remote Auth Token
field, and paste in the new one.
Replication will begin when the periodic snapshot task runs.
Additional replications can use the same dedicated user that has already been set up. The permissions and
read only settings made through the Shell (page 288) must be set on each new destination dataset.
140
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
8.3.4 Example: FreeNAS® to FreeNAS® or Other Systems, Manual Setup
This example uses the same basic configuration of source and destination computers shown above, but the
destination computer is not required to be a FreeNAS® system. Other operating systems can receive the
replication if they support SSH, ZFS, and the same features that are in use on the source system. The details
of creating volumes and datasets, enabling SSH, and copying encryption keys will vary when the destination
computer is not a FreeNAS® system.
Encryption Keys
A public encryption key must be copied from Alpha to Beta to allow a secure connection without a password prompt. On Alpha, select Storage → Replication Tasks → View Public Key, producing
the window shown in Figure 8.27. Use the mouse to highlight the key data shown in the window, then copy
it.
Fig. 8.27: Copy the Replication Key
On Beta, select Account → Users → View Users. Click the root account to select it, then click Modify
User. Paste the copied key into the SSH Public Key field and click OK as shown in Figure 8.28.
8.3. Replication Tasks
141
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.28: Paste the Replication Key
Back on Alpha, create the replication task by clicking Replication Tasks and Add Replication. alphavol/alphadata
is selected as the dataset to replicate. The destination volume is betavol. The alphadata dataset and snapshots are replicated there. The IP address of Beta is entered in the Remote hostname field as shown in Figure
8.29. A hostname can be entered here if local DNS resolves for that hostname.
Click the SSH Key Scan button to retrieve the SSH host keys from Beta and fill the Remote hostkey field. Finally,
click OK to create the replication task. After each periodic snapshot is created, a replication task will copy it
to the destination system. See Limiting Replication Times (page 145) for information about restricting when
replication is allowed to run.
142
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
8.3. Replication Tasks
Fig. 8.29: Add Replication Dialog
143
FreeNAS® 11.0-U4 User Guide, Release 11.0
8.3.5 Replication Options
Table 8.8 describes the options in the replication task dialog.
Table 8.8: Replication Task Options
Setting
Volume/Dataset
Remote ZFS Volume/Dataset
Value
dropdown
menu
string
Recursively replicate
child dataset’s snapshots
Delete stale snapshots
checkbox
Replication Stream
Compression
dropdown
menu
integer
Limit (kB/s)
Begin
End
Enabled
Setup mode
checkbox
dropdown
menu
dropdown
menu
checkbox
Remote hostname
dropdown
menu
string
Remote port
string
Dedicated User Enabled
Dedicated User
checkbox
Encryption Cipher
Remote hostkey
dropdown
menu
dropdown
menu
string
Description
ZFS volume or dataset on the source computer containing the
snapshots to be replicated; the drop-down menu is empty if a
snapshot does not already exist
ZFS volume on the remote or destination computer which will
store the snapshots; if the destination dataset is not present, it
will be created; /mnt/ is assumed, do not include it in the path
when checked, also replicate snapshots of datasets that are children of the main dataset
when checked, delete previous snapshots on the remote or destination computer which are no longer present on the source
computer
choices are lz4 (fastest), pigz (all rounder), plzip (best compression),
or Off (no compression); selecting a compression algorithm can
reduce the size of the data being replicated
limit replication speed to the specified value in kilobytes/second; default of 0 is unlimited
replication is not allowed to start before this time; times entered
in the Begin and End fields set when replication can occur
replication must start by this time; once started, replication will
continue until it is finished
uncheck to disable the scheduled replication task without deleting it
Manual or Semi-automatic
IP address or DNS name of remote computer where replication
is sent
the port used by the SSH server on the remote or destination
computer
allow a user account other than root to be used for replication
only available if Dedicated User Enabled is checked; select the
user account to be used for replication
Standard, Fast, or Disabled
use the SSH Key Scan button to retrieve the public host key of
the remote or destination computer and populate this field with
that key
The replication task runs after a new periodic snapshot is created. The periodic snapshot and any new
manual snapshots of the same dataset are replicated onto the destination computer.
144
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
When multiple replications have been created, replication tasks run serially, one after another. Completion
time depends on the number and size of snapshots and the bandwidth available between the source and
destination computers.
The first time a replication runs, it must duplicate data structures from the source to the destination computer. This can take much longer to complete than subsequent replications, which only send differences in
data.
Selecting Storage → Replication Tasks displays Figure 8.30, the list of replication tasks. The Last
snapshot sent to remote side column shows the name of the last snapshot that was successfully replicated,
and Status shows the current status of each replication task. The display is updated every five seconds,
always showing the latest status.
Fig. 8.30: Replication Task List
After a snapshot has been successfully replicated to another system, an OK is shown in the Replication
column of the snapshot list at Storage → Snapshots.
Note:
The encryption key that was copied from the source computer (Alpha) to the destination computer (Beta) is an RSA public key located in the /data/ssh/replication.pub file on the
source computer. The host public key used to identify the destination computer (Beta) is from the
/etc/ssh/ssh_host_rsa_key.pub file on the destination computer.
8.3.6 Replication Encryption
The default Encryption Cipher Standard setting provides good security. Fast is less secure than Standard but
can give reasonable transfer rates for devices with limited cryptographic speed. For networks where the
entire path between source and destination computers is trusted, the Disabled option can be chosen to
send replicated data without encryption.
8.3.7 Limiting Replication Times
The Begin and End times in a replication task make it possible to restrict when replication is allowed. These
times can be set to only allow replication after business hours, or at other times when disk or network
activity will not slow down other operations like snapshots or Scrubs (page 147). The default settings allow
replication to occur at any time.
These times control when replication task are allowed to start, but will not stop a replication task that is
already running. Once a replication task has begun, it will run until finished.
8.3.8 Troubleshooting Replication
Replication depends on SSH, disks, network, compression, and encryption to work. A failure or misconfiguration of any of these can prevent successful replication.
8.3. Replication Tasks
145
FreeNAS® 11.0-U4 User Guide, Release 11.0
SSH
SSH (page 237) must be able to connect from the source system to the destination system with an encryption
key. This can be tested from Shell (page 288) by making an SSH (page 237) connection from the source
system to the destination system. From the previous example, this is a connection from Alpha to Beta at
10.0.0.118. Start the Shell (page 288) on the source machine (Alpha), then enter this command:
ssh -vv -i /data/ssh/replication 10.0.0.118
On the first connection, the system might say
No matching host key fingerprint found in DNS.
Are you sure you want to continue connecting (yes/no)?
Verify that this is the correct destination computer from the preceding information on the screen and type
yes. At this point, an SSH (page 237) shell connection is open to the destination system, Beta.
If a password is requested, SSH authentication is not working. See Figure 8.27 above. This key value
must be present in the /root/.ssh/authorized_keys file on Beta, the destination computer. The
/var/log/auth.log file can show diagnostic errors for login problems on the destination computer also.
Compression
Matching compression and decompression programs must be available on both the source and destination
computers. This is not a problem when both computers are running FreeNAS® , but other operating systems
might not have lz4, pigz, or plzip compression programs installed by default. An easy way to diagnose
the problem is to set Replication Stream Compression to Off. If the replication runs, select the preferred
compression method and check /var/log/debug.log on the FreeNAS® system for errors.
Manual Testing
On Alpha, the source computer, the /var/log/messages file can also show helpful messages to locate
the problem.
On the source computer, Alpha, open a Shell (page 288) and manually send a single snapshot to the destination computer, Beta. The snapshot used in this example is named auto-20161206.1110-2w. As before,
it is located in the alphavol/alphadata dataset. A @ symbol separates the name of the dataset from the name
of the snapshot in the command.
zfs send alphavol/alphadata@auto-20161206.1110-2w | ssh -i /data/ssh/replication 10.0.
˓→0.118 zfs recv betavol
If a snapshot of that name already exists on the destination computer, the system will refuse to overwrite
it with the new snapshot. The existing snapshot on the destination computer can be deleted by opening a
Shell (page 288) on Beta and running this command:
zfs destroy -R betavol/alphadata@auto-20161206.1110-2w
Then send the snapshot manually again. Snapshots on the destination system, Beta, can be listed from the
Shell (page 288) with zfs list -t snapshot or by going to Storage → Snapshots.
Error messages here can indicate any remaining problems.
146
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
8.4 Scrubs
A scrub is the process of ZFS scanning through the data on a volume. Scrubs help to identify data integrity
problems, detect silent data corruptions caused by transient hardware issues, and provide early alerts of
impending disk failures. FreeNAS® makes it easy to schedule periodic automatic scrubs.
Each volume should be scrubbed at least once a month. Bit errors in critical data can be detected by ZFS,
but only when that data is read. Scheduled scrubs can find bit errors in rarely-read data. The amount of
time needed for a scrub is proportional to the quantity of data on the volume. Typical scrubs take several
hours or longer.
The scrub process is I/O intensive and can negatively impact performance. Schedule scrubs for evenings
or weekends to minimize impact to users. Make certain that scrubs and other disk-intensive activity like
S.M.A.R.T. Tests (page 92) are scheduled to run on different days to avoid disk contention and extreme performance impacts.
Scrubs only check used disk space. To check unused disk space, schedule S.M.A.R.T. Tests (page 92) of Type
Long Self-Test to run once or twice a month.
Scrubs are scheduled and managed with Storage → Scrubs.
When a volume is created, a ZFS scrub is automatically scheduled. An entry with the same volume name
is added to Storage → Scrubs. A summary of this entry can be viewed with Storage → Scrubs →
View Scrubs. Figure 8.31 displays the default settings for the volume named volume1. In this example,
the entry has been highlighted and the Edit button clicked to display the Edit screen. Table 8.9 summarizes
the options in this screen.
Fig. 8.31: Viewing a Volume’s Default Scrub Settings
8.4. Scrubs
147
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 8.9: ZFS Scrub Options
Setting
Volume
Threshold
days
Description
Minute
Value
drop-down
menu
integer
Month
Day of week
string
slider or
minute selections
slider or hour
selections
slider or
month selections
checkboxes
checkboxes
Enabled
checkbox
Hour
Day of Month
Description
select ZFS volume to scrub
number of days since the last scrub completed before the next
scrub can occur, regardless of the calendar schedule; the default
is a multiple of 7 which should ensure that the scrub always occurs
on the same day of the week
optional
if use the slider, scrub occurs every N minutes; if use minute selections, scrub starts at the highlighted minutes
if use the slider, scrub occurs every N hours; if use hour selections,
scrub occurs at the highlighted hours
if use the slider, scrub occurs every N days; if use month selections,
scrub occurs on the highlighted days of the selected months
scrub occurs on the selected months
scrub occurs on the selected days; default is Sunday to least impact
users
uncheck to disable the scheduled scrub without deleting it
Review the default selections and, if necessary, modify them to meet the needs of the environment.
Scrubs can be deleted with the Delete button, but deleting a scrub is not recommended as a scrub provides an early indication of disk issues that could lead to a disk failure. If a scrub is too intensive
for the hardware, consider unchecking the Enabled button for the scrub as a temporary measure until the
hardware can be upgraded.
8.5 Snapshots
The Snapshots tab is used to review the listing of available snapshots. An example is shown in Figure 8.32.
Note: If snapshots do not appear, check that the current time configured in Periodic Snapshot Tasks
(page 134) does not conflict with the Begin, End, and Interval settings. If the snapshot was attempted but
failed, an entry is added to /var/log/messages. This log file can be viewed in Shell (page 288).
148
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.32: Viewing Available Snapshots
The listing includes the name of the volume or dataset, the name of each snapshot, and the amount of used
and referenced data.
Used is the amount of space consumed by this dataset and all of its descendants. This value is checked
against the dataset’s quota and reservation. The space used does not include the dataset’s reservation, but
does take into account the reservations of any descendent datasets. The amount of space that a dataset
consumes from its parent, as well as the amount of space that are freed if this dataset is recursively destroyed, is the greater of its space used and its reservation. When a snapshot is created, the space is initially
shared between the snapshot and the filesystem, and possibly with previous snapshots. As the filesystem
changes, space that was previously shared becomes unique to the snapshot, and is counted in the snapshot’s space used. Additionally, deleting snapshots can increase the amount of space unique to (and used
by) other snapshots. The amount of space used, available, or referenced does not take into account pending changes. While pending changes are generally accounted for within a few seconds, disk changes do not
necessarily guarantee that the space usage information is updated immediately.
Tip: Space used by individual snapshots can be seen by running zfs list -t snapshot from Shell
(page 288).
Refer indicates the amount of data accessible by this dataset, which may or may not be shared with other
datasets in the pool. When a snapshot or clone is created, it initially references the same amount of space
as the file system or snapshot it was created from, since its contents are identical.
Replication shows whether the snapshot has been replicated to a remote system.
Snapshots have icons on the right side for several actions.
Clone Snapshot prompts for the name of the clone to create. A clone is a writable copy of the snapshot.
Since a clone is actually a dataset which can be mounted, it appears in the Volumes tab rather than the
Snapshots tab. By default, -clone is added to the name of a snapshot when a clone is created.
Destroy Snapshot a pop-up message asks for confirmation. Child clones must be destroyed before their
parent snapshot can be destroyed. While creating a snapshot is instantaneous, deleting a snapshot can be
I/O intensive and can take a long time, especially when deduplication is enabled. In order to delete a block
in a snapshot, ZFS has to walk all the allocated blocks to see if that block is used anywhere else; if it is not,
it can be freed.
8.5. Snapshots
149
FreeNAS® 11.0-U4 User Guide, Release 11.0
The most recent snapshot also has a Rollback Snapshot icon. Clicking the icon asks for confirmation before
rolling back to this snapshot state. Confirming by clicking Yes causes any files that have changed since the
snapshot was taken to be reverted back to their state at the time of the snapshot.
Note: Rollback is a potentially dangerous operation and causes any configured replication tasks to fail as
the replication system uses the existing snapshot when doing an incremental backup. To restore the data
within a snapshot, the recommended steps are:
1. Clone the desired snapshot.
2. Share the clone with the share type or service running on the FreeNAS® system.
3. After users have recovered the needed data, destroy the clone in the Active Volumes tab.
This approach does not destroy any on-disk data and has no impact on replication.
A range of snapshots can be selected with the mouse. Click on the checkbox in the left column of the first
snapshot, then press and hold Shift and click on the checkbox for the end snapshot. This can be used
to select a range of obsolete snapshots to be deleted with the Destroy icon at the bottom. Be cautious and
careful when deleting ranges of snapshots.
Periodic snapshots can be configured to appear as shadow copies in newer versions of Windows Explorer,
as described in Configuring Shadow Copies (page 193). Users can access the files in the shadow copy using
Explorer without requiring any interaction with the FreeNAS® graphical administrative interface.
The ZFS Snapshots screen allows the creation of filters to view snapshots by selected criteria. To create a
filter, click the Define filter icon (near the text No filter applied). When creating a filter:
• select the column or leave the default of Any Column.
• select the condition. Possible conditions are: contains (default), is, starts with, ends with, does not
contain, is not, does not start with, does not end with, and is empty.
• enter a value that meets your view criteria.
• click the Filter button to save your filter and exit the define filter screen. Alternately, click the + button
to add another filter.
If you create multiple filters, select the filter to use before leaving the define filter screen. Once a filter is
selected, the No filter applied text changes to Clear filter. If you click Clear filter, a pop-up message indicates
that this removes the filter and all available snapshots are listed.
8.6 VMware-Snapshot
Storage → VMware-Snapshot allows you to coordinate ZFS snapshots when using FreeNAS® as a
VMware datastore. Once this type of snapshot is created, FreeNAS® will automatically snapshot any running
VMware virtual machines before taking a scheduled or manual ZFS snapshot of the dataset or zvol backing
that VMware datastore. The temporary VMware snapshots are then deleted on the VMware side but still
exist in the ZFS snapshot and can be used as stable resurrection points in that snapshot. These coordinated
snapshots will be listed in Snapshots (page 148).
Figure 8.33 shows the menu for adding a VMware snapshot and Table 8.10 summarizes the available options.
150
Chapter 8. Storage
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 8.33: Adding a VMware Snapshot
Table 8.10: VMware Snapshot Options
Setting
Hostname
Value
string
Username
string
Password
ZFS Filesystem
Datastore
string
drop-down menu
drop-down menu
8.6. VMware-Snapshot
Description
IP address or hostname of VMware host; when clustering, this is
the vCenter server for the cluster
user on VMware host with enough permission to snapshot virtual machines
password associated with Username
the filesystem to snapshot
after entering the Hostname, Username, and Password, click Fetch
Datastores to populate the menu and select the datastore with
which to synchronize
151
CHAPTER
NINE
DIRECTORY SERVICES
FreeNAS® supports integration with these directory services:
• Active Directory (page 152) (for Windows 2000 and higher networks)
• LDAP (page 158)
• NIS (page 161)
It also supports Kerberos Realms (page 162), Kerberos Keytabs (page 163), and the ability to add additional
parameters to Kerberos Settings (page 163).
This section summarizes each of these services and their available configurations within the FreeNAS® GUI.
9.1 Active Directory
Active Directory (AD) is a service for sharing resources in a Windows network.
AD
can be configured on a Windows server that is running Windows Server 2000
or higher or on a Unix-like operating system that is running Samba version 4
(https://wiki.samba.org/index.php/Samba4/HOWTO#Provisioning_The_Samba_Active_Directory).
Since
AD provides authentication and authorization services for the users in a network, it is not necessary to
recreate these user accounts on the FreeNAS® system. Instead, configure the Active Directory service so
that it can import the account information and imported users can be authorized to access the SMB shares
on the FreeNAS® system.
Many changes and improvements have been made to Active Directory support within FreeNAS® . It is
strongly recommended to update the system to the latest FreeNAS® 11.0 before attempting Active Directory
integration.
Before configuring the Active Directory service, ensure name resolution is properly configured by ping
ing the domain name of the Active Directory domain controller from Shell (page 288) on the FreeNAS®
system. If the ping fails, check the DNS server and default gateway settings in Network → Global
Configuration on the FreeNAS® system.
Next, add a DNS record for the FreeNAS® system on the Windows server and verify that the hostname of
the FreeNAS® system can be pinged from the domain controller.
Active Directory relies on Kerberos, which is a time sensitive protocol. The time on both the FreeNAS®
system and the Active Directory Domain Controller cannot be out of sync by more than a few minutes. The
best way to ensure that the same time is running on both systems is to configure both systems to:
• use the same NTP server (set in System → NTP Servers on the FreeNAS® system)
• have the same timezone
• be set to either localtime or universal time at the BIOS level
152
FreeNAS® 11.0-U4 User Guide, Release 11.0
Figure 9.1 shows the screen that appears when Directory Service → Active Directory is chosen. Table 9.1 describes the configurable options. Some settings are only available in Advanced Mode. To
see these settings, either click the Advanced Mode button or configure the system to always display these
settings by checking the box Show advanced fields by default in System → Advanced.
Fig. 9.1: Configuring Active Directory
Table 9.1: Active Directory Configuration Options
Setting
Value
Domain Name
(DNS/RealmName)
string
Domain Account
Name
string
Domain Account
Password
string
AD check connectivity frequency
(seconds)
How many recovery attempts
Enable Monitoring
integer
9.1. Active Directory
integer
checkbox
Advanced
Mode
Description
name of Active Directory domain (example.com)
or child domain (sales.example.com); this setting is
mandatory and the GUI will refuse to save the settings
if the domain controller for the specified domain cannot be found
name of the Active Directory administrator account;
this setting is mandatory and the GUI will refuse to
save the settings if it cannot connect to the domain
controller using this account name
password for the Active Directory administrator account; this setting is mandatory and the GUI will
refuse to save the settings if it cannot connect to the
domain controller using this password
how often to verify that Active Directory services are
active
number of times to attempt reconnecting to the Active
Directory server; tries forever when set to 0
restart Active Directory automatically if the service is
disconnected
Continued on next page
153
FreeNAS® 11.0-U4 User Guide, Release 11.0
Verbose logging
Table 9.1 – continued from previous page
Advanced Description
Mode
drop-down
X
choices are Off, SSL, or TLS
menu
drop-down
X
select the certificate of the Active Directory server if
menu
SSL connections are used; if a certificate does not exist yet, create a CA (page 74), then create a certificate
on the Active Directory server and import it to the
FreeNAS® system with Certificates (page 77)
checkbox
X
when checked, logs attempts to join the domain to
UNIX extensions
checkbox
X
Allow Trusted Domains
checkbox
X
Use Default Domain
checkbox
X
Allow DNS updates
Disable Active Directory
user/group cache
User Base
checkbox
X
checkbox
X
string
X
Group Base
string
X
Site Name
string
X
Domain Controller
string
X
Global Catalog
Server
Kerberos Realm
string
X
X
AD timeout
drop-down
menu
drop-down
menu
integer
DNS timeout
integer
X
Setting
Encryption Mode
Certificate
Kerberos Principal
154
Value
X
X
/var/log/messages
only check this box if the AD server has been explicitly configured to map permissions for UNIX users;
checking this box provides persistent UIDs and GUIDs,
otherwise, users/groups are mapped to the UID/GUID
range configured in Samba
should only be enabled if network has active domain/forest trusts (https://technet.microsoft.com/enus/library/cc757352(WS.10).aspx) and you need to
manage files on multiple domains; use with caution
as it will generate more winbindd traffic, slowing down
the ability to filter through user/group information
when unchecked, the domain name is prepended to
the username; if Allow Trusted Domains is checked and
multiple domains use the same usernames, uncheck
this box to prevent name collisions
when unchecked, disables Samba from doing DNS updates when joining a domain
when checked, disables caching AD users and groups;
useful if you cannot bind to a domain with a large
number of users or groups
distinguished name (DN) of the user container in Active Directory
distinguished name (DN) of the group container in Active Directory
the relative distinguished name of the site object in
Active Directory
will automatically be added to the SRV record for the
domain and, when multiple controllers are specified,
FreeNAS® selects the closest DC which responds
if the hostname of the global catalog server to use is
specified, make sure it is resolvable
select the realm created using the instructions in Kerberos Realms (page 162)
browse to the location of the keytab created using the
instructions in Kerberos Keytabs (page 163)
in seconds, increase if the AD service does not start
after connecting to the domain
in seconds, increase if AD DNS queries timeout
Continued on next page
Chapter 9. Directory Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Table 9.1 – continued from previous page
Advanced Description
Mode
drop-down
X
select the backend to use to map Windows security
menu and
identifiers (SIDs) to UNIX UIDs and GIDs; see Table 9.2
Edit
for a summary of the available backends; click the Edit
link to configure that backend’s editable options
drop-down
X
defines the schema to use when querying AD for
menu
user/group info; rfc2307 uses the RFC2307 schema
support included in Windows 2003 R2, sfu20 is for
Services For Unix 3.0 or 3.5, and sfu is for Services For
Unix 2.0
drop-down
X
defines how LDAP traffic is transmitted; choices are
menu
plain (plain text), sign (signed only), or seal (signed and
encrypted); Windows 2000 SP3 and higher can be configured to enforce signed LDAP connections
checkbox
Enable the Active Directory service
string
X
limited to 15 characters; automatically populated with
the system’s original hostname; it must be different
from the Workgroup name
string
X
limited to 15 characters
Value
Idmap backend
Windbind NSS
Info
SASL wrapping
Enable
NetBIOS name
NetBIOS alias
Table 9.2 summarizes the backends which are available in the Idmap backend drop-down menu. Each backend has its own man page (https://www.samba.org/samba/docs/man/manpages/) which gives implementation details. Since selecting the wrong backend will break Active Directory integration, a pop-up menu will
appear whenever changes are made to this setting.
Table 9.2: ID Mapping Backends
Value
ad
autorid
fruit
hash
ldap
nss
rfc2307
9.1. Active Directory
Description
AD server uses RFC2307 or Services For Unix schema extensions;
mappings must be provided in advance by adding the uidNumber
attributes for users and gidNumber attributes for groups in the AD
similar to rid, but automatically configures the range to be used
for each domain, so there is no need to specify a specific range
for each domain in the forest; the only needed configuration is the
range of UID/GIDs to use for user/group mappings and an optional
size for the ranges
generate IDs the way Apple Mac OS X does, so UID and GID can be
identical on all FreeNAS® servers on the network; for use in LDAP
(page 158) environments where Apple’s Open Directory is the authoritative LDAP server
uses a hashing algorithm for mapping and can be used to support
local name mapping files
stores and retrieves mapping tables in an LDAP directory service;
default for LDAP directory service
provides a simple means of ensuring that the SID for a Unix user is
reported as the one assigned to the corresponding domain user
an AD server is required to provide the mapping between the name
and SID and an LDAP server is required to provide the mapping
between the name and the UID/GID
Continued on next page
155
FreeNAS® 11.0-U4 User Guide, Release 11.0
Value
rid
tdb
tdb2
Table 9.2 – continued from previous page
Description
default for AD; requires an explicit idmap configuration for each
domain, using disjoint ranges where a writeable default idmap
range should be defined, using a backend like tdb or ldap
default backend used by winbindd for storing mapping tables
substitute for tdb used by winbindd in clustered environments
Click the Rebuild Directory Service Cache button if a new Active Directory user needs immediate access to
FreeNAS® . This occurs automatically once a day as a cron job.
Note: Active Directory places restrictions on which characters are allowed in Domain and NetBIOS names,
a limits the length of those names to 15 characters. If there are problems connecting to the realm, verify
(https://support.microsoft.com/en-us/kb/909264) that your settings do not include any disallowed characters. Also, the Administrator account password cannot contain the $ character. If a $ exists in the domain
administrator’s password, kinit will report a “Password Incorrect” error and ldap_bind will report an
“Invalid credentials (49)” error.
It can take a few minutes after configuring the Active Directory service for the AD information to be populated to the FreeNAS® system. Once populated, the AD users and groups will be available in the drop-down
menus of the Permissions screen of a volume/dataset. For performance reasons, every available user may
not show in the listing. However, it will autocomplete all applicable users when typing in a username.
The Active Directory users and groups that have been imported to the FreeNAS® system can be shown by
using these commands from the FreeNAS® Shell (page 288). To view users:
wbinfo -u
To view groups:
wbinfo -g
In addition, wbinfo -t will test the connection and, if successful, will show a message similar to:
checking the trust secret for domain YOURDOMAIN via RPC calls succeeded
To manually check that a specified user can authenticate:
net ads join -S dcname -U username
If no users or groups are listed in the output, these commands can provide more troubleshooting information:
getent passwd
getent group
If the wbinfo commands display the network users, but they do not show up in the drop-down menu of
a Permissions screen, it may be because it is taking longer than the default ten seconds for the FreeNAS®
system to join Active Directory. Try bumping up the value of AD timeout to 60 seconds.
Tip: To change a certificate, set the Encryption Mode to Off, then disable AD by unchecking Enable. Click
the Save button. Select the new Certificate, set the Encryption Mode as desired, set the Enable checkbox to
156
Chapter 9. Directory Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
re-enable AD, and click the Save button to restart AD.
9.1.1 Troubleshooting Tips
When running AD in a 2003/2008 mixed domain, refer to (https://forums.freenas.org/index.php?threads/2008r22003-mixed-domain.1931/) for instructions on how to prevent the secure channel key from becoming
corrupt.
Active Directory uses DNS to determine the location of the domain controllers and global catalog servers in
the network. Use the host -t srv _ldap._tcp.domainname.com command to determine the network’s SRV records and, if necessary, change the weight and/or priority of the SRV record to reflect the
fastest server. More information about SRV records can be found in the Technet article How DNS Support
for Active Directory Works (https://technet.microsoft.com/en-us/library/cc759550(WS.10).aspx).
The realm that is used depends upon the priority in the SRV DNS record, meaning that DNS can override
your Active Directory settings. When unable to connect to the correct realm, check the SRV records on
the DNS server. This article (http://www.informit.com/guides/content.aspx?g=security&seqNum=37&rll=1)
describes how to configure KDC discovery over DNS and provides some examples of records with differing
priorities.
If the cache becomes out of sync due to an AD server being taken off and back online, resync the cache
using Directory Service → Active Directory → Rebuild Directory Service Cache.
An expired password for the administrator account will cause kinit to fail, so ensure that the password is
still valid. Also, double-check that the password on the AD account being used does not include any spaces
or special symbols, and is not unusually long.
If the Windows server version is lower than 2008 R2, try creating a Computer entry on the Windows server’s
OU. When creating this entry, enter the FreeNAS® hostname in the name field. Make sure that it is under 15 characters and that it is the same name as the one set in the Hostname field in Network →
Global Configuration and the NetBIOS Name in Directory Service → Active Directory settings. Make sure the hostname of the domain controller is set in the Domain Controller field of Directory
Service → Active Directory.
9.1.2 If the System Will not Join the Domain
If the system will not join the Active Directory domain, run these commands in the order listed. If any of the
commands fail or result in a traceback, create a bug report at bugs.freenas.org (https://bugs.freenas.org/)
that includes the commands in the order in which they were run and the exact wording of the error message
or traceback.
Start with these commands, where the echo commands should return a value of 0 and the klist command should show a Kerberos ticket:
sqlite3
echo $?
service
service
service
service
echo $?
klist
/data/freenas-v1.db "update directoryservice_activedirectory set ad_enable=1;"
ix-kerberos start
ix-nsswitch start
ix-kinit start
ix-kinit status
Next, only run these two commands if the Unix extensions box is checked in Advanced Mode and a keytab
has been uploaded using Kerberos Keytabs (page 163):
9.1. Active Directory
157
FreeNAS® 11.0-U4 User Guide, Release 11.0
service ix-sssd start
service sssd start
Finally, run these commands. Again, the echo command should return a 0:
python /usr/local/www/freenasUI/middleware/notifier.py start cifs
service ix-activedirectory start
service ix-activedirectory status
echo $?
python /usr/local/www/freenasUI/middleware/notifier.py restart cifs
service ix-pam start
service ix-cache start &
9.2 LDAP
FreeNAS® includes an OpenLDAP (http://www.openldap.org/) client for accessing information from an LDAP
server. An LDAP server provides directory services for finding network resources such as users and their
associated permissions. Examples of LDAP servers include Microsoft Server (2000 and newer), Mac OS X
Server, Novell eDirectory, and OpenLDAP running on a BSD or Linux system. If an LDAP server is running on
your network, configure the FreeNAS® LDAP service so network users can authenticate to the LDAP server
and have authorized access to the data stored on the FreeNAS® system.
Note: LDAP authentication for SMB shares is disabled unless the LDAP directory has been configured for
and populated with Samba attributes. The most popular script for performing this task is smbldap-tools
(http://download.gna.org/smbldap-tools/) and instructions for using it can be found at The Linux SambaOpenLDAP Howto (http://download.gna.org/smbldap-tools/docs/samba-ldap-howto/#htoc29). In addition,
the LDAP server must support SSL/TLS and the certificate for the LDAP server must be imported with
System → Certificates → Import Certificate.
Tip: Apple’s Open Directory (https://manuals.info.apple.com/en_US/Open_Directory_Admin_v10.5_3rd_Ed.pdf)
is an LDAP-compatible directory service into which FreeNAS® can be integrated. See FreeNAS with Open
Directory in Mac OS X environments (https://forums.freenas.org/index.php?threads/howto-freenas-withopen-directory-in-mac-os-x-environments.46493/).
Figure 9.2 shows the LDAP Configuration screen that is seen after clicking Directory Service → LDAP.
158
Chapter 9. Directory Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 9.2: Configuring LDAP
Table 9.3 summarizes the available configuration options. Some settings are only available in Advanced
Mode. To see these settings, either click the Advanced Mode button or configure the system to always
display these settings by checking the box Show advanced fields by default in System → Advanced.
Those who are new to LDAP terminology should skim through the OpenLDAP Software 2.4 Administrator’s
Guide (http://www.openldap.org/doc/admin24/).
Table 9.3: LDAP Configuration Options
Setting
Value
Hostname
Base DN
string
string
Bind DN
string
Bind password
Allow Anonymous
Binding
User Suffix
string
checkbox
X
string
X
Group Suffix
string
X
Password Suffix
string
X
9.2. LDAP
Advanced
Mode
Description
hostname or IP address of LDAP server
top level of the LDAP directory tree to be used when
searching for resources (e.g. dc=test,dc=org)
name of administrative account on LDAP server (e.g.
cn=Manager,dc=test,dc=org)
password for Root bind DN
instructs LDAP server to not provide authentication
and to allow read and write access to any client
optional; can be added to name when user account
added to LDAP directory (e.g. dept. or company name)
optional; can be added to name when group added to
LDAP directory (e.g. dept. or company name)
optional; can be added to password when password
added to LDAP directory
Continued on next page
159
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Machine Suffix
SUDO Suffix
Kerberos Realm
Kerberos Principal
Encryption Mode
Certificate
LDAP timeout
DNS timeout
Idmap backend
Samba Schema
Auxiliary Parameters
Schema
Enable
NetBIOS Name
NetBIOS Alias
Table 9.3 – continued from previous page
Advanced Description
Mode
string
X
optional; can be added to name when system added
to LDAP directory (e.g. server, accounting)
string
X
use if LDAP-based users need superuser access
drop-down
X
select the realm created using the instructions in Kermenu
beros Realms (page 162)
drop-down
X
browse to the location of the principal in the keytab
menu
created as described in Kerberos Keytabs (page 163)
drop-down
X
choices are Off, SSL, or TLS; note that either SSL or TLS
menu
and a Certificate must be selected in order for authentication to work
drop-down
X
select the certificate of the LDAP server or the CA that
menu
signed that certificate (required if authentication is
used); if the LDAP server does not already have a certificate, create a CA (page 74), then the certificate using
Certificates (page 77), and install the certificate on the
LDAP server
integer
X
increase this value (in seconds) if obtaining a Kerberos
ticket times out
integer
X
increase this value (in seconds) if DNS queries timeout
drop-down
X
select the backend to use to map Windows security
menu and
identifiers (SIDs) to UNIX UIDs and GIDs; see Table 9.2
Edit
for a summary of the available backends; click the Edit
link to configure the backend’s editable options
checkbox
X
only check this box if you need LDAP authentication
for SMB shares and have already configured the
LDAP server with Samba attributes
string
X
additional options for sssd.conf(5)
(https://jhrozek.fedorapeople.org/sssd/1.11.6/man/sssd.conf.5.html)
drop-down
X
if Samba Schema is checked, select the schema to use;
menu
choices are rfc2307 and rfc2307bis
checkbox
uncheck to disable the configuration without deleting
it
string
X
limited to 15 characters; automatically populated with
the system’s original hostname; must be different
from the Workgroup name
string
X
limited to 15 characters
Value
Click the Rebuild Directory Service Cache button after adding a user to LDAP who needs immediate access to
FreeNAS® . Otherwise this occurs automatically once a day as a cron job.
Note: FreeNAS® automatically appends the root DN. This means that the scope and root DN should not
be included when configuring the user, group, password, and machine suffixes.
LDAP users and groups appear in the drop-down menus of the Permissions screen of a volume/dataset
after configuring the LDAP service. Type getent passwd from Shell (page 288) to verify that the users
have been imported. Type getent group to verify that the groups have been imported.
If the users and groups are not listed, refer to Common errors encountered when using OpenLDAP
Software (http://www.openldap.org/doc/admin24/appendix-common-errors.html) for common errors and
160
Chapter 9. Directory Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
how to fix them. When troubleshooting LDAP, open Shell (page 288) and look for error messages in
/var/log/auth.log.
9.3 NIS
Network Information Service (NIS) is a service which maintains and distributes a central directory of Unix
user and group information, hostnames, email aliases, and other text-based tables of information. If a NIS
server is running on your network, the FreeNAS® system can be configured to import the users and groups
from the NIS directory.
Note:
In Windows Server 2016, Microsoft removed the Identity Management for Unix
(IDMU) and NIS Server Role.
See Clarification regarding the status of Identity Management
for Unix (IDMU) & NIS Server Role in Windows Server 2016 Technical Preview and beyond
(https://blogs.technet.microsoft.com/activedirectoryua/2016/02/09/identity-management-for-unix-idmuis-deprecated-in-windows-server/).
Figure 9.3 shows the configuration screen which opens when you click Directory Service → NIS.
Table 9.4 summarizes the configuration options.
Fig. 9.3: NIS Configuration
Table 9.4: NIS Configuration Options
Setting
NIS domain
Value
string
Description
name of NIS domain
Continued on next page
9.3. NIS
161
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
NIS servers
Secure mode
Value
string
checkbox
Manycast
checkbox
Enable
checkbox
Table 9.4 – continued from previous page
Description
comma delimited list of hostnames or IP addresses
if checked, ypbind(8)
(http://www.freebsd.org/cgi/man.cgi?query=ypbind) will
refuse to bind to any NIS server that is not running as root on a
TCP port number over 1024
if checked, ypbind will bind to the server that responds the
fastest; this is useful when no local NIS server is available on
the same subnet
uncheck to disable the configuration without deleting it
Click the Rebuild Directory Service Cache button after adding a user to NIS who needs immediate access to
FreeNAS® . Otherwise this occurs automatically once a day as a cron job.
9.4 Kerberos Realms
A default Kerberos realm is created for the local system in FreeNAS® . Directory Service →
Kerberos Realms can be used to view and add Kerberos realms. If the network contains a KDC, click
the Add kerberos realm button to add the Kerberos realm. This configuration screen is shown in Figure 9.4.
Fig. 9.4: Adding a Kerberos Realm
Table 9.5 summarizes the configurable options. Some settings are only available in Advanced Mode. To
see these settings, either click the Advanced Mode button or configure the system to always display these
settings by checking the box Show advanced fields by default in System → Advanced.
Table 9.5: Kerberos Realm Options
Setting
Value
Realm
KDC
Admin Server
string
string
string
X
X
Password Server
string
X
162
Advanced
Mode
Description
mandatory; name of the realm
name of the Key Distribution Center
server where all changes to the database are performed
server where all password changes are performed
Chapter 9. Directory Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
9.5 Kerberos Keytabs
Kerberos keytabs are used to do Active Directory or LDAP joins without a password. This means that
the password for the Active Directory or LDAP administrator account does not need to be saved into the
FreeNAS® configuration database, which is a security risk in some environments.
When using a keytab, it is recommended to create and use a less privileged account for performing the
required queries as the password for that account will be stored in the FreeNAS® configuration database.
To create the keytab on a Windows system, use these commands:
ktpass.exe -out hostname.keytab host/ hostname@DOMAINNAME -ptype KRB5_NT_PRINCIPAL ˓→mapuser DOMAIN\username -pass userpass
setspn -A host/ hostname@DOMAINNAME DOMAIN\username
where:
• hostname is the fully qualified hostname of the domain controller
• DOMAINNAME is the domain name in all caps
• DOMAIN is the pre-Windows 2000 short name for the domain
• username is the privileged account name
• userpass is the password associated with username
This will create a keytab with sufficient privileges to grant tickets.
After the keytab is generated, use Directory Service → Kerberos Keytabs → Add kerberos
keytab to add it to the FreeNAS® system.
To instruct the Active Directory service to use the keytab, select the installed keytab using the drop-down
Kerberos keytab menu in Directory Service → Active Directory. When using a keytab with Active
Directory, make sure that the “username” and “userpass” in the keytab matches the “Domain Account Name”
and “Domain Account Password” fields in Directory Service → Active Directory.
To instruct LDAP to use a principal from the keytab, select the principal from the drop-down Kerberos Principal menu in Directory Service → LDAP.
9.6 Kerberos Settings
To configure additional Kerberos parameters, use Directory Service → Kerberos Settings. Figure 9.5 shows the fields available:
• Appdefaults auxiliary parameters: contains settings used by some Kerberos applications.
The available settings and their syntax are listed in the [appdefaults] section of krb.conf(5)
(http://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html#appdefaults).
• Libdefaults auxiliary parameters: contains settings used by the Kerberos library.
The
available settings and their syntax are listed in the [libdefaults] section of krb.conf(5)
(http://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html#libdefaults).
9.5. Kerberos Keytabs
163
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 9.5: Additional Kerberos Settings
164
Chapter 9. Directory Services
CHAPTER
TEN
SHARING
Shares are created to make part or all of a volume accessible to other computers on the network. The type
of share to create depends on factors like which operating systems are being used by computers on the
network, security requirements, and expectations for network transfer speeds.
FreeNAS® provides a Wizard (page 280) for creating shares. The Wizard (page 280) automatically creates the
correct type of dataset and permissions for the type of share, sets the default permissions for the share
type, and starts the service needed by the share. It is recommended to use the Wizard to create shares,
fine-tune the share settings using the instructions in the rest of this chapter if needed, then fine-tune the
default permissions from the client operating system to meet the requirements of the network.
Note: Shares are created to provide and control access to an area of storage. Before creating shares, it is
recommended to make a list of the users that need access to storage data, which operating systems these
users are using, whether all users should have the same permissions to the stored data, and whether these
users should authenticate before accessing the data. This information can help determine which type of
shares are needed, whether multiple datasets are needed to divide the storage into areas with different
access and permissions, and how complex it will be to set up those permission requirements. Note that
shares are used to provide access to data. When a share is deleted, it removes access to data but does not
delete the data itself.
These types of shares and services are available:
• AFP (page 166): Apple File Protocol shares are often used when the client computers all run Mac OS X.
Apple has slowly shifted to preferring SMB (page 183) for modern networks, although Time Machine
still requires AFP.
• Unix (NFS) (page 174): Network File System shares are accessible from Mac OS X, Linux, BSD, and the
professional and enterprise versions (but not the home editions) of Windows. This can be are a good
choice when the client computers do not all run the same operating system but NFS client software is
available for all of them.
• WebDAV (page 182): WebDAV shares are accessible using an authenticated web browser (read-only) or
WebDAV client (https://en.wikipedia.org/wiki/WebDAV#Clients) running on any operating system.
• SMB (page 183): Server Message Block shares, also known as Common Internet File System (CIFS)
shares, are accessible by Windows, Mac OS X, Linux, and BSD computers. Access is slower than an
NFS share due to the single-threaded design of Samba. SMB provides more configuration options
than NFS and is a good choice on a network for Windows systems. However, it is a poor choice if the
CPU on the FreeNAS® system is limited; if the CPU is maxed out, upgrade the CPU or consider another
type of share.
• Block (iSCSI) (page 195): block or iSCSI shares appear as an unformatted disk to clients running iSCSI
initiator software or a virtualization solution such as VMware. These are usually used as virtual drives.
165
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fast access from any operating system can be obtained by configuring the FTP (page 217) service instead of a
share and using a cross-platform FTP file manager application such as Filezilla (https://filezilla-project.org/).
Secure FTP can be configured if the data needs to be encrypted.
When data security is a concern and the network users are familiar with SSH command line utilities or
WinSCP (http://winscp.net/eng/index.php), consider using the SSH (page 237) service instead of a share. It
is slower than unencrypted FTP due to the encryption overhead, but the data passing through the network
is encrypted.
Note: It is generally a mistake to share a volume or dataset with more than one share type or access
method. Different types of shares and services use different file locking methods. For example, if the same
volume is configured to use both NFS and FTP, NFS will lock a file for editing by an NFS user, but a FTP user
can simultaneously edit or delete that file. This results in lost edits and confused users. Another example:
if a volume is configured for both AFP and SMB, Windows users can be confused by the “extra” filenames
used by Mac files and delete them. This corrupts the files on the AFP share. Pick the one type of share or
service that makes the most sense for the types of clients accessing that volume, and use that single type of
share or service. To support multiple types of shares, divide the volume into datasets and use one dataset
per share.
This section demonstrates configuration and fine-tuning of AFP, NFS, SMB, WebDAV, and iSCSI shares. FTP
and SSH configurations are described in Services (page 210).
10.1 Apple (AFP) Shares
FreeNAS® uses the Netatalk (http://netatalk.sourceforge.net/) AFP server to share data with Apple systems. This section describes the configuration screen for fine-tuning AFP shares created using the Wizard
(page 280). It then provides configuration examples for using the Wizard (page 280) to create a guest share,
configuring Time Machine to back up to a dataset on the FreeNAS® system, and for connecting to the share
from a Mac OS X client.
To view the AFP share created by the Wizard, click Sharing → Apple (AFP) and highlight the name of
the share. Click its Edit button to see the configuration options shown in Figure 10.1. The values showing
for these options will vary, depending upon the information given when the share was created.
166
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.1: Creating an AFP Share
Note:
Table 10.1 summarizes the options available to fine-tune an AFP share.
These options should usually be left at the default settings. Changing them might cause unexpected behavior.
Most settings are only available with Advanced Mode.
Do not change an advanced
option without fully understanding the function of that option.
Refer to Setting up Netatalk
(http://netatalk.sourceforge.net/2.2/htmldocs/configuration.html) for a more detailed explanation of these
options.
Table 10.1: AFP Share Configuration Options
Setting
Value
Path
browse button
Name
string
Share Comment
Allow List
string
string
10.1. Apple (AFP) Shares
Advanced
Mode
X
X
Description
browse to the volume/dataset to share; do not nest
additional volumes, datasets, or symbolic links beneath this path because Netatalk does not fully support that
volume name which appears in the Mac computer’s
connect to server dialog; limited to 27 characters and
cannot contain a period
optional comment
comma-delimited list of allowed users and/or groups
where groupname begins with a @; note that adding
an entry will deny any user/group that is not specified
Continued on next page
167
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Deny List
Read-only Access
Read-write Access
Time Machine
Zero Device Numbers
No Stat
AFP3 UNIX Privs
Default file permission
Default directory
permission
Default umask
Hosts Allow
Hosts Deny
Auxiliary Parameters
Table 10.1 – continued from previous page
Advanced Description
Mode
string
X
comma-delimited list of denied users and/or groups
where groupname begins with a @; note that adding
an entry will allow all users/groups that are not specified
string
X
comma-delimited list of users and/or groups who only
have read access where groupname begins with a @
string
X
comma-delimited list of users and/or groups who
have read and write access where groupname begins
with a @
checkbox
when checked, FreeNAS® advertises itself as a Time
Machine disk so it can be found by Macs; due to a limitation in how the Mac deals with low-diskspace issues
when multiple Macs share the same volume, checking
Time Machine on multiple shares could result in intermittent failed backups
checkbox
X
enable when the device number is not constant across
a reboot
checkbox
X
if checked, AFP does not stat the volume path when
enumerating the volumes list; useful for automounting or volumes created by a preexec script
checkbox
X
enable Unix privileges supported by OSX 10.5 and
higher; do not enable this if the network contains Mac
OS X 10.4 clients or lower as they do not support this
feature
checkboxes
X
only works with Unix ACLs; new files created on the
share are set with the selected permissions
checkboxes
X
only works with Unix ACLs; new directories created on
the share are set with the selected permissions
integer
X
umask used for newly created files, default is 000 (anyone can read, write, and execute)
string
X
comma-, space-, or tab-delimited list of allowed hostnames or IP addresses
string
X
comma-, space-, or tab-delimited list of denied hostnames or IP addresses
string
additional afp.conf
(http://netatalk.sourceforge.net/3.1/htmldocs/afp.conf.5.html)
parameters not covered by other option fields
Value
10.1.1 Creating AFP Guest Shares
AFP supports guest logins, meaning that Mac OS X users can access the AFP share without requiring their
user accounts to first be created on or imported into the FreeNAS® system.
Note: When a guest share is created along with a share that requires authentication, AFP only maps users
who log in as guest to the guest share. If a user logs in to the share that requires authentication, permissions
on the guest share can prevent that user from writing to the guest share. The only way to allow both guest
and authenticated users to write to a guest share is to set the permissions on the guest share to 777 or to
add the authenticated users to a guest group and set the permissions to 77x.
168
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Before creating a guest share, go to Services → AFP and make sure that the Guest Access box is checked.
To create the AFP guest share, click Wizard, then click the Next button twice to display the screen shown in
Figure 10.2. Complete these fields in this screen:
1. Share name: enter a name for the share that is identifiable but less than 27 characters long. This
name cannot contain a period. In this example, the share is named afp_guest.
2. Click the button for Mac OS X (AFP).
3. Click the Ownership button. Click the drop-down User menu and select nobody. Click the Return button
to return to the previous screen.
4. Click the Add button. The share is not created until the button is clicked. Clicking the Add button
adds an entry to the Name frame with the name that was entered in Share name.
Fig. 10.2: Creating a Guest AFP Share
Click the Next button twice, then the Confirm button to create the share. The Wizard automatically creates a
dataset for the share that contains the correct default permissions and starts the AFP service so the share
is immediately available. The new share is also added as an entry to Sharing → Apple (AFP).
Mac OS X users can connect to the guest AFP share by clicking Go → Connect to Server. In the example shown in Figure 10.3, the user has entered afp:// followed by the IP address of the FreeNAS® system.
10.1. Apple (AFP) Shares
169
FreeNAS® 11.0-U4 User Guide, Release 11.0
Click the Connect button. Once connected, Finder opens automatically. The name of the AFP share is displayed in the SHARED section in the left frame and the contents of any data saved in the share is displayed
in the right frame.
Fig. 10.3: Connect to Server Dialogue
To disconnect from the volume, click the eject button in the Shared sidebar.
10.1.2 Creating Authenticated and Time Machine Shares
Mac OS X includes the Time Machine application which can be used to schedule automatic backups. In this
configuration example, a Time Machine user will be configured to backup to an AFP share on a FreeNAS®
system. It is recommended to create a separate Time Machine share for each user that will be using Time
Machine to backup their Mac OS X system to FreeNAS® . The process for creating an authenticated share
for a user is the same as creating a Time Machine share for that user.
To use the Wizard to create an authenticated or Time Machine share, enter the following information, as
seen in the example in Figure 10.4.
1. Share name: enter a name for the share that is identifiable but less than 27 characters long. The
name cannot contain a period. In this example, the share is named backup_user1.
2. Click the button for Mac OS X (AFP) and check the box for Time Machine. If the user will not be using
Time Machine, leave the box unchecked.
3. Click the Ownership button. If the user already exists on the FreeNAS® system, click the drop-down
User menu to select their user account. If the user does not yet exist on the FreeNAS® system, type
their name into the User field and check the Create User checkbox. If the user will be a member of a
group that already exists on the FreeNAS® system, click the drop-down Group menu to select the group
name. To create a new group to be used by Time Machine users, enter the name in the Group field
and check the Create Group checkbox. Otherwise, enter the same name as the user. In the example
shown in Figure 10.5, both a new user1 user and a new tm_backups group will be created. Since a new
user is being created, this screen prompts for the user password to be used when accessing the share.
170
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
It also provides an opportunity to change the default permissions on the share. When finished, click
Return to return to the screen shown in Figure 10.4.
4. Click the Add button. Remember to do this or the share will not be created. Clicking the Add button
adds an entry to the Name frame with the name that was entered in Share name.
To configure multiple authenticated or Time Machine shares, repeat for each user, giving each user their
own Share name and Ownership. When finished, click the Next button twice, then the Confirm button to
create the shares. The Wizard automatically creates a dataset for each share with the correct ownership
and starts the AFP service so the shares are immediately available. The new shares are also added to
Sharing → Apple (AFP).
Fig. 10.4: Creating a Time Machine Share
10.1. Apple (AFP) Shares
171
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.5: Creating an Authenticated User
At this point, it may be desirable to configure a quota for each Time Machine share, to restrict backups from
using all of the available space on the FreeNAS® system. The first time Time Machine makes a backup, it
will create a full backup after waiting two minutes. It will then create a one hour incremental backup for the
next 24 hours, and then one backup each day, each week and each month. Since the oldest backups are
deleted when a Time Machine share becomes full, make sure that the quota size is sufficient to hold
the desired number of backups. Note that a default installation of Mac OS X is ~21 GB in size.
To configure a quota, go to Storage → Volumes and highlight the entry for the share. In the example
shown in Figure 10.6, the Time Machine share name is backup_user1. Click the Edit Options button for the
share, then Advanced Mode. Enter a value in the Quota for this dataset field, then click Edit Dataset to save
the change. In this example, the Time Machine share is restricted to 200 GB.
172
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.6: Setting a Quota
Note: An alternative is to create a global quota using the instructions in Set up Time Machine for multiple machines with OSX Server-Style Quotas (https://forums.freenas.org/index.php?threads/how-to-set-uptime-machine-for-multiple-machines-with-osx-server-style-quotas.47173/).
To configure Time Machine on the Mac OS X client, go to System Preferences → Time Machine
which opens the screen shown in Figure 10.7. Click ON and a pop-up menu shows the FreeNAS® system as
a backup option. In our example, it is listed as backup_user1 on “freenas”. Highlight the FreeNAS® system
and click Use Backup Disk. A connection bar opens and prompts for the user account’s password–in this
example, the password that was set for the user1 account.
10.1. Apple (AFP) Shares
173
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.7: Configuring Time Machine on Mac OS X Lion
If Time Machine could not complete the backup. The backup disk image could not be created (error 45) is shown
when backing up to the FreeNAS® system, a sparsebundle image must be created using these instructions
(http://forum1.netgear.com/showthread.php?t=49482).
If Time Machine completed a verification of your backups.
To improve reliability, Time Machine must create a new backup for you.
is shown, follow the instructions in this post
(http://www.garth.org/archives/2011,08,27,169,fix-time-machine-sparsebundle-nas-based-backuperrors.html) to avoid making another backup or losing past backups.
10.2 Unix (NFS) Shares
FreeNAS® supports sharing over the Network File System (NFS). Clients use the mount command to mount
the share. Once mounted, the NFS share appears as just another directory on the client system. Some
Linux distros require the installation of additional software in order to mount an NFS share. On Windows
systems, enable Services for NFS in the Ultimate or Enterprise editions or install an NFS client application.
Note: For performance reasons, iSCSI is preferred to NFS shares when FreeNAS® is installed on ESXi. When
considering creating NFS shares on ESXi, read through the performance analysis at Running ZFS over NFS
as a VMware Store (http://blog.laspina.ca/ubiquitous/running-zfs-over-nfs-as-a-vmware-store).
To create an NFS share using the Wizard (page 280), click the Next button twice to display the screen shown
in Figure 10.8. Enter a Share name. Spaces are not allowed in these names. Click the button for Generic Unix
174
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
(NFS), then click Add so the share name appears in the Name frame. When finished, click the Next button
twice, then the Confirm button to create the share. Creating an NFS share using the wizard automatically
creates a new dataset for the share, starts the services required for NFS, and adds an entry in Sharing →
Unix (NFS) Shares. Depending on your requirements, the IP addresses that are allowed to access the
NFS share can be restricted, or the permissions adjusted.
Fig. 10.8: NFS Share Wizard
NFS shares are edited by clicking Sharing → Unix (NFS), highlighting the entry for the share, and clicking its Edit button. In the example shown in Figure 10.9, the configuration screen is open for the nfs_share1
share.
10.2. Unix (NFS) Shares
175
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.9: NFS Share Settings
Table 10.2 summarizes the available configuration options in this screen. Some settings are only available
by clicking the Advanced Mode button.
Table 10.2: NFS Share Options
Setting
Value
Path
browse button
string
Comment
Advanced
Mode
Authorized networks
string
X
Authorized IP addresses or hosts
All directories
string
X
Read only
checkbox
176
checkbox
Description
browse to the volume or dataset to be shared; click
Add extra path to select multiple paths
set the share name; if left empty, share name is the list
of selected Path entries
list of allowed networks in network/mask CIDR notation, like 1.2.3.0/24, space-delimited; leave empty to
allow all
list of allowed IP addresses or hostnames, spacedelimited; leave empty to allow all
when checked, allow the client to mount any subdirectory within the Path
prohibit writing to the share
Continued on next page
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Quiet
Maproot User
Maproot Group
Mapall User
Mapall Group
Security
Table 10.2 – continued from previous page
Advanced Description
Mode
checkbox
X
inhibit otherwise-useful syslog diagnostics to avoid
some annoying error messages; see exports(5)
(http://www.freebsd.org/cgi/man.cgi?query=exports)
for examples
drop-down
X
when a user is selected, the root user is limited to that
menu
user’s permissions
drop-down
X
when a group is selected, the root user is also limited
menu
to that group’s permissions
drop-down
X
the specified user’s permissions are used by all clients
menu
drop-down
X
the specified group’s permissions are used by all
menu
clients
selection
X
only appears if Enable NFSv4 is checked in Services
→ NFS; choices are sys or these Kerberos options:
krb5 (authentication only), krb5i (authentication and
integrity), or krb5p (authentication and privacy); if multiple security mechanisms are added to the Selected
column using the arrows, use the Up or Down buttons
to list in order of preference
Value
When creating NFS shares, keep the following points in mind:
1. Clients will specify the Path when mounting the share.
2. The Maproot and Mapall options are exclusive, meaning only one can be used–the GUI does not allow
both. The Mapall options supersede the Maproot options. To restrict only the root user’s permissions,
set the Maproot option. To restrict permissions of all users, set the Mapall options.
3. Each volume or dataset is considered to be its own filesystem and NFS is not able to cross filesystem
boundaries.
4. The network or host must be unique per share and per filesystem or directory.
5. The All directories option can only be used once per share per filesystem.
To better understand these restrictions, consider the following scenario where there are:
• 2 networks named 10.0.0.0/8 and 20.0.0.0/8
• a ZFS volume named volume1 with 2 datasets named dataset1 and dataset2
• dataset1 has a directory named directory1
Because of restriction #3, an error is shown when trying to create one NFS share like this:
• Authorized networks set to 10.0.0.0/8 20.0.0.0/8
• Path set to /mnt/volume1/dataset1 and /mnt/volume1/dataset1/directory1
Instead, set a Path of /mnt/volume1/dataset1 and check the All directories box.
That directory could also be restricted to one of the networks by creating two shares instead:
First NFS share:
• Authorized networks set to 10.0.0.0/8
• Path set to /mnt/volume1/dataset1
10.2. Unix (NFS) Shares
177
FreeNAS® 11.0-U4 User Guide, Release 11.0
Second NFS share:
• Authorized networks set to 20.0.0.0/8
• Path set to /mnt/volume1/dataset1/directory1
Note that this requires the creation of two shares. It cannot be done with only one share.
10.2.1 Example Configuration
By default, the Mapall options show as N/A. This means that when a user connects to the NFS share, they
connect with the permissions associated with their user account. This is a security risk if a user is able to
connect as root as they will have complete access to the share.
A better scenario is to do the following:
1. Specify the built-in nobody account to be used for NFS access.
2. In the Change Permissions screen of the volume/dataset that is being shared, change the owner and
group to nobody and set the permissions according to your requirements.
3. Select nobody in the Mapall User and Mapall Group drop-down menus for the share in Sharing →
Unix (NFS) Shares.
With this configuration, it does not matter which user account connects to the NFS share, as it will be
mapped to the nobody user account and will only have the permissions that were specified on the volume/dataset. For example, even if the root user is able to connect, it will not gain root access to the share.
10.2.2 Connecting to the Share
The following examples share this configuration:
1. The FreeNAS® system is at IP address 192.168.2.2.
2. A dataset named /mnt/volume1/nfs_share1 is created and the permissions set to the nobody
user account and the nobody group.
3. An NFS share is created with these attributes:
• Path: /mnt/volume1/nfs_share1
• Authorized Networks: 192.168.2.0/24
• All Directories checkbox is checked
• MapAll User is set to nobody
• MapAll Group is set to nobody
From BSD or Linux
The NFS share is mounted on BSD or Linux systems needing access with this command executed as the
superuser or with sudo:
mount -t nfs 192.168.2.2:/mnt/volume1/nfs_share1 /mnt
• -t nfs specifies the filesystem type of the share
• 192.168.2.2 is the IP address of the FreeNAS® system
• /mnt/volume/nfs_share1 is the name of the directory to be shared, a dataset in this case
178
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
• /mnt is the mountpoint on the client system. This must be an existing, empty directory. The data in
the NFS share appears in this directory on the client computer.
A successful mounting of the share returns to the command prompt without any status or error messages.
Note:
If this command fails on a Linux system, make
(http://sourceforge.net/projects/nfs/files/nfs-utils/) package is installed.
sure
that
the
nfs-utils
This configuration allows users on the client system to copy files to and from /mnt (the mount point). All
files are owned by nobody:nobody. Changes to any files or directories in /mnt are written to the FreeNAS®
system’s /mnt/volume1/nfs_share1 dataset.
Settings cannot be changed on the NFS share if it is mounted on any client computers. The umount command is used to unmount the share on BSD and Linux clients. Run it as the superuser or with sudo on each
client computer:
umount /mnt
From Microsoft
Windows NFS client support varies with versions and releases. For best results, use Windows (SMB) Shares
(page 183).
From Mac OS X
To mount the NFS volume from a Mac OS X client, click on Go → Connect to Server. In the Server
Address field, enter nfs:// followed by the IP address of the FreeNAS® system and the name of the volume/dataset being shared by NFS. The example shown in Figure 10.10 continues with our example of
192.168.2.2:/mnt/volume1/nfs_share1.
Finder opens automatically after connecting. The IP address of the FreeNAS® system is displayed in the
SHARED section in the left frame and the contents of the share are displayed in the right frame. In the
example shown in Figure 10.11, /mnt/data has one folder named images. The user can now copy files to
and from the share.
10.2. Unix (NFS) Shares
179
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.10: Mounting the NFS Share from Mac OS X
180
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.11: Viewing the NFS Share in Finder
10.2.3 Troubleshooting NFS
Some NFS clients do not support the NLM (Network Lock Manager) protocol used by NFS. This is the case
if the client receives an error that all or part of the file may be locked when a file transfer is attempted. To
resolve this error, add the option -o nolock when running the mount command on the client to allow write
access to the NFS share.
If a “time out giving up” error is shown when trying to mount the share from a Linux system, make sure
that the portmapper service is running on the Linux client. If portmapper is running and timeouts are still
shown, force the use of TCP by including -o tcp in the mount command.
If a “RPC: Program not registered” error is shown, upgrade to the latest version of FreeNAS® and restart the
NFS service after the upgrade to clear the NFS cache.
If clients see “reverse DNS” errors, add the FreeNAS® IP address in the Host name database field of Network
→ Global Configuration.
If clients receive timeout errors when trying to mount the share, add the client IP address and hostname to
the Host name data base field in Network → Global Configuration.
Some older versions of NFS clients default to UDP instead of TCP and do not auto-negotiate for TCP. By
default, FreeNAS® uses TCP. To support UDP connections, go to Services → NFS and check the box
10.2. Unix (NFS) Shares
181
FreeNAS® 11.0-U4 User Guide, Release 11.0
Serve UDP NFS clients.
The nfsstat -c or nfsstat -s commands can be helpful to detect problems from the Shell (page 288).
A high proportion of retries and timeouts compared to reads usually indicates network problems.
10.3 WebDAV Shares
In FreeNAS® , WebDAV shares can be created so that authenticated users can browse the contents of the
specified volume, dataset, or directory from a web browser.
Configuring WebDAV shares is a two step process. First, create the WebDAV shares to specify which data
can be accessed. Then, configure the WebDAV service by specifying the port, authentication type, and
authentication password. Once the configuration is complete, the share can be accessed using a URL in the
format:
protocol://IP_address:port_number/share_name
where:
• protocol: is either http or https, depending upon the Protocol configured in Services → WebDAV.
• IP address: is the IP address or hostname of the FreeNAS® system. Take care when configuring a
public IP address to ensure that the network’s firewall only allows access to authorized systems.
• port_number: is configured in Services → WebDAV. If the FreeNAS® system is to be accessed
using a public IP address, consider changing the default port number and ensure that the network’s
firewall only allows access to authorized systems.
• share_name: is configured in Sharing → WebDAV Shares.
Entering the URL in a web browser brings up an authentication pop-up message. Enter a username of
webdav and the password configured in Services → WebDAV.
Warning: At this time, only the webdav user is supported. For this reason, it is important to set a
good password for this account and to only give the password to users which should have access to the
WebDAV share.
To create a WebDAV share, click Sharing → WebDAV Shares → Add WebDAV Share which will open
the screen shown in Figure 10.12.
182
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.12: Adding a WebDAV Share
Table 10.3 summarizes the available options.
Table 10.3: WebDAV Share Options
Setting
Share Path Name
Comment
Path
Read Only
Change User &
Group Ownership
Value
string
string
browse button
checkbox
checkbox
Description
input a name for the share
optional
browse to the volume/dataset to share
if checked, users cannot write to the share
if checked, automatically sets the share’s contents to the webdav
user and group
After clicking OK, a pop-up asks about enabling the service. Once the service starts, review the settings
in Services → WebDAV as they are used to determine which URL is used to access the WebDAV share
and whether or not authentication is required to access the share. These settings are described in WebDAV
(page 244).
10.4 Windows (SMB) Shares
FreeNAS® uses Samba (https://www.samba.org/) to share volumes using Microsoft’s SMB protocol. SMB is
built into the Windows and Mac OS X operating systems and most Linux and BSD systems pre-install the
Samba client in order to provide support for SMB. If your distro did not, install the Samba client using the
distro’s software repository.
The SMB protocol supports many different types of configuration scenarios, ranging from the very simple to
quite complex. The complexity of the scenario depends upon the types and versions of the client operating
systems that will connect to the share, whether the network has a Windows server, and whether Active
Directory is being used. Depending on the authentication requirements, it might be necessary to create or
import users and groups.
Samba supports server-side copy of files on the same share with clients from Windows 8 and higher. Copying between two different shares is not server-side. Windows 7 clients support server-side copying with
Robocopy (https://technet.microsoft.com/en-us/library/cc733145).
10.4. Windows (SMB) Shares
183
FreeNAS® 11.0-U4 User Guide, Release 11.0
This chapter starts by summarizing the available configuration options. It demonstrates some common
configuration scenarios as well as offering some troubleshooting tips. It is recommended to first read
through this entire chapter before creating any SMB shares to get a better idea of the configuration scenario
that best meets your network’s needs.
Tip:
SMB Tips and Tricks (https://forums.freenas.org/index.php?resources/smb-tips-and-tricks.15/)
shows helpful hints for configuring and managing SMB networking.
The FreeNAS and Samba
(CIFS) permissions (https://www.youtube.com/watch?v=RxggaE935PM) and Advanced Samba (CIFS) permissions on FreeNAS (https://www.youtube.com/watch?v=QhwOyLtArw0) videos clarify setting up permissions on SMB shares. Another helpful reference is Methods For Fine-Tuning Samba Permissions
(https://forums.freenas.org/index.php?threads/methods-for-fine-tuning-samba-permissions.50739/).
Tip: Run smbstatus from the Shell (page 288) for a list of active connections and users.
Figure 10.13 shows the configuration screen that appears after clicking Sharing → Windows (SMB
Shares) → Add Windows (SMB) Share.
Fig. 10.13: Adding an SMB Share
Table 10.4 summarizes the options when creating a SMB share.
Some settings are only
available after clicking the Advanced Mode button.
For simple sharing scenarios, Advanced
Mode options are not needed.
For more complex sharing scenarios, only change an Advanced Mode option after fully understanding the function of that option.
smb.conf(5)
(https://www.freebsd.org/cgi/man.cgi?query=smb.conf&manpath=FreeBSD+11.0-RELEASE+and+Ports)
provides more details for each configurable option.
184
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 10.4: Options for a SMB Share
Setting
Value
Path
browse button
checkbox
Use as home
share
Name
Comment
Apply Default Permissions
Advanced
Mode
Description
select volume/dataset/directory to share
string
string
checkbox
X
Export Read Only
Browsable to Network Clients
checkbox
checkbox
X
X
Export Recycle Bin
checkbox
X
Show Hidden Files
checkbox
X
Allow Guest Access
checkbox
Only Allow Guest
Access
Hosts Allow
checkbox
X
string
X
Hosts Deny
string
X
VFS Objects
selection
X
Periodic Snapshot
Task
drop-down
menu
X
Auxiliary Parameters
string
X
check this box if the share is meant to hold user home
directories; only one share can be the homes share
mandatory; name of share
optional description
sets the ACLs to allow read/write for owner/group and
read-only for others; should only be unchecked when
creating a share on a system that already has custom
ACLs set
prohibits write access to the share
when checked, users see the contents of /homes (including other home directories of other users) and
when unchecked, users see only their own home directory
deleted files are moved to a hidden .recycle in the
root folder of the share; the .recycle directory can
be deleted to reclaim space and is automatically recreated when a file is deleted
if enabled, the Windows hidden attribute is not set
when filenames that begin with a dot (a Unix hidden
file) are created; existing files are not affected
if checked, a password is not required to connect to
the share; connections with a bad password are rejected unless the user account does not exist, in which
case it is mapped to the guest account and granted
the permissions of the guest user defined in the SMB
(page 230) service
requires Allow guest access to also be checked; forces
guest access for all connections
comma-, space-, or tab-delimited list of allowed hostnames or IP addresses
comma-, space-, or tab-delimited list of denied hostnames or IP addresses; allowed hosts take precedence
so can use ALL in this field and specify allowed hosts in
Hosts Allow
adds virtual file system modules to enhance functionality; Table 10.5 summarizes the available modules
used to configure directory shadow copies on a pershare basis; select the pre-configured periodic snapshot task to use for the share’s shadow copies; periodic snapshot must be recursive
additional smb4.conf parameters not covered by
other option fields
Note the following regarding some of the Advanced Mode settings:
• Hostname lookups add some time to accessing the SMB share. If you only use IP addresses, uncheck
the Hostnames lookups box in Services → SMB.
10.4. Windows (SMB) Shares
185
FreeNAS® 11.0-U4 User Guide, Release 11.0
• When the Browsable to Network Clients box is checked (the default), the share is visible through Windows File Explorer or through net view. When the Use as a home share box is checked, unchecking
the Browsable to Network Clients box hides the share named homes so that only the dynamically generated share containing the authenticated user’s home directory will be visible. By default, the homes
share and the user’s home directory are both visible. Users are not automatically granted read or
write permissions on browsable shares. This option provides no real security because shares that are
not visible in Windows File Explorer can still be accessed with a UNC path.
• If some files on a shared volume should be hidden and inaccessible to users,
put a veto files= line in the Auxiliary Parameters field.
The syntax for the
veto files option and some examples can be found in the smb.conf manual
page
(https://www.freebsd.org/cgi/man.cgi?query=smb.conf&manpath=FreeBSD+11.0RELEASE+and+Ports).
To configure support for OS/2 clients, add this line to Auxiliary Parameters:
lanman auth = yes
To configure lanman authentication for pre-NT authentication, add these lines instead:
client lanman auth = yes
client plaintext auth = yes
Samba disables NTLMv1 authentication by default for security. Standard configurations of Windows XP
and some configurations of later clients like Windows 7 will not be able to connect with NTLMv1 disabled. Security guidance for NTLMv1 and LM network authentication (https://support.microsoft.com/enus/help/2793313/security-guidance-for-ntlmv1-and-lm-network-authentication) has information about the
security implications and ways to enable NTLMv2. If changing the client configuration is not possible,
NTLMv1 authentication can be enabled by checking the box NTLMv1 auth in Services → SMB.
Table 10.5 provides an overview of the available VFS modules. Be sure to research each module before adding or deleting it from the Selected column of the VFS Objects field of the share.
Some modules need additional configuration after they are added. Refer to Stackable VFS modules
(https://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/VFS.html) and the vfs_* man pages
(https://www.samba.org/samba/docs/man/manpages/) for more details.
Table 10.5: Available VFS Modules
Value
acl_tdb
acl_xattr
aio_fork
aio_pthread
audit
cacheprime
cap
186
Description
stores NTFS ACLs in a tdb file to enable full
mapping of Windows ACLs
stores NTFS ACLs in Extended Attributes (EAs)
to enable the full mapping of Windows ACLs
enables async I/O
implements async I/O in Samba vfs using a
pthread pool instead of the internal Posix AIO
interface
logs share access, connects/disconnects,
directory opens/creates/removes, and file
opens/closes/renames/unlinks/chmods to syslog
primes the kernel file data cache
translates filenames to and from the CAP encoding format, commonly used in Japanese
language environments
Continued on next page
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 10.5 – continued from previous page
Description
creates filenames that use characters that are
illegal in SMB filenames
commit
tracks the amount of data written to a file
and synchronizes it to disk when a specified
amount accumulates
crossrename
allows server side rename operations even if
source and target are on different physical devices
default_quota
stores the default quotas that are reported to a
windows client in the quota record of a user
dfs_samba4
distributed file system for providing an alternative name space, load balancing, and automatic failover
dirsort
sorts directory entries alphabetically before
sending them to the client
expand_msdfs
enables support for Microsoft Distributed File
System (DFS)
extd_audit
sends audit logs to both syslog and the Samba
log files
fake_acls
stores file ownership and ACLs as extended
attributes
fake_perms
allows roaming profile files and directories to
be set as read-only
fruit
enhances OS X support by providing the SMB2
AAPL extension and Netatalk interoperability
(see NOTE below table)
full_audit
record selected client operations to the system
log; if selected, a warning will indicate that Windows 10 clients may experience issues when
transferring files to the NAS system when this
module is enabled
linux_xfs_sgid
used to work around an old Linux XFS bug
media_harmony
allows Avid editorial workstations to share a
network drive
netatalk
eases the co-existence of SMB and AFP shares
offline
marks all files in the share with the DOS offline
attribute; this can prevent Windows Explorer
from reading files just to make thumbnail images
posix_eadb
provides Extended Attributes (EAs) support so
they can be used on filesystems which do not
provide native support for EAs
preopen
useful for video streaming applications that
want to read one file per frame
readahead
useful for Windows Vista clients reading data
using Windows Explorer
readonly
marks a share as read-only for all clients connecting within the configured time period
shadow_copy
allows Microsoft shadow copy clients to
browse shadow copies on Windows shares
Continued on next page
Value
catia
10.4. Windows (SMB) Shares
187
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 10.5 – continued from previous page
Value
Description
shadow_copy_test shadow copy testing
shell_snap
provides shell-script callouts for snapshot creation and deletion operations issued by remote clients using the File Server Remote VSS
Protocol (FSRVP)
skel_opaque
implements dummy versions of all VFS modules (useful to VFS module developers)
skel_transparent
implements dummy passthrough functions of
all VFS modules (useful to VFS module developers)
snapper
provides the ability for remote SMB clients to
access shadow copies of FSRVP snapshots using Windows Explorer
streams_depot
experimental module to store alternate data
streams in a central directory; the association with the primary file can be lost due to
inode numbers changing when a directory is
copied to a new location (see http://marc.info/
?l=samba&m=132542069802160&w=2)
streams_xattr
enables storing of NTFS alternate data streams
in the file system
syncops
ensures metadata operations are performed
synchronously
time_audit
logs system calls that take longer than the
number of defined milliseconds
unityed_media
allows multiple Avid clients to share a network
drive
winmsa
emulate Microsoft’s MoveSecurityAttributes=0
registry option, setting the ACL for file and directory hierarchies to inherit from the parent
directory into which they are moved
worm
controls the writability of files and folders
depending on their change time and an adjustable grace period
xattr_tdb
stores Extended Attributes (EAs) in a tdb file so
they can be used on filesystems which do not
provide support for EAs
zfs_space
correctly calculates ZFS space used by the
share, including space used by ZFS snapshots,
quotas, and resevations; enabled by default
zfsacl
provide ACL extensions for proper integration
with ZFS; enabled by default
Note: When using fruit, also add the streams_xattr and catia VFS objects and be sure to configure all SMB
shares this way. Reboot the Mac client after making this change.
These VFS objects do not appear in the selection box:
• recycle: moves deleted files to the recycle directory instead of deleting them. Controlled by Export
Recycle Bin in the SMB share options (page 185).
188
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
• shadow_copy2: a more recent implementation of shadow_copy with some additional features.
shadow_copy2 and its associated parameters are automatically added to the smb4.conf when a Periodic Snapshot Task is selected.
10.4.1 Configuring Unauthenticated Access
SMB supports guest logins, meaning that users can access the SMB share without needing to provide a
username or password. This type of share is convenient as it is easy to configure, easy to access, and does
not require any users to be configured on the FreeNAS® system. This type of configuration is also the least
secure as anyone on the network can access the contents of the share. Additionally, since all access is as
the guest user, even if the user inputs a username or password, there is no way to differentiate which users
accessed or modified the data on the share. This type of configuration is best suited for small networks
where quick and easy access to the share is more important than the security of the data on the share.
To configure an unauthenticated SMB share, click Wizard, then click the Next button twice to display the
screen shown in Figure 10.14. Complete the following fields in this screen:
1. Share name: enter a name for the share that is useful to you. In this example, the share is named
smb_insecure.
2. Click the button for Windows (SMB) and check the box for Allow Guest.
3. Click the Ownership button. Click the drop-down User menu and select nobody. Click the Return button
to return to the previous screen.
4. Click the Add button. If you forget to do this, the share will not be created. Clicking the Add button
adds an entry to the Name frame with the name that was entered in Share name.
10.4. Windows (SMB) Shares
189
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.14: Creating an Unauthenticated SMB Share
Click the Next button twice, then the Confirm button to create the share. The Wizard automatically creates
a dataset for the share and starts the SMB service so the share is immediately available. The new share is
also be added to Sharing → Windows (SMB).
Users can now access the share from any SMB client and will not be prompted for their username or password. For example, to access the share from a Windows system, open Explorer and click on Network. For
this configuration example, a system named FREENAS appears with a share named insecure_smb. The user
can copy data to and from the unauthenticated SMB share.
10.4.2 Configuring Authenticated Access Without a Domain Controller
Most configuration scenarios require each user to have their own user account and to authenticate before
accessing the share. This allows the administrator to control access to data, provide appropriate permissions to that data, and to determine who accesses and modifies stored data. A Windows domain controller
is not needed for authenticated SMB shares, which means that additional licensing costs are not required.
However, since there is no domain controller to provide authentication for the network, each user account
needs to be created on the FreeNAS® system. This type of configuration scenario is often used in home and
small networks as it does not scale well if many users accounts are needed.
Before configuring this scenario, determine which users will need authenticated access. While not required
for the configuration, it eases troubleshooting if the username and password that will be created on the
190
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
FreeNAS® system matches that information on the client system. Next, determine if each user should
have their own share to store their own data or if several users will be using the same share. The simpler
configuration is to make one share per user as it does not require the creation of groups, adding the correct
users to the groups, and ensuring that group permissions are set correctly.
To use the Wizard to create an authenticated SMB share, enter the following information, as shown in the
example in Figure 10.15.
1. Share name: enter a name for the share that is useful to you. In this example, the share is named
smb_user1.
2. Click the button for Windows (SMB).
3. Click the Ownership button. To create the user account on the FreeNAS® system, type their name into
the User field and check the Create User checkbox. The user’s password is then entered and confirmed.
If the user will not be sharing this share with other users, type their name into the Group field and
click Create Group. If, however, the share will be used by several users, instead type in a group
name and check the Create Group box. In the example shown in Figure 10.16, user1 has been used
for both the user and group name, meaning that this share will only be used by user1. When finished,
click Return to return to the screen shown in Figure 10.15.
4. Click the Add button. If you forget to do this, the share will not be created. Clicking the Add button
adds an entry to the Name frame with the name that was entered in Share name.
If you wish to configure multiple authenticated shares, repeat for each user, giving each user their own
Share name and Ownership. When finished, click Next twice, then Confirm to create the shares. The Wizard
automatically creates a dataset with the correct ownership for each share and starts the SMB service so the
shares are available immediately. The new shares are also added to Sharing → Windows (SMB).
10.4. Windows (SMB) Shares
191
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.15: Creating an Authenticated SMB Share
Fig. 10.16: Creating the User and Group
192
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
The authenticated share can now be tested from any SMB client. For example, to test an authenticated
share from a Windows system, open Explorer and click on Network. For this configuration example, a system
named FREENAS appears with a share named smb_user1. If you click on smb_user1, a Windows Security popup screen prompts for that user’s username and password. Enter the values that were configured for that
share, in this case user user1. After authentication, the user can copy data to and from the SMB share.
To prevent Windows Explorer from hanging when accessing the share, map the share as a network drive.
To do this, right-click the share and select Map network drive.... Choose a drive letter from the drop-down
menu and click the Finish button.
Note that Windows systems cache a user’s credentials. This can cause issues when testing or accessing
multiple authenticated shares as only one authentication is allowed at a time. If you are having problems
authenticating to a share and are sure that you are entering the correct username and password, type cmd
in the Search programs and files box and use the following command to see if you have already authenticated
to a share. In this example, the user has already authenticated to the smb_user1 share:
net use
New connections will be remembered.
Status
Local
Remote
Network
-----------------------------------------------------------------------OK
\\FREENAS\smb_user1 Microsoft Windows Network
The command completed successfully.
To clear the cache:
net use * /DELETE
You have these remote connections:
\\FREENAS\smb_user1
Continuing will cancel the connections.
Do you want to continue this operation? <Y/N> [N]: y
An additional warning is shown if the share is currently open in Explorer:
There are open files and/or incomplete directory searches pending on the connection
to \\FREENAS|smb_user1.
Is it OK to continue disconnecting and force them closed? <Y/N> [N]: y
The command completed successfully.
The next time a share is accessed with Explorer, you will be prompted to authenticate.
10.4.3 Configuring Shadow Copies
Shadow Copies (https://en.wikipedia.org/wiki/Shadow_copy), also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots. Shadow copies allow you to easily restore previous versions of files from within Windows Explorer. Shadow Copy support
is built into Vista and Windows 7. Windows XP or 2000 users need to install the Shadow Copy client
(http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=16220).
When you create a periodic snapshot task on a ZFS volume that is configured as a SMB share in FreeNAS® ,
it is automatically configured to support shadow copies.
Before using shadow copies with FreeNAS® , be aware of the following caveats:
10.4. Windows (SMB) Shares
193
FreeNAS® 11.0-U4 User Guide, Release 11.0
• If the Windows system is not fully patched to the latest service pack, Shadow Copies may not work.
If you are unable to see any previous versions of files to restore, use Windows Update to make sure
that the system is fully up-to-date.
• Shadow copy support only works for ZFS pools or datasets. This means that the SMB share must be
configured on a volume or dataset, not on a directory.
• Datasets are filesystems and shadow copies cannot traverse filesystems. If you want to be able to see
the shadow copies in your child datasets, create separate shares for them.
• Shadow copies will not work with a manual snapshot, you must create a periodic snapshot task for
the pool or dataset being shared by SMB or a recursive task for a parent dataset.
• The periodic snapshot task should be created and at least one snapshot should exist before creating
the SMB share. If the SMB share was created first, restart the SMB service in Services → Control
Services.
• Appropriate permissions must be configured on the volume/dataset being shared by SMB.
• Users cannot delete shadow copies on the Windows system due to the way Samba works. Instead, the
administrator can remove snapshots from the FreeNAS® administrative GUI. The only way to disable
shadow copies completely is to remove the periodic snapshot task and delete all snapshots associated
with the SMB share.
To configure shadow copy support, use the instructions in Configuring Authenticated Access Without a Domain
Controller (page 190) to create the desired number of shares. In this configuration example, a Windows 7
computer has two users: user1 and user2. For this example, two authenticated shares are created so that
each user account has their own share. The first share is named user1 and the second share is named user2.
Then:
1. Use Storage → Periodic Snapshot Tasks → Add Periodic Snapshot to create at least
one periodic snapshot task. You can either create a snapshot task for each user’s dataset, in this
example the datasets /mnt/volume1/user1 and /mnt/volume1/user2, or you can create one
periodic snapshot task for the entire volume, in this case /mnt/volume1. Before continuing to the
next step, confirm that at least one snapshot for each defined task is displayed in the Storage →
Snapshots tab. When creating the schedule for the periodic snapshot tasks, keep in mind how often
your users need to access modified files and during which days and time of day they are likely to make
changes.
2. Go to Sharing → Windows (SMB) Shares. Highlight a share and click Edit, then Advanced
Mode. Click the Periodic Snapshot Task drop-down menu and select the periodic snapshot task to
use for that share. Repeat for each share being configured as a shadow copy. For this example, the share named /mnt/volume1/user1 is configured to use a periodic snapshot task that
was configured to take snapshots of the /mnt/volume1/user1 dataset and the share named
/mnt/volume1/user2 is configured to use a periodic snapshot task that was configured to take
snapshots of the /mnt/volume1/user2 dataset.
3. Verify that the SMB service is set to ON in Services → Control Services.
Figure 10.17 provides an example of using shadow copies while logged in as user1 on the Windows system.
In this example, the user right-clicked modified file and selected Restore previous versions from the menu. This
particular file has three versions: the current version, plus two previous versions stored on the FreeNAS®
system. The user can choose to open one of the previous versions, copy a previous version to the current
folder, or restore one of the previous versions, overwriting the existing file on the Windows system.
194
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.17: Viewing Previous Versions within Explorer
10.5 Block (iSCSI)
iSCSI is a protocol standard for the consolidation of storage data. iSCSI allows FreeNAS® to act like a storage
area network (SAN) over an existing Ethernet network. Specifically, it exports disk devices over an Ethernet
network that iSCSI clients (called initiators) can attach to and mount. Traditional SANs operate over fibre
channel networks which require a fibre channel infrastructure such as fibre channel HBAs, fibre channel
switches, and discrete cabling. iSCSI can be used over an existing Ethernet network, although dedicated
networks can be built for iSCSI traffic in an effort to boost performance. iSCSI also provides an advantage
in an environment that uses Windows shell programs; these programs tend to filter “Network Location” but
iSCSI mounts are not filtered.
Before configuring the iSCSI service, be familiar with this iSCSI terminology:
CHAP: an authentication method which uses a shared secret and three-way authentication to determine
if a system is authorized to access the storage device and to periodically confirm that the session has not
been hijacked by another system. In iSCSI, the initiator (client) performs the CHAP authentication.
10.5. Block (iSCSI)
195
FreeNAS® 11.0-U4 User Guide, Release 11.0
Mutual CHAP: a superset of CHAP in that both ends of the communication authenticate to each other.
Initiator: a client which has authorized access to the storage data on the FreeNAS® system. The client
requires initiator software to initiate the connection to the iSCSI share.
Target: a storage resource on the FreeNAS® system. Every target has a unique name known as an iSCSI
Qualified Name (IQN).
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP
network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
LUN: Logical Unit Number representing a logical SCSI device. An initiator negotiates with a target to establish
connectivity to a LUN. The result is an iSCSI connection that emulates a connection to a SCSI hard disk.
Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote
directories, initiators format and directly manage filesystems on iSCSI LUNs. When configuring multiple
iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the
same TCP connection, there can be TCP contention when more than one target accesses the same LUN.
FreeNAS® supports up to 1024 LUNs.
In FreeNAS® , iSCSI is built into the kernel. This version of iSCSI supports Microsoft Offloaded Data Transfer (ODX) (https://technet.microsoft.com/en-us/library/hh831628), meaning that file copies happen locally,
rather than over the network. It also supports the VAAI (page 327) (vStorage APIs for Array Integration) primitives for efficient operation of storage tasks directly on the NAS. To take advantage of the VAAI primitives,
create a zvol using the instructions in Create zvol (page 118) and use it to create a device extent, as described
in Extents (page 203).
To configure iSCSI:
1. Review the target global configuration parameters.
2. Create at least one portal.
3. Determine which hosts are allowed to connect using iSCSI and create an initiator.
4. Decide if authentication will be used, and if so, whether it will be CHAP or mutual CHAP. If using
authentication, create an authorized access.
5. Create a target.
6. Create either a device or a file extent to be used as storage.
7. Associate a target with an extent.
8. Start the iSCSI service in Services → Control Services.
The rest of this section describes these steps in more detail.
10.5.1 Target Global Configuration
Sharing → Block (iSCSI) → Target Global Configuration, shown in Figure 10.18, contains
settings that apply to all iSCSI shares. Table 10.6 summarizes the settings that can be configured in the
Target Global Configuration screen.
Some built-in values affect iSNS usage. Fetching of allowed initiators from iSNS is not implemented, so
target ACLs must be configured manually. To make iSNS registration useful, iSCSI targets should have explicitly configured port IP addresses. This avoids initiators attempting to discover unconfigured target portal
addresses like 0.0.0.0.
196
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
The iSNS registration period is 900 seconds. Registered Network Entities not updated during this period are
unregistered. The timeout for iSNS requests is 5 seconds.
Fig. 10.18: iSCSI Target Global Configuration Variables
Table 10.6: Target Global Configuration Settings
Setting
Base Name
Value
string
ISNS Servers
string
Pool Available Space
Threshold
integer
Description
see the “Constructing iSCSI names using the iqn. format” section
of RFC 3721 (https://tools.ietf.org/html/rfc3721.html) if unfamiliar with this format
space delimited list of hostnames or IP addresses of ISNS
servers with which to register the system’s iSCSI targets and portals
enter the percentage of free space that should remain in the
pool; when this percentage is reached, the system issues an
alert, but only if zvols are used; see VAAI (page 327) Threshold
Warning
10.5.2 Portals
A portal specifies the IP address and port number to be used for iSCSI connections. Sharing → Block
(iSCSI) → Portals → Add Portal brings up the screen shown in Figure 10.19.
Table 10.19 summarizes the settings that can be configured when adding a portal. If you need to assign
additional IP addresses to the portal, click the link Add extra Portal IP.
10.5. Block (iSCSI)
197
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.19: Adding an iSCSI Portal
Table 10.7: Portal Configuration Settings
Setting
Comment
Value
string
Discovery Auth Method
dropdown
menu
dropdown
menu
dropdown
menu
integer
Discovery Auth Group
IP address
Port
Description
optional description; portals are automatically assigned a numeric group ID
configures the authentication level required by the target for
discovery of valid devices, where None will allow anonymous
discovery while CHAP and Mutual CHAP require authentication
select a user created in Authorized Access if the Discovery Auth
Method is set to CHAP or Mutual CHAP
select the IP address associated with an interface or the wildcard address of 0.0.0.0 (any interface)
TCP port used to access the iSCSI target; default is 3260
FreeNAS® systems with multiple IP addresses or interfaces can use a portal to provide services on different
interfaces or subnets. This can be used to configure multi-path I/O (MPIO). MPIO is more efficient than a
198
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
link aggregation.
If the FreeNAS® system has multiple configured interfaces, portals can also be used to provide network
access control. For example, consider a system with four interfaces configured with the following addresses:
192.168.1.1/24
192.168.2.1/24
192.168.3.1/24
192.168.4.1/24
You could create a portal containing the first two IP addresses (group ID 1) and a portal containing the
remaining two IP addresses (group ID 2). You could then create a target named A with a Portal Group ID of
1 and a second target named B with a Portal Group ID of 2. In this scenario, the iSCSI service would listen on
all four interfaces, but connections to target A would be limited to the first two networks and connections
to target B would be limited to the last two networks.
Another scenario would be to create a portal which includes every IP address except for the one used by a
management interface. This would prevent iSCSI connections to the management interface.
10.5.3 Initiators
The next step is to configure authorized initiators, or the systems which are allowed to connect to the
iSCSI targets on the FreeNAS® system. To configure which systems can connect, use Sharing → Block
(iSCSI) → Initiators → Add Initiator, shown in Figure 10.20.
Fig. 10.20: Adding an iSCSI Initiator
Table 10.8 summarizes the settings that can be configured when adding an initiator.
Table 10.8: Initiator Configuration Settings
Setting
Initiators
Value
string
Authorized network
string
Comment
string
10.5. Block (iSCSI)
Description
use ALL keyword or a list of initiator hostnames separated by
spaces
use ALL keyword or a network address with CIDR mask such as
192.168.2.0/24
optional description
199
FreeNAS® 11.0-U4 User Guide, Release 11.0
In the example shown in Figure 10.21, two groups have been created. Group 1 allows connections from any
initiator on any network. Group 2 allows connections from any initiator on the 10.10.1.0/24 network. Click
an initiator’s entry to display its Edit and Delete buttons.
Note: Attempting to delete an initiator causes a warning that indicates if any targets or target/extent
mappings depend upon the initiator. Confirming the delete causes these to be deleted as well.
Fig. 10.21: Sample iSCSI Initiator Configuration
10.5.4 Authorized Accesses
If you will be using CHAP or mutual CHAP to provide authentication, you must create an authorized
access in Sharing → Block (iSCSI) → Authorized Accesses → Add Authorized Access.
This screen is shown in Figure 10.22.
Note: This screen sets login authentication. This is different from discovery authentication which is set in
Target Global Configuration (page 196).
200
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.22: Adding an iSCSI Authorized Access
Table 10.9 summarizes the settings that can be configured when adding an authorized access:
Table 10.9: Authorized Access Configuration Settings
Setting
Group ID
Value
integer
User
string
Secret
string
Peer User
string
Peer Secret
string
Description
allows different groups to be configured with different authentication profiles; for instance, all users with a Group ID of 1 will
inherit the authentication profile associated with Group 1
name of user account to create for CHAP authentication with
the user on the remote system; many initiators default to using
the initiator name as the user
password to be associated with User; the iSCSI standard requires that this be between 12 and 16 characters
only input when configuring mutual CHAP; in most cases it will
need to be the same value as User
the mutual secret password which must be different than the
Secret; required if Peer User is set
Note: CHAP does not work with GlobalSAN initiators on Mac OS X.
As authorized accesses are added, they will be listed under View Authorized Accesses. In the example shown
in Figure 10.23, three users (test1, test2, and test3) and two groups (1 and 2) have been created, with group
1 consisting of one CHAP user and group 2 consisting of one mutual CHAP user and one CHAP user. Click
an authorized access entry to display its Edit and Delete buttons.
10.5. Block (iSCSI)
201
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.23: Viewing Authorized Accesses
10.5.5 Targets
Next, create a Target using Sharing → Block (iSCSI) → Targets → Add Target, as shown in
Figure 10.24. A target combines a portal ID, allowed initiator ID, and an authentication method. Table 10.10
summarizes the settings that can be configured when creating a Target.
Note: An iSCSI target creates a block device that may be accessible to multiple initiators. A clustered
filesystem is required on the block device, such as VMFS used by VMware ESX/ESXi, in order for multiple
initiators to mount the block device read/write. If a traditional filesystem such as EXT, XFS, FAT, NTFS, UFS,
or ZFS is placed on the block device, care must be taken that only one initiator at a time has read/write
access or the result will be filesystem corruption. If multiple clients need access to the same data on a
non-clustered filesystem, use SMB or NFS instead of iSCSI, or create multiple iSCSI targets (one per client).
202
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.24: Adding an iSCSI Target
Table 10.10: Target Settings
Setting
Target Name
Value
string
Target Alias
Portal Group ID
string
dropdown
menu
dropdown
menu
dropdown
menu
dropdown
menu
Initiator Group ID
Auth Method
Authentication Group
number
Description
required value; base name will be appended automatically if it
does not start with iqn
optional user-friendly name
leave empty or select number of existing portal to use
select which existing initiator group has access to the target
choices are None, Auto, CHAP, or Mutual CHAP
None or integer representing number of existing authorized access
10.5.6 Extents
iSCSI targets provide virtual access to resources on the FreeNAS® system. Extents are used to define resources to share with clients. There are two types of extents: device and file.
Device extents provide virtual storage access to zvols, zvol snapshots, or physical devices like a
10.5. Block (iSCSI)
203
FreeNAS® 11.0-U4 User Guide, Release 11.0
disk, an SSD, a hardware RAID volume, or a HAST device (http://www.freebsd.org/doc/en_US.ISO88591/books/handbook/disks-hast.html).
File extents provide virtual storage access to an individual file.
Tip: For typical use as storage for virtual machines where the virtualization software is the iSCSI
initiator, device extents with zvols provide the best performance and most features. For other applications, device extents sharing a raw device can be appropriate. File extents do not have the performance
or features of device extents, but do allow creating multiple extents on a single filesystem.
Virtualized zvols support all the FreeNAS® VAAI (page 327) primitives and are recommended for use with
virtualization software as the iSCSI initiator.
The ATS, WRITE SAME, XCOPY and STUN, primitives are supported by both file and device extents. The
UNMAP primitive is supported by zvols and raw SSDs. The threshold warnings primitive is fully supported
by zvols and partially supported by file extents.
Virtualizing a raw device like a single disk or hardware RAID volume limits performance to the abilities of
the device. Because this bypasses ZFS, such devices do not benefit from ZFS caching or provide features
like block checksums or snapshots.
Virtualizing a zvol adds the benefits of ZFS, such as read and write cache. Even if the client formats a device
extent with a different filesystem, the data still resides on a ZFS volume and benefits from ZFS features like
block checksums and snapshots.
Warning: For performance reasons and to avoid excessive fragmentation, keep the used space of
the pool below 50% when using iSCSI. The capacity of an existing extent can be increased as shown in
Growing LUNs (page 208).
To add an extent, go to Sharing → Block (iSCSI) → Extents → Add Extent. In the example
shown in Figure 10.25, the device extent is using the export zvol that was previously created from the
/mnt/volume1 volume.
Table 10.11 summarizes the settings that can be configured when creating an extent. Note that file extent
creation will fail if you do not append the name of the file to be created to the volume/dataset name.
204
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.25: Adding an iSCSI Extent
Table 10.11: Extent Configuration Settings
Setting
Extent Name
Value
string
Extent Type
dropdown
menu
dropdown
menu
string
Device
Serial
Path to the extent
10.5. Block (iSCSI)
browse
button
Description
name of extent; if the Extent size is not 0, it cannot be an existing
file within the volume/dataset
select from File or Device
only appears if Device is selected; select the unformatted disk,
controller, zvol, zvol snapshot, or HAST device
unique LUN ID; the default is generated from the system’s MAC
address
only appears if File is selected; browse to an existing file and use
0 as the Extent size, or browse to the volume or dataset, click
Close, append the Extent Name to the path, and specify a value
in Extent size; extents cannot be created inside the jail root directory
Continued on next page
205
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Extent size
Logical Block Size
Disable Physical Block
Size Reporting
Available Space Threshold
Comment
Enable TPC
Xen initiator compat
mode
LUN RPM
Read-only
Table 10.11 – continued from previous page
Value
Description
integer
only appears if File is selected; if the size is specified as 0, the file
must already exist and the actual file size will be used; otherwise, specify the size of the file to create
droponly override the default if the initiator requires a different
down
block size
menu
checkbox
if the initiator does not support physical block size values over
4K (MS SQL), check this box
string
only appears if File or a zvol is selected; when the specified percentage of free space is reached, the system issues an alert; see
VAAI (page 327) Threshold Warning
string
optional
checkbox
if checked, an initiator can bypass normal access control and
access any scannable target; this allows xcopy operations otherwise blocked by access control
checkbox
check this box when using Xen as the iSCSI initiator
dropdown
menu
checkbox
do NOT change this setting when using Windows as the initiator; only needs to be changed in large environments where the
number of systems using a specific RPM is needed for accurate
reporting statistics
check this box to prevent the initiator from initializing this LUN
10.5.7 Target/Extents
The last step is associating an extent to a target within Sharing → Block (iSCSI) → Associated
Targets → Add Target/Extent. This screen is shown in Figure 10.26. Use the drop-down menus to
select the existing target and extent. Click OK to add an entry for the LUN.
Fig. 10.26: Associating a Target With an Extent
Table 10.12 summarizes the settings that can be configured when associating targets and extents.
206
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 10.12: Target/Extents Configuration Settings
Setting
Target
LUN ID
Value
drop-down menu
drop-down menu
Extent
drop-down menu
Description
select the pre-created target
select the value of the ID or type in the desired value; FreeNAS®
supports up to 1024 LUNs
select the pre-created extent
It is recommended to always associate extents to targets in a one-to-one manner, even though the GUI will
allow multiple extents to be associated with the same target.
Note: Each LUN entry has Edit and Delete buttons for modifying the settings or deleting the LUN entirely. A
verification popup appears when the Delete button is clicked. If an initiator has an active connection to the
LUN, it is indicated in red text. It is recommended to clear initiator connections to a LUN before deleting it.
After iSCSI has been configured, remember to start it in Services → Control Services. Click the red
OFF button next to iSCSI. After a second or so, it will change to a blue ON, indicating that the service has
started.
10.5.8 Connecting to iSCSI
To access the iSCSI target, clients must use iSCSI initiator software.
An iSCSI Initiator client is pre-installed with Windows 7.
A detailed how-to for this client can
be found here (http://www.windowsnetworking.com/articles-tutorials/windows-7/Connecting-Windows-7iSCSI-SAN.html). A client for Windows 2000, XP, and 2003 can be found here (http://www.microsoft.com/enus/download/details.aspx?id=18986).
This how-to (http://blog.pluralsight.com/freenas-8-iscsi-targetwindows-7) shows how to create an iSCSI target for a Windows 7 system.
Mac OS X does not include an initiator. globalSAN (http://www.studionetworksolutions.com/globalsan-iscsiinitiator/) is a commercial, easy-to-use Mac initiator.
BSD systems provide command line initiators: iscontrol(8) (http://www.freebsd.org/cgi/man.cgi?query=iscontrol)
comes with FreeBSD versions 9.x and lower, iscsictl(8) (https://www.freebsd.org/cgi/man.cgi?query=iscsictl)
comes with FreeBSD versions 10.0 and higher, iscsi-initiator(8) (http://netbsd.gw.com/cgi-bin/mancgi?iscsi-initiator++NetBSD-current) comes with NetBSD, and iscsid(8) (http://www.openbsd.org/cgibin/man.cgi/OpenBSD-current/./man8/iscsid.8?query=iscsid) comes with OpenBSD.
Some Linux distros provide the command line utility iscsiadm from Open-iSCSI (http://www.openiscsi.com/). Use a web search to see if a package exists for your distribution should the command not
exist on your Linux system.
If a LUN is added while iscsiadm is already connected, it will not see the new LUN until rescanned with
iscsiadm -m node -R. Alternately, use iscsiadm -m discovery -t st -p portal_IP to find
the new LUN and iscsiadm -m node -T LUN_Name -l to log into the LUN.
Instructions for connecting from a VMware ESXi Server can be found at How to configure FreeNAS 8
for iSCSI and connect to ESX(i) (http://www.vladan.fr/how-to-configure-freenas-8-for-iscsi-and-connect-toesxi/). Note that the requirements for booting vSphere 4.x off iSCSI differ between ESX and ESXi. ESX
requires a hardware iSCSI adapter while ESXi requires specific iSCSI boot firmware support. The magic is on
the booting host side, meaning that there is no difference to the FreeNAS® configuration. See the iSCSI SAN
Configuration Guide (http://www.vmware.com/pdf/vsphere4/r41/vsp_41_iscsi_san_cfg.pdf) for details.
10.5. Block (iSCSI)
207
FreeNAS® 11.0-U4 User Guide, Release 11.0
The VMware firewall only allows iSCSI connections on port 3260 by default. If a different port has been selected, outgoing connections to that port must be manually added to the firewall before those connections
will work.
If the target can be seen but does not connect, check the Discovery Auth settings in Target Global Configuration.
If the LUN is not discovered by ESXi, make sure that promiscuous mode is set to Accept in the vSwitch.
10.5.9 Growing LUNs
The method used to grow the size of an existing iSCSI LUN depends on whether the LUN is backed by a file
extent or a zvol. Both methods are described in this section.
Enlarging a LUN with one of the methods below gives it more unallocated space, but does not automatically
resize filesystems or other data on the LUN. This is the same as binary-copying a smaller disk onto a larger
one. More space is available on the new disk, but the partitions and filesystems on it must be expanded to
use this new space. Resizing virtual disk images is usually done from virtual machine management software.
Application software to resize filesystems is dependent on the type of filesystem and client, but is often run
from within the virtual machine. For instance, consider a Windows VM with the last partition on the disk
holding an NTFS filesystem. The LUN is expanded and the partition table edited to add the new space to
the last partition. The Windows disk manager must still be used to resize the NTFS filesystem on that last
partition to use the new space.
Zvol Based LUN
To grow a zvol based LUN, go to Storage → Volumes → View Volumes, highlight the zvol to be
grown, and click Edit zvol. In the example shown in Figure 10.27, the current size of the zvol named zvol1 is
4GB.
208
Chapter 10. Sharing
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 10.27: Editing an Existing Zvol
Enter the new size for the zvol in the Size field and click Edit ZFS Volume. This menu closes and the new size
for the zvol is immediately shown in the Used column of the View Volumes screen.
Note: The GUI does not allow reducing (shrinking) the size of the zvol, as doing so could result in loss of
data. It also does not allow increasing the size of the zvol past 80% of the volume size.
File Extent Based LUN
To grow a file extent based LUN, go to Services → iSCSI → File Extents → View File
Extents to determine the path of the file extent to grow. Open Shell to grow the extent. This example
grows /mnt/volume1/data by 2 G:
truncate -s +2g /mnt/volume1/data
Go back to Services → iSCSI → File Extents → View File Extents and click the Edit button for the file extent. Set the size to 0 as this causes the iSCSI target to use the new size of the file.
10.5. Block (iSCSI)
209
CHAPTER
ELEVEN
SERVICES
The Services section of the GUI is where various services that ship with the FreeNAS® system are configured,
started, or stopped. FreeNAS® includes these built-in services:
• AFP (page 212)
• Domain Controller (page 214)
• Dynamic DNS (page 216)
• FTP (page 217)
• iSCSI (page 223)
• LLDP (page 223)
• NFS (page 224)
• Rsync (page 225)
• S3 (page 228)
• S.M.A.R.T. (page 229)
• SMB (page 230)
• SNMP (page 236)
• SSH (page 237)
• TFTP (page 240)
• UPS (page 241)
• WebDAV (page 244)
This section demonstrates starting a FreeNAS® service and the available configuration options for each
FreeNAS® service.
11.1 Control Services
Services → Control Services, shown in Figure 11.1, shows which services are currently running and
can start, stop, or configure them. The S.M.A.R.T. service is enabled by default, but only runs if the storage
devices support S.M.A.R.T. data (http://en.wikipedia.org/wiki/S.M.A.R.T.) Other services default to off until
started.
210
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 11.1: Control Services
Stopped services show a red stop symbol and a Start Now button. Running services show a green light with
a Stop Now button.
Tip: Using a proxy server can prevent the list of services from being displayed. If a proxy server is used,
configure it to not proxy local network connections or websocket connections. VPN software can also cause
problems. If the list of services is displayed when connecting on the local network but not when connecting
through the VPN, check the VPN software configuration.
Services are configured by clicking the wrench icon or the name of the service in the Services section of the
tree menu.
11.1. Control Services
211
FreeNAS® 11.0-U4 User Guide, Release 11.0
If a service does not start, go to System → Advanced and check the box Show console messages in the
footer. Console messages appear at the bottom of the browser. Clicking the console message area makes
it into a pop-up window, allowing scrolling through or copying the messages. Watch these messages for
errors when stopping or starting the problematic service.
To read the system logs for more information about a service failure, open Shell (page 288) and type more
/var/log/messages.
11.2 AFP
The settings that are configured when creating AFP Shares in Sharing → Apple (AFP) Shares →
Add Apple (AFP) Share are specific to each configured AFP Share. In contrast, global settings which
apply to all AFP shares are configured in Services → AFP.
Figure 11.2 shows the available global AFP configuration options which are described in Table 11.1.
212
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 11.2: Global AFP Configuration
Table 11.1: Global AFP Configuration Options
Setting
Guest Access
Value
checkbox
Guest account
Max Connections
Enable home
directories
drop-down menu
11.2. AFP
integer
checkbox
Description
if checked, clients will not be prompted to authenticate before
accessing AFP shares
select account to use for guest access; the selected account
must have permissions to the volume or dataset being shared
maximum number of simultaneous connections
if checked, any user home directories located under Home directories will be available over the share
Continued on next page
213
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Home directories
Home share
name
Database
Path
Global auxiliary parameters
Map ACLs
Bind IP Addresses
Table 11.1 – continued from previous page
Value
Description
browse button
select the volume or dataset which contains user home directories
string
overrides default home folder name with the specified value
browse button
string
drop-down menu
selection
select the path to store the CNID databases used by AFP (default is the root of the volume); the path must be writable
additional afp.conf(5)
(http://netatalk.sourceforge.net/3.0/htmldocs/afp.conf.5.html)
parameters not covered elsewhere in this screen
choose mapping of effective permissions for authenticated
users; Rights (default, Unix-style permissions), Mode (ACLs), or
None
specify the IP addresses to listen for FTP connections; highlight
the desired IP addresses in the Available list and use the >> button to add to the Selected list
When configuring home directories, it is recommended to create a dataset to hold the home directories which contains a child dataset for each user. As an example, create a dataset named
volume1/homedirs and browse to this dataset when configuring the Home directories field of the AFP
service. Then, as you create each user, first create a child dataset for that user. For example, create a dataset named volume1/homedirs/user1. When you create the user1 user, browse to the
volume1/homedirs/user1 dataset in the Home Directory field of the Add New User screen.
11.2.1 Troubleshooting AFP
You can determine which users are connected to an AFP share by typing afpusers.
If Something wrong with the volume’s CNID DB is shown, run this command from Shell (page 288), replacing
the path to the problematic AFP share:
dbd -rf /path/to/share
This command may take a while, depending upon the size of the volume or dataset being shared. This
command will wipe the CNID database and rebuild it from the CNIDs stored in the AppleDouble files.
11.3 Domain Controller
FreeNAS® can be configured to act either as the domain controller for a network or to join an existing Active
Directory (page 152) network as a domain controller.
Note: This section demonstrates how to configure the FreeNAS® system to act as a domain controller. If
the goal is to integrate with an existing Active Directory (page 152) network to access its authentication and
authorization services, configure Active Directory (page 152) instead.
Be aware that configuring a domain controller is a complex process that requires a good understanding of how Active Directory (page 152) works. While Services → Domain Controller makes it easy
to input the needed settings into the administrative graphical interface, it is important to understand
what those settings should be. Before beginning configuration, read through the Samba AD DC HOWTO
214
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
(https://wiki.samba.org/index.php/Samba_AD_DC_HOWTO). After FreeNAS® is configured, use the RSAT utility from a Windows system to manage the domain controller. The Samba AD DC HOWTO includes instructions for installing and configuring RSAT.
Figure 11.3 shows the configuration screen for creating a domain controller and Table 11.2 summarizes the
available options.
Fig. 11.3: Domain Controller Settings
Table 11.2: Domain Controller Configuration Options
Setting
Realm
Domain
Server Role
Value
string
string
drop-down menu
DNS Forwarder
Domain Forest Level
string
drop-down menu
11.3. Domain Controller
Description
capitalized DNS realm name
capitalized domain name
at this time, the only supported role is as the domain controller
for a new domain
IP address of DNS forwarder; required for recursive queries
when SAMBA_INTERNAL is selected
choices are 2000, 2003, 2008, or 2008_R2; refer to Understanding Active Directory Domain Services (AD DS) Functional Levels
(https://technet.microsoft.com/en-us/library/understandingactive-directory-functional-levels(WS.10).aspx) for details
Continued on next page
215
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Administrator
password
Kerberos
Realm
Table 11.2 – continued from previous page
Description
password to be used for the Active Directory (page 152) administrator account
drop-down menu
auto-populates with information from the Realm when the settings in this screen are saved
Value
string
11.3.1 Samba Domain Controller Backup
A samba_backup script is available to back up Samba4 domain controller settings is available. From the
Shell (page 288), run /usr/local/bin/samba_backup --usage to show the input options.
11.4 Dynamic DNS
Dynamic DNS (DDNS) is useful if the FreeNAS® system is connected to an ISP that periodically changes the
IP address of the system. With dynamic DNS, the system can automatically associate its current IP address
with a domain name, allowing you to access the FreeNAS® system even if the IP address changes. DDNS
requires you to register with a DDNS service such as DynDNS (http://dyn.com/dns/).
Figure 11.4 shows the DDNS configuration screen and Table 11.3 summarizes the configuration options.
The values to enter will be provided by the DDNS provider. After configuring DDNS, remember to start the
DDNS service in Services → Control Services.
Fig. 11.4: Configuring DDNS
216
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 11.3: DDNS Configuration Options
Setting
Provider
Value
drop-down menu
IP Server
string
Domain name
Username
Password
Update period
Forced update period
Auxiliary parameters
string
string
string
integer
integer
string
Description
several providers are supported; if your provider is not listed,
leave this field blank and specify the custom provider in the Auxiliary parameters field
can be used to specify the hostname and port of the IP check
server
fully qualified domain name (e.g. yourname.dyndns.org)
username used to logon to the provider and update the record
password used to logon to the provider and update the record
how often the IP is checked in seconds
how often the IP should be updated, even it has not changed, in
seconds
additional parameters passed to the provider during record
update; an example of specifying a custom provider is dyndns_system default@provider.com
When using “freedns.afraid.org”, see this forum post (https://forums.freenas.org/index.php?threads/dynamicdns-and-freeedns-afraid-org.24455/#post-151746) for an example configuration.
When using “he.net”, enter the domain name for Username and enter the DDNS key generated for that
domain’s A entry at the he.net website for Password.
11.5 FTP
FreeNAS® uses the proftpd (http://www.proftpd.org/) FTP server to provide FTP services. Once the FTP
service is configured and started, clients can browse and download data using a web browser or FTP client
software. The advantage of FTP is that easy-to-use cross-platform utilities are available to manage uploads
to and downloads from the FreeNAS® system. The disadvantage of FTP is that it is considered to be an
insecure protocol, meaning that it should not be used to transfer sensitive files. If you are concerned about
sensitive data, see Encrypting FTP.
This section provides an overview of the FTP configuration options. It then provides examples for configuring anonymous FTP, specified user access within a chroot environment, encrypting FTP connections, and
troubleshooting tips.
Figure 11.5 shows the configuration screen for Services → FTP. Some settings are only available in
Advanced Mode. To see these settings, either click the Advanced Mode button or configure the system to
always display these settings by checking the box Show advanced fields by default in System → Advanced.
11.5. FTP
217
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 11.5: Configuring FTP
Table 11.4 summarizes the available options when configuring the FTP server.
Table 11.4: FTP Configuration Options
Setting
Value
Port
Clients
Connections
integer
integer
integer
Login Attempts
integer
Timeout
integer
Allow Root Login
Allow Anonymous
Login
Path
checkbox
checkbox
Allow Local User
Login
Display Login
218
browse button
checkbox
string
Advanced
Mode
Description
port the FTP service listens on
maximum number of simultaneous clients
maximum number of connections per IP address
where 0 means unlimited
maximum number of attempts before client is disconnected; increase this if users are prone to typos
maximum client idle time in seconds before client is
disconnected
discouraged as increases security risk
enables anonymous FTP logins with access to the directory specified in Path
root directory for anonymous FTP connections
required if Anonymous Login is disabled
message displayed to local login users after authentication; not displayed to anonymous login users
Continued on next page
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Table 11.4 – continued from previous page
Advanced Description
Mode
checkboxes
X
sets default permissions for newly created files
checkboxes
X
sets default permissions for newly created directories
Value
File Permission
Directory Permission
Enable FXP
checkbox
X
enables File eXchange Protocol which is discouraged
(https://en.wikipedia.org/wiki/File_eXchange_Protocol)
as it makes the server vulnerable to FTP bounce attacks
Allow Transfer
checkbox
allows FTP clients to resume interrupted transfers
Resumption
Always Chroot
checkbox
a local user is only allowed access to their home directory unless the user is a member of group wheel
Require IDENT
checkbox
X
will result in timeouts if identd is not running on the
Authentication
client
Perform Reverse
checkbox
perform reverse DNS lookups on client IPs; can cause
DNS Lookups
long delays if reverse DNS is not configured
Masquerade adstring
public IP address or hostname; set if FTP clients candress
not connect through a NAT device
Minimum passive
integer
X
used by clients in PASV mode, default of 0 means any
port
port above 1023
Maximum passive
integer
X
used by clients in PASV mode, default of 0 means any
port
port above 1023
Local user upload
integer
X
in KB/s, default of 0 means unlimited
bandwidth
Local user downinteger
X
in KB/s, default of 0 means unlimited
load bandwidth
Anonymous user
integer
X
in KB/s, default of 0 means unlimited
upload bandwidth
Anonymous user
integer
X
in KB/s, default of 0 means unlimited
download bandwidth
Enable TLS
checkbox
X
enables encrypted connections and requires a certificate to be created or imported using Certificates
(page 77)
TLS policy
drop-down
X
the selected policy defines whether the conmenu
trol channel, data channel, both channels, or
neither channel of an FTP session must occur
over SSL/TLS; the policies are described here
(http://www.proftpd.org/docs/directives/linked/config_ref_TLSRequired.h
TLS allow client
checkbox
X
checking this box is not recommended as
renegotiations
it breaks several security measures; for this
and the rest of the TLS fields, refer to mod_tls
(http://www.proftpd.org/docs/contrib/mod_tls.html)
for more details
TLS allow dot locheckbox
X
if checked, the user’s home directory is checked
gin
for a .tlslogin file which contains one or more
PEM-encoded certificates; if not found, the user is
prompted for password authentication
TLS allow per user checkbox
X
if checked, the user’s password may be sent unencrypted
Continued on next page
11.5. FTP
219
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Table 11.4 – continued from previous page
Advanced Description
Mode
checkbox
X
if checked, the common name in the certificate must
match the FQDN of the host
checkbox
X
if checked when troubleshooting a connection, logs
more verbosely
checkbox
X
if checked, exports the certificate environment variables
checkbox
X
try checking this box if the client cannot connect and
it is suspected that the client software is not properly
handling the server’s certificate request
checkbox
X
checking this box is not recommended as it bypasses
a security mechanism
checkbox
X
checking this box reduces the security of the connection, so only use it if the client does not understand
reused SSL sessions
checkbox
X
if checked, sets several environment variables
Value
TLS common
name required
TLS enable diagnostics
TLS export certificate data
TLS no certificate
request
TLS no empty
fragments
TLS no session
reuse required
TLS export standard vars
TLS DNS name
required
checkbox
X
TLS IP address
required
Certificate
checkbox
X
Auxiliary parameters
string
drop-down
menu
if checked, the client’s DNS name must resolve to its
IP address and the cert must contain the same DNS
name
if checked, the client’s certificate must contain the IP
address that matches the IP address of the client
the SSL certificate to be used for TLS FTP connections; to create a certificate, use System →
Certificates
X
used to add proftpd(8)
(http://linux.die.net/man/8/proftpd) parameters
not covered elsewhere in this screen
This example demonstrates the auxiliary parameters that prevent all users from performing the FTP DELETE
command:
<Limit DELE>
DenyAll
</Limit>
11.5.1 Anonymous FTP
Anonymous FTP may be appropriate for a small network where the FreeNAS® system is not accessible from
the Internet and everyone in your internal network needs easy access to the stored data. Anonymous FTP
does not require you to create a user account for every user. In addition, passwords are not required so it
is not necessary to manage changed passwords on the FreeNAS® system.
To configure anonymous FTP:
1. Give the built-in ftp user account permissions to the volume/dataset to be shared in Storage →
Volumes as follows:
• Owner(user): select the built-in ftp user from the drop-down menu
• Owner(group): select the built-in ftp group from the drop-down menu
220
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Mode: review that the permissions are appropriate for the share
Note: For FTP, the type of client does not matter when it comes to the type of ACL. This means that
you always use Unix ACLs, even if Windows clients will be accessing FreeNAS® via FTP.
2. Configure anonymous FTP in Services → FTP by setting the following attributes:
• check the box Allow Anonymous Login
• Path: browse to the volume/dataset/directory to be shared
3. Start the FTP service in Services → Control Services. Click the Start Now button next to FTP.
The FTP service takes a second or so to start. The indicator changes to green to show that the service
is running, and the button changes to Stop Now.
4. Test the connection from a client using a utility such as Filezilla (https://filezilla-project.org/).
In the example shown in Figure 11.6, the user has enter the following information into the Filezilla client:
• IP address of the FreeNAS® server: 192.168.1.113
• Username: anonymous
• Password: the email address of the user
Fig. 11.6: Connecting Using Filezilla
The messages within the client indicate that the FTP connection is successful. The user can now navigate
the contents of the root folder on the remote site—this is the volume/dataset that was specified in the FTP
service configuration. The user can also transfer files between the local site (their system) and the remote
site (the FreeNAS® system).
11.5.2 FTP in chroot
If you require your users to authenticate before accessing the data on the FreeNAS® system, you will need to
either create a user account for each user or import existing user accounts using Active Directory (page 152)
or LDAP. If you then create a ZFS dataset for :each user, you can chroot each user so that they are limited
to the contents of their own home directory. Datasets provide the added benefit of configuring a quota so
that the size of the user’s home directory is limited to the size of the quota.
To configure this scenario:
11.5. FTP
221
FreeNAS® 11.0-U4 User Guide, Release 11.0
1. Create a ZFS dataset for each user in Storage → Volumes. Click an existing ZFS volume →
Create ZFS Dataset and set an appropriate quota for each dataset. Repeat this process to create
a dataset for every user that needs access to the FTP service.
2. If you are not using AD or LDAP, create a user account for each user in Account → Users → Add
User. For each user, browse to the dataset created for that user in the Home Directory field. Repeat
this process to create a user account for every user that needs access to the FTP service, making sure
to assign each user their own dataset.
3. Set the permissions for each dataset in Storage → Volumes. Click the Change Permissions button
for a dataset to assign a user account as Owner of that dataset and to set the desired permissions for
that user. Repeat for each dataset.
Note: For FTP, the type of client does not matter when it comes to the type of ACL. This means that
you always use Unix ACLs, even if Windows clients will be accessing FreeNAS® via FTP.
4. Configure FTP in Services → FTP with these attributes:
• Path: browse to the parent volume containing the datasets
• make sure the boxes for Allow Anonymous Login and Allow Root Login are unchecked
• check the box Allow Local User Login
• check the box Always Chroot
5. Start the FTP service in Services → Control Services. Click the Start Now button next to FTP.
The FTP service takes a second or so to start. The indicator changes to green to show that the service
is running, and the button changes to Stop Now.
6. Test the connection from a client using a utility such as Filezilla.
To test this configuration in Filezilla, use the IP address of the FreeNAS® system, the Username of a user
that has been associated with a dataset, and the Password for that user. The messages should indicate
that the authorization and the FTP connection are successful. The user can now navigate the contents of
the root folder on the remote site—this time it is not the entire volume but the dataset that was created for
that user. The user should be able to transfer files between the local site (their system) and the remote site
(their dataset on the FreeNAS® system).
11.5.3 Encrypting FTP
To configure any FTP scenario to use encrypted connections:
1. Import or create a certificate authority using the instructions in CAs (page 74). Then, import or create
the certificate to use for encrypted connections using the instructions in Certificates (page 77).
2. In Services → FTP, check the box Enable TLS and select the certificate in the Certificate drop-down
menu.
3. Specify secure FTP when accessing the FreeNAS® system.
For example, in Filezilla input
ftps://IP_address (for an implicit connection) or ftpes://IP_address (for an explicit connection) as the
Host when connecting. The first time a user connects, they will be presented with the certificate
of the FreeNAS® system. Click OK to accept the certificate and negotiate an encrypted connection.
4. To force encrypted connections, select on for the TLS Policy.
222
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
11.5.4 Troubleshooting FTP
The FTP service will not start if it cannot resolve the system’s hostname to an IP address using DNS. To see
if the FTP service is running, open Shell (page 288) and issue the command:
sockstat -4p 21
If there is nothing listening on port 21, the FTP service is not running. To see the error message that occurs
when FreeNAS® tries to start the FTP service, go to System → Advanced, check the box Show console
messages in the footer and click Save. Next, go to Services → Control Services and switch the FTP
service off, then back on. Watch the console messages at the bottom of the browser for errors.
If the error refers to DNS, either create an entry in the local DNS server with the FreeNAS® system’s hostname and IP address or add an entry for the IP address of the FreeNAS® system in the Host name database
field of Network → Global Configuration.
11.6 iSCSI
Refer to Block (iSCSI) (page 195) for instructions on configuring iSCSI. To start the iSCSI service, click its entry
in Services.
A warning message is shown if you stop the iSCSI service when initiators are connected. Type
ctladm islist to determine the names of the connected initiators.
Note:
11.7 LLDP
The Link Layer Discovery Protocol (LLDP) is used by network devices to advertise their identity, capabilities,
and neighbors on an Ethernet network. FreeNAS® uses the ladvd (https://github.com/sspans/ladvd) LLDP
implementation. If your network contains managed switches, configuring and starting the LLDP service will
tell the FreeNAS® system to advertise itself on the network.
Figure 11.7 shows the LLDP configuration screen and Table 11.5 summarizes the configuration options for
the LLDP service.
Fig. 11.7: Configuring LLDP
11.6. iSCSI
223
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 11.5: LLDP Configuration Options
Setting
Interface Description
Country Code
Value
checkbox
Location
string
string
Description
when checked, receive mode is enabled and received peer information is saved in interface descriptions
required for LLDP location support; input 2 letter ISO 3166
country code
optional; specify the physical location of the host
11.8 NFS
The settings that are configured when creating NFS Shares in Sharing → Unix (NFS) Shares →
Add Unix (NFS) Share are specific to each configured NFS Share. In contrast, global settings which
apply to all NFS shares are configured in Services → NFS.
Figure 11.8 shows the configuration screen and Table 11.6 summarizes the configuration options for the
NFS service.
Fig. 11.8: Configuring NFS
224
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 11.6: NFS Configuration Options
Setting
Number of
servers
Value
integer
Serve UDP
NFS clients
Bind IP Addresses
Allow nonroot mount
Enable NFSv4
NFSv3 ownership model
for NFSv4
checkbox
Require Kerberos for
NFSv4
mountd(8)
bind port
rpc.statd(8)
bind port
rpc.lockd(8)
bind port
checkbox
Support>16
groups
checkbox
Log
mountd(8)
requests
Log
rpc.statd(8)
and
rpc.lockd(8)
checkbox
checkboxes
checkbox
checkbox
checkbox
integer
integer
integer
checkbox
Description
the number of servers can be increased if NFS client responses
are slow; to limit CPU context switching, keep this number less
than or equal to the number of CPUs reported by sysctl -n
kern.smp.cpus.
check if NFS clients need to use UDP
IP addresses to listen on for NFS requests; when unchecked,
NFS listens on all available addresses
check this box only if the NFS client requires it
NFSv3 is the default, check this box to switch to NFSv4
grayed out unless Enable NFSv4 is checked and, in turn, will gray
out Support>16 groups which is incompatible; check this box if
NFSv4 ACL support is needed without requiring the client and
the server to sync users and groups
when checked, NFS shares will fail if the Kerberos ticket is unavailable
optional; specify port that mountd(8)
(http://www.freebsd.org/cgi/man.cgi?query=mountd) binds to
optional; specify port that rpc.statd(8)
(http://www.freebsd.org/cgi/man.cgi?query=rpc.statd) binds to
optional; specify port that rpc.lockd(8)
(http://www.freebsd.org/cgi/man.cgi?query=rpc.lockd)
binds to
check this box if any users are members of more than 16
groups (useful in AD environments); note that this assumes that
group membership has been configured correctly on the NFS
server
enable logging of mountd(8)
(http://www.freebsd.org/cgi/man.cgi?query=mountd) requests
by syslog
enable logging of rpc.statd(8)
(http://www.freebsd.org/cgi/man.cgi?query=rpc.statd) and
rpc.lockd(8) (http://www.freebsd.org/cgi/man.cgi?query=rpc.lockd)
requests by syslog
Note: NFSv4 sets all ownership to nobody:nobody if user and group do not match on client and server.
11.9 Rsync
Services → Rsync is used to configure an rsync server when using rsync module mode. Refer to Rsync
Module Mode (page 89) for a configuration example.
This section describes the configurable options for the rsyncd service and rsync modules.
11.9. Rsync
225
FreeNAS® 11.0-U4 User Guide, Release 11.0
11.9.1 Configure Rsyncd
Figure 11.9 shows the rsyncd configuration screen which is accessed from Services → Rsync →
Configure Rsyncd.
Fig. 11.9: Rsyncd Configuration
Table 11.7 summarizes the options that can be configured for the rsync daemon:
Table 11.7: Rsyncd Configuration Options
Setting
TCP Port
Auxiliary parameters
Value
integer
string
Description
port for rsyncd to listen on, default is 873
additional parameters from rsyncd.conf(5)
(https://www.samba.org/ftp/rsync/rsyncd.conf.html)
11.9.2 Rsync Modules
Figure 11.10 shows the configuration screen that appears after clicking Services → Rsync → Rsync
Modules → Add Rsync Module.
Table 11.8 summarizes the options that can be configured when creating a rsync module.
226
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 11.10: Adding an Rsync Module
Table 11.8: Rsync Module Configuration Options
Setting
Module name
Comment
Path
Access Mode
Maximum
connections
User
Value
string
string
browse button
drop-down menu
integer
Description
mandatory; needs to match the setting on the rsync client
optional description
volume/dataset to hold received data
choices are Read and Write, Read-only, or Write-only
0 is unlimited
drop-down menu
Group
drop-down menu
Hosts allow
string
Hosts deny
Auxiliary parameters
string
string
select user that file transfers to and from that module should
take place as
select group that file transfers to and from that module should
take place as
see rsyncd.conf(5)
(https://www.samba.org/ftp/rsync/rsyncd.conf.html) for
allowed formats
see rsyncd.conf(5) for allowed formats
additional parameters from rsyncd.conf(5)
11.9. Rsync
227
FreeNAS® 11.0-U4 User Guide, Release 11.0
11.10 S3
S3 is a distributed or clustered filesystem protocol compatible with Amazon S3 cloud storage. The FreeNAS®
S3 service uses Minio (https://minio.io/) to provide S3 storage hosted on the FreeNAS® system itself. Minio
also provides features beyond the limits of the basic Amazon S3 specifications.
Figure 11.11 shows the S3 service configuration screen and Table 11.9 summarizes the configuration options. After configuring the S3 service, start it in Services → Control Services.
Fig. 11.11: Configuring S3
Table 11.9: S3 Configuration Options
Setting
IP Address
Value
drop-down menu
Port
Access Key
Secret Key
string
string
string
Confirm S3
Key
Disks
Enable
Browser
string
Description
the IP address on which to run the S3 service; 0.0.0.0 sets the
server to listen on all addresses
TCP port on which to provide the S3 service (default 9000)
the S3 user name
the password to be used by connecting S3 systems; must be at
least 8 but no more than 40 characters long
re-enter the S3 password to confirm
string
checkbox
S3 filesystem directory
Enable the web user interface for the S3 service
228
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
11.11 S.M.A.R.T.
S.M.A.R.T., or Self-Monitoring, Analysis, and Reporting Technology (http://en.wikipedia.org/wiki/S.M.A.R.T.),
is an industry standard for disk monitoring and testing. Drives can be monitored for status and problems,
and several types of self-tests can be run to check the drive health.
Tests run internally on the drive. Most tests can run at the same time as normal disk usage. However, a
running test can greatly reduce drive performance, so they should be scheduled at times when the system
is not busy or in normal use. It is very important to avoid scheduling disk-intensive tests at the same time.
For example, do not schedule S.M.A.R.T. tests to run at the same time, or preferably, even on the same days
as Scrubs (page 147).
Of particular interest in a NAS environment are the Short and Long S.M.A.R.T. tests. Details vary between
drive manufacturers, but a Short test generally does some basic tests of a drive that takes a few minutes.
The Long test scans the entire disk surface, and can take several hours on larger drives.
FreeNAS® uses the smartd(8) (http://www.smartmontools.org/browser/trunk/smartmontools/smartd.8.in)
service to monitor S.M.A.R.T. information. A complete configuration consists of:
1. Scheduling when S.M.A.R.T. tests are run in Tasks → S.M.A.R.T. Tests → Add S.M.A.R.T.
Test.
2. Enabling or disabling S.M.A.R.T. for each disk member of a volume in Volumes → View Disks.
This setting is enabled by default for disks that support S.M.A.R.T.
3. Checking the configuration of the S.M.A.R.T. service as described in this section.
4. Starting the S.M.A.R.T. service with Services → Control Services.
Figure 11.12 shows the configuration screen that appears after clicking Services → S.M.A.R.T.
Fig. 11.12: S.M.A.R.T Configuration Options
smartd wakes up at the configured Check Interval. It checks the times configured in Tasks →
S.M.A.R.T. Tests to see whether tests should be run. Since the smallest time increment for a test is an
hour (60 minutes), it does not make sense to set a Check Interval value higher than 60 minutes. For example,
Note:
11.11. S.M.A.R.T.
229
FreeNAS® 11.0-U4 User Guide, Release 11.0
if the Check Interval is set to 120 minutes and the smart test to every hour, the test will only be run every
two hours because smartd only wakes up every two hours.
Table 11.10 summarizes the options in the S.M.A.R.T configuration screen.
Table 11.10: S.M.A.R.T Configuration Options
Setting
Check interval
Value
integer
Power mode
drop-down menu
Difference
integer in degrees
Celsius
Informational
integer in degrees
Celsius
Critical
integer in degrees
Celsius
Email to report
string
Description
in minutes, how often smartd wakes up to check if any tests
have been configured to run
tests are not performed if the system enters the specified
power mode; choices are: Never, Sleep, Standby, or Idle
default of 0 disables this check, otherwise reports if the temperature of a drive has changed by N degrees Celsius since last
report
default of 0 disables this check, otherwise will message with a
log level of LOG_INFO if the temperature is higher than specified
degrees in Celsius
default of 0 disables this check, otherwise will message with a
log level of LOG_CRIT and send an email if the temperature is
higher than specified degrees in Celsius
email address of person or alias to receive S.M.A.R.T. alerts
11.12 SMB
The settings that are configured when creating SMB Shares in Sharing → Windows (SMB) Shares →
Add Windows (SMB) Share are specific to each configured SMB Share. In contrast, global settings which
apply to all SMB shares are configured in Services → SMB.
Note:
After starting the SMB service, it can take several minutes for the master browser election
(http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/NetworkBrowsing.html#id2581357)
to occur and for the FreeNAS® system to become available in Windows Explorer.
Figure
11.13
shows
the
global
SMB
configuration
options
which
are
described
in Table 11.11.
This configuration screen is really a front-end to smb4.conf
(https://www.freebsd.org/cgi/man.cgi?query=smb4.conf&manpath=FreeBSD+11.0-RELEASE+and+Ports).
230
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
11.12. SMB
231
Fig. 11.13: Global SMB Configuration
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 11.11: Global SMB Configuration Options
Setting
NetBIOS
Name
Value
string
NetBIOS Alias
Workgroup
string
string
Description
DOS charset
string
drop-down menu
UNIX charset
Log level
Use syslog
only
drop-down menu
drop-down menu
checkbox
Local Master
checkbox
Domain logons
Time Server
for Domain
checkbox
Guest Account
drop-down menu
File mask
integer
Directory
mask
Allow Empty
Password
integer
Auxiliary parameters
string
Unix Extensions
Zeroconf
share discovery
Hostname
lookups
checkbox
232
checkbox
checkbox
checkbox
checkbox
Description
automatically populated with the system’s original hostname;
limited to 15 characters; it must be different from the Workgroup name
limited to 15 characters
must match Windows workgroup name; this setting is ignored
if the Active Directory (page 152) or LDAP (page 158) service is
running
optional
the character set Samba uses when communicating with DOS
and Windows 9x/ME clients; default is CP437
default is UTF-8 which supports all characters in all languages
choices are Minimum, Normal, or Debug
when checked, authentication failures are logged
to /var/log/messages instead of the default of
/var/log/samba4/log.smbd
determines whether or not the system participates in a browser
election; should be disabled when network contains an AD or
LDAP server and is not necessary if Vista or Windows 7 machines are present
only check if need to provide the netlogin service for older Windows clients
determines whether or not the system advertises itself as a time
server to Windows clients; should be disabled when network
contains an AD or LDAP server
account to be used for guest access; default is nobody; account
must have permission to access the shared volume/dataset; if
Guest Account user is deleted, resets to nobody
overrides default file creation mask of 0666 which creates files
with read and write access for everybody
overrides default directory creation mask of 0777 which grants
directory read, write and execute access for everybody
if checked, users can just press Enter when prompted for a
password; requires that the username/password be the same
as the Windows user account
smb.conf options not covered elsewhere in this screen; see the Samba Guide
(http://www.oreilly.com/openbook/samba/book/appb_02.html)
for additional settings
allows non-Windows SMB clients to access symbolic links and
hard links, has no effect on Windows clients
enable if Mac clients will be connecting to the SMB share
allows using hostnames rather than IP addresses in the Hosts Allow or Hosts Deny fields of a SMB share; uncheck if IP addresses
are used to avoid the delay of a host lookup
Continued on next page
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Server minimum protocol
Server maximum protocol
Allow execute
always
Obey pam
restrictions
NTLMv1 auth
Bind IP Addresses
Idmap Range
Low
Idmap Range
High
Table 11.11 – continued from previous page
Value
Description
drop-down menu
the minimum protocol version the server will support; default
selects LANMAN1; SMB clients automatically negotiate the highest supported protocol version that meets or exceeds this value;
refer to Table 11.12 for descriptions
drop-down menu
the maximum protocol version the server will support; refer to
Table 11.12 for descriptions
checkbox
if checked, Samba will allow the user to execute a file, even if
that user’s permissions are not set to execute
checkbox
uncheck this box to allow cross-domain authentication, to allow
users and groups to be managed on another forest, or to allow
permissions to be delegated from Active Directory (page 152)
users and groups to domain admins on another forest
checkbox
when checked, allow NTLMv1 authentication, required by Windows XP clients and sometimes by clients in later versions of
Windows
checkboxes
check the IP addresses on which SMB should listen
integer
the beginning UID/GID for which this system is authoritative;
any UID/GID lower than this value is ignored, providing a way to
avoid accidental UID/GID overlaps between local and remotely
defined IDs
the ending UID/GID for which this system is authoritative; any
UID/GID higher than this value is ignored, providing a way to
avoid accidental UID/GID overlaps between local and remotely
defined IDs
integer
Table 11.12: SMB Protocol Versions
Value
CORE
COREPLUS
LANMAN1
LANMAN2
NT1
SMB2
SMB2_02
SMB2_10
11.12. SMB
Description
used by DOS
used by DOS
used by Windows
for Workgroups,
OS/2, and Windows 9x
used by Windows
for Workgroups,
OS/2, and Windows 9x
used by Windows
NT
used by Windows 7; same as
SMB2_10
used by Windows
Vista
used by Windows
7
Continued on next page
233
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 11.12 – continued from previous page
Value
Description
SMB3
used by Windows 10; same
as SMB3_11
SMB3_00
used by Windows
8
SMB3_02
used by Windows
8.1 and Windows
Server 2012
SMB3_11
used by Windows
10
Changes to SMB settings take effect immediately. Changes to share settings only take effect after the client
and server negotiate a new session.
Note: Do not set the directory name cache size as an Auxiliary parameter. Due to differences in how Linux and
BSD handle file descriptors, directory name caching is disabled on BSD systems to improve performance.
Note: SMB (page 230) cannot be disabled while Active Directory (page 152) is enabled.
11.12.1 Troubleshooting SMB
Do not connect to SMB shares as root, and do not add the root user in the SMB user database.
There are security implications in attempting to do so, and Samba 4 and later take measures to
prevent such actions. This can produce auth_check_ntlm_password and FAILED with error
NT_STATUS_WRONG_PASSWORD errors.
Samba is single threaded, so CPU speed makes a big difference in SMB performance. A typical 2.5Ghz Intel
quad core or greater should be capable of handling speeds in excess of Gb LAN while low power CPUs such
as Intel Atoms and AMD C-30sE-350E-450 will not be able to achieve more than about 30-40MB/sec typically.
Remember that other loads such as ZFS will also require CPU resources and may cause Samba performance
to be less than optimal.
Samba’s write cache parameter has been reported to improve write performance in some configurations and
can be added to the Auxiliary parameters field. Use an integer value which is a multiple of _SC_PAGESIZE (typically 4096) to avoid memory fragmentation. This will increase Samba’s memory requirements and should
not be used on systems with limited RAM.
Windows automatically caches file sharing information. If changes are made to an SMB share or to the
permissions of a volume/dataset being shared by SMB and the share becomes inaccessible, try logging out
and back into the Windows system. Alternately, users can type net use /delete from the command line
to clear their SMB sessions.
Windows also automatically caches login information. To require users to log in every time access is required, reduce the cache settings on the client computers.
Where possible, avoid using a mix of case in filenames as this can cause confusion
for
Windows
users.
Representing
and
resolving
filenames
with
Samba
(http://www.oreilly.com/openbook/samba/book/ch05_04.html) explains in more detail.
234
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
If a particular user cannot connect to a SMB share, make sure that their password does not contain the ?
character. If it does, have the user change the password and try again.
If permissions work for Windows users but not for OS X users, try disabling Unix Extensions and restarting
the SMB service.
If the SMB service will not start, run this command from Shell (page 288) to see if there is an error in the
configuration:
testparm /usr/local/etc/smb4.conf
If clients have problems connecting to the SMB share, go to Services → SMB and verify that Server maximum protocol is set to SMB2.
It is recommended to use a dataset for SMB sharing. When creating the dataset, make sure that the Share
type is set to Windows.
Do not use chmod to attempt to fix the permissions on a SMB share as it destroys the Windows ACLs. The
correct way to manage permissions on a SMB share is to manage the share security from a Windows system
as either the owner of the share or a member of the group that owns the share. To do so, right-click on
the share, click Properties and navigate to the Security tab. If you already destroyed the ACLs using chmod,
winacl can be used to fix them. Type winacl from Shell (page 288) for usage instructions.
The
Common
Errors
(http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/domainmember.html#id2573692) section of the Samba documentation contains additional troubleshooting
tips.
The Samba Performance Tuning (https://wiki.samba.org/index.php/Performance_Tuning) page describes
options to improve performance.
Directory listing speed in folders with a large number of files is sometimes a problem. A few specific changes
can help improve the performance. However, changing these settings can affect other usage. In general,
the defaults are adequate. Do not change these settings unless there is a specific need.
• Use at least the SMB2 version of the protocol when possible. Enable this on the client if possible. The
default settings for Server minimum protocol (—-) and Server maximum protocol (SMB3) in the global
SMB service options (page 232) allow clients to connect and negotiate higher and faster levels of the
protocol. If these have been changed from the default, they might reduce performance. Note that
Windows XP does not support SMB2, so it is particularly important to leave Server minimum protocol
at the default on networks with XP clients.
• Hostname Lookups and Log Level can also have a performance penalty. When not needed, they can be
disabled or reduced in the global SMB service options (page 232).
• Make Samba datasets case insensitive by setting Case Sensitivity to Insensitive when creating them. This
ZFS property is only available when creating a dataset. It cannot be changed on an existing dataset. To
convert such datasets, back up the data, create a new case-insensitive dataset, create an SMB share
on it, set the share level auxiliary parameter case sensitive = true, then copy the data from the old one
onto it. After the data has been checked and verified on the new share, the old one can be deleted.
• If present, remove options for extended attributes and DOS attributes in the share’s Auxiliary Parameters (page 185).
• Disable as many VFS Objects as possible in the share settings (page 185). Many have performance
overhead.
11.12. SMB
235
FreeNAS® 11.0-U4 User Guide, Release 11.0
11.13 SNMP
SNMP (Simple Network Management Protocol) is used to monitor network-attached devices for conditions
that warrant administrative attention. FreeNAS® uses Net-SNMP (http://net-snmp.sourceforge.net/) to provide SNMP. When you start the SNMP service, the following port will be enabled on the FreeNAS® system:
• UDP 161 (listens here for SNMP requests)
Available MIBS are located in /usr/local/share/snmp/mibs.
Figure 11.14 shows the SNMP configuration screen. Table 11.13 summarizes the configuration options.
Fig. 11.14: Configuring SNMP
Table 11.13: SNMP Configuration Options
Setting
Location
Value
string
Description
optional description of system’s location
Continued on next page
236
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 11.13 – continued from previous page
Description
optional email address of administrator
check this box to enable support for SNMP version 3
Setting
Contact
SNMP v3 Support
Community
Value
string
checkbox
Username
string
Authentication
Type
Password
drop-down menu
Privacy Protocol
Privacy
Passphrase
Auxiliary Parameters
drop-down menu
string
string
string
string
default is public and should be changed for security reasons;
can only contain alphanumeric characters, underscores, dashes,
periods, and spaces; this value can be empty for SNMPv3 networks
only applies if SNMP v3 Support is checked; specify the username to register with this service; refer to snmpd.conf(5)
(http://net-snmp.sourceforge.net/docs/man/snmpd.conf.html)
for more information regarding the configuration of this setting
as well as the Authentication Type, Password, Privacy Protocol, and
“Privacy Passphrase” fields
only applies if SNMP v3 Support is checked; choices are MD5 or
SHA
only applies if SNMP v3 Support is checked; specify and confirm a
password of at least eight characters
only applies if SNMP v3 Support is checked; choices are AES or
DES
if not specified, Password is used
additional snmpd.conf(5) (http://netsnmp.sourceforge.net/docs/man/snmpd.conf.html) options not
covered in this screen, one per line
11.14 SSH
Secure Shell (SSH) allows for files to be transferred securely over an encrypted network. If you configure
your FreeNAS® system as an SSH server, the users in your network will need to use SSH client software
(https://en.wikipedia.org/wiki/Comparison_of_SSH_clients) to transfer files with SSH.
This section shows the FreeNAS® SSH configuration options, demonstrates an example configuration that
restricts users to their home directory, and provides some troubleshooting tips.
Figure 11.15 shows the Services → SSH configuration screen. After configuring SSH, remember to start
it in Services → Control Services.
11.14. SSH
237
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 11.15: SSH Configuration
Table 11.14 summarizes the configuration options. Some settings are only available in Advanced Mode. To
see these settings, either click the Advanced Mode button, or configure the system to always display these
settings by checking the box Show advanced fields by default in System → Advanced.
Table 11.14: SSH Configuration Options
Setting
Value
Bind Interfaces
selection
TCP Port
integer
Login as Root with
password
checkbox
Allow Password
Authentication
checkbox
Allow Kerberos
Authentication
checkbox
Allow TCP Port
Forwarding
checkbox
Compress Connections
SFTP Log Level
checkbox
238
drop-down
menu
Advanced
Mode
Description
X
by default, SSH listens on all interfaces unless specific interfaces are highlighted in the Available field and
added to the Selected field
port to open for SSH connection requests; 22 by default
for security reasons, root logins are discouraged
and disabled by default if enabled, password must
be set for root user in View Users
if unchecked, key-based authentication for all
users is required; requires additional setup
(http://the.earth.li/%7Esgtatham/putty/0.55/htmldoc/Chapter8.html)
on both the SSH client and server
before checking this box, ensure that Kerberos Realms
(page 162) and Kerberos Keytabs (page 163) have been
configured and that the FreeNAS® system can communicate with the KDC
allows users to bypass firewall restrictions using SSH’s port forwarding feature
(http://www.symantec.com/connect/articles/ssh-portforwarding)
may reduce latency over slow networks
X
select the syslog(3)
(http://www.freebsd.org/cgi/man.cgi?query=syslog)
level of the SFTP server
Continued on next page
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
SFTP Log Facility
Extra Options
Table 11.14 – continued from previous page
Advanced Description
Mode
drop-down
X
select the syslog(3)
menu
(http://www.freebsd.org/cgi/man.cgi?query=syslog)
facility of the SFTP server
string
X
additional sshd_config(5)
(http://www.freebsd.org/cgi/man.cgi?query=sshd_config)
options not covered in this screen, one per line; these
options are case-sensitive and misspellings may
prevent the SSH service from starting
Value
A few sshd_config(5) (http://www.freebsd.org/cgi/man.cgi?query=sshd_config) options that are useful to enter in the Extra Options field include:
• increase the ClientAliveInterval if SSH connections tend to drop
• ClientMaxStartup defaults to 10; increase this value if you need more concurrent SSH connections
11.14.1 SCP Only
When you configure SSH, authenticated users with a user account created using Account → Users →
Add User can use the ssh command to login to the FreeNAS® system over the network. A user’s home
directory will be the volume/dataset specified in the Home Directory field of their FreeNAS® user account.
While the SSH login will default to the user’s home directory, users are able to navigate outside of their
home directory, which can pose a security risk.
It is possible to allow users to use the scp and sftp commands to transfer files between their local computer and their home directory on the FreeNAS® system, while restricting them from logging into the system using ssh. To configure this scenario, go to Account → Users → View Users, select the user
and click Modify User, and change the user’s Shell to scponly. Repeat for each user that needs restricted SSH
access.
Test the configuration from another system by running the sftp, ssh, and scp commands as the user.
The sftp and scp commands should work but the ssh should fail.
Note: Some utilities such as WinSCP and Filezilla can bypass the scponly shell. This section assumes that
users are accessing the system using the command line versions of scp and sftp.
11.14.2 Troubleshooting SSH
When adding any Extra Options, be aware that the keywords listed in sshd_config(5)
(http://www.freebsd.org/cgi/man.cgi?query=sshd_config) are case sensitive.
This means that your
configuration will fail to do what you intended if you do not match the upper and lowercase letters of the
keyword.
If your clients are receiving “reverse DNS” or timeout errors, add an entry for the IP address of the FreeNAS®
system in the Host name database field of Network → Global Configuration.
When configuring SSH, always test your configuration as an SSH user account to ensure that the user is
limited to what you have configured and that they have permission to transfer files within the intended
directories. If the user account is experiencing problems, the SSH error messages are usually pretty specific
11.14. SSH
239
FreeNAS® 11.0-U4 User Guide, Release 11.0
to what the problem is. Type the following command within Shell (page 288) to read these messages as they
occur:
tail -f /var/log/messages
Additional messages regarding authentication errors may be found in /var/log/auth.log.
11.15 TFTP
Trivial File Transfer Protocol (TFTP) is a light-weight version of FTP usually used to transfer configuration or
boot files between machines, such as routers, in a local environment. TFTP provides an extremely limited
set of commands and provides no authentication.
If the FreeNAS® system will be used to store images and configuration files for the network’s devices, configure and start the TFTP service. Starting the TFTP service will open UDP port 69.
Figure 11.16 shows the TFTP configuration screen and Table 11.15 summarizes the available options:
Fig. 11.16: TFTP Configuration
Table 11.15: TFTP Configuration Options
Setting
Directory
Value
browse
button
Allow New Files
checkbox
Port
Username
integer
dropdown
menu
Description
browse to an existing directory to be used for storage; some
devices require a specific directory name, refer to the device’s
documentation for details
enable if network devices need to send files to the system (for
example, to back up their configuration)
UDP port to listen for TFTP requests, 69 by default
account used for tftp requests; must have permission to the
Directory
Continued on next page
240
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Umask
Extra options
Table 11.15 – continued from previous page
Value
Description
integer
umask for newly created files, default is 022 (everyone can read,
nobody can write); some devices require a less strict umask
string
additional tftpd(8)
(http://www.freebsd.org/cgi/man.cgi?query=tftpd) options
not shown in this screen, one per line
11.16 UPS
FreeNAS® uses NUT (http://www.networkupstools.org/) (Network UPS Tools) to provide UPS support. If the
FreeNAS® system is connected to a UPS device, configure the UPS service then start it in Services →
Control Services.
Figure 11.17 shows the UPS configuration screen:
11.16. UPS
241
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 11.17: UPS Configuration Screen
Table 11.16 summarizes the options in the UPS Configuration screen.
Table 11.16: UPS Configuration Options
Setting
UPS Mode
Value
dropdown
menu
Description
select from Master or Slave
Continued on next page
242
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
Identifier
Driver
Port
Auxiliary Parameters
(ups.conf)
Auxiliary Parameters
(upsd.conf)
Description
Shutdown mode
Shutdown timer
Shutdown Command
Monitor User
Monitor Password
Extra users
Remote monitor
Send Email Status Updates
To email
Email Subject
Power Off UPS
Table 11.16 – continued from previous page
Value
Description
string
can contain alphanumeric, period, comma, hyphen, and underscore characters
dropsupported UPS devices are listed at http://www.
down
networkupstools.org/stable-hcl.html
menu
dropselect the serial or USB port the UPS is plugged into (see NOTE
down
below)
menu
string
additional options from ups.conf(5)
(http://www.networkupstools.org/docs/man/ups.conf.html)
string
additional options from upsd.conf(5)
(http://www.networkupstools.org/docs/man/upsd.conf.html)
string
optional
dropchoices are UPS goes on battery and UPS reaches low battery
down
menu
integer
in seconds; will initiate shutdown after this many seconds after
UPS enters UPS goes on battery, unless power is restored
string
the command to run to shut down the computer when battery
power is low or shutdown timer runs out
string
default is upsmon
string
default is known value fixmepass and should be changed; cannot contain a space or #
string
defines the accounts that have administrative access; see upsd.users(5)
(http://www.networkupstools.org/docs/man/upsd.users.html)
for examples
checkbox
if enabled, be aware that the default is to listen on all interfaces and to use the known values user upsmon and password
fixmepass
checkbox
if checked, activates the To email field
email address
string
checkbox
if Send Email box checked, email address to receive status updates; separate multiple email addresses with a semicolon
subject line to be used in the email
if checked, the UPS will also power off after shutting down the
FreeNAS system
Note: For USB devices, the easiest way to determine the correct device name is to check the box Show
console messages in System → Advanced. Plug in the USB device and console messages show the name
of the /dev/ugenX.X device, where the X’s are the numbers that show on the console.
upsc(8) (http://www.networkupstools.org/docs/man/upsc.html) can be used to get status variables from
the UPS daemon such as the current charge and input voltage. It can be run from Shell using the following
syntax. The man page gives some other usage examples.
upsc ups@localhost
upscmd(8) (http://www.networkupstools.org/docs/man/upscmd.html) can be used to send commands directly to the UPS, assuming that the hardware supports the command being sent. Only users with adminis11.16. UPS
243
FreeNAS® 11.0-U4 User Guide, Release 11.0
trative rights can use this command. These users are created in the Extra users field.
11.16.1 Multiple Computers with One UPS
A UPS with adequate capacity can be used to power multiple computers. One computer is connected to the
UPS data port with a serial or USB cable. This master makes UPS status available on the network for other
computers. These slave computers are powered by the UPS, but receive UPS status data from the master
computer. See the NUT User Manual (http://networkupstools.org/docs/user-manual.chunked/index.html)
and NUT User Manual Pages (http://networkupstools.org/docs/man/index.html#User_man).
11.17 WebDAV
The WebDAV service can be configured to provide a file browser over a web connection. Before starting
this service, you must create at least one WebDAV share using Sharing → WebDAV Shares → Add
WebDAV Share. Refer to WebDAV Shares (page 182) for instructions on how to create a share and then how
to connect to it once the service is configured and started.
The settings in the WebDAV service apply to all WebDAV shares. Figure 11.18 shows the WebDAV configuration screen. Table 11.17 summarizes the available options.
Fig. 11.18: WebDAV Configuration Screen
Table 11.17: WebDAV Configuration Options
Setting
Protocol
HTTP Port
244
Value
dropdown
menu
string
Description
choices are HTTP (connection always unencrypted), HTTPS (connection always encrypted), or HTTP+HTTPS (both types of connections allowed)
only appears if the selected Protocol is HTTP or HTTP+HTTPS and
is used to specify the port to be used for unencrypted connections; the default of 8080 should work, if you change it, do not
use a port number already being used by another service
Continued on next page
Chapter 11. Services
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
HTTPS Port
Webdav SSL Certificate
HTTP Authentication
Webdav Password
11.17. WebDAV
Table 11.17 – continued from previous page
Value
Description
string
only appears if the selected Protocol is HTTPS or HTTP+HTTPS and
is used to specify the port to be used for encrypted connections;
the default of 8081 should work, if you change it, do not use a
port number already being used by another service
droponly appears if the selected Protocol is HTTPS or HTTP+HTTPS;
down
select the SSL certificate to be used for encrypted connections;
menu
to create a certificate, use System → Certificates
dropchoices are Basic Authentication (unencrypted) or Digest Authentidown
cation (encrypted)
menu
string
default is davtest; this should be changed as it is a known value
245
CHAPTER
TWELVE
PLUGINS
FreeNAS® 8.2.0 introduced the ability to extend the built-in NAS services by providing a mechanism for installing additional software.
This mechanism was known as the Plugins architecture and is based on FreeBSD jails (https://en.wikipedia.org/wiki/Freebsd_jail) and PC-BSD 9.x PBIs
(http://wiki.pcbsd.org/index.php/AppCafe%C2%AE/9.2). This allowed users to install and configure additional applications once they had created and configured a plugins jail.
FreeNAS® 9.x simplifies this procedure by providing two methods for software installation. The Plugins
method, described in this section, is meant for users who prefer to browse for, install, and configure available software using the GUI. This method is very easy to use, but is limited in the amount of software that
is available. Each application will automatically be installed into its own jail, meaning that this method may
not be suitable for users who wish to run multiple applications within the same jail.
The Jails method provides much more control over software installation but assumes that the user is comfortable working from the command line can and has a good understanding of networking basics and
software installation on FreeBSD-based systems.
It is recommended that users skim through both the Plugins (page 246) and Jails (page 253) sections in order
to become familiar with the features and limitations of each and to choose the method that best meets their
software needs.
Note: Plugins created for FreeNAS® 9.3 or later are expected to work on the current release. Plugins
created for earlier releases of FreeNAS® must be reinstalled.
12.1 Installing Plugins
A plugin is a self-contained application installer which has been designed to integrate into the FreeNAS®
GUI. A plugin offers several advantages:
• the FreeNAS® GUI provides a browser for viewing the list of available plugins
• the FreeNAS® GUI provides buttons for installing, starting, managing, and deleting plugins
• if the plugin has configuration options, a screen will be added to the FreeNAS® GUI so that these
options can be configured from the GUI
To install a plugin, click Plugins. As seen in Figure 12.1, the list of available plugins will be displayed.
246
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 12.1: Viewing the List of Available Plugins
Note: if the list of available plugins is not displayed, open Shell (page 288) and verify that the FreeNAS®
system can ping an address on the Internet. If it cannot, you may have to add a default gateway address
and/or DNS server address in Network → Global Configuration.
Highlight the plugin you would like to install, click its Install button, then click OK. In the example shown in
Figure 12.2, SABnzbd is selected for installation.
12.1. Installing Plugins
247
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 12.2: Installing a Plugin
The installation will take a few minutes as the system will first download and configure a jail to contain the
installed software. It will then install the plugin and add it to the Installed tab as shown in Figure 12.3.
Warning: Be patient and wait for the installation to finish. Navigating away from the installation before
it is finished will cause problems with the installation.
248
Chapter 12. Plugins
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 12.3: Viewing Installed PBIs
As seen in the example shown in Figure 12.3, entries for the installed PBI will appear in the following locations:
• the Installed tab of Plugins
• the Plugins section of the tree
• the Jails section of the tree
The entry in the Installed tab of Plugins will display the plugin name and version, the name of the PBI that
was installed, the name of the jail that was created, whether the application status is ON or OFF, and a
button to delete the application and its associated jail. If a newer version of the application is available as a
plugin, a button to update the application will also appear.
Note: The Service status of a plugin must be turned to ON before the installed application is available.
Before starting the service, check to see if it has a configuration menu by clicking its entry in the Plugins
section of the tree. If the application is configurable, this will open a screen that contains the available
configuration options. Plugins which are not configurable will instead display a message with a hyperlink
for accessing the software. However, that hyperlink does not work until the plugin is started.
Always review a plugin’s configuration options before attempting to start it. some plugins have options
that need to be set before their service will successfully start. If you have never configured that application
before, check the application’s website to see what documentation is available. A link to the website for
each available plugin can be found in Available Plugins (page 251).
If the application requires access to the data stored on the FreeNAS® system, click the entry for the associated jail in the Jails section of the tree and add a storage as described in Add Storage (page 260).
If you need to access the shell of the jail containing the application to complete or test your configuration,
click the entry for the associated jail in the Jails section of the tree. You can then click its “shell” icon as
12.1. Installing Plugins
249
FreeNAS® 11.0-U4 User Guide, Release 11.0
described in Managing Jails (page 258).
Once the configuration is complete, click the red OFF button for the entry for the plugin. If the service
starts successfully, it will change to a blue ON. If it fails to start, click the jail’s Shell icon and type tail
/var/log/messages to see if any errors were logged.
12.2 Updating Plugins
When a newer version of a plugin becomes available in the official repository, an Update button is added
to the entry for the plugin in the Installed tab. In the example shown in Figure 12.4, a newer version of
Transmission is available.
Fig. 12.4: Updating an Installed Plugin
Click the OK button to start the download and installation of the latest version of the plugin. Once the
update is complete, the entry for the plugin will be refreshed to show the new version number and the
Update button will disappear.
12.3 Uploading Plugins
The Available tab of Plugins contains an Upload button. This button allows installation of plugins that are
not yet available in the official repository or which are still being tested. These plugins must be manually
downloaded and should end in a .pbi extension. When downloading a plugin, make sure that it is 64-bit
and that it was developed for 9.x. as 8.x and 10.x applications will not work on a 9.x FreeNAS® system.
Upload the new plugin with the Upload button. As seen in the example in Figure 12.5, this prompts you to
browse to the location of the plugin file. Select the file and click Upload to begin the installation.
Fig. 12.5: Installing a Previously Downloaded .pbi File
250
Chapter 12. Plugins
FreeNAS® 11.0-U4 User Guide, Release 11.0
When the installation is complete, an entry for the plugin will be added to the Installed tab and its associated
jail is listed under Jails. However, if it is not a FreeNAS® plugin, it will not be added to Plugins in the tree. In
this case, any required jail configuration must be done from the command line of the jail’s shell instead of
from the GUI.
12.4 Deleting Plugins
When you install a plugin, an associated jail is created. If you decide to delete a plugin, the associated jail
is also deleted as it is no longer required. Before deleting a plugin, make sure that you do not have any
data or configuration in the jail that you need to save. If you do, back up that data first, before deleting the
plugin.
In the example shown in Figure 12.6, Sabnzbd has been installed and the user has clicked its Delete button. A
pop-up message asks the user if they are sure that they want to delete. This is the one and only warning.
If the user clicks Yes, the plugin and the associated jail are permanently deleted.
Fig. 12.6: Deleting an Installed Plugin
12.5 Available Plugins
These plugins are available for FreeNAS® 11.0:
• bacula-sd (storage daemon) (http://bacula.org/)
• CouchPotato (https://couchpota.to/)
• crashplan (http://www.code42.com/crashplan/)
• Emby (http://emby.media/)
• firefly (https://en.wikipedia.org/wiki/Firefly_Media_Server)
• Headphones (https://github.com/rembo10/headphones)
• HTPC-Manager (http://htpc.io/)
• LazyLibrarian (https://github.com/lazylibrarian/LazyLibrarian)
• Madsonic (http://madsonic.org/)
• Maraschino (http://www.maraschinoproject.com/)
12.4. Deleting Plugins
251
FreeNAS® 11.0-U4 User Guide, Release 11.0
• MineOS (http://minecraft.codeemo.com/)
• Mylar (https://github.com/evilhero/mylar)
• Nextcloud (https://nextcloud.com/)
• NZBHydra (https://github.com/theotherp/nzbhydra)
• owncloud (https://owncloud.org/)
• PlexMediaServer (https://plex.tv/)
• Resilio (https://www.resilio.com/)
• s3cmd (http://s3tools.org/s3cmd)
• SABnzbd (http://sabnzbd.org/)
• SickBeard (http://sickbeard.com/)
• SickRage (https://github.com/SiCKRAGETV/SickRage)
• Sonarr (https://sonarr.tv/)
• Subsonic (http://www.subsonic.org/pages/index.jsp)
• Syncthing (https://syncthing.net/)
• Transmission (http://www.transmissionbt.com/)
• XDM (https://github.com/lad1337/XDM)
While the FreeNAS® Plugins system makes it easy to install software, it is still up to you to know how to
configure and use the installed application. When in doubt, refer to the documentation for that application.
252
Chapter 12. Plugins
CHAPTER
THIRTEEN
JAILS
The previous section described how to find, install, and configure software using Plugins (page 246).
This section describes how to use Jails, which allow users who are comfortable with the command line to
have more control over software installation and management. Any software installed using Jails must be
managed from the command line of the jail. If you prefer to use a GUI to manage software, use Plugins
(page 246) instead.
FreeNAS® automatically creates a jail whenever a plugin is installed, but does not let the user install multiple
plugins into the same jail. In contrast, using Jails allows users to create as many jails as needed and to
customize the operating system and installed software within each jail.
By default, a FreeBSD jail (https://en.wikipedia.org/wiki/Freebsd_jail) is created. This provides a very lightweight, operating system-level virtualization. Consider it as another independent instance of FreeBSD running on the same hardware, without all of the overhead usually associated with virtualization. The jail will
install the FreeBSD software management utilities so FreeBSD ports can be compiled and FreeBSD packages
can be installed from the command line of the jail.
It is important to understand that any users, groups, installed software, and configurations within a jail
are isolated from both the FreeNAS® operating system and any other jails running on that system. During
creation, the VIMAGE option can be selected to provide the jail with an independent networking stack. The
jail can then do its own IP broadcasting, which is required by some applications.
Advanced users can also create custom templates to automate the creation of pre-installed and customized
operating systems.
The ability to create multiple jails running different operating systems offers great flexibility regarding software management. For example, the administrator can choose to provide application separation by installing different applications in each jail, or to create one jail for all installed applications, or to mix and
match how software is installed into each jail.
Note: Jails created with FreeNAS® 9.3 or later are expected to work with the current release. Jails created
on older versions of FreeNAS® must be reinstalled due to ABI changes.
The rest of this section describes:
• Jails Configuration (page 254)
• Adding Jails (page 255)
• Managing Jail Templates (page 268)
• Using iocage (page 270)
253
FreeNAS® 11.0-U4 User Guide, Release 11.0
13.1 Jails Configuration
Jails are stored in a volume or dataset. Using a separate dataset for the Jail Root is strongly recommended. The volume or dataset to be used must already exist or can be created with Volume Manager
(page 108).
Note: The Jail Root volume or dataset cannot be created on a Share (page 165).
Begin global jail configuration by choosing Jails → Configuration to open the screen shown in Figure
13.1. Jails are automatically installed into their own dataset under the specified path as they are created. For
example, if the Jail Root is set to /mnt/volume1/dataset1 and a jail named jail1 is created, it is installed
into its own dataset named /mnt/volume1/dataset1/jail1.
Fig. 13.1: Global Jail Configuration
Warning: If any Plugins (page 246) have already been installed, the Jail Root, IPv4 Network, IPv4 Network
Start Address, and IPv4 Network End Address are automatically filled. Double-check that the pre-configured
IP address values are appropriate for the jails and do not conflict with addresses used by other systems
on the network.
Table 13.1 summarizes the fields in this configuration screen. Refer to the text below the table for more
details on how to properly configure the Jail Root and network settings. Some settings are only available
in Advanced Mode. To see these settings, either click the Advanced Mode button or configure the system to
always display these settings by checking the box Show advanced fields by default in System → Advanced.
Table 13.1: Jail Configuration Options
Setting
Value
Jail Root
browse button
checkbox
string
string
IPv4 DHCP
IPv4 Network
IPv4 Network
Start Address
254
Advanced
Mode
Description
mandatory; jails cannot be added until this is set
X
X
check this box if the network has a DHCP server
format is IP address of network/CIDR mask
enter the first IP address in the reserved range in the
format host/CIDR mask
Continued on next page
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
Setting
IPv4 Network End
Address
IPv6 Autoconfigure
IPv6 Network
IPv6 Network
Start Address
IPv6 Network End
Address
Collection URL
Table 13.1 – continued from previous page
Advanced Description
Mode
string
X
enter the last IP address in the reserved range in the
format host/CIDR mask
checkbox
check this box if the network has a DHCPv6 server and
IPv6 will be used to access jails
string
X
enter the network address for a properly configured
IPv6 network
string
X
enter the first IP address in the reserved range for a
properly configured IPv6 network
string
X
enter the last IP address in the reserved range for a
properly configured IPv6 network
string
X
changing the default may break the ability to install
jails
Value
When selecting the Jail Root, ensure that the size of the selected volume or dataset is sufficient to hold the
number of jails to be installed as well as any software, log files, and data to be stored within each jail. At a
bare minimum, budget at least 2 GB per jail and do not select a dataset that is less than 2 GB in size.
Note: If you plan to add storage to a jail, be aware that the path size is limited to 88 characters. Make sure
that the length of the volume name plus the dataset name plus the jail name does not exceed this limit.
If the network contains a DHCP server, it is recommended to check the box IPv4 DHCP (or IPv6 Autoconfigure,
for a properly configured IPv6 network). This will prevent IP address conflicts on the network as the DHCP
server will automatically assign the jail the next available lease and record the lease as in use.
If a static IP address is needed so that users always know the IP address of the jail, enter the start and
end address for the IPv4 and/or IPv6 network. The range defined by the start and end addresses will
be automatically assigned as jails are created. For example, if you plan to create 5 jails on the 192.168.1.0
network, enter a IPv4 Network Start Address of 192.168.1.100 and a IPv4 Network End Address of 192.168.1.104.
If you create a start and end range on a network that contains a DHCP server, it is very important
that you also reserve those addresses on the DHCP server. Otherwise, the DHCP server will not be aware
that those addresses are being used by jails and there will be IP address conflicts and weird networking
errors on the network. When troubleshooting jails that do not install or which are unavailable, doublecheck that the IP address being used by the jail is not also being used by another jail or system in the
network.
FreeNAS® will automatically detect and display the IPv4 Network to which the administrative interface is
connected. This setting is important. The IP addresses used by the jails must be pingable from the FreeNAS®
system for the jails and any installed software to be accessible. If the network topology requires changing
the default value, a default gateway and possibly a static route need to be added to the specified network.
After changing this value, ensure that the subnet mask value is correct, as an incorrect mask can make the
IP network unreachable. When in doubt, keep the default setting for IPv4 Network. With VMware, make sure
that the vswitch is set to “promiscuous mode”.
After clicking the Save button to save the configuration, the system is ready to create and manage jails as
described in the rest of this chapter.
13.2 Adding Jails
To create a jail, click Jails → Add Jail to access the screen shown in Figure 13.2.
13.2. Adding Jails
255
FreeNAS® 11.0-U4 User Guide, Release 11.0
Note: the Add Jail menu item will not appear until after you configure Jails → Configuration.
Fig. 13.2: Creating a Jail
By default, the only required value to create a jail is a name. FreeBSD jails are created by default.
Table 13.2 summarizes the available options. Most settings are only available in Advanced Mode and are not
needed if the intent is to create a FreeBSD jail. To see these settings, either click the Advanced Mode button
or configure the system to always display these settings by checking the box Show advanced fields by default
in System → Advanced.
Table 13.2: Jail Configuration Options
Setting
Value
Jail Name
string
Template
X
IPv4 DHCP
drop-down
menu
checkbox
IPv4 address
integer
X
IPv4 netmask
drop-down
menu
integer
X
mandatory; can only contain letters, numbers, dashes,
or the underscore character
contains any created custom templates as described
in Managing Jail Templates (page 268)
if unchecked, make sure that the defined address does
not conflict with the DHCP server’s pool of available
addresses
this and the other IPv4 settings are grayed out if IPv4
DHCP is checked; enter a unique IP address that is in
the local network and not already used by anyother
computer
select the subnet mask associated with IPv4 address
X
grayed out unless VIMAGE is checked; see NOTE below
drop-down
menu
X
select the subnet mask associated with IPv4 bridge address; grayed out unless VIMAGE is checked
Continued on next page
IPv4 bridge address
IPv4 bridge netmask
256
Advanced
Mode
X
Description
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 13.2 – continued from previous page
Advanced Description
Mode
X
grayed out unless VIMAGE is checked
Setting
Value
IPv4 default gateway
IPv6 Autoconfigure
string
checkbox
X
IPv6 address
integer
X
IPv6 prefix length
drop-down
menu
integer
X
if unchecked, make sure that the defined address does
not conflict with the DHCP server’s pool of available
addresses
this and other IPv6 settings are grayed out if IPv6 Autoconfigure is checked; enter a unique IPv6 address that
is in the local network and not already used by any
other computer
select the prefix length associated with IPv6 address
X
grayed out unless VIMAGE is checked; see NOTE below
drop-down
menu
string
X
string
X
X
Sysctls
drop-down
menu
string
Autostart
VIMAGE
checkbox
checkbox
X
X
NAT
checkbox
X
grayed out unless VIMAGE is checked; select the prefix
length associated with IPv6 address
grayed out unless VIMAGE is checked; used to set the
jail’s default gateway IPv6 address
grayed out unless VIMAGE is checked; if a static MAC
address is entered, unique static MAC addresses must
be entered for every jail created
grayed out if VIMAGE is checked; can be used to specify
the interface to use for jail connections
comma-delimited list of sysctls to set inside jail (like
allow.sysvipc=1,allow.raw_sockets=1)
uncheck if the jail will be started manually
gives a jail its own virtualized network stack; requires
promiscuous mode be enabled on the interface
grayed out for Linux jails or if VIMAGE is unchecked;
enables Network Address Translation for the jail
IPv6 bridge address
IPv6 bridge prefix
length
IPv6 default gateway
MAC
NIC
X
X
Note:
The IPv4 and IPv6 bridge interface is used to bridge the epair(4)
(http://www.freebsd.org/cgi/man.cgi?query=epair) device, which is automatically created for each started
jail, to a physical network device. The default network device is the one that is configured with a default
gateway. So, if em0 is the FreeBSD name of the physical interface and three jails are running, these virtual
interfaces are automatically created: bridge0, epair0a, epair1a, and epair2a. The physical interface em0 will
be added to the bridge, as well as each epair device. The other half of the epair will be placed inside the jail
and will be assigned the IP address specified for that jail. The bridge interface will be assigned an alias of
the default gateway for that jail, if configured, or the bridge IP, if configured; either is correct.
The only time an IP address and mask are required for the bridge is when the jail will be on a different
network than the FreeNAS® system. For example, if the FreeNAS® system is on the 10.0.0.0/24 network and
the jail will be on the 192.168.0.0/24 network, set the IPv4 bridge address and IPv4 bridge netmask fields for
the jail.
If both the VIMAGE and NAT boxes are unchecked, the jail must be configured with an IP address within the
same network as the interface it is bound to, and that address will be assigned as an alias on that interface.
To use a VIMAGE jail on the same subnet, uncheck NAT and configure an IP address within the same network.
In both of these cases, configure only an IP address and do not configure a bridge or a gateway address.
13.2. Adding Jails
257
FreeNAS® 11.0-U4 User Guide, Release 11.0
After making selections, click the OK button. The jail is created and added to the Jails tab as well as in the
tree menu under Jails. Jails start automatically. To prevent this, uncheck the Autostart box.
The first time a jail is added or used as a template, the GUI automatically downloads the necessary components from the internet. A progress bar indicates the status of the download and provides an estimated
time for the process to complete. If it is unable to connect to the internet, jail creation fails.
Warning: Failure to download is often caused by the default gateway not being set, preventing internet
access. See the Network Global Configuration (page 95) section for information on setting the default
gateway.
After the first jail is created or a template has been used, subsequent jails will be added very quickly because
the downloaded base for creating the jail has been saved to the Jail Root.
13.2.1 Managing Jails
Click Jails to view and configure the added jails. In the example shown in Figure 13.3, the list entry for the jail
named xdm_1 has been clicked to enable that jail’s configuration options. The entry indicates the jail name,
IP address, whether it will start automatically at system boot, if it is currently running, and jail type: standard
for a FreeBSD jail, or pluginjail if it was installed using Plugins (page 246).
Fig. 13.3: Viewing Jails
258
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
From left to right, these configuration icons are available:
Edit Jail: edit the jail settings which were described in Table 13.2.
After a jail has been created, the jail name and type cannot be changed, so these fields will be grayed out.
Note: To modify the IP address information for a jail, use the Edit Jail button instead of the associated
networking commands from the command line of the jail.
Add Storage: configure the jail to access an area of storage as described in Add Storage (page 260).
Upload Plugin: manually upload a plugin previously downloaded from the plugins repository
(http://download.freenas.org/plugins/9/x64/).
Start/Stop: this icon changes appearance depending on the current Status of the jail. When the jail is not
running, the icon is green and clicking it starts the jail. When the jail is already running, the icon is red and
clicking it stops the jail. A stopped jail and its applications are inaccessible until it is restarted.
Restart: restart the jail.
Shell: access a root command prompt to configure the selected jail from the command line. When finished,
type exit to close the shell.
Delete: delete the jail and any periodic snapshots of it. The contents of the jail are entirely removed.
Warning: Back up data and programs in the jail before deleting it. There is no way to recover
the contents of a jail after deletion.
Accessing a Jail Using SSH
ssh can be used to access a jail instead of the jail’s Shell icon. This requires starting the ssh service and
creating a user account for ssh access. Start by clicking the Shell icon for the desired jail.
Find the sshd_enable= line in the jail’s /etc/rc.conf and set it to “YES”:
sshd_enable="YES"
Then start the SSH daemon:
service sshd start
The first time the service runs, the jail’s RSA key pair is generated and the key fingerprint and random art
image displayed.
Add a user account by typing adduser and following the prompts. If the user needs superuser privileges,
they must be added to the wheel group. For those users, enter wheel at this prompt:
Login group is user1. Invite user1 into other groups? []: wheel
After creating the user, set the root password so that the new user will be able to use the su command to
gain superuser privilege. To set the password, type passwd then enter and confirm the desired password.
Finally, test from another system that the user can successfully ssh in and become the superuser. In this
example, a user named user1 uses ssh to access the jail at 192.168.2.3. The first time the user logs in, they
will be asked to verify the fingerprint of the host:
13.2. Adding Jails
259
FreeNAS® 11.0-U4 User Guide, Release 11.0
ssh user1@192.168.2.3
The authenticity of host '192.168.2.3 (192.168.2.3)' can't be established.
RSA key fingerprint is 6f:93:e5:36:4f:54:ed:4b:9c:c8:c2:71:89:c1:58:f0.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '192.168.2.3' (RSA) to the list of known hosts.
Password: type_password_here
Note: Each jail has its own user accounts and service configuration. These steps must be repeated for
each jail that requires SSH access.
Add Storage
It is possible to give a FreeBSD jail access to an area of storage on the FreeNAS® system. This is useful for
applications that store a large amount of data or if an application in a jail needs access to the data stored
on the FreeNAS® system. One example is transmission, which stores torrents. The storage is added using the mount_nullfs(8) (http://www.freebsd.org/cgi/man.cgi?query=mount_nullfs) mechanism, which links
data that resides outside of the jail as a storage area within the jail.
To add storage, click the Add Storage button for a highlighted jail’s entry to open the screen shown in Figure
13.4. This screen can also be accessed by expanding the jail name in the tree view and clicking Storage
→ Add Storage.
Fig. 13.4: Adding Storage to a Jail
Browse to the Source and Destination, where:
260
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Source: is the directory or dataset on the FreeNAS® system which will be accessed by the jail. This
directory must reside outside of the volume or dataset being used by the jail. This is why it is recommended to create a separate dataset to store jails, so the dataset holding the jails is always separate
from any datasets used for storage on the FreeNAS® system.
• Destination: select an existing, empty directory within the jail to link to the Source storage area. If
that directory does not exist yet, enter the desired directory name and check the Create directory box.
Storage is typically added because the user and group account associated with an application installed
inside of a jail needs to access data stored on the FreeNAS® system. Before selecting the Source, it is
important to first ensure that the permissions of the selected directory or dataset grant permission to the
user/group account inside of the jail. This is not the default, as the users and groups created inside of a jail
are totally separate from the users and groups of the FreeNAS® system.
The workflow for adding storage usually goes like this:
1. Determine the name of the user and group account used by the application. For example, the installation of the transmission application automatically creates a user account named transmission and
a group account also named transmission. When in doubt, check the files /etc/passwd (to find the
user account) and /etc/group (to find the group account) inside the jail. Typically, the user and
group names are similar to the application name. Also, the UID and GID are usually the same as the
port number used by the service.
A media user and group (GID 8675309) are part of the base system. Having applications run as this
group or user makes it possible to share storage between multiple applications in a single jail, between
multiple jails, or even between the host and jails.
2. On the FreeNAS® system, create a user account and group account that match the user and group
names used by the application in the jail.
3. Decide whether the jail should have access to existing data or if a new area of storage will be set aside
for the jail to use.
4. If the jail will access existing data, edit the permissions of the volume or dataset so the user and group
accounts have the desired read and write access. If multiple applications or jails are to have access to
the same data, create a new group and add each needed user account to that group.
5. If an area of storage is being set aside for that jail or individual application, create a dataset. Edit the
permissions of that dataset so the user and group account has the desired read and write access.
6. Use the Add Storage button of the jail and select the configured volume/dataset as the Source.
To prevent writes to the storage, check the box Read-Only.
By default, the Create directory box is checked. This means that the directory will automatically be created
under the specified Destination path if the directory does not already exist.
After storage has been added or created, it appears in the tree under the specified jail. In the example shown in Figure 13.5, a dataset named volume1/data has been chosen as the Source as it contains the files stored on the FreeNAS® system. When the storage was created, the user browsed to
volume1/jails/freebsd1/usr/local in the Destination field, then entered test as the directory. Since
this directory did not already exist, it was created, because the Create directory box was left checked. The
resulting storage was added to the freenas1 entry in the tree as /usr/local/test. The user has clicked
this /usr/local/test entry to access the Edit screen.
13.2. Adding Jails
261
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 13.5: Example Storage
Storage is normally mounted as it is created. To unmount the storage, uncheck the Mounted? box.
Note: A mounted dataset will not automatically mount any of its child datasets. While the child datasets
may appear to be browsable inside the jail, any changes will not be visible. Since each dataset is considered
to be its own filesystem, each child dataset must have its own mount point, so separate storage must be
created for any child datasets which need to be mounted.
To delete the storage, click its Delete button.
Warning: It is important to realize that added storage is really just a pointer to the selected storage
directory on the FreeNAS® system. It does not copy that data to the jail. Files that are deleted from
the Destination directory in the jail are really deleted from the Source directory on the FreeNAS®
system. However, removing the jail storage entry only removes the pointer, leaving the data intact but
not accessible from the jail.
13.2.2 Installing FreeBSD Packages
The quickest and easiest way to install software inside the jail is to install a FreeBSD package. FreeBSD packages are pre-compiled. They contains all the binaries and a list of dependencies required for the software
to run on a FreeBSD system.
A huge amount of software has been ported to FreeBSD, currently over 24,000 applications, and most of
that software is available as a package. One way to find FreeBSD software is to use the search bar at
FreshPorts.org (http://www.freshports.org/).
262
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
After finding the name of the desired package, use the pkg install command to install it. For example,
to install the audiotag package, use this command:
pkg install audiotag
When prompted, type y to complete the installation. The installation messages will indicate if the package
and its dependencies successfully download and install.
Warning: Some older versions of FreeBSD used package systems which are now obsolete. Do not use
commands from those obsolete package systems in a FreeNAS® jail, as they will cause inconsistencies
in the jail’s package management database. Use the current FreeBSD package system as shown in these
examples.
A successful installation can be confirmed by querying the package database:
pkg info -f audiotag
audiotag-0.19_1
Name:
audiotag
Version:
0.19_1
Installed on:
Fri Nov 21 10:10:34 PST 2014
Origin:
audio/audiotag
Architecture:
freebsd:9:x86:64
Prefix:
/usr/local
Categories:
multimedia audio
Licenses:
GPLv2
Maintainer:
ports@FreeBSD.org
WWW:
http://github.com/Daenyth/audiotag
Comment:
Command-line tool for mass tagging/renaming of audio files
Options:
DOCS:
on
FLAC:
on
ID3:
on
MP4:
on
VORBIS:
on
Annotations:
repo_type:
binary
repository:
FreeBSD
Flat size:
62.8KiB
Description:
Audiotag is a command-line tool for mass tagging/renaming of audio
˓→files
it supports the vorbis comment, id3 tags, and MP4 tags.
WWW:
http://github.com/Daenyth/audiotag
To show what was installed by the package:
pkg info -l audiotag
audiotag-0.19_1:
/usr/local/bin/audiotag
/usr/local/share/doc/audiotag/COPYING
/usr/local/share/doc/audiotag/ChangeLog
/usr/local/share/doc/audiotag/README
/usr/local/share/licenses/audiotag-0.19_1/GPLv2
/usr/local/share/licenses/audiotag-0.19_1/LICENSE
/usr/local/share/licenses/audiotag-0.19_1/catalog.mk
In FreeBSD, third-party software is always stored in /usr/local to differentiate it from the software that
13.2. Adding Jails
263
FreeNAS® 11.0-U4 User Guide, Release 11.0
came with the operating system. Binaries are almost always located in a subdirectory called bin or sbin
and configuration files in a subdirectory called etc.
13.2.3 Compiling FreeBSD Ports
Software is typically installed into FreeBSD jails using packages. But sometimes there are good reasons to
compile a port instead. Compiling ports offers these advantages:
• Not every port has an available package. This is usually due to licensing restrictions or known, unaddressed security vulnerabilities.
• Sometimes the package is out-of-date and a feature is needed that only became available in the newer
version.
• Some ports provide compile options that are not available in the pre-compiled package. These options
are used to add or remove features or options.
Compiling a port has these disadvantages:
• It takes time. Depending upon the size of the application, the amount of dependencies, the speed of
the CPU, the amount of RAM available, and the current load on the FreeNAS® system, the time needed
can range from a few minutes to a few hours or even to a few days.
Note: If the port does not provide any compile options, it saves time and preserves the FreeNAS® system’s
resources to just use the pkg install command instead.
The FreshPorts.org (http://www.freshports.org/) listing shows whether a port has any configurable compile
options. Figure 13.6 shows the Configuration Options for audiotag.
264
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 13.6: Configuration Options for Audiotag
This port has five configurable options (DOCS, FLAC, ID3, MP4, and VORBIS) and each option is enabled (on)
by default.
FreeBSD packages are always built using the default options. When compiling a port yourself, those options
are presented in a menu, allowing the default values to be changed.
The Ports Collection must be installed in a jail before ports can be compiled. Inside the jail, use the
portsnap utility. This command downloads the ports collection and extracts it to the jail’s /usr/ports/
directory:
portsnap fetch extract
To install additional software at a later date, make sure the ports collection is updated with
portsnap fetch update.
Note:
To compile a port, cd into a subdirectory of /usr/ports/. The entry for the port at FreshPorts provides
the location to cd into and the make command to run. This example compiles and installs the audiotag
port:
cd /usr/ports/audio/audiotag
make install clean
13.2. Adding Jails
265
FreeNAS® 11.0-U4 User Guide, Release 11.0
Since this port has configurable options, the first time this command is run, the configure screen shown in
Figure 13.7 is displayed:
Fig. 13.7: Configuration Options for Audiotag Port
Use the arrow keys to select an option and press spacebar to toggle the value. When all the values are as
desired, press Enter. The port will begin to compile and install.
Note: The configuration screen will not be shown again, even if the build is stopped and restarted. It can
be redisplayed by typing make config. Change the settings, then rebuild with make clean install
clean.
Many ports depend on other ports. Those other ports can also have configuration screens that will be
shown before compiling begins. It is a good idea to keep an eye on the compile until it finishes and the
command prompt returns.
When the port is installed, it is registered in the same package database that manages packages. The same
pkg info command can be used to determine what was installed, as described in the previous section.
13.2.4 Starting Installed Software
After packages or ports are installed, they need to be configured and started. If you are familiar with the
software, look for the configuration file in /usr/local/etc or a subdirectory of it. Many FreeBSD packages contain a sample configuration file as a reference. If you are unfamiliar with the software, you will
need to spend some time at the software’s website to learn which configuration options are available and
which configuration files require editing.
Most FreeBSD packages that contain a startable service include a startup script which is automatically installed to /usr/local/etc/rc.d/. After the configuration is complete, the starting of the service can be
tested by running the script with the onestart option. As an example, if openvpn is installed into the jail,
these commands run its startup script and verify that the service started:
/usr/local/etc/rc.d/openvpn onestart
Starting openvpn.
266
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
/usr/local/etc/rc.d/openvpn onestatus
openvpn is running as pid 45560.
sockstat -4
USER COMMAND
root openvpn
PID
48386
FD
4
PROTO
udp4
LOCAL ADDRESS
*:54789
FOREIGN ADDRESS
*:*
If it produces an error:
/usr/local/etc/rc.d/openvpn onestart
Starting openvpn.
/usr/local/etc/rc.d/openvpn: WARNING: failed to start openvpn
Run tail /var/log/messages to see if any error messages hint at the problem. Most startup failures
are related to a misconfiguration: either a typo or a missing option in a configuration file.
After verifying that the service starts and is working as intended, add a line to /etc/rc.conf to start the
service automatically when the jail is started. The line to start a service always ends in _enable=”YES” and
typically starts with the name of the software. For example, this is the entry for the openvpn service:
openvpn_enable="YES"
When in doubt, the startup script shows the line to put in /etc/rc.conf. This is the description in
/usr/local/etc/rc.d/openvpn:
# This script supports running multiple instances of openvpn.
# To run additional instances link this script to something like
# % ln -s openvpn openvpn_foo
# and define additional openvpn_foo_* variables in one of
# /etc/rc.conf, /etc/rc.conf.local or /etc/rc.conf.d /openvpn_foo
#
#
#
#
#
#
#
#
#
#
#
Below NAME should be substituted with the name of this script. By default
it is openvpn, so read as openvpn_enable. If you linked the script to
openvpn_foo, then read as openvpn_foo_enable etc.
The following variables are supported (defaults are shown).
You can place them in any of
/etc/rc.conf, /etc/rc.conf.local or /etc/rc.conf.d/NAME
NAME_enable="NO"
set to YES to enable openvpn
The startup script also indicates if any additional parameters are available:
#
#
#
#
#
#
#
#
#
#
#
#
NAME_if=
driver(s) to load, set to "tun", "tap" or "tun tap"
it is OK to specify the if_ prefix.
# optional:
NAME_flags=
additional command line arguments
NAME_configfile="/usr/local/etc/openvpn/NAME.conf"
--config file
NAME_dir="/usr/local/etc/openvpn"
--cd directory
13.2. Adding Jails
267
FreeNAS® 11.0-U4 User Guide, Release 11.0
13.3 Managing Jail Templates
FreeNAS® supports the ability to add custom templates to the Templates drop-down menu described in
Table 13.2.
To create a custom template, first install the desired operating system and configure it as needed. The
installation can be either to an existing jail or on another system.
Next, create an mtree specification using this command, replacing /path/to/jail with the actual path to the
jail:
mtree -c -p /path/to/jail -k sha256digest > file.mtree
After configuration is complete, create a tarball of the entire operating system to be used as a template.
This tarball needs to be compressed with gzip and end in a .tgz extension. Be careful when creating
the tarball as it is possible to end up in a recursive loop. In other words, the resulting tarball must be
saved outside of the operating system being tarballed, such as to an external USB drive or network share.
Alternately, create a temporary directory within the operating system and use the –exclude switch to tar
to exclude this directory from the tarball. The exact tar command to use will vary, depending upon the
operating system being used to create the tarball.
Save the generated .mtree and .tgz files to either an FTP share or an HTTP server. The FTP or HTTP URL
is needed to add the template to the list of available templates.
To add the template, click Jails → Templates → Add Jail Templates which opens the screen
shown in Figure 13.8.
Fig. 13.8: Adding A Custom Jail Template
Table 13.3 summarizes the fields in this screen.
268
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 13.3: Jail Template Options
Setting
Name
OS
Architecture
URL
Value
string
drop-down menu
drop-down menu
string
Mtree
string
Description
value appears in the Name column of View Jail Templates
choices are FreeBSD or Linux
choices are x86 (32-bit) or x64 (64-bit)
enter the full URL to the .tgz file, including the protocol (ftp://
or or http://)
paste the mtree specification for the template
Added templates appear in Jails → Templates. An example is shown in Figure 13.9.
Fig. 13.9: Viewing Available Templates
The listing contains these columns:
• Name: appears in the Template drop-down menu when adding a new jail.
• URL: when adding a new jail using this template, the template is downloaded from this location.
• Instances: indicates if the template has been used to create a jail. In this example, the template has
not yet been used, so Instances shows as 0.
Click the entry for a template to access its Edit and Delete buttons. Clicking a template’s Edit button opens
the configuration screen shown in Figure 13.10.
13.3. Managing Jail Templates
269
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 13.10: Editing Template Options
Clicking a template’s Delete button shows a warning message that prompts for confirmation of the deletion.
Note that once a template is deleted, it is removed from the Templates drop-down menu and will no longer
be available for creating new jails.
13.4 Using iocage
Beginning with FreeNAS® 9.10.1, the iocage (https://github.com/iocage/iocage) command line utility is included for creating, and managing jails.
The built-in help can be displayed with iocage --help | more. Each subcommand also has help, which
is displayed by giving the subcommand name followed by the --help flag. For example, help on the
activate subcommand is displayed with iocage activate --help.
13.4.1 Managing iocage Jails
Create a jail named examplejail that uses IP address 192.168.1.10 with a netmask of /24 on the em0 interface.
Install FreeBSD 11.0-RELEASE in the jail.
iocage create tag=examplejail ip4_addr="em0|192.168.1.10/24" -r 11.0-RELEASE
Start the new jail:
270
Chapter 13. Jails
FreeNAS® 11.0-U4 User Guide, Release 11.0
iocage start examplejail
Get a console on the jail:
iocage console examplejail
Shut down the jail after use:
iocage stop examplejail
13.4. Using iocage
271
CHAPTER
FOURTEEN
VMS
A Virtual Machine (VM) is an environment on a host computer that can be used as if it were a separate
physical computer. VMs can be used to run multiple operating systems simultaneously. Operating systems
running inside a VM see emulated virtual hardware rather than the actual hardware of the host computer.
This provides more isolation than Jails (page 253), although there is additional overhead. A portion of system
RAM is assigned to each VM, and each VM uses a zvol (page 118) for storage. While a VM is running, these
resources are not available to the host computer or other VMs.
FreeNAS® VMs use the bhyve(8) (https://www.freebsd.org/cgi/man.cgi?query=bhyve&manpath=FreeBSD+11.0RELEASE+and+Ports) virtual machine software. This type of virtualization requires an Intel processor with
Extended Page Tables (EPT) or an AMD processor with Rapid Virtualization Indexing (RVI) or Nested Page
Tables (NPT).
To verify that an Intel processor has the required features, use Shell (page 288) to run grep VT-x
/var/run/dmesg.boot. If the EPT and UG features are shown, this processor can be used with bhyve.
To verify that an AMD processor has the required features, use Shell (page 288) to run grep POPCNT
/var/run/dmesg.boot. If the output shows the POPCNT feature, this processor can be used with bhyve.
Note: AMD K10 “Kuma” processors include POPCNT but do not support NRIPS, which is required for use
with bhyve. Production of these processors ceased in 2012 or 2013.
14.1 Creating VMs
Select VMs → Add VM for the Add VM dialog shown in Figure 14.1:
272
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 14.1: Add VM
VM configuration options are described in Table 14.1.
Table 14.1: VM Options
Setting
Name
Description
Virtual CPUs
Value
string
string
integer
Memory Size (MiB)
Boot Method
integer
dropdown
menu
checkbox
Autostart
Description
a name to identify the VM
a short description of the VM or its purpose
quantity of virtual CPUs allocated to the VM, up to 16; although
these are virtual and not strictly related to host processor cores,
the host CPU might limit the maximum number; the operating
system used in the VM might also have operational or licensing
restrictions on the number of CPUs allowed
megabytes of RAM allocated to the VM
UEFI for newer operating systems, or UEFI-CSM (Compatibility
Support Mode) for older operating systems that only understand BIOS booting
start the VM automatically on boot
14.2 Adding Devices to a VM
After creating the VM, click it to select it, then click the Devices button at the bottom of the screen to add
virtual hardware to it:
14.2. Adding Devices to a VM
273
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 14.2: Add Devices to a VM
VMs are given a NIC (Network Interface Card) by default. This interface emulates an Intel E1000 (82545)
Ethernet card for compatibility with most operating systems:
Fig. 14.3: VM Network Interface Device
The Adapter Type can be changed to VirtIO to provide better performance when the operating system installed in the VM supports VirtIO paravirtualized network drivers.
VMs set to UEFI booting are also given a VNC (Virtual Network Computing) remote connection:
Tip: If a RealVNC 5.X Client shows the error RFB protocol error: invalid message type, disable the Adapt to network speed option and move the slider to Best quality. On later versions of RealVNC,
select File → Preferences, click Expert, ProtocolVersion, then select 4.1 from the drop-down menu.
274
Chapter 14. VMs
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 14.4: VM VNC Device
A standard VNC (https://en.wikipedia.org/wiki/Virtual_Network_Computing) client can connect to the VM to
provide screen output and keyboard and mouse input. The VNC port number can be set to 0 or left empty
for FreeNAS® to assign a port when the VM is started, or set to a fixed, preferred port number.
Zvols (page 118) are used as virtual hard drives. After creating a zvol (page 118), select Add device, choose
the VM, select a Type of Disk, select the zvol, then set the Mode:
Fig. 14.5: VM Disk Device
AHCI emulates an AHCI hard disk for best software compatibility. VirtIO uses paravirtualized drivers and can
provide better performance, but requires the operating system installed in the VM to support VirtIO disk
devices.
Adding a CD-ROM device makes it possible to boot the VM from a CD-ROM image, typically an installation CD. The image must be present on an accessible portion of the FreeNAS® storage. In this example, a
FreeBSD installation image is shown:
14.2. Adding Devices to a VM
275
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 14.6: VM CD-ROM Device
Note: VMs from other virtual machine systems can be recreated for use in FreeNAS® . Back up the original
VM, then create a new FreeNAS® VM with virtual hardware as close as possible to the original VM. Binarycopy the disk image data into the zvol (page 118) created for the FreeNAS® VM with a tool that operates at
the level of disk blocks, like dd(1) (https://www.freebsd.org/cgi/man.cgi?query=dd). For some VM systems,
it is best to back up data, install the operating system from scratch in a new FreeNAS® VM, and restore the
data into the new VM.
14.3 Running VMs
Select VMs to see a list of configured VMs. Configuration and control buttons appear at the bottom of the
screen when an individual VM is selected with a mouse click:
Fig. 14.7: VM Configuration and Control Buttons
The name, description, running state, VNC port (if present), and other configuration values are shown. A
Start button is shown when the VM is not running. Click this to start the VM. If a VNC port is present, use
276
Chapter 14. VMs
FreeNAS® 11.0-U4 User Guide, Release 11.0
VNC client software to connect to that port for screen output and keyboard and mouse input.
On running VMs, the button is shown as Stop, and used, unsurprisingly, to stop them.
14.3. Running VMs
277
CHAPTER
FIFTEEN
REPORTING
Reporting displays several graphs, as seen in the example in Figure 15.1. Click the tab for a device type to
see its graphs.
Fig. 15.1: Reporting Graphs
FreeNAS® uses collectd (https://collectd.org/) to provide reporting statistics. collectd plugins are enabled in
/conf/base/etc/local/collectd.conf to provide reporting graphs. These graphs are grouped into
several tabs on the Reporting page:
• CPU
– CPU (https://collectd.org/wiki/index.php/Plugin:CPU) shows the amount of time spent by the CPU
in various states such as executing user code, executing system code, and being idle.
• Disk
– Disk (https://collectd.org/wiki/index.php/Plugin:Disk) shows statistics on I/O, percent busy, latency, operations per second, and pending I/O requests.
278
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Memory
– Memory (https://collectd.org/wiki/index.php/Plugin:Memory) displays memory usage.
– Swap (https://collectd.org/wiki/index.php/Plugin:Swap) displays the amount of free and used
swap space.
• Network
– Interface (https://collectd.org/wiki/index.php/Plugin:Interface) shows received and transmitted
traffic in bits per second for each configured interface.
• Partition
– Disk space (https://collectd.org/wiki/index.php/Plugin:DF) displays free and used space for each
volume and dataset. However, the disk space used by an individual zvol is not displayed as it is a
block device.
• System
– Processes and Uptime (https://collectd.org/wiki/index.php/Plugin:Processes) displays the number of processes, grouped by state.
– Uptime (https://collectd.org/wiki/index.php/Plugin:Uptime) keeps track of the system uptime, the
average running time, and the maximum reached uptime.
• Target
– Target shows bandwidth statistics for iSCSI ports.
• ZFS
– ZFS (https://collectd.org/wiki/index.php/Plugin:ZFS_ARC) shows ARC size, hit ratio, and requests.
Reporting data is saved to permit viewing and monitoring usage trends over time. This data is preserved
across system upgrades and restarts.
Data files are saved in /var/db/collectd/rrd/.
The reporting data file recording method is controlled by the System → System Dataset Reporting
database checkbox. When unchecked, data files are recorded in a temporary filesystem and copied hourly
to on-disk files.
When System → System Dataset Reporting database is checked, data files are written directly to the
System Dataset (page 66).
Warning: Reporting data is frequently written and should not be stored on the boot pool or boot device.
Use the magnifier buttons next to each graph to increase or decrease the displayed time increment from 10
minutes, hourly, daily, weekly, or monthly. The << and >> buttons can be used to scroll through the output.
Update on using Graphite with FreeNAS (http://cmhramblings.blogspot.com/2015/12/update-on-usinggraphite-with-freenas.html) contains instructions for sending the collected information to a Graphite
(http://graphite.wikidot.com/) server.
279
CHAPTER
SIXTEEN
WIZARD
FreeNAS® provides a wizard which helps complete the steps needed to quickly configure FreeNAS® for
serving data over a network. The wizard can be run at any time by clicking the Wizard icon.
Figure 16.1 shows the first wizard configuration screen.
Fig. 16.1: Configuration Wizard
Note: You can exit the wizard at any time by clicking the Exit button. However, exiting the wizard will
not save any selections. The wizard can always be run again by clicking the Wizard icon. Alternately, the
FreeNAS® GUI can be used to configure the system, as described in the rest of this Guide.
This screen can be used to change the default language, keyboard map, and timezone. After making your
selections, click Next. The next screen depends on whether or not the storage disks have already been
formatted into a ZFS pool.
Figure 16.2 shows the configuration screen that appears if the storage disks have not yet been formatted.
280
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 16.2: Volume Creation Wizard
Note: The wizard will not recognize an encrypted ZFS pool. If your ZFS pool is GELI-encrypted, cancel the
wizard and use the instructions in Importing an Encrypted Pool (page 122) to import the encrypted volume.
You can then rerun the wizard afterwards, if you wish to use it for post-configuration, and it will recognize
that the volume has been imported and will not prompt to reformat the disks.
Enter
a
name
for
the
ZFS
pool
that
conforms
(http://docs.oracle.com/cd/E23824_01/html/821-1448/gbcpt.html).
name that will stick out in the logs (e.g. not data or freenas).
to
these
naming
conventions
It is recommended to choose a
Decide if the pool should provide disk redundancy, and if so, which type. The ZFS Primer (page 323) discusses
RAIDZ redundancy in more detail. If you prefer to make a more complex configuration, click the Exit button
to close the wizard and instead use Volume Manager (page 108).
These redundancy types are available:
• Automatic: automatically creates a mirrored, RAIDZ1, or RAIDZ2 pool, depending upon the number
of disks. If you prefer to control the type of redundancy, select one of the other options.
• RAID 10: creates a striped mirror and requires a minimum of 4 disks.
• RAIDZ2: requires a minimum of 4 disks. Up to 2 disks can fail without data loss.
• RAIDZ1: requires a minimum of 3 disks. Up to 1 disk can fail without data loss.
• Stripe: requires a minimum of 1 disk. Provides no redundancy, meaning if any of the disks in the
stripe fails, all data in the stripe is lost.
Once you have made your selection, click Next to continue.
If the disks have already been formatted with ZFS and the disks have not been encrypted, the next screen
will instead prompt to import the volume, as shown in Figure 16.3.
281
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 16.3: Volume Import Screen
Select the existing volume from the drop-down menu and click Next to continue.
The next screen in the wizard is shown in Figure 16.4.
Fig. 16.4: Directory Service Selection
If the FreeNAS® system is on a network that does not contain an Active Directory, LDAP, or NIS server, click
Next to skip to the next screen.
However, if the FreeNAS® system is on a network containing an Active Directory, LDAP, or NIS server and you
wish to import the users and groups from that server, select the type of directory service in the Directory
Service drop-down menu. The rest of the fields in this screen will vary, depending upon which directory
service is selected. Available configuration options for each directory service are summarized in Tables 16.1
through 16.3.
Note: Additional configuration options are available for each directory service. The wizard can be used to
set the initial values required to connect to that directory service. You can then review the other available
options in Directory Services (page 152) to determine if additional configuration is required.
Table 16.1: Active Directory Options
Setting
Domain Name
Value
string
Domain Account Name
Domain Account Password
string
string
282
Description
name of Active Directory domain (e.g. example.com) or child domain (e.g. sales.example.com)
name of the Active Directory administrator account
password for the Active Directory administrator account
Chapter 16. Wizard
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 16.2: LDAP Options
Setting
Hostname
Base DN
Value
string
string
Bind DN
string
Base password
string
Description
hostname or IP address of LDAP server
top level of the LDAP directory tree to be used when searching
for resources (e.g. dc=test,dc=org)
name of administrative account on LDAP server (e.g.
cn=Manager,dc=test,dc=org)
password for
Table 16.3: NIS Options
Setting
NIS domain
NIS servers
Secure mode
Value
string
string
checkbox
Manycast
checkbox
Description
name of NIS domain
comma delimited list of hostnames or IP addresses
if checked, ypbind(8)
(http://www.freebsd.org/cgi/man.cgi?query=ypbind) will
refuse to bind to any NIS server that is not running as root on a
TCP port number over 1024
if checked, ypbind will bind to the server that responds the
fastest; this is useful when no local NIS server is available on
the same subnet
The next configuration screen, shown in Figure 16.5, is used to create network shares.
283
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 16.5: Network Shares
FreeNAS® supports several types of shares for providing storage data to the clients in a network. The initial
wizard can be used to quickly make shares using default permissions which should “just work” for common
scenarios. For more complex scenarios, refer to the section on Sharing (page 165).
To create a share using the wizard, enter a name for the share, then select the Purpose of the share:
• Windows (SMB): this type of share can be accessed by any operating system using a SMB client. Check
the box for Allow Guest to allow users to access the share without a password. SMB shares created
with the wizard can be fine-tuned afterward with Windows (SMB) Shares (page 183).
• Mac OS X (AFP): this type of share can be accessed by Mac OS X users. Check the box for Time Machine
if Mac users will be using the FreeNAS® system as a backup device. AFP shares created with the wizard
can be fine-tuned afterward with Apple (AFP) Shares (page 166).
• Generic Unix (NFS): this type of share can be accessed by any operating system using a NFS client.
NFS shares created using the wizard can be fine-tuned afterward with Unix (NFS) Shares (page 174).
• Block Storage (iSCSI): this type of share can be accessed by any operating system using iSCSI initiator
software. Enter the size of the block storage to create in the format 20G (for 20 GB). iSCSI shares
created with the wizard can be fine-tuned afterward with iSCSI (page 223).
After selecting the Purpose, click the Ownership button to see the screen shown in Figure 16.6.
284
Chapter 16. Wizard
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 16.6: Share Permissions
The default permissions for the share are displayed. To create a user or group, enter the desired name,
then check the Create User box to create that user and the Create Group box to create the group. Check or
uncheck the boxes in the Mode section to set the initial access permissions for the share. When finished,
click the Return button to return to the share creation screen. Click the Add button to finish creating that
share, which will then appear in the Name frame.
The Delete button can be used to remove the share highlighted in the Name frame. To edit a share, highlight
it, make the change, then press the Update button.
When finished making shares, click the Next button to advance to the screen shown in Figure 16.7.
Fig. 16.7: Miscellaneous Settings
285
FreeNAS® 11.0-U4 User Guide, Release 11.0
This screen can be used to configure these settings:
• Console messages: check this box if you would like to view system messages at the bottom of the
graphical administrative interface. This can be handy when troubleshooting a service that will not
start. When using the console message view, if you click the console messages area, it will pop-up as
a window, allowing you to scroll through the output and to copy its contents.
• Root E-mail: FreeNAS® provides an “Alert” icon in the upper right corner to provide a visual indication
of events that warrant administrative attention. The alert system automatically emails the root user
account whenever an alert is issued. It is important to enter the email address of the person to
receive these alerts and other administrative emails. The rest of the email settings in this screen
should also be reviewed and edited as necessary. Before leaving this screen, click the “Send Test Mail”
button to ensure that email notifications are working correctly.
• From email: the from email address to use when sending email notifications.
• Outgoing mail server: hostname or IP address of SMTP server.
• Port to connect to: port number used by the SMTP server.
• TLS/SSL: encryption type used by the SMTP server.
• Use SMTP Authentication: check this box if the SMTP server requires authentication.
• Username: enter the username if the SMTP server requires authentication.
• Password: enter the password if the SMTP server requires authentication.
When finished, click Next. A message will indicate that the wizard is ready to perform all of the saved actions.
To make changes, click the Return to Wizard button to review your edits. If you click the Exit without saving
button, none of your selections will be saved. To save your edits, click the Confirm button. A status bar will
indicate when the wizard has completed applying the new settings.
In addition to the settings that you specify, the wizard will automatically enable S.M.A.R.T. Tests (page 92),
create a boot environment, and add the new boot environment to the boot menu. If you also wish to save
a backup of the configuration database to the system being used to access the administrative graphical
interface, go to System → General, click the Save Config button, and browse to the directory where
the configuration will be saved. Always back up your configuration after making any configuration
changes.
The rest of this Guide describes the FreeNAS® graphical interface in more detail. The layout of this Guide
follows the order of the menu items in the tree located in the left frame of the graphical interface.
Note: It is important to use the GUI (or the Console Setup menu) for all configuration changes. FreeNAS®
uses a configuration database to store its settings. While it is possible to use the command line to modify
your configuration, changes made at the command line are not written to the configuration database. This
means that any changes made at the command line will not persist after a reboot and will be overwritten
by the values in the configuration database during an upgrade.
286
Chapter 16. Wizard
CHAPTER
SEVENTEEN
DISPLAY SYSTEM PROCESSES
Clicking
Display
System
Processes
opens
a
screen
showing
the
output
(http://www.freebsd.org/cgi/man.cgi?query=top). An example is shown in Figure 17.1.
of
top(1)
Fig. 17.1: System Processes Running on FreeNAS®
The display will automatically refresh itself. Click the X in the upper right corner to close the display. Note
that the display is read-only, meaning that you will not be able to issue a kill command within it.
287
CHAPTER
EIGHTEEN
SHELL
Beginning with version 8.2.0, the FreeNAS® GUI provides a web shell, making it convenient to run command
line tools from the web browser as the root user. The link to Shell is the fourth entry from the bottom of the
menu tree. In Figure 18.1, the link has been clicked and Shell is open.
Fig. 18.1: Web Shell
The prompt indicates that the current user is root, the hostname is freenas, and the current working directory is ~ (root‘s home directory).
To change the size of the shell, click the 80x25 drop-down menu and select a different size.
To copy text from shell, highlight the text, right-click, and select Copy from the right-click menu. To paste into
288
FreeNAS® 11.0-U4 User Guide, Release 11.0
the shell, click the Paste button, paste the text into the box that opens, and click the OK button to complete
the paste operation.
Shell provides history (use your up arrow to see previously entered commands and press Enter to repeat
the currently displayed command) and tab completion (type a few letters and press tab to complete a
command name or filename in the current directory). When you are finished using Shell, type exit to
leave the session.
While you are in Shell, you will not have access to any of the other GUI menus. If you need to have access
to a prompt while using the GUI menus, use tmux (page 317) instead as it supports multiple shell sessions
and the detachment and reattachment of sessions.
Note: Not all of Shell’s features render correctly in Chrome. Firefox is the recommended browser for using
Shell.
Most FreeBSD command line utilities are available in Shell. Additional troubleshooting utilities that are
provided by FreeNAS® are described in Command Line Utilities (page 302).
289
CHAPTER
NINETEEN
LOG OUT
Click the Log Out entry in the FreeNAS® GUI to log out.
After logging out, a message appears with a link to log back in. When logging back in, the root password is
required.
290
CHAPTER
TWENTY
REBOOT
Clicking the Reboot entry in the tree shows the warning message in Figure 20.1. The browser screen color
changes to red to indicate that this option will negatively impact current users of the FreeNAS® system.
Fig. 20.1: Reboot Warning Message
If a scrub or resilver is in progress when a reboot is requested, an additional warning will ask you to make
sure that you wish to proceed. In this case, it is recommended to Cancel the reboot request and to periodically run zpool status from Shell until it is verified that the scrub or resilver process is complete. Once
complete, the reboot request can be re-issued.
Click the Cancel button to cancel the reboot request. Otherwise, click the Reboot button to reboot the
system. Rebooting the system disconnects all clients, including the web administration GUI. The URL in
the web browser changes to add /system/reboot/ to the end of the IP address. Wait a few minutes for the
system to boot, then use your browser’s “back” button to return to the FreeNAS® system’s IP address. If
all went well, the GUI login screen will appear. If the login screen does not appear, physical access to the
FreeNAS® system’s monitor and keyboard is needed to determine what problem is preventing the system
from resuming normal operation.
291
CHAPTER
TWENTYONE
SHUTDOWN
Clicking the Shutdown entry in the tree opens the warning message shown in Figure 21.1. The browser
window color changes to red to indicate that this command will negatively impact current users of the
FreeNAS® system.
Fig. 21.1: Shutdown Warning Message
If a scrub or resilver is in progress when a shutdown is requested, an additional warning will ask if you wish
to proceed. In this case, it is recommended to Cancel the shutdown request and to periodically run zpool
status from Shell (page 288) until the scrub or resilver process is complete. Once complete, the shutdown
request can be re-issued.
Click the Cancel button to cancel the shutdown request. Otherwise, click the Shutdown button to halt the
system. Shutting down the system disconnects all clients, including the web administration GUI, and powers
off the FreeNAS® system. Physical access to the FreeNAS® system will be needed to turn it back on.
292
CHAPTER
TWENTYTWO
SUPPORT ICON
The Support icon, the third icon from the left in the top menubar, provides a shortcut to System →
Support. This screen can be used to create a support ticket. Refer to Support (page 80) for detailed usage
instructions.
293
CHAPTER
TWENTYTHREE
GUIDE
The Documentation icon, the second icon from the left in the top menubar, provides a built-in browser to
the FreeNAS® User Guide (this documentation).
294
CHAPTER
TWENTYFOUR
ALERT
FreeNAS® provides an alert system to provide a visual warning of any conditions that require administrative
attention. The Alert button in the far right corner flashes red when there is an outstanding alert. In the
example alert shown in Figure 24.1, the system is warning that the S.M.A.R.T. service is not running.
Fig. 24.1: Example Alert Message
Informational messages have a green OK, warning messages flash yellow, and messages requiring attention
are listed as a red CRITICAL. CRITICAL messages are also emailed to the root user account. If you are aware
of a critical condition but wish to remove the flashing alert until you deal with it, uncheck the box next to
that message.
Behind the scenes, an alert daemon checks for various alert conditions, such as volume and disk status,
and writes the current conditions to /var/tmp/alert. The daemon retrieves the current alert status
every minute and will change the solid green alert icon to flashing red if a new alert is detected.
Current alerts can also be viewed from the Shell option of the Console Setup Menu (Figure 3.1) or from the
Web Shell (Figure 18.1) by running alertcli.py.
Some of the conditions that trigger an alert include:
• used space on a volume goes over 80%
• new OpenZFS feature flags are available for the pool; this alert can be unchecked if you choose not to
upgrade the pool at this time
• a new update is available
• non-optimal multipath states detected
• ZFS pool status changes from HEALTHY
• a S.M.A.R.T. error occurs
• the system dataset does not reside on the boot pool
• the system is unable to bind to the WebGUI IPv4 Address set in System → General
• the system can not find an IP address configured on an iSCSI portal
295
FreeNAS® 11.0-U4 User Guide, Release 11.0
• a periodic snapshot or replication task fails
• a VMware login or a VMware-Snapshot (page 150) task fails
• deleting a VMware snapshot fails
• a Certificate Authority or certificate is invalid or malformed
• an update failed, or the system needs to reboot to complete a successful update
• a re-key operation fails on an encrypted pool
• LDAP failed to bind to the domain
• any member interfaces of a lagg interface are not active
• the
status
of
an
Avago
MegaRAID
SAS
controller
has
changed;
mfiutil(8)
(http://www.freebsd.org/cgi/man.cgi?query=mfiutil) is included for managing these devices
296
Chapter 24. Alert
CHAPTER
TWENTYFIVE
SUPPORT RESOURCES
FreeNAS® has a large installation base and an active user community. This means that many usage questions have already been answered and the details are available on the Internet. If you get stuck using
FreeNAS® , spend a few moments searching the Internet for the word FreeNAS with some keywords that
describe the error message or the function you are trying to implement.
The rest of this section discusses the following resources which are available to FreeNAS® users:
• Website and Social Media (page 297)
• Forums (page 297)
• IRC (page 299)
• Mailing Lists (page 300)
• Videos (page 300)
• Professional Support (page 301)
25.1 Website and Social Media
The FreeNAS® website (http://www.freenas.org/) contains links to all of the available documentation, support, and social media resources. Major announcements are also posted to the main page.
Users are welcome to network on the FreeNAS® social media sites:
• LinkedIn (http://www.linkedin.com/groups/FreeNAS8-3903140)
• Google+ (https://plus.google.com/110373675402281849911/posts)
• Facebook FreeNAS Community (https://www.facebook.com/freenascommunity)
• Facebook FreeNAS Consortium (please request to be added) (https://www.facebook.com/groups/1707686686200221)
• Twitter (https://twitter.com/freenasteam)
25.2 Forums
The FreeNAS® Forums are another information source which contains categorized user-contributed tips
and guides. This makes it an ideal resource for learning more about a certain aspect of FreeNAS® . A search
bar is included for searching by keyword. Or click a category to browse through the threads that exist for
that topic.
These categories are available under Forum Information:
297
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Forum Guidelines (https://forums.freenas.org/index.php?forums/forum-guidelines-read-beforeposting.26/): read this first before creating a forum post.
• Announcements (https://forums.freenas.org/index.php?forums/announcements.27/): subscribe to
this forum if you wish to receive announcements about new FreeNAS® versions and features.
These categories are available under Help and Support:
• New to FreeNAS®? (https://forums.freenas.org/index.php?forums/new-to-freenas.5/): post here if
you are new to FreeNAS® and are unsure which category best matches your question.
• Feature Requests (https://forums.freenas.org/index.php?forums/feature-requests.6/): for the discussion of upcoming features.
• Bug Reporting (https://forums.freenas.org/index.php?forums/bug-reporting.7/): use this forum if you
think you have found a bug in FreeNAS® and want to discuss it before creating a support ticket.
• Hardware (https://forums.freenas.org/index.php?forums/hardware.18/): for the discussion of hardware and tips for getting the most out of your hardware.
• User Authentication (https://forums.freenas.org/index.php?forums/user-authentication.19/): LDAP
and Active Directory.
• Sharing (https://forums.freenas.org/index.php?forums/sharing.20/): AFP, CIFS, NFS, and iSCSI.
• Storage (https://forums.freenas.org/index.php?forums/storage.21/): replication, snapshots, volumes,
and ZFS.
• Networking (https://forums.freenas.org/index.php?forums/networking.22/): networking hardware,
performance, link aggregation, VLANs, DDNS, FTP, SNMP, SSH, and TFTP.
• Installation (https://forums.freenas.org/index.php?forums/installation.32/): installing help or advice
before performing the installation.
• Plugins (https://forums.freenas.org/index.php?forums/plugins.34/): provides a discussion area for
creating and troubleshooting PBIs.
These categories are available under Development:
• FreeNAS (https://forums.freenas.org/index.php?forums/freenas.9/): general development discussion.
• nanobsd (https://forums.freenas.org/index.php?forums/nanobsd.10/): the embedded operating system on which FreeNAS® is based.
• Django (https://forums.freenas.org/index.php?forums/django.11/): the web framework used by the
FreeNAS® graphical administrative interface.
• Dojo Toolkit (https://forums.freenas.org/index.php?forums/dojo-toolkit.12/): the javascript toolkit
used to create widgets and handle client side processing.
These categories are available under How-To Guides:
• Hacking (https://forums.freenas.org/index.php?forums/hacking.14/): undocumented tricks for getting
the most out of your FreeNAS® system.
• Installation (https://forums.freenas.org/index.php?forums/installation.15/): specific installation scenarios (hardware and/or software).
• Configuration (https://forums.freenas.org/index.php?forums/configuration.16/): specific configuration scenarios (e.g. software or client configuration).
• Hardware (https://forums.freenas.org/index.php?forums/hardware.17/): instructions for setting up
specific hardware.
298
Chapter 25. Support Resources
FreeNAS® 11.0-U4 User Guide, Release 11.0
• Useful Scripts (https://forums.freenas.org/index.php?forums/useful-scripts.47/):
scripts.
user-contributed
For tips on testing and increasing the performance of your system, check out the Performance
(https://forums.freenas.org/index.php?forums/performance.37/) forum.
These categories are available under Community Forum:
• Off-topic (https://forums.freenas.org/index.php?forums/off-topic.23/): want to discuss something of
interest to FreeNAS® users but which is not necessarily related to FreeNAS® ? This is the place.
• Resources (https://forums.freenas.org/index.php?forums/resources.24/): blogs, reviews, and other
sources of FreeNAS® information not listed at freenas.org (http://www.freenas.org/).
• Introductions (https://forums.freenas.org/index.php?forums/introductions.25/): FreeNAS® Community meet ‘n greet - introduce yourself and let us know who we are chatting with.
These language-specific categories are available under International, allowing FreeNAS® users to interact
with each other in their native language:
• Dutch - Nederlands (http://forums.freenas.org/forumdisplay.php?35-Dutch-Nederlands)
• French - Francais (http://forums.freenas.org/forumdisplay.php?29-French-Francais)
• German - Deutsch (http://forums.freenas.org/forumdisplay.php?31-German-Deutsch)
• Italian - Italiano (http://forums.freenas.org/forumdisplay.php?30-Italian-Italiano)
• Portuguese - Português (http://forums.freenas.org/forums/portuguese-português.44/)
• Russian (http://goo.gl/sCMUe5)
• Spanish - Espanol (http://forums.freenas.org/forumdisplay.php?33-Spanish-Espanol)
• Swedish - Svenske (https://forums.freenas.org/index.php?forums/swedish-svenske.51/)
• Turkish - Türkçe (http://forums.freenas.org/forumdisplay.php?36-Turkish-T%FCrk%E7e)
To ask a question on the forum, click the Sign Up Now! link to create an account and log in using that account.
When asking a question on the forum, it is important to:
• First check to see if the question has already been asked. If a similar question exists, do not create a
new thread. Instead use the Reply link at the bottom of the post to add your comments to the existing
thread.
• Review the available categories to see which one is most closely related to your question. Click on that
category and use the Post New Thread button to open the editor. After typing your post but before
clicking the Create Thread button, make sure the Watch this thread... box is checked. To be notified by
email, also check the and receive email notifications box. You will be notified whenever anyone answers
your question.
25.3 IRC
To ask a question in real time, you can use the #freenas channel on IRC Freenode (http://freenode.net/).
Depending on the time of day and your time zone, FreeNAS® developers or other users may be available
to provide assistance. If no one answers right away, remain on the channel, as other users tend to read the
channel history to answer questions as time permits.
Typically, an IRC client (http://en.wikipedia.org/wiki/Comparison_of_Internet_Relay_Chat_clients) is used to
access the #freenas IRC channel. Alternately, use webchat (http://webchat.freenode.net/?channels=freenas)
from a web browser.
25.3. IRC
299
FreeNAS® 11.0-U4 User Guide, Release 11.0
To get the most out of the IRC channel, keep these points in mind:
• Do not ask “can anyone help me?”. Just ask the question. If someone knows the answer, they will try
to help.
• Do not ask a question and then leave. Users who know the answer cannot help you if you disappear.
• Do not take it personally if no one answers or demand that someone answers your question. Maybe
no one who knows the answer is available, maybe your question is really difficult, or maybe it is a
question that has already been answered many times in the other support resources. Try asking
again in a few hours or research the other resources to see if you have missed anything.
• Do not post error messages in the channel as the IRC software will probably kick you out. Instead, use
a pasting service such as pastebin (http://www.pastebin.com/) and paste the resulting URL into the
IRC discussion.
25.4 Mailing Lists
Several FreeNAS® mailing lists are available which allow users and developers to ask and answer questions
related to the topic of the mailing list. To post an email to a list, you will need to subscribe to it first. Each
mailing list is archived, allowing you to browse for information by date, thread name, or author.
These mailing lists are available:
• Freenas-announce (http://lists.freenas.org/mailman/listinfo/freenas-announce): this is a low-volume,
read-only list where major milestones, such as new releases, are announced.
• Freenas-commit (http://lists.freenas.org/mailman/listinfo/freenas-commit): this is a read-only list. As
code changes in the FreeNAS® repository, the commit message is automatically sent to this list.
• Freenas-devel (http://lists.freenas.org/mailman/listinfo/freenas-devel): FreeNAS® developers are subscribed to this list. Technical questions about the current FreeNAS® release can be posted here.
• Freenas-docs (http://lists.freenas.org/mailman/listinfo/freenas-docs): this list is for discussion regarding FreeNAS® documentation <http://doc.freenas.org/>‘_.
• Freenas-testing (http://lists.freenas.org/mailman/listinfo/freenas-testing): FreeNAS® developers are
subscribed to this list. Technical questions about the upcoming FreeNAS® release and feedback on
testing snapshots can be posted here.
• Freenas-translations (http://lists.freenas.org/mailman/listinfo/freenas-translations): this list is for discussion regarding FreeNAS® localization <http://pootle.freenas.org/>‘_ and translating FreeNAS® documentation.
Note:
The mailing lists were migrated from SourceForge to Mailman in December, 2013.
Archives of the SourceForge mailing lists are available at Gmane
(http://dir.gmane.org/index.php?prefix=gmane.os.freenas).
25.5 Videos
A series of instructional videos are available for FreeNAS® :
• Changes in FreeNAS® 9.3 (https://www.youtube.com/watch?v=weKWqmbWdR4)
• FreeNAS 9.3 Updates (https://www.youtube.com/watch?v=lC7af_ahwSE)
300
Chapter 25. Support Resources
FreeNAS® 11.0-U4 User Guide, Release 11.0
• How to Upgrade FreeNAS® 9.3 (https://www.youtube.com/watch?v=L61IJF98eP8)
• How to Install FreeNAS® 9.3 (https://www.youtube.com/watch?v=k-mRgeDS8rk)
• FreeNAS®
9.3
Shares
Overview
(AFP,
(https://www.youtube.com/watch?v=GVJQ0Vx_6i4)
NFS,
CIFS,
+
New
WebDAV)
• How to Replace HDD in FreeNAS® 9.3 (https://www.youtube.com/watch?v=c8bvtj-LQ_A)
• TrueNAS® 9.3 Snapshots Setup (https://www.youtube.com/watch?v=R92wb_xN9k4)
• Install Murmur (Mumble server) on FreeNAS/FreeBSD (https://www.youtube.com/watch?v=aAeZRNfarJc)
• FreeNAS® 9.3 - First Time Setup Wizard (https://www.youtube.com/watch?v=isvHJ51YRBk)
• FreeNAS® 9.3 Permissions Overview (https://www.youtube.com/watch?v=RBszScnsRgY)
• FreeNAS® 9.3 iSCSI Overview (https://www.youtube.com/watch?v=HvyOWlFISdo&)
• FreeNAS® 9.10 - Certificate Authority & SSL Certificates (https://www.youtube.com/watch?v=OT1Le5VQIc0)
• How to Update FreeNAS® 9.10 (https://www.youtube.com/watch?v=2nvb90AhgL8)
• FreeNAS® 9.10 LAGG & VLAN Overview (https://www.youtube.com/watch?v=wqSH_uQSArQ)
• FreeNAS 9.10 and Samba (SMB) Permissions (https://www.youtube.com/watch?v=RxggaE935PM)
25.6 Professional Support
In addition to the freely available community resources, professional support may be available through
iXsystem’s network of third-party consultants. Submit a support inquiry using the form at https://www.
ixsystems.com/freenas-commercial-support/.
25.6. Professional Support
301
CHAPTER
TWENTYSIX
COMMAND LINE UTILITIES
Several command line utilities which are provided with FreeNAS® are demonstrated in this section.
The following utilities can be used for benchmarking and performance testing:
• Iperf (page 302): used for measuring maximum TCP and UDP bandwidth performance
• Netperf (page 305): a tool for measuring network performance
• IOzone (page 306): filesystem benchmark utility used to perform a broad filesystem analysis
• arcstat (page 309): used to gather ZFS ARC statistics
The following utilities are specific to RAID controllers:
• tw_cli (page 314):_used to monitor and maintain 3ware RAID controllers
• MegaCli (page 316): used to configure and manage Avago MegaRAID SAS family of RAID controllers
This section also describes these utilities:
• freenas-debug (page 316): the backend used to dump FreeNAS® debugging information
• tmux (page 317): a terminal multiplexer similar to GNU screen
• Dmidecode (page 318): reports information about system hardware as described in the system’s BIOS
26.1 Iperf
Iperf is a utility for measuring maximum TCP and UDP bandwidth performance. It can be used to chart
network throughput over time. For example, you can use it to test the speed of different types of shares to
determine which type best performs on your network.
FreeNAS® includes the Iperf server. To perform network testing, you will need to install an Iperf client on a
desktop system that has network access to the FreeNAS® system. This section will demonstrate how to use
the xjperf GUI client (http://code.google.com/p/xjperf/downloads/detail?name=jperf-2.0.2.zip) as it works
on Windows, Mac OS X, Linux, and BSD systems.
Since this client is Java-based, the appropriate JRE (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
must be installed on the client computer.
Linux and BSD users will need to install the iperf package using their operating system’s package management system.
To start xjperf on Windows: unzip the downloaded file, start Command Prompt in Run as administrator
mode, cd to the unzipped folder, and run jperf.bat.
To start xjperf on Mac OS X, Linux, or BSD, unzip the downloaded file, cd to the unzipped directory, type
chmod u+x jperf.sh, and run ./jperf.sh.
302
FreeNAS® 11.0-U4 User Guide, Release 11.0
Once the client is ready, you need to start the Iperf server on FreeNAS® . To see the available server options,
open Shell and type:
iperf --help | more
Usage: iperf [-s|-c host] [options]
iperf [-h|--help] [-v|--version]
Client/Server:
-f, --format [kmKM] format to report: Kbits, Mbits, KBytes, MBytes
-i, --interval
#
seconds between periodic bandwidth reports
-l, --len
#[KM]
length of buffer to read or write (default 8 KB)
-m, --print_mss
print TCP maximum segment size (MTU - TCP/IP header)
-o, --output <filename> output the report or error message to this specified file
-p, --port
#
server port to listen on/connect to
-u, --udp
use UDP rather than TCP
-w, --window #[KM]
TCP window size (socket buffer size)
-B, --bind
<host> bind to <host>, an interface or multicast address
-C, --compatibility for use with older versions does not sent extra msgs
-M, --mss
#
set TCP maximum segment size (MTU - 40 bytes)
-N, --nodelay
set TCP no delay, disabling Nagle's Algorithm
-V, --IPv6Version
Set the domain to IPv6
Server specific:
-s, --server
-U, --single_udp
-D, --daemon
run in server mode
run in single threaded UDP mode
run the server as a daemon
Client specific:
-b, --bandwidth #[KM]
-c,
-d,
-n,
-r,
-t,
-F,
-I,
-L,
-P,
-T,
-Z,
for UDP, bandwidth to send at in bits/sec
(default 1 Mbit/sec, implies -u)
--client <host> run in client mode, connecting to <host>
--dualtest
Do a bidirectional test simultaneously
--num
#[KM]
number of bytes to transmit (instead of -t)
--tradeoff
Do a bidirectional test individually
--time
#
time in seconds to transmit for (default 10 secs)
--fileinput <name>
input the data to be transmitted from a file
--stdin
input the data to be transmitted from stdin
--listenport #
port to receive bidirectional tests back on
--parallel
#
number of parallel client threads to run
--ttl
#
time-to-live, for multicast (default 1)
--linux-congestion <algo> set TCP congestion control algorithm (Linux only)
Miscellaneous:
-x, --reportexclude [CDMSV]
˓→V(server) reports
-y, --reportstyle C
-h, --help
-v, --version
exclude C(connection) D(data) M(multicast) S(settings)
report as a Comma-Separated Values
print this message and quit
print version information and quit
[KM] Indicates options that support a K or M suffix for kilo- or megaThe TCP window size option can be set by the environment variable
TCP_WINDOW_SIZE. Most other options can be set by an environment variable
IPERF_<long option name>, such as IPERF_BANDWIDTH.
For example, to perform a TCP test and start the server in daemon mode (so that you get your prompt
back), type:
26.1. Iperf
303
FreeNAS® 11.0-U4 User Guide, Release 11.0
iperf -sD
-----------------------------------------------------------Server listening on TCP port 5001
TCP window size: 64.0 KByte (default)
-----------------------------------------------------------Running Iperf Server as a daemon
The Iperf daemon process ID: 4842
Note: If you close Shell (page 288), the daemon process will stop. Have your environment set up (e.g.
shares configured and started) before starting the iperf process.
From your desktop, open the client. Enter the IP of address of the FreeNAS® system, specify the running
time for the test under Application layer options → Transmit (the default test time is 10 seconds), and click the Run Iperf! button. Figure 26.1 shows an example of the client running on a Windows
system while an SFTP transfer is occurring on the network.
Fig. 26.1: Viewing Bandwidth Statistics Using xjperf
Depending upon the traffic being tested (e.g. the type of share running on your network), you may need to
test UDP instead of TCP. To start the iperf server in UDP mode, use iperf -sDu as the u specifies UDP;
the startup message should indicate that the server is listening for UDP datagrams. If you are not sure if
the traffic that you wish to test is UDP or TCP, run this command to determine which services are running
on the FreeNAS® system:
304
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
sockstat
USER
root
root
www
www
www
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
-4 | more
COMMAND PID
iperf
4870
iperf
4842
nginx
4827
nginx
4827
nginx
4827
sshd
3852
python 2503
mountd 2363
mountd 2363
rpcbind 2359
rpcbind 2359
rpcbind 2359
nginx
2044
python 2029
python 2029
python 2029
ntpd
1548
ntpd
1548
ntpd
1548
syslogd 1089
FD
6
6
3
5
7
5
5
7
8
9
10
11
7
3
4
7
20
22
25
6
PROTO
udp4
tcp4
tcp4
tcp4
tcp4
tcp4
udp4
udp4
tcp4
udp4
udp4
tcp4
tcp4
udp4
tcp4
tcp4
udp4
udp4
udp4
udp4
LOCAL ADDRESS
FOREIGN ADDRESS
*:5001
*:*
*:5001
*:*
127.0.0.1:15956 127.0.0.1:9042
192.168.2.11:80 192.168.2.26:56964
*:80
*:*
*:22
*:*
:
* *
*:*
*:812
*:*
*:812
*:*
*:111
*:*
:886
*
*:*
*:111
*:*
*:80
*:*
*:*
*:*
127.0.0.1:9042 *:*
127.0.0.1:9042 127.0.0.1:15956
*:123
*:*
192.168.2.11:123*:*
127.0.0.1:123
*:*
127.0.0.1:514
*:*
When you are finished testing, either type killall iperf or close Shell to terminate the iperf server
process.
26.2 Netperf
Netperf is a benchmarking utility that can be used to measure the performance of unidirectional throughput
and end-to-end latency.
Before you can use the netperf command, you must start its server process using this command:
netserver
Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
The following command will display the available options for performing tests with the netperf command.
The Netperf Manual (http://www.netperf.org/svn/netperf2/tags/netperf-2.6.0/doc/netperf.html) describes
each option in more detail and explains how to perform many types of tests. It is the best reference for
understanding how each test works and how to interpret your results. When you are finished with your
tests, type killall netserver to stop the server process.
netperf -h |more
Usage: netperf [global
Global options:
-a send,recv
-A send,recv
-B brandstr
-c [cpu_rate]
-C [cpu_rate]
-d
-D [secs,units] *
-f G|M|K|g|m|k
-F fill_file
-h
26.2. Netperf
options] -- [test options]
Set the local send,recv buffer alignment
Set the remote send,recv buffer alignment
Specify a string to be emitted with brief output
Report local CPU usage
Report remote CPU usage
Increase debugging output
Display interim results at least every secs seconds
using units as the initial guess for units per second
Set the output units
Pre-fill buffers with data from fill_file
Display this text
305
FreeNAS® 11.0-U4 User Guide, Release 11.0
-H name|ip,fam *
-i max,min
-I lvl[,intvl]
-j
-l
-L
-o
-O
-n
-N
-p
-P
-r
-s
-S
-t
-T
-v
-W
-v
-V
testlen
name|ip,fam *
send,recv
send,recv
numcpu
port,lport*
0|1
seconds
testname
lcpu,rcpu
verbosity
send,recv
level
Specify the target machine and/or local ip and family
Specify the max and min number of iterations (15,1)
Specify confidence level (95 or 99) (99)
and confidence interval in percentage (10)
Keep additional timing statistics
Specify test duration (>0 secs) (<0 bytes|trans)
Specify the local ip|name and address family
Set the local send,recv buffer offsets
Set the remote send,recv buffer offset
Set the number of processors for CPU util
Establish no control connection, do 'send' side only
Specify netserver port number and/or local port
Don't/Do display test headers
Allow confidence to be hit on result only
Wait seconds between test setup and test start
Set SO_KEEPALIVE on the data connection
Specify test to perform
Request netperf/netserver be bound to local/remote cpu
Specify the verbosity level
Set the number of send,recv buffers
Set the verbosity level (default 1, min 0)
Display the netperf version and exit
For those options taking two parms, at least one must be specified; specifying one value without a comma
will set both parms to that value, specifying a value with a leading comma will set just the second parm,
a value with a trailing comma will set just the first. To set each parm to unique values, specify both and
separate them with a comma.
For these options taking two parms, specifying one value with no comma will only set the first parms and
will leave the second at the default value. To set the second value it must be preceded with a comma or be
a comma-separated pair. This is to retain previous netperf behaviour.
26.3 IOzone
IOzone is a disk and filesystem benchmarking tool. It can be used to test file I/O performance for the
following operations: read, write, re-read, re-write, read backwards, read strided, fread, fwrite, random
read, pread, mmap, aio_read, and aio_write.
FreeNAS® ships with IOzone, meaning that it can be run from Shell. When using IOzone on FreeNAS® , cd
to a directory in a volume that you have permission to write to, otherwise you will get an error about being
unable to write the temporary file.
Before
using
IOzone,
read
through
the
IOzone
documentation
PDF
(http://www.iozone.org/docs/IOzone_msword_98.pdf) as it describes the tests, the many command
line switches, and how to interpret your results.
If you have never used this tool before, these resources provide good starting points on which tests to run,
when to run them, and how to interpret the results:
• How To Measure Linux Filesystem I/O Performance With iozone (http://www.cyberciti.biz/tips/linuxfilesystem-benchmarking-with-iozone.html)
• Analyzing NFS Client Performance with IOzone (http://www.iozone.org/docs/NFSClientPerf_revised.pdf)
• 10
iozone
Examples
for
Disk
I/O
Performance
(http://www.thegeekstuff.com/2011/05/iozone-examples/)
306
Measurement
on
Linux
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
You can receive a summary of the available switches by typing the following command. As you can see from
the number of options, IOzone is comprehensive and it may take some time to learn how to use the tests
effectively.
Starting with version 9.2.1, FreeNAS® enables compression on newly created ZFS pools by default. Since
IOzone creates test data that is compressible, this can skew test results. To configure IOzone to generate
incompressible test data, include the options -+w 1 -+y 1 -+C 1.
Alternatively, consider temporarily disabling compression on the ZFS pool or dataset when running IOzone
benchmarks.
Note: If you prefer to visualize the collected data, scripts are available to render IOzone’s output in Gnuplot
(http://www.gnuplot.info/).
iozone -h | more
iozone: help mode
Usage: iozone[-s filesize_Kb] [-r record_size_Kb] [-f [path]filename] [-h]
[-i test] [-E] [-p] [-a] [-A] [-z] [-Z] [-m] [-M] [-t children]
[-l min_number_procs] [-u max_number_procs] [-v] [-R] [-x] [-o]
[-d microseconds] [-F path1 path2...] [-V pattern] [-j stride]
[-T] [-C] [-B] [-D] [-G] [-I] [-H depth] [-k depth] [-U mount_point]
[-S cache_size] [-O] [-L cacheline_size] [-K] [-g maxfilesize_Kb]
[-n minfilesize_Kb] [-N] [-Q] [-P start_cpu] [-e] [-c] [-b Excel.xls]
[-J milliseconds] [-X write_telemetry_filename] [-w] [-W]
[-Y read_telemetry_filename] [-y minrecsize_Kb] [-q maxrecsize_Kb]
[-+u] [-+m cluster_filename] [-+d] [-+x multiplier] [-+p # ]
[-+r] [-+t] [-+X] [-+Z] [-+w percent dedupable] [-+y percent_interior_
˓→dedup]
[-+C percent_dedup_within]
-a Auto mode
-A Auto2 mode
-b Filename Create Excel worksheet file
-B Use mmap() files
-c Include close in the timing calculations
-C Show bytes transferred by each child in throughput testing
-d # Microsecond delay out of barrier
-D Use msync(MS_ASYNC) on mmap files
-e Include flush (fsync,fflush) in the timing calculations
-E Run extension tests
-f filename to use
-F filenames for each process/thread in throughput test
-g # Set maximum file size (in Kbytes) for auto mode (or #m or #g)
-G Use msync(MS_SYNC) on mmap files
-h help
-H # Use POSIX async I/O with # async operations
-i # Test to run (0=write/rewrite, 1=read/re-read, 2=random-read/write
3=Read-backwards, 4=Re-write-record, 5=stride-read, 6=fwrite/re-fwrite
7=fread/Re-fread, 8=random_mix, 9=pwrite/Re-pwrite, 10=pread/Re-pread
11=pwritev/Re-pwritev, 12=preadv/Re-preadv)
-I Use VxFS VX_DIRECT, O_DIRECT,or O_DIRECTIO for all file operations
-j # Set stride of file accesses to (# * record size)
-J # milliseconds of compute cycle before each I/O operation
-k # Use POSIX async I/O (no bcopy) with # async operations
-K Create jitter in the access pattern for readers
-l # Lower limit on number of processes to run
-L # Set processor cache line size to value (in bytes)
-m Use multiple buffers
26.3. IOzone
307
FreeNAS® 11.0-U4 User Guide, Release 11.0
-M
-n
-N
-o
-O
-p
-P
-q
-Q
-r
Report uname -a output
# Set minimum file size (in Kbytes) for auto mode (or #m or #g)
Report results in microseconds per operation
Writes are synch (O_SYNC)
Give results in ops/sec.
Purge on
# Bind processes/threads to processors, starting with this cpu
# Set maximum record size (in Kbytes) for auto mode (or #m or #g)
Create offset/latency files
# record size in Kb
or -r #k .. size in Kb
or -r #m .. size in Mb
or -r #g .. size in Gb
-R Generate Excel report
-s # file size in Kb
or -s #k .. size in Kb
or -s #m .. size in Mb
or -s #g .. size in Gb
-S # Set processor cache size to value (in Kbytes)
-t # Number of threads or processes to use in throughput test
-T Use POSIX pthreads for throughput tests
-u # Upper limit on number of processes to run
-U Mount point to remount between tests
-v version information
-V # Verify data pattern write/read
-w Do not unlink temporary file
-W Lock file when reading or writing
-x Turn off stone-walling
-X filename Write telemetry file. Contains lines with (offset reclen
˓→compute_time) in ascii
-y # Set minimum record size (in Kbytes) for auto mode (or #m or #g)
-Y filename Read telemetry file. Contains lines with (offset reclen compute_
˓→time) in ascii
-z Used in conjunction with -a to test all possible record sizes
-Z Enable mixing of mmap I/O and file I/O
-+E Use existing non-Iozone file for read-only testing
-+K Sony special. Manual control of test 8.
-+m Cluster_filename Enable Cluster testing
-+d File I/O diagnostic mode. (To troubleshoot a broken file I/O subsystem)
-+u Enable CPU utilization output (Experimental)
-+x # Multiplier to use for incrementing file and record sizes
-+p # Percentage of mix to be reads
-+r Enable O_RSYNC|O_SYNC for all testing.
-+t Enable network performance test. Requires -+m
-+n No retests selected.
-+k Use constant aggregate data set size.
-+q Delay in seconds between tests.
-+l Enable record locking mode.
-+L Enable record locking mode, with shared file.
-+B Sequential mixed workload.
-+A # Enable madvise. 0 = normal, 1=random, 2=sequential 3=dontneed,
˓→4=willneed
-+N Do not truncate existing files on sequential writes.
-+S # Dedup-able data is limited to sharing within each numerically
˓→identified file set
-+V Enable shared file. No locking.
-+X Enable short circuit mode for filesystem testing ONLY
ALL Results are NOT valid in this mode.
308
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
-+Z Enable old data set compatibility mode. WARNING.. Published
hacks may invalidate these results and generate bogus, high values for
˓→results.
-+w ## Percent of dedup-able data in buffers.
-+y ## Percent of dedup-able within & across files in buffers.
-+C ## Percent of dedup-able within & not across files in buffers.
-+H Hostname Hostname of the PIT server.
-+P Service Service of the PIT server.
-+z Enable latency histogram logging.
26.4 arcstat
Arcstat is a script that prints out ZFS ARC (https://en.wikipedia.org/wiki/Adaptive_replacement_cache) statistics. Originally it was a perl script created by Sun. That perl script was ported to FreeBSD and was then
ported as a Python script for use on FreeNAS® .
Watching ARC hits/misses and percentages will provide an indication of how well your ZFS pool is fetching
from the ARC rather than using disk I/O. Ideally, you want as many things fetching from cache as possible.
Keep your load in mind as you review the stats. For random reads, expect a miss and having to go to disk
to fetch the data. For cached reads, expect it to pull out of the cache and have a hit.
Like all cache systems, the ARC takes time to fill with data. This means that it will have a lot of misses until
the pool has been in use for a while. If there continues to be lots of misses and high disk I/O on cached
reads, there is cause to investigate further and tune the system.
The FreeBSD ZFS Tuning Guide (https://wiki.FreeBSD.org/ZFSTuningGuide) provides some suggestions for
commonly tuned sysctl values. It should be noted that performance tuning is more of an art than a
science and that any changes you make will probably require several iterations of tune and test. Be aware
that what needs to be tuned will vary depending upon the type of workload and that what works for one
person’s network may not benefit yours.
In particular, the value of pre-fetching depends upon the amount of memory and the type of workload, as
seen in these two examples:
• Understanding ZFS: Prefetch (http://www.cuddletech.com/blog/pivot/entry.php?id=1040)
• ZFS prefetch algorithm can cause performance drawbacks (http://southbrain.com/south/2008/04/thenightmare-comes-slowly-zfs.html)
FreeNAS® provides two command line scripts which can be manually run from Shell (page 288):
• arc_summary.py: provides a summary of the statistics
• arcstat.py: used to watch the statistics in real time
The advantage of these scripts is that they can be used to provide real time (right now) information, whereas
the current GUI reporting mechanism is designed to only provide graphs charted over time.
This forum post (https://forums.freenas.org/index.php?threads/benchmarking-zfs.7928/) demonstrates
some examples of using these scripts with hints on how to interpret the results.
To view the help for arcstat.py:
arcstat.py -h
Usage: arcstat [-hvx] [-f fields] [-o file] [-s string] [interval [count]]
-h: Print this help message
-v: List all possible field headers and definitions
-x: Print extended stats
26.4. arcstat
309
FreeNAS® 11.0-U4 User Guide, Release 11.0
-f: Specify specific fields to print (see -v)
-o: Redirect output to the specified file
-s: Override default field separator with custom character or string
Examples:
arcstat -o /tmp/a.log 2 10
arcstat -s "," -o /tmp/a.log 2 10
arcstat -v
arcstat -f time,hit%,dh%,ph%,mh% 1
To view ARC statistics in real time, specify an interval and a count. This command will display every 1 second
for a count of five.
arcstat.py 1 5
time read
06:19:03
7
06:19:04
257
06:19:05
193
06:19:06
193
06:19:07
255
miss
0
0
0
0
0
miss%
0
0
0
0
0
dmis
0
0
0
0
0
dm%
0
0
0
0
0
pmis
0
0
0
0
0
pm%
0
0
0
0
0
mmis
0
0
0
0
0
mm%
0
0
0
0
0
arcsz
153M
153M
153M
153M
153M
c
6.6G
6.6G
6.6G
6.6G
6.6G
Table 26.1 briefly describes the columns in the output.
Table 26.1: arcstat Column Descriptions
Column
read
miss
miss%
dmis
dm%
pmis
pm%
mmis
mm%
arcsz
c
Description
total ARC accesses/second
ARC misses/second
ARC miss percentage
demand data misses/second
demand data miss percentage
prefetch misses per second
prefetch miss percentage
metadata misses/second
metadata miss percentage
arc size
arc target size
To receive a summary of statistics, use:
arcsummary.py
System Memory:
2.36%
93.40
MiB Active,
8.38%
330.89 MiB Wired,
80.16% 3.09
GiB Free,
Real Installed:
Real Available:
Real Managed:
Logical Total:
Logical Used:
Logical Free:
Kernel Memory:
Data:
Text:
Kernel Memory Map:
310
8.95%
0.15%
0.00%
99.31%
97.10%
13.93%
86.07%
69.91%
30.09%
353.43
5.90
0
4.00
3.97
3.86
4.00
570.77
3.44
87.62
61.25
26.37
3.86
MiB Inact
MiB Cache
Bytes Gap
GiB
GiB
GiB
GiB
MiB
GiB
MiB
MiB
MiB
GiB
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
ARC
ARC
ARC
ARC
ARC
ARC
ZFS
Size:
Free:
Summary: (HEALTHY)
Storage pool Version:
Filesystem Version:
Memory Throttle Count:
Misc:
Deleted:
Mutex Misses:
Evict Skips:
Size:
Target Size: (Adaptive)
Min Size (Hard Limit):
Max Size (High Water):
Size Breakdown:
Recently Used Cache Size:
Frequently Used Cache Size:
Hash Breakdown:
Elements Max:
Elements Current:
Collisions:
Chain Max:
Chains:
Total accesses:
Cache Hit Ratio:
Cache Miss Ratio:
Actual Hit Ratio:
Data Demand Efficiency:
CACHE HITS BY CACHE LIST:
Anonymously Used:
Most Recently Used:
Most Frequently Used:
Most Recently Used Ghost:
Most Frequently Used Ghost:
CACHE HITS BY DATA TYPE:
Demand Data:
Prefetch Data:
Demand Metadata:
Prefetch Metadata:
CACHE MISSES BY DATA TYPE:
Demand Data:
Prefetch Data:
Demand Metadata:
Prefetch Metadata:
Tunable (sysctl):
kern.maxusers
vm.kmem_size
vm.kmem_size_scale
vm.kmem_size_min
vm.kmem_size_max
vfs.zfs.vol.unmap_enabled
vfs.zfs.vol.mode
vfs.zfs.sync_pass_rewrite
vfs.zfs.sync_pass_dont_compress
vfs.zfs.sync_pass_deferred_free
vfs.zfs.zio.exclude_metadata
vfs.zfs.zio.use_uma
vfs.zfs.cache_flush_disable
26.4. arcstat
5.11%
94.89%
201.70
3.66
MiB
GiB
5000
5
0
8
0
0
5.83%
170.45 MiB
100.00% 2.86
GiB
12.50% 365.69 MiB
8:1
2.86
GiB
50.00%
50.00%
1.43
1.43
GiB
GiB
5.90k
100.00% 5.90k
72
1
23
954.06k
99.18%
0.82%
98.84%
99.20%
946.25k
7.81k
943.00k
458.77k
0.34%
3.73%
95.92%
0.00%
0.00%
3.25k
35.33k
907.67k
0
0
48.10%
0.00%
51.56%
0.34%
455.10k
0
487.90k
3.25k
46.93%
0.00%
49.76%
3.30%
3.66k
0
3.88k
258
590
4141375488
1
0
1319413950874
1
2
2
5
2
0
1
0
311
FreeNAS® 11.0-U4 User Guide, Release 11.0
vfs.zfs.zil_replay_disable
0
vfs.zfs.version.zpl
5
vfs.zfs.version.spa
5000
vfs.zfs.version.acl
1
vfs.zfs.version.ioctl
5
vfs.zfs.debug
0
vfs.zfs.super_owner
0
vfs.zfs.min_auto_ashift
9
vfs.zfs.max_auto_ashift
13
vfs.zfs.vdev.write_gap_limit
4096
vfs.zfs.vdev.read_gap_limit
32768
vfs.zfs.vdev.aggregation_limit
131072
vfs.zfs.vdev.trim_max_active
64
vfs.zfs.vdev.trim_min_active
1
vfs.zfs.vdev.scrub_max_active
2
vfs.zfs.vdev.scrub_min_active
1
vfs.zfs.vdev.async_write_max_active
10
vfs.zfs.vdev.async_write_min_active
1
vfs.zfs.vdev.async_read_max_active
3
vfs.zfs.vdev.async_read_min_active
1
vfs.zfs.vdev.sync_write_max_active
10
vfs.zfs.vdev.sync_write_min_active
10
vfs.zfs.vdev.sync_read_max_active
10
vfs.zfs.vdev.sync_read_min_active
10
vfs.zfs.vdev.max_active
1000
vfs.zfs.vdev.async_write_active_max_dirty_percent60
vfs.zfs.vdev.async_write_active_min_dirty_percent30
vfs.zfs.vdev.mirror.non_rotating_seek_inc1
vfs.zfs.vdev.mirror.non_rotating_inc
0
vfs.zfs.vdev.mirror.rotating_seek_offset1048576
vfs.zfs.vdev.mirror.rotating_seek_inc
5
vfs.zfs.vdev.mirror.rotating_inc
0
vfs.zfs.vdev.trim_on_init
1
vfs.zfs.vdev.larger_ashift_minimal
0
vfs.zfs.vdev.bio_delete_disable
0
vfs.zfs.vdev.bio_flush_disable
0
vfs.zfs.vdev.cache.bshift
16
vfs.zfs.vdev.cache.size
0
vfs.zfs.vdev.cache.max
16384
vfs.zfs.vdev.metaslabs_per_vdev
200
vfs.zfs.vdev.trim_max_pending
10000
vfs.zfs.txg.timeout
5
vfs.zfs.trim.enabled
1
vfs.zfs.trim.max_interval
1
vfs.zfs.trim.timeout
30
vfs.zfs.trim.txg_delay
32
vfs.zfs.space_map_blksz
4096
vfs.zfs.spa_slop_shift
5
vfs.zfs.spa_asize_inflation
24
vfs.zfs.deadman_enabled
1
vfs.zfs.deadman_checktime_ms
5000
vfs.zfs.deadman_synctime_ms
1000000
vfs.zfs.recover
0
vfs.zfs.spa_load_verify_data
1
vfs.zfs.spa_load_verify_metadata
1
vfs.zfs.spa_load_verify_maxinflight
10000
vfs.zfs.check_hostid
1
vfs.zfs.mg_fragmentation_threshold
85
312
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
vfs.zfs.mg_noalloc_threshold
0
vfs.zfs.condense_pct
200
vfs.zfs.metaslab.bias_enabled
1
vfs.zfs.metaslab.lba_weighting_enabled 1
vfs.zfs.metaslab.fragmentation_factor_enabled1
vfs.zfs.metaslab.preload_enabled
1
vfs.zfs.metaslab.preload_limit
3
vfs.zfs.metaslab.unload_delay
8
vfs.zfs.metaslab.load_pct
50
vfs.zfs.metaslab.min_alloc_size
33554432
vfs.zfs.metaslab.df_free_pct
4
vfs.zfs.metaslab.df_alloc_threshold
131072
vfs.zfs.metaslab.debug_unload
0
vfs.zfs.metaslab.debug_load
0
vfs.zfs.metaslab.fragmentation_threshold70
vfs.zfs.metaslab.gang_bang
16777217
vfs.zfs.free_bpobj_enabled
1
vfs.zfs.free_max_blocks
18446744073709551615
vfs.zfs.no_scrub_prefetch
0
vfs.zfs.no_scrub_io
0
vfs.zfs.resilver_min_time_ms
3000
vfs.zfs.free_min_time_ms
1000
vfs.zfs.scan_min_time_ms
1000
vfs.zfs.scan_idle
50
vfs.zfs.scrub_delay
4
vfs.zfs.resilver_delay
2
vfs.zfs.top_maxinflight
32
vfs.zfs.delay_scale
500000
vfs.zfs.delay_min_dirty_percent
60
vfs.zfs.dirty_data_sync
67108864
vfs.zfs.dirty_data_max_percent
10
vfs.zfs.dirty_data_max_max
4294967296
vfs.zfs.dirty_data_max
426512793
vfs.zfs.max_recordsize
1048576
vfs.zfs.zfetch.array_rd_sz
1048576
vfs.zfs.zfetch.max_distance
8388608
vfs.zfs.zfetch.min_sec_reap
2
vfs.zfs.zfetch.max_streams
8
vfs.zfs.prefetch_disable
1
vfs.zfs.mdcomp_disable
0
vfs.zfs.nopwrite_enabled
1
vfs.zfs.dedup.prefetch
1
vfs.zfs.l2c_only_size
0
vfs.zfs.mfu_ghost_data_lsize
0
vfs.zfs.mfu_ghost_metadata_lsize
0
vfs.zfs.mfu_ghost_size
0
vfs.zfs.mfu_data_lsize
26300416
vfs.zfs.mfu_metadata_lsize
1780736
vfs.zfs.mfu_size
29428736
vfs.zfs.mru_ghost_data_lsize
0
vfs.zfs.mru_ghost_metadata_lsize
0
vfs.zfs.mru_ghost_size
0
vfs.zfs.mru_data_lsize
122090496
vfs.zfs.mru_metadata_lsize
2235904
vfs.zfs.mru_size
139389440
vfs.zfs.anon_data_lsize
0
vfs.zfs.anon_metadata_lsize
0
vfs.zfs.anon_size
163840
26.4. arcstat
313
FreeNAS® 11.0-U4 User Guide, Release 11.0
vfs.zfs.l2arc_norw
vfs.zfs.l2arc_feed_again
vfs.zfs.l2arc_noprefetch
vfs.zfs.l2arc_feed_min_ms
vfs.zfs.l2arc_feed_secs
vfs.zfs.l2arc_headroom
vfs.zfs.l2arc_write_boost
vfs.zfs.l2arc_write_max
vfs.zfs.arc_meta_limit
vfs.zfs.arc_free_target
vfs.zfs.arc_shrink_shift
vfs.zfs.arc_average_blocksize
vfs.zfs.arc_min
vfs.zfs.arc_max
1
1
1
200
1
2
8388608
8388608
766908416
7062
7
8192
383454208
3067633664
When reading the tunable values, 0 means no, 1 typically means yes, and any other number represents a
value. To receive a brief description of a “sysctl” value, use sysctl -d. For example:
sysctl -d vfs.zfs.zio.use_uma
vfs.zfs.zio.use_uma: Use uma(9) for ZIO allocations
The ZFS tunables require a fair understanding of how ZFS works, meaning that you will be reading man
pages and searching for the meaning of acronyms you are unfamiliar with. Do not change a tunable’s
value without researching it first. If the tunable takes a numeric value (rather than 0 for no or 1 for yes),
do not make one up. Instead, research examples of beneficial values that match your workload.
If you decide to change any of the ZFS tunables, continue to monitor the system to determine the effect of
the change. It is recommended that you test your changes first at the command line using sysctl. For
example, to disable pre-fetch (i.e. change disable to 1 or yes):
sysctl vfs.zfs.prefetch_disable=1
vfs.zfs.prefetch_disable: 0 -> 1
The output will indicate the old value followed by the new value. If the change is not beneficial, change it
back to the original value. If the change turns out to be beneficial, you can make it permanent by creating a
sysctl using the instructions in Tunables (page 67).
26.5 tw_cli
FreeNAS® includes the tw_cli command line utility for providing controller, logical unit, and
drive management for AMCC/3ware ATA RAID Controllers.
The supported models are listed
in the man pages for the twe(4) (http://www.freebsd.org/cgi/man.cgi?query=twe) and twa(4)
(http://www.freebsd.org/cgi/man.cgi?query=twa) drivers.
Before using this command, read its man page (http://www.cyberciti.biz/files/tw_cli.8.html) as it describes
the terminology and provides some usage examples.
If you type tw_cli in Shell, the prompt will change, indicating that you have entered interactive mode
where you can run all sorts of maintenance commands on the controller and its arrays.
Alternately, you can specify one command to run. For example, to view the disks in the array:
tw_cli /c0 show
Unit
UnitType
Status %RCmpl %V/I/M Stripe Size(GB)
Cache
AVrfy
-----------------------------------------------------------------------------u0
RAID-6
OK
256K
5587.88
RiW
ON
314
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
u1
u2
SPARE
RAID-10
OK
OK
-
-
256K
931.505
1862.62
RiW
OFF
ON
VPort Status
Unit
Size
Type
Phy Encl-Slot
Model
-----------------------------------------------------------------------------p8
OK
u0
931.51 GB SAS
/c0/e0/slt0
SEAGATE ST31000640SS
p9
OK
u0
931.51 GB SAS
/c0/e0/slt1
SEAGATE ST31000640SS
p10
OK
u0
931.51 GB SAS
/c0/e0/slt2
SEAGATE ST31000640SS
p11
OK
u0
931.51 GB SAS
/c0/e0/slt3
SEAGATE ST31000640SS
p12
OK
u0
931.51 GB SAS
/c0/e0/slt4
SEAGATE ST31000640SS
p13
OK
u0
931.51 GB SAS
/c0/e0/slt5
SEAGATE ST31000640SS
p14
OK
u0
931.51 GB SAS
/c0/e0/slt6
SEAGATE ST31000640SS
p15
OK
u0
931.51 GB SAS
/c0/e0/slt7
SEAGATE ST31000640SS
p16
OK
u1
931.51 GB SAS
/c0/e0/slt8
SEAGATE ST31000640SS
p17
OK
u2
931.51 GB SATA /c0/e0/slt9
ST31000340NS
p18
OK
u2
931.51 GB SATA /c0/e0/slt10
ST31000340NS
p19
OK
u2
931.51 GB SATA /c0/e0/slt11
ST31000340NS
p20
OK
u2
931.51 GB SATA /c0/e0/slt15
ST31000340NS
Name
OnlineState
BBUReady
Status Volt
Temp
Hours
LastCapTest
--------------------------------------------------------------------------bbu
On
Yes
OK
OK
OK
212
03-Jan-2012
Or, to review the event log:
tw_cli /c0 show events
Ctl
Date
Severity
AEN Message
-----------------------------------------------------------------------------c0
[Thu Feb 23 2012 14:01:15]
INFO
Battery charging started
c0
[Thu Feb 23 2012 14:03:02]
INFO
Battery charging completed
c0
[Sat Feb 25 2012 00:02:18]
INFO
Verify started: unit=0
c0
[Sat Feb 25 2012 00:02:18]
INFO
Verify started: unit=2,
˓→subunit=0
c0
[Sat Feb 25 2012 00:02:18]
INFO
Verify started: unit=2,
˓→subunit=1
c0
[Sat Feb 25 2012 03:49:35]
INFO
Verify completed: unit=2,
˓→subunit=0
c0
[Sat Feb 25 2012 03:51:39]
INFO
Verify completed: unit=2,
˓→subunit=1
c0
[Sat Feb 25 2012 21:55:59]
INFO
Verify completed: unit=0
c0
[Thu Mar 01 2012 13:51:09]
INFO
Battery health check started
c0
[Thu Mar 01 2012 13:51:09]
INFO
Battery health check completed
c0
[Thu Mar 01 2012 13:51:09]
INFO
Battery charging started
c0
[Thu Mar 01 2012 13:53:03]
INFO
Battery charging completed
c0
[Sat Mar 03 2012 00:01:24]
INFO
Verify started: unit=0
c0
[Sat Mar 03 2012 00:01:24]
INFO
Verify started: unit=2,
˓→subunit=0
c0
[Sat Mar 03 2012 00:01:24]
INFO
Verify started: unit=2,
˓→subunit=1
c0
[Sat Mar 03 2012 04:04:27]
INFO
Verify completed: unit=2,
˓→subunit=0
c0
[Sat Mar 03 2012 04:06:25]
INFO
Verify completed: unit=2,
˓→subunit=1
c0
[Sat Mar 03 2012 16:22:05]
INFO
Verify completed: unit=0
c0
[Thu Mar 08 2012 13:41:39]
INFO
Battery charging started
c0
[Thu Mar 08 2012 13:43:42]
INFO
Battery charging completed
c0
[Sat Mar 10 2012 00:01:30]
INFO
Verify started: unit=0
c0
[Sat Mar 10 2012 00:01:30]
INFO
Verify started: unit=2,
˓→subunit=0
26.5. tw_cli
315
FreeNAS® 11.0-U4 User Guide, Release 11.0
c0
[Sat
subunit=1
c0
[Sat
˓→subunit=0
c0
[Sat
˓→subunit=1
c0
[Sat
Mar 10 2012 00:01:30]
INFO
Verify started: unit=2,
Mar 10 2012 05:06:38]
INFO
Verify completed: unit=2,
Mar 10 2012 05:08:57]
INFO
Verify completed: unit=2,
Mar 10 2012 15:58:15]
INFO
Verify completed: unit=0
˓→
If you add some disks to the array and they are not showing up in the GUI, try running this command:
tw_cli /c0 rescan
Use the drives to create units and export them to the operating system. When finished, run camcontrol
rescan all and they should now be available in the FreeNAS® GUI.
This forum post (https://forums.freenas.org/index.php?threads/3ware-drive-monitoring.13835/) contains a
handy wrapper script that will notify you of errors.
26.6 MegaCli
MegaCli is the command line interface for the Avago :MegaRAID SAS family of RAID controllers. FreeNAS®
also includes the mfiutil(8) (http://www.freebsd.org/cgi/man.cgi?query=mfiutil) utility which can be used to
configure and manage connected storage devices.
The MegaCli command is quite complex with several dozen options. The commands demonstrated in the
Emergency Cheat Sheet (http://tools.rapidsoft.de/perc/perc-cheat-sheet.html) can get you started.
26.7 freenas-debug
The FreeNAS® GUI provides an option to save debugging information to a text file using System →
Advanced → Save Debug. This debugging information is created by the freenas-debug command
line utility and a copy of the information is saved to /var/tmp/fndebug.
This command can be run manually from Shell (page 288) to gather specific debugging information. To see
a usage explanation listing all options, run the command without any options:
freenas-debug
Usage: /usr/local/bin/freenas-debug <options>
Where options are:
-e Email debug log to this comma-delimited list of email addresses
-A Dump all debug information
-a
-f
-c
-D
-d
-g
-G
-h
-I
-i
-j
-l
316
Dump
Dump
Dump
Dump
Dump
Dump
Dump
Dump
Dump
Dump
Dump
Dump
Active Directory Configuration
AFP Configuration
(AD|LDAP) Cache
Domain Controller Configuration
DTrace Scripts
GEOM Configuration
Grub Configuration
Hardware Configuration
IPMI Configuration
iSCSI Configuration
Jail Information
LDAP Configuration
Chapter 26. Command Line Utilities
FreeNAS® 11.0-U4 User Guide, Release 11.0
-T
-n
-N
-S
-C
-s
-y
-t
-v
-z
Loader Configuration Information
Dump Network Configuration
Dump NFS Configuration
Dump SMART Information
Dump SMB Configuration
Dump SSL Configuration
Dump Sysctl Configuration
Dump System Information
Dump Boot System File Verification Status and Inconsistencies
Dump ZFS Configuration
Individual tests can be run alone. For example, when troubleshooting an Active Directory configuration,
use:
freenas-debug -a
To collect the output of every module, use -A:
freenas-debug -A
26.8 tmux
tmux is a terminal multiplexer which enables a number of :terminals to be created, accessed, and controlled
from a single :screen. tmux is an alternative to GNU screen. Similar to screen, tmux can be detached from
a screen and continue running in the background, then later reattached. Unlike Shell (page 288), tmux
allows you to have access to a command prompt while still providing access to the graphical administration
screens.
To start a session, simply type tmux. As seen in Figure 26.2, a new session with a single window opens with
a status line at the bottom of the screen. This line shows information on the current session and is used to
enter interactive commands.
26.8. tmux
317
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 26.2: tmux Session
To create a second window, press Ctrl+b then ". To close a window, type exit within the window.
tmux(1) (http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/./man1/tmux.1?query=tmux) lists all
of the key bindings and commands for interacting with tmux windows and sessions.
If you close Shell (page 288) while tmux is running, it will detach its session. The next time you open Shell,
run tmux attach to return to the previous session. To leave the tmux session entirely, type exit. If you
have multiple windows running, you will need to exit out of each first.
These resources provide more information about using tmux:
• A tmux Crash Course (https://robots.thoughtbot.com/a-tmux-crash-course)
• TMUX - The
multiplexer/)
Terminal
Multiplexer
(http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-
26.9 Dmidecode
Dmidecode reports hardware information as reported by the system BIOS. Dmidecode does not
scan the hardware, it only reports what the BIOS told it to. A sample output can be seen here
(http://www.nongnu.org/dmidecode/sample/dmidecode.txt).
To view the BIOS report, type the command with no arguments:
dmidecode | more
dmidecode(8) (http://linux.die.net/man/8/dmidecode) describes the supported strings and types.
318
Chapter 26. Command Line Utilities
CHAPTER
TWENTYSEVEN
CONTRIBUTING TO FREENAS®
FreeNAS® is an open source community, relying on the input and expertise of its users to help grow and
improve FreeNAS® . When you take time to assist the community, your contributions benefit everyone who
uses FreeNAS® .
This section describes some areas of participation to get you started. It is by no means an exhaustive list. If
you have an idea that you think would benefit the FreeNAS® community, bring it up on one of the resources
mentioned in Support Resources (page 297).
This section demonstrates how you can:
• Help with Translation (page 319)
27.1 Translation
Not everyone speaks English, and having a complete translation of the user interface into native languages
can make FreeNAS® much more useful to communities around the world.
FreeNAS® uses Weblate (https://weblate.org/) to manage the translation of text shown in the FreeNAS®
graphical administrative interface. Weblate provides an easy-to-use web-based editor and commenting
system, making it possible for individuals to assist with translation or comment on existing translations.
To see the status of translations, open http://weblate.trueos.org/projects/freenas/, as shown in Figure 27.1.
Fig. 27.1: FreeNAS® Translation System
319
FreeNAS® 11.0-U4 User Guide, Release 11.0
To assist with translating FreeNAS® , create an account by clicking the Register button. Enter the information requested, then a confirmation email will be sent. Follow the link in the email to set a password and
complete the account creation. The Dashboard screen is shown after logging in:
Fig. 27.2: Weblate Dashboard
Click Manage your languages to choose languages for translation. Select languages, then click Save. Click the
Dashboard link at the top of the screen to go back to the dashboard, then choose Your languages from the
drop-down menu:
Fig. 27.3: Selected Languages
Projects are a collection of text to be translated. In this example, the Django and DjangoJS projects have both
been partially translated into Spanish. Click one of the entries under Project to help translate that project.
The Overview screen shows the current translation status along with categories of translatable strings:
320
Chapter 27. Contributing to FreeNAS®
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 27.4: Translation Overview
Click on a category of string, like Strings needing action, to see the translation screen:
27.1. Translation
321
FreeNAS® 11.0-U4 User Guide, Release 11.0
Fig. 27.5: Translate Strings
Enter translations here, clicking Save to save the work. The controls at the top of the screen can be used
to skip forward and back in the list of strings to be translated. Click Dashboard at the top of the screen to
return to the Dashboard.
All assistance with translations helps to benefit the FreeNAS® community. Thank you!
322
Chapter 27. Contributing to FreeNAS®
CHAPTER
TWENTYEIGHT
ZFS PRIMER
ZFS is an advanced, modern filesystem that was specifically designed to provide features not available in
traditional UNIX filesystems. It was originally developed at Sun with the intent to open source the filesystem so that it could be ported to other operating systems. After the Oracle acquisition of Sun, some of the
original ZFS engineers founded OpenZFS (http://open-zfs.org/wiki/Main_Page) to provide continued, collaborative development of the open source version. To differentiate itself from Oracle ZFS version numbers,
OpenZFS uses feature flags. Feature flags are used to tag features with unique names in order to provide
portability between OpenZFS implementations running on different platforms, as long as all of the feature
flags enabled on the ZFS pool are supported by both platforms. FreeNAS® uses OpenZFS and each new
version of FreeNAS® keeps up-to-date with the latest feature flags and OpenZFS bug fixes.
Here is an overview of the features provided by ZFS:
ZFS is a transactional,
Copy-On-Write (COW) (https://en.wikipedia.org/wiki/ZFS#Copy-onwrite_transactional_model) filesystem. For each write request, a copy is made of the associated disk
blocks and all changes are made to the copy rather than to the original blocks. When the write is complete,
all block pointers are changed to point to the new copy. This means that ZFS always writes to free space,
most writes are sequential, and old versions of files are not unlinked until a complete new version has
been written successfully. ZFS has direct access to disks and bundles multiple read and write requests into
transactions. Most filesystems cannot do this, as they only have access to disk blocks. A transaction either
completes or fails, meaning there will never be a write-hole (https://blogs.oracle.com/bonwick/entry/raid_z)
and a filesystem checker utility is not necessary. Because of the transactional design, as additional storage
capacity is added, it becomes immediately available for writes. To rebalance the data, one can copy it to
re-write the existing data across all available disks. As a 128-bit filesystem, the maximum filesystem or file
size is 16 exabytes.
ZFS was designed to be a self-healing filesystem. As ZFS writes data, it creates a checksum for each disk
block it writes. As ZFS reads data, it validates the checksum for each disk block it reads. Media errors or
“bit rot” can cause data to change, and the checksum no longer matches. When ZFS identifies a disk block
checksum error on a pool that is mirrored or uses RAIDZ, it replaces the corrupted data with the correct
data. Since some disk blocks are rarely read, regular scrubs should be scheduled so that ZFS can read all
of the data blocks to validate their checksums and correct any corrupted blocks. While multiple disks are
required in order to provide redundancy and data correction, ZFS will still provide data corruption detection
to a system with one disk. FreeNAS® automatically schedules a monthly scrub for each ZFS pool and the
results of the scrub are displayed by selecting the Volume (page 108) then clicking the Volume Status button.
Checking scrub results can provide an early indication of potential disk problems.
Unlike traditional UNIX filesystems, it is not necessary to define partition sizes when filesystems are
created. Instead, a group of disks, known as a vdev, are built into a ZFS pool. Filesystems are created from
the pool as needed. As more capacity is needed, identical vdevs can be striped into the pool. In FreeNAS® ,
Volume Manager (page 108) can be used to create or extend ZFS pools. After a pool is created, it can be
divided into dynamically-sized datasets or fixed-size zvols as needed. Datasets can be used to optimize
storage for the type of data being stored as permissions and properties such as quotas and compression
323
FreeNAS® 11.0-U4 User Guide, Release 11.0
can be set on a per-dataset level. A zvol is essentially a raw, virtual block device which can be used for
applications that need raw-device semantics such as iSCSI device extents.
ZFS supports real-time data compression. Compression happens when a block is written to disk, but only
if the written data will benefit from compression. When a compressed block is accessed, it is automatically
decompressed. Since compression happens at the block level, not the file level, it is transparent to any
applications accessing the compressed data. By default, ZFS pools made using FreeNAS® version 9.2.1 or
later will use the recommended LZ4 compression algorithm.
ZFS provides low-cost, instantaneous snapshots of the specified pool, dataset, or zvol. Due to COW,
snapshots initially take no additional space. The size of a snapshot increases over time as changes to the
files in the snapshot are written to disk. Snapshots can be used to provide a copy of data at the point in
time the snapshot was created. When a file is deleted, its disk blocks are added to the free list; however,
the blocks for that file in any existing snapshots are not added to the free list until all referencing snapshots
are removed. This makes snapshots a clever way to keep a history of files, useful for recovering an older
copy of a file or a deleted file. For this reason, many administrators take snapshots often (e.g., every 15
minutes), store them for a period of time (e.g., for a month), and store them on another system. Such a
strategy allows the administrator to roll the system back to a specific time. If there is a catastrophic loss, an
off-site snapshot can restore the system up to the last snapshot interval (e.g., within 15 minutes of the data
loss). Snapshots are stored locally but can also be replicated to a remote ZFS pool. During replication, ZFS
does not do a byte-for-byte copy but instead converts a snapshot into a stream of data. This design means
that the ZFS pool on the receiving end does not need to be identical and can use a different RAIDZ level,
volume size, or compression settings.
ZFS boot environments provide a method for recovering from a failed upgrade. In FreeNAS® , a snapshot of the dataset the operating system resides on is automatically taken before an upgrade or a system
update. This saved boot environment is automatically added to the GRUB boot loader. Should the upgrade
or configuration change fail, simply reboot and select the previous boot environment from the boot menu.
Users can also create their own boot environments in System → Boot as needed, for example before
making configuration changes. This way, the system can be rebooted into a snapshot of the system that did
not include the new configuration changes.
ZFS
provides
a
write
cache
in
RAM
as
well
as
a
ZFS
Intent
Log
(ZIL
(https://blogs.oracle.com/realneel/entry/the_zfs_intent_log)). The ZIL is a storage area that temporarily
holds *synchronous* writes until they are written to the ZFS pool (https://pthree.org/2013/04/19/zfsadministration-appendix-a-visualizing-the-zfs-intent-log/). Adding a fast (low-latency), power-protected SSD
as a SLOG (Separate Log) device permits much higher performance. This is a necessity for NFS over ESXi,
and highly recommended for database servers or other applications that depend on synchronous writes.
More detail on SLOG benefits and usage is available in these blog and forum posts:
• The ZFS ZIL and SLOG Demystified (http://www.freenas.org/blog/zfs-zil-and-slog-demystified/)
• Some insights into SLOG/ZIL with ZFS on FreeNAS® (https://forums.freenas.org/index.php?threads/someinsights-into-slog-zil-with-zfs-on-freenas.13633/)
• ZFS Intent Log (http://nex7.blogspot.com/2013/04/zfs-intent-log.html)
Synchronous writes are relatively rare with SMB, AFP, and iSCSI, and adding a SLOG to improve
performance of these protocols only makes sense in special cases. The zilstat utility can be
run from Shell (page 288) to determine if the system will benefit from a SLOG. See this website
(http://www.richardelling.com/Home/scripts-and-programs-1/zilstat) for usage information.
ZFS currently uses 16 GB of space for SLOG. Larger SSDs can be installed, but the extra space will not
be used. SLOG devices cannot be shared between pools. Each pool requires a separate SLOG device.
Bandwidth and throughput limitations require that a SLOG device must only be used for this single purpose.
Do not attempt to add other caching functions on the same SSD, or performance will suffer.
In mission-critical systems, a mirrored SLOG device is highly recommended. Mirrored SLOG devices are
required for ZFS pools at ZFS version 19 or earlier. ZFS pool version can be checked from the Shell (page 288)
324
Chapter 28. ZFS Primer
FreeNAS® 11.0-U4 User Guide, Release 11.0
with zpool get version poolname. A version value of - means the ZFS pool is version 5000 (also
known as Feature Flags) or later.
ZFS provides a read cache in RAM, known as the ARC, which reduces read latency. FreeNAS® adds ARC
stats to top(1) (http://www.freebsd.org/cgi/man.cgi?query=top) and includes the arc_summary.py and
arcstat.py tools for monitoring the efficiency of the ARC. If an SSD is dedicated as a cache device, it
is known as an L2ARC (https://blogs.oracle.com/brendan/entry/test). Additional read data is cached here,
which can increase random read performance. L2ARC does not reduce the need for sufficient RAM. In fact,
L2ARC needs RAM to function. If there is not enough RAM for a adequately-sized ARC, adding an L2ARC will
not increase performance. Performance actually decreases in most cases, potentially causing system instability. RAM is always faster than disks, so always add as much RAM as possible before considering whether
the system can benefit from an L2ARC device.
When applications perform large amounts of random reads on a dataset small enough to fit into L2ARC,
read performance can be increased by adding a dedicated cache device. SSD cache devices only help if the
active data is larger than system RAM but small enough that a significant percentage fits on the SSD. As
a general rule, L2ARC should not be added to a system with less than 32 GB of RAM, and the size of an
L2ARC should not exceed ten times the amount of RAM. In some cases, it may be more efficient to have
two separate pools: one on SSDs for active data, and another on hard drives for rarely used content. After
adding an L2ARC device, monitor its effectiveness using tools such as arcstat. To increase the size of an
existing L2ARC, stripe another cache device with it. The GUI will always stripe L2ARC, not mirror it, as the
contents of L2ARC are recreated at boot. Failure of an individual SSD from an L2ARC pool will not affect the
integrity of the pool, but may have an impact on read performance, depending on the workload and the
ratio of dataset size to cache size. Note that dedicated L2ARC devices cannot be shared between ZFS pools.
ZFS was designed to provide redundancy while addressing some of the inherent limitations of hardware RAID such as the write-hole and corrupt data written over time before the hardware controller provides an alert. ZFS provides three levels of redundancy, known as RAIDZ, where the number after the RAIDZ
indicates how many disks per vdev can be lost without losing data. ZFS also supports mirrors, with no restrictions on the number of disks in the mirror. ZFS was designed for commodity disks so no RAID controller
is needed. While ZFS can also be used with a RAID controller, it is recommended that the controller be put
into JBOD mode so that ZFS has full control of the disks.
When determining the type of ZFS redundancy to use, consider whether the goal is to maximize disk space
or performance:
• RAIDZ1 maximizes disk space and generally performs well when data is written and read in large
chunks (128K or more).
• RAIDZ2 offers better data availability and significantly better mean time to data loss (MTTDL) than
RAIDZ1.
• A mirror consumes more disk space but generally performs better with small random reads. For
better performance, a mirror is strongly favored over any RAIDZ, particularly for large, uncacheable,
random read loads.
• Using more than 12 disks per vdev is not recommended. The recommended number of disks per vdev
is between 3 and 9. With more disks, use multiple vdevs.
• Some older ZFS documentation recommends that a certain number of disks is needed for each type
of RAIDZ in order to achieve optimal performance. On systems using LZ4 compression, which is
the default for FreeNAS® 9.2.1 and higher, this is no longer true. See ZFS RAIDZ stripe width, or:
How I Learned to Stop Worrying and Love RAIDZ (http://blog.delphix.com/matt/2014/06/06/zfs-stripewidth/) for details.
These resources can also help determine the RAID configuration best suited to your storage needs:
• Getting the Most out of ZFS Pools (https://forums.freenas.org/index.php?threads/getting-the-mostout-of-zfs-pools.16/)
325
FreeNAS® 11.0-U4 User Guide, Release 11.0
• A Closer Look at ZFS, Vdevs and Performance (http://constantin.glez.de/blog/2010/06/closer-look-zfsvdevs-and-performance)
Warning: RAID AND DISK REDUNDANCY ARE NOT A SUBSTITUTE FOR A RELIABLE BACKUP STRATEGY.
BAD THINGS HAPPEN AND A GOOD BACKUP STRATEGY IS STILL REQUIRED TO PROTECT VALUABLE DATA.
See Periodic Snapshot Tasks (page 134) and Replication Tasks (page 136) to use replicated ZFS snapshots
as part of a backup strategy.
ZFS manages devices. When an individual drive in a mirror or RAIDZ fails and is replaced by the user,
ZFS adds the replacement device to the vdev and copies redundant data to it in a process called resilvering.
Hardware RAID controllers usually have no way of knowing which blocks were in use and must copy every
block to the new device. ZFS only copies blocks that are in use, reducing the time it takes to rebuild the
vdev. Resilvering is also interruptable. After an interruption, resilvering resumes where it left off rather
than starting from the beginning.
While ZFS provides many benefits, there are some caveats:
• At 90% capacity, ZFS switches from performance- to space-based optimization, which has massive
performance implications. For maximum write performance and to prevent problems with drive replacement, add more capacity before a pool reaches 80%. If you are using iSCSI, it is recommended
to not let the pool go over 50% capacity to prevent fragmentation issues.
• When considering the number of disks to use per vdev, consider the size of the disks and the amount
of time required for resilvering, which is the process of rebuilding the vdev. The larger the size of the
vdev, the longer the resilvering time. When replacing a disk in a RAIDZ, it is possible that another disk
will fail before the resilvering process completes. If the number of failed disks exceeds the number
allowed per vdev for the type of RAIDZ, the data in the pool will be lost. For this reason, RAIDZ1 is not
recommended for drives over 1 TB in size.
• It is recommended to use drives of equal sizes when creating a vdev. While ZFS can create a vdev
using disks of differing sizes, its capacity will be limited by the size of the smallest disk.
For those new to ZFS, the Wikipedia entry on ZFS (https://en.wikipedia.org/wiki/Zfs) provides an excellent
starting point to learn more about its features. These resources are also useful for reference:
• FreeBSD ZFS Tuning Guide (https://wiki.FreeBSD.org/ZFSTuningGuide)
• ZFS Administration Guide (http://docs.oracle.com/cd/E19253-01/819-5461/index.html)
• Becoming a ZFS Ninja (video) (https://blogs.oracle.com/video/entry/becoming_a_zfs_ninja)
• Slideshow explaining VDev,
zpool,
ZIL and L2ARC and other newbie mistakes!
(https://forums.freenas.org/index.php?threads/slideshow-explaining-vdev-zpool-zil-and-l2arc-fornoobs.7775/)
• A Crash Course on ZFS (http://www.bsdnow.tv/tutorials/zfs)
• ZFS: The Last Word in File Systems - Part 1 (video) (https://www.youtube.com/watch?v=uT2i2ryhCio)
• The Zettabyte Filesystem (https://www.youtube.com/watch?v=ptY6-K78McY)
326
Chapter 28. ZFS Primer
CHAPTER
TWENTYNINE
VAAI
VMware’s vStorage APIs for Array Integration, or VAAI, allows storage tasks such as large data moves to be
offloaded from the virtualization hardware to the storage array. These operations are performed locally on
the NAS without transferring bulk data over the network.
29.1 VAAI for iSCSI
VAAI for iSCSI supports these operations:
• Atomic Test and Set (ATS) allows multiple initiators to synchronize LUN access in a fine-grained manner
rather than locking the whole LUN and preventing other hosts from accessing the same LUN simultaneously.
• Clone Blocks (XCOPY) copies disk blocks on the NAS. Copies occur locally rather than over the network.
The operation is similar to Microsoft ODX (https://technet.microsoft.com/en-us/library/hh831628).
• LUN Reporting allows a hypervisor to query the NAS to determine whether a LUN is using thin provisioning.
• Stun pauses running virtual machines when a volume runs out of space. The space issue can then be
fixed and the virtual machines can continue rather than reporting write errors.
• Threshold Warning the system reports a warning when a configurable capacity is reached. In FreeNAS® ,
this threshold can be configured at the pool level when using zvols (see Table 10.6) or at the extent
level (see Table 10.11) for both file- and device-based extents. Typically, the warning is set at the pool
level, unless file extents are used, in which case it must be set at the extent level.
• Unmap informs FreeNAS® that the space occupied by deleted files should be freed. Without unmap,
the NAS is unaware of freed space created when the initiator deletes files. For this feature to work,
the initiator must support the unmap command.
• Zero Blocks or Write Same zeros out disk regions. When allocating virtual machines with thick provisioning, the zero write is done locally, rather than over the network. This makes virtual machine creation
and any other zeroing of disk regions much quicker.
327
CHAPTER
THIRTY
USING THE API
A REST (https://en.wikipedia.org/wiki/Representational_state_transfer) API is provided to be used as an alternate mechanism for remotely controlling a FreeNAS® system.
REST provides an easy-to-read, HTTP implementation of functions, known as resources, which are available
beneath a specified base URL. Each resource is manipulated using the HTTP methods defined in RFC 2616
(https://tools.ietf.org/html/rfc2616.html), such as GET, PUT, POST, or DELETE.
As shown in Figure 30.1, an online version of the API is available at api.freenas.org (http://api.freenas.org).
Fig. 30.1: API Documentation
The rest of this section shows code examples to illustrate the use of the API.
Note: Beginning with FreeNAS® 9.10.2, a new API has been added. The old API is still present for compatibility. Documentation for the new API is available on the FreeNAS® system at the /api/docs/ URL. For
example, if the FreeNAS® system is at IP address 192.168.1.119, enter http://192.168.1.119/api/docs/ in a
browser to see the API documentation.
328
FreeNAS® 11.0-U4 User Guide, Release 11.0
30.1 A Simple API Example
The api directory of the FreeNAS® github repository (https://github.com/freenas/freenas/tree/master/examples/api)
contains some API usage examples. This section provides a walk-through of the newuser.py script, shown
below, as it provides a simple example that creates a user.
A FreeNAS® system running at least version 9.2.0 is required when creating a customized script based on
this example. To test the scripts directly on the FreeNAS® system, create a user account and select an
existing volume or dataset for the user’s Home Directory. After creating the user, start the SSH service using
Services → Control Services. That user will now be able to ssh to the IP address of the FreeNAS®
system to create and run scripts. Alternately, scripts can be tested on any system with the required software
installed as shown in the previous section.
To customize this script, copy the contents of this example into a filename that ends in .py. The text
that is highlighted in red below can be modified in the new version to match the needs of the user being
created. The text in black should not be changed. After saving changes, run the script by typing python
scriptname.py. If all goes well, the new user account will appear in Account → Users → View
Users in the FreeNAS® GUI.
Here is the example script with an explanation of the line numbers below it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import json
import requests
r = requests.post(
'https://freenas.mydomain/api/v1.0/account/users/',
auth=('root', 'freenas'),
headers={'Content-Type': 'application/json'},
verify=False,
data=json.dumps({
'bsdusr_uid': '1100',
'bsdusr_username': 'myuser',
'bsdusr_mode': '755',
'bsdusr_creategroup': 'True',
'bsdusr_password': '12345',
'bsdusr_shell': '/usr/local/bin/bash',
'bsdusr_full_name': 'Full Name',
'bsdusr_email': 'name@provider.com',
})
)
print r.text
Where:
Lines 1-2: import the Python modules used to make HTTP requests and handle data in JSON format.
Line 4: replace freenas.mydomain with the Hostname value in System → System Information. Note
that the script will fail if the machine running it is not able to resolve that hostname. Change https to http to
use HTTP rather than HTTPS to access the FreeNAS® system.
Line 5: replace freenas with the password used to access the FreeNAS® system.
Line 7: if you are using HTTPS and want to force validation of the SSL certificate, change False to True.
Lines 8-16:
set the values for the user being created.
The Users resource
(http://api.freenas.org/resources/account.html#users) describes this in more detail. Allowed parameters are listed in the JSON Parameters section of that resource. Since this resource creates a FreeBSD user,
the values entered must be valid for a FreeBSD user account. Table 30.1 summarizes acceptable values.
This resource uses JSON, so the boolean values are True or False.
30.1. A Simple API Example
329
FreeNAS® 11.0-U4 User Guide, Release 11.0
Table 30.1: JSON Parameters for Users Create Resource
JSON Parameter
bsdusr_username
Type
string
bsdusr_full_name
bsdusr_password
string
string
bsdusr_uid
integer
bsdusr_group
integer
bsdusr_creategroup boolean
bsdusr_mode
string
bsdusr_shell
string
bsdusr_password_disabled
boolean
bsdusr_locked
boolean
bsdusr_sudo
boolean
bsdusr_sshpubkey string
Description
maximum 32 characters, though a maximum of 8 is recommended for interoperability; can include numerals but cannot
include a space
may contain spaces and uppercase characters
can include a mix of upper and lowercase letters, characters, and
numbers
by convention, user accounts have an ID greater than 1000 with a
maximum allowable value of 65,535
if bsdusr_creategroup is set to False, specify the numeric ID of the
group to create
if set to True, a primary group with the same numeric ID as bsdusr_uid will be created automatically
sets default numeric UNIX permissions of user’s home directory
specify full path to a UNIX shell that is installed on the system
if set to True, user is not allowed to log in
if set to True, user is not allowed to log in
if set to True, sudo is enabled for the user
contents of SSH authorized keys file
Note: When using boolean values, JSON returns raw lowercase values but Python uses uppercase values.
So use True or False in Python scripts even though the example JSON responses in the API documentation
are displayed as true or false.
30.2 A More Complex Example
This section provides a walk-through of a more complex example found in the startup.py script. Use the
searchbar within the API documentation to quickly locate the JSON parameters used here. This example
defines a class and several methods to create a ZFS volume, create a ZFS dataset, share the dataset over
CIFS, and enable the CIFS service. Responses from some methods are used as parameters in other methods.
In addition to the import lines seen in the previous example, two additional Python modules are imported
to provide parsing functions for command line arguments:
import argparse
import sys
It then creates a Startup class which is started with the hostname, username, and password provided by the
user via the command line:
1
2
3
4
5
6
7
8
9
10
class Startup(object):
def __init__(self, hostname, user, secret):
self._hostname = hostname
self._user = user
self._secret = secret
self._ep = 'http://%s/api/v1.0' % hostname
def request(self, resource, method='GET', data=None):
if data is None:
data = ''
r = requests.request(
330
Chapter 30. Using the API
FreeNAS® 11.0-U4 User Guide, Release 11.0
method,
'%s/%s/' % (self._ep, resource),
data=json.dumps(data),
headers={'Content-Type': "application/json"},
auth=(self._user, self._secret),
11
12
13
14
15
16
17
18
19
20
21
22
)
if r.ok:
try:
return r.json()
except:
return r.text
raise ValueError(r)
A get_disks method is defined to get all the disks in the system as a disk_name response. The create_pool
method uses this information to create a ZFS pool named tank which is created as a stripe. The volume_name
and layout JSON parameters are described in the “Storage Volume” resource of the API documentation.
1
2
3
def _get_disks(self):
disks = self.request('storage/disk')
return [disk['disk_name'] for disk in disks]
4
5
6
7
8
9
10
11
12
def create_pool(self):
disks = self._get_disks()
self.request('storage/volume', method='POST', data={
'volume_name': 'tank',
'layout': [
{'vdevtype': 'stripe', 'disks': disks},
],
})
The create_dataset method is defined which creates a dataset named MyShare:
1
2
3
4
def create_dataset(self):
self.request('storage/volume/tank/datasets', method='POST', data={
'name': 'MyShare',
})
The create_cifs_share method is used to share /mnt/tank/MyShare with guest-only access enabled. The
cifs_name, cifs_path, cifs_guestonly JSON parameters, as well as the other allowable parameters, are described in the “Sharing CIFS” resource of the API documentation.
1
2
3
4
5
6
def create_cifs_share(self):
self.request('sharing/cifs', method='POST', data={
'cifs_name': 'My Test Share',
'cifs_path': '/mnt/tank/MyShare',
'cifs_guestonly': True
})
Finally, the service_start method enables the CIFS service. The srv_enable JSON parameter is described in the
Services resource.
1
2
3
def service_start(self, name):
self.request('services/services/%s' % name, method='PUT', data={
'srv_enable': True,
4
5
})
30.2. A More Complex Example
331
INDEX
Symbols
802.1Q, 105
A
Dmidecode, 318
Domain Controller, 214
Download, 10
Dynamic DNS, 216
Add Group, 48
Add Jail, 255
Add User, 51
Adding Devices to a VM, 273
AFP, 166, 212
Alert, 294
Alert Services, 72
API, 327
Apple Filing Protocol, 166, 212
arcstat, 309
Autotune, 64
E
B
G
Boot Environments, 58
Burn ISO, 11
Getting FreeNAS\ :sup:‘®‘, 10
Groups, 47
Guide, 293
Email, 64
Encryption, 110
EtherChannel, 99
F
File Transfer Protocol, 217
Forums, 297
freenas-debug, 316
FTP, 217
C
CA, 74
Certificate Authority, 74
Certificates, 77
Checksum, 10
CIFS, 183, 230
Compression, 118
Create Dataset, 115
Create Group, 48
Create Jail, 255
Create User, 51
Creating VMs, 272
Cron Jobs, 83
D
DC, 214
DDNS, 216
Deduplication, 117
Delete Group, 49
Delete User, 53
Dell PERC H330, 8
Dell PERC H730, 8
332
H
Hardware Recommendations, 6
Highpoint RAID, 8
I
Install, 13
Internet Small Computer System Interface, 195
iocage, 270
IOzone, 306
Iperf, 302
IRC, 299
iSCSI, 195
ISO, 11
J
Jails, 252
L
LACP, 99
LAGG, 99
Link Aggregation, 99
FreeNAS® 11.0-U4 User Guide, Release 11.0
Link Layer Discovery Protocol, 223
LLDP, 223
Localize, 319
Log Out, 289
M
Mailing Lists, 300
MegaCli, 316
Minio, 227
Mirroring the Boot Device, 61
Multiple Boot Environments, 58
N
Netperf, 305
Network File System, 174, 224
Network Settings, 94
New Group, 48
New Jail, 255
New User, 51
NFS, 174, 224
P
Path and Name Lengths, 5
Periodic Snapshot, 134
Plugin, 245
Professional Support, 301
R
Reboot, 290
Remove Group, 49
Remove User, 53
Replace Failed Drive, 131
Replication, 136
Reporting, 277
RFC
RFC 2616, 328
RFC 3721, 197
Route, 105
Rsync, 225
Rsync Tasks, 85
Running VMs, 276
S
S.M.A.R.T., 228
S.M.A.R.T. Tests, 92
S3, 227
Samba, 183, 230
SCP, 239
Scrub, 146
Secure Copy, 239
Secure Shell, 237
Services, 209
Shadow Copies, 193
Index
Shell, 287
Shutdown, 291
Simple Network Management Protocol, 235
SMB, 183, 230
Snapshot, 134
Snapshots, 148
SNMP, 235
SSH, 237
Start Service, 210
Static Route, 105
Stop Service, 210
Support, 80, 292
System Dataset, 66
T
Tasks, 82
TFTP, 240
Time Machine, 170
tmux, 317
Translate, 319
Translation, 319
Trivial File Transfer Protocol, 240
Trunking, 105
Tunables, 67
tw_cli, 314
U
Uninterruptible Power Supply, 241
Upgrade, 20
Upgrade ZFS Pool, 25
UPS, 241
USB Stick, 11
Users, 49
V
VAAI, 326
VAAI for iSCSI, 327
Virtualization, 26
VLAN, 105
VM, 26
VMs, 271
VMware Snapshot, 150
Volumes, 108
W
WebDAV, 182, 244
Windows File Share, 230
Windows Shares, 183
Wizard, 279
Z
ZVOL, 118
333
Download PDF
Similar pages