THIS SITE IS NOW DEPRECATED AND IN READ-ONLY MODE. REFER TO DOC.FREENAS.ORG FOR FREENAS DOCUMENTATION.
Secure Shell (SSH) allows 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 in order to transfer files using SSH.
This section summarizes the FreeNAS® SSH configuration options, demonstrates an example configuration that restricts users to their home directory, and provides some troubleshooting tips.
SSH Configuration Screen
Figure 8.12a shows the Services → SSH configuration screen. Once you have configured SSH, don't forget to start it in Services → Control Services.
Figure 8.12a: SSH Configuration
Table 8.12a 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 → Settings → Advanced.
Table 8.12a: SSH Configuration Options
|TCP Port||integer||port to open for SSH connection requests; 22 by default|
|Login as Root with password||checkbox||for security reasons, root logins are discouraged and disabled by default; if enabled, password must be set for root user in Account → Users → View Users|
|Allow Password Authentication||checkbox||if unchecked, key based authentication for all users is required; requires [additional setup] on both the SSH client and server|
|Allow TCP Port Forwarding||checkbox||allows users to bypass firewall restrictions using SSH's [port forwarding feature]|
|Compress Connections||checkbox||may reduce latency over slow networks|
|Host Private Key||string||only available in Advanced Mode; allows you to paste a specific host key as the default key is changed with every installation|
|SFTP Log Level||drop-down menu||only available in Advanced Mode; select the syslog(3) level of the SFTP server|
|SFTP Log Facility||drop-down menu||only available in Advanced Mode; select the syslog(3) facility of the SFTP server|
|Extra Options||string||only available in Advanced Mode; additional sshd_config(5) options not covered in this screen, one per line; these options are case-sensitive and mis-spellings may prevent the SSH service from starting|
A few sshd_config(5) options that are useful to input in the Extra Options field include:
- ClientAliveInterval: increase this number if SSH connections tend to drop
- ClientMaxStartup: defaults to 10; increase if you have more users
Chrooting Command Line SFTP Users
By default when you configure SSH, users can use the ssh command to login to the FreeNAS® system. A user's home directory will be the volume/dataset specified in the Home Directory field of their user account on the FreeNAS® system. Users can also use the scp and sftp commands to transfer files between their local computer and their home directory on the FreeNAS® system.
While these commands will default to the user's home directory, users are able to navigate outside of their home directory which can pose a security risk. SSH supports using a chroot to confine users to only the sftp command and to be limited to the contents of their own home directory. To configure this scenario on FreeNAS®, perform the following steps.
NOTE: some utilities such as WinSCP can bypass the chroot. This section assumes that users are accessing the chroot using the command line sftp.
1. Create a ZFS dataset for each user requiring sftp access in Storage → Volumes.
2. If you are not using Active Directory or LDAP, create a user account for each user in Account → Users → Add User. In the Home Directory field, browse to the location of the dataset you created for that user. Repeat this process to create a user account for every user that will need access to the SSH service.
3. Create a group named sftp in Account → Groups → Add Group. Then, click on the sftp group in View Groups and add the users who are to be restricted to their home directories when using sftp.
4. Set permissions for each dataset in Storage → Volume → View Volumes. SSH chroot is very specific with regards to the required permissions (see the ChrootDirectory keyword in sshd_config(5) for details). Your configuration will not work if the permissions on the datasets used by SSH chroot users differ from those shown in Figure 8.12b.
Figure 8.12b: Permissions Required by SSH Chroot
5. Create a home directory within each dataset using Shell. Due to the permissions required by SSH chroot, the user will not have permissions to write to the root of their own dataset until you do this. Since your intention is to limit them to the contents of their home directory, manually create a home directory for each user within their own dataset and change the ownership of the directory to the user. Example 8.12a demonstrates the commands used to create a home directory called user1 for the user account user1 on dataset /mnt/volume1/user1:
Example 8.12a: Creating a User's Home Directory
mkdir /mnt/volume1/user1/user1 chown user1:user1 /mnt/volume1/user1/user1
6. Configure SSH in Services → SSH. Add these lines to the Extra Options section:
Match Group sftp ChrootDirectory %h ForceCommand internal-sftp AllowTcpForwarding no
7. Start the SSH service in Control Services. Click the red OFF button next to SSH. After a second or so, it will change to a blue ON, indicating that the service has been enabled.
8. Test the connection from a client by running sftp, ssh, and scp as the user. The sftp command should work but be limited to the user's home directory and the ssh and scp commands should fail.
Troubleshooting SSH Connections
If you add any Extra Options in the SSH configuration screen, be aware that the keywords listed in sshd_config(5) 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 to what the problem is. Type the following command within Shell 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.