Using chroot on the IBM i to Restrict ssh, sftp, and scp to Specific Directories

Resolving The Problem

Chroot is a function commonly found in UNIX and Linux operating systems. Preventing malicious users from exploiting vulnerabilities in the daemons or services running on these platforms is chroot's primary goal. Users accessing services that have been chrooted are placed into subdirectories underneath the root "/" filesystem. The chroot directory is also known as the chroot jail because it prevents users from accessing files outside of the designated jail. The OpenSSH implementation (5733SC1 - IBM Portable Utilities) on the IBM i has access to the chroot function. On releases v5r4m0 and higher, the IBM i uses the chroot function within OpenSSH to isolate the directories in the IFS that users connected using ssh, sftp, and scp. This document describes how to set up the chroot environment on the IBM i platform.

Prerequisites:

• SI33703 (V5R4)
• SI33600 (V6R1)
• 5722SS1 Option 30 (Qshell)
• 5722SS1 Option 33 (Portable Application Solutions Environment - PASE)
• User profile with *ALLOBJ authority to run the chroot script.
• QSECOFR user profile to start the ssh daemon and activate the chroot function.

The chroot script file (chroot_setup_script.sh) is located in the IFS directory below:

/QOpenSys/QIBM/ProdData/SC1/OpenSSH/openssh_version/sbin'

The script can then be used to create a minimally functional chroot directory structure in the IFS.

Notes:
1. The default OpenSSH implemenation on v5r4 machines is openssh-3.5p1.

2. The default OpenSSH implemenation on v6r1 machines is openssh-3.8.1p1.

3. The default OpenSSH implemenation on v7r1 machines is openssh-4.7p1.

Note: The openssh-xxxx folder was removed on v7r2 systems & higher.

Step 1: With the QSECOFR user profile or one that has *ALLOBJ authority, sign onto a system running V5R4 or higher.

Step 2: On the operating system command line, run the CALL QP2TERM operating system command to enter the PASE environment. You are shown a screen similar to the following:



Step 3: Invoke the script (chroot_setup_script.sh) to create the chroot environment. Use the syntax below to invoke the chroot script:

/QOpenSys/QIBM/ProdData/SC1/OpenSSH/openssh-3.5p1/sbin/chroot_setup_script.sh sshtest

Note: IBM's recommendation is to copy and paste the above command and press Enter. For users invoking the script on v6r1m0 machines, you should replace the openssh-3.5p1 folder in the IFS path above with openssh-3.8.1p1. On v7r1m0 machines, you should replace the openssh-3.5p1 folder with openssh-4.7p1. On v7r2m0 machines, the openssh-xxxx folder does not exist anymore. The chroot script is located in IFS directory /QOpenSys/QIBM/ProdData/SC1/OpenSSH/sbin on systems running 7.2 & higher of the operating system. When invoking the script, you have the option of passing one user profile. In the syntax above, user profile sshtest is passed to the chroot script. The script will modify the home directory parameter in sshtest's user profile to point to the chroot path in the IFS. The script will also create a home directory for sshtest in the chroot home directory. You should replace sshtest with a valid profile on your IBM i machine. During SSH connections to the IBM i, this user profile will only have access to the chroot structure in the IFS.





Step 4: Verify that the HOMEDIR parameter in the 'SSHTEST' user profile was modified to the chroot directory. To display the details of a user profile on the IBM i, use the CL command below:

Type DSPUSRPRF (SSHTEST) and press the enter key. Page down until you reach the Home directory parameter.

User profile . . . . . . . . . . . . . . . : SSHTEST

Home directory . . . . . . . . . . . . . . : /QOpenSys/QIBM/UserData/SC1/OpenSSH/openssh-3.5p1/chroot/./home/sshtest


Note: When a user profile with a "." (dot) in their home directory path connects using ssh, sftp, or scp path the "/" (root) directory for that connected session is set to be the portion of the directory path prior to the "." This directory is referred to as the "chroot directory. The portion of the user profile home directory path after the "." is used to set the HOME environment variable for the session.

Step 5: Change the LOCALE parameter in the user profile to *NONE, *C, or *POSIX. Use the CL command below to change the LOCALE parameter in the user's profile:

CHGUSRPRF USRPRF(SSHTEST) LOCALE(*NONE)

Note: SSH, SFTP, and SCP users connecting to the chroot environment on the IBM i will fail if the LOCALE path in the user's profile is set to
anything in the '/QSYS.LIB' filesystem. Set the LOCALE path to *NONE, *C, or *POSIX in the user profile to avoid this restriction.

