SSH
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.
Contents |
SSH Configuration Screen
Figure 8.14a shows the Services → SSH configuration screen and Table 8.14a summarizes the configuration options. Once you have configured SSH, don't forget to start it in Services → Control Services.
Figure 8.14a: SSH Configuration
Table 8.14a: SSH Configuration Options
| Setting | Value | Description |
| 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 | allows you to paste a specific host key as the default key is changed with every installation |
| Extra Options | string | 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. 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.14b.
Figure 8.14b: Permissions Required by SSH Chroot
4. 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.14a demonstrates the commands used to create a home directory called user1 for the user account user1 on dataset /mnt/volume1/user1:
Example 8.14a: Creating a User's Home Directory
mkdir /mnt/volume1/user1/user1 chown user1:user1 /mnt/volume1/user1/user1
5. Configure SSH in Services → SSH. Add these lines to the Extra Options section:
Match Group sftp ChrootDirectory %h ForceCommand internal-sftp AllowTcpForwarding no
6. 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.
7. Test the connection from a client using a utility such as WinSCP.
In the example shown in Figure 8.14c, user1 is connecting to a FreeNAS® server with an IP address of 192.168.2.9. The password matches the one set in their user account on the FreeNAS® system and SFTP has been selected as the File protocol for the connection.
Figure 8.14c: Connecting to the SSH chroot from WinSCP
Once connected, the user can see the files on their Windows system in the left frame and the files on the FreeNAS® system in the right frame, as shown in Figure 8.14d.
Figure 8.14d: Using WinSCP Within a chroot
Notice that the directory structure on the FreeNAS® system starts at <root>. If the user clicks on <root>, they can not navigate to a higher folder. If the user tries to copy a file from the Windows system to <root>, the operation will fail. However, if the user clicks on their home folder (in this example, user1), they will enter that folder and can copy files to/from the Windows system within that folder.
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.