Step 6: Start the SSH daemon. In order to activate or enable the chroot function, the SSH daemon needs to run under the QSECOFR user profile. To start the SSH daemon under the QSECOFR user profile, log in to the IBM i with the QSECOFR user profile and run the following CL command:

QSH CMD('/QOpenSys/usr/sbin/sshd')

Note: The SSH daemon must be started with the QSECOFR user profile to activate the chroot function. Starting the SSH daemon with a profile that has QSECOFR authority will not activate the chroot function. A user profile with a UID of (0) is required to activate the chroot function. The QSECOFR user profile on the IBM i is shipped with a UID of (0).

Issues known to cause the chroot function to fail:

• Starting the SSH daemon without the QSECOFR user profile. For the reasons mentioned in Step 5, activation of the chroot function

requires that the SSH daemon be started with the QSECOFR user profile.

• Copy any existing SSH configurations from the default user home directory '/home/user_profile' into the user's home folder in the chroot environment. The chroot script if passed an optional parameter for a specific user profile will create a home folder for this particular user in the chroot environment. It will not copy the contents of the user's previous home folder into the newly created home directory. For new SSH configurations, everything should be created in the user's chroot home directory. Rochester Support Center knowledgebase document New, Debugging Unattended SFTP: contains a listing of the authorities required by SSH. The section titled On the Server System deals specifically with the authorities needed for successful inbound SSH connections into the IBM i.

• Running the SSH daemon jobs in a dedicated subsystem environment. Rochester Support Center knowledge base document New, Starting the SSH Daemon in a Dedicated Subsystem Environment: provides step-by-step instructions to configure a dedicated subsystem for the SSH daemon jobs. Because QSECOFR is not a valid entry for the USER parameter in the JOBD, this creates a potential problem if you want the SSH daemon jobs to continue to run in the dedicated subsystem. In order to overcome this potential problem, you need to use the ADDJOBSCDE CL command to start the SSH daemon. The user profile invoking the ADDJOBSCDE CL command needs *USE authority to the QSECOFR user profile. Some customers might prefer to include the command in their start up program to allow the SSH daemon to start during IPL time. If the start up program is running under user profile e.g. QPGMR, then this profile should be given correct authority to the QSECOFR user profile. In order to avoid any conflicts and allow the SSH daemon jobs to run under QSECOFR during IPL time, remove the autostart job entry assigned to the dedicated subsystem. A copy of the syntax for the add job schedule entry command is listed below:

ADDJOBSCDE JOB(SSHD) CMD(QSH CMD('/QOpenSys/usr/sbin/sshd')) FRQ(*ONCE) JOBQ(SSHLIB/SSHJOBQ) USER(QSECOFR)

Note: At release v6r1m0, there is no need to use a dedicated subsystem for the SSH daemon jobs. The SSH daemon is part of the TCP servers at this release. CL commands STRTCPSVR *SSHD and ENDTCPSVR *SSHD can be used to start and end the SSH daemon jobs. The daemon jobs run under the QSECOFR user profile in the QUSRWRK subsystem.

• User profiles with the LOCALE path set to anything in the '/QSYS.LIB' filesystem. SSH, SFTP, and SCP users connecting to the chroot environment on the IBM i will fail because the operating system is unable to find the '/QSYS.LIB' path in the new chroot directory. Set the LOCALE path to *NONE, *C, or *POSIX in the user profile to avoid this restriction.

More information regarding the chroot script:

• The chroot script can be invoked from either the PASE environment or Qshell. In the example provided in Step 3, the chroot script was invoked within the PASE environment. The script can accept one optional parameter as the name of the user profile e.g. sshtest that will have its HOMEDIR path modified to the change root directory.

• The chroot script is intended to be run only once. Running the script a second time will generate an error similiar to the one below:

chroot_setup_script.sh
########## STEP 1 ##########
Verify that the chroot-dir does not yet exist
Error: chroot-dir /QOpenSys/QIBM/UserData/SC1/OpenSSH/openssh_version/chroot already exists

• Restricting or isolating additional users within the chroot jail requires the manual creation of home folders in the chroot's home directory. IFS authorities could be used to prevent access to the individual folders in the chroot home directory. Alternatively, the chroot script can be modified to create additional chroot directories to isolate individual chroot user profiles from each other. Modification of the chroot script is not handled under Support Line. If the customer needs help modifying the script, they will have to enter into a Consult Line agreement.

• The chroot_config.log file in the '/QOpenSys/QIBM/UserData/SC1/OpenSSH/openssh_version' folder can provide some useful debug information regarding the script's execution.