(Originally published by IBM Systems Magazine in December 2015).

This past week I was configuring a customer’s machine to be a Git server and ran into an interesting issue. Whenever I ran Git commands I would get errors like the following:

$ git init
fatal: Out of memory? mmap failed: No such device

I went Googling and tried many things to resolve the problem.  None seemed to help.  Not only that, there was a good chance that if I did fix it by altering settings in PASE that it might cause something else to break.  The potential for “toe-stepping” in PASE creates an interesting conundrum.  How do we use the IBM i as a workhorse and ensure all open source applications operate error-free?

This is where a new IBM i open source project named “IBM i Chroot” (or ibmichroot) comes into play. By using ibmichroot I was able to create a new pristine environment on the same IBM i where Git works as expected.

Great!  Problem solved.

So what is a “chroot”?  Well, it stands for “Change Root”.  Wikipedia describes chroot as follows:

A chroot on Unix operating systems is an operation that changes the apparent root directory for the current running process and its children. A program that is run in such a modified environment cannot name (and therefore normally cannot access) files outside the designated directory tree.

So what does that exactly mean?  Well, first you should know that Chroot exists on IBM i, in PASE.  And to further describe Chroot I think an example that builds on itself is in order.

First, you need to get into PASE using either CALL QP2TERM from a 5250 session or SSH into your IBM i machine using something like putty or Secure Shell.  Below I am in PASE and used pwd to print my working directory so you can understand my context.

$ pwd

The chroot command has options, similar to how commands ls and rm have options.  If I just type the chroot command I get a response that tells me what the parameters are.

$ chroot
usage: chroot rootdir command

Ok, now we know it is expecting a “rootdir” and a “command”.   Let’s create a directory and specify a command to run.  In this case we want to enter into a new interactive shell environment where we can enter commands, much like the shell environment we are currently in.

$ mkdir chroot1
$ chroot chroot1 /QOpenSys/usr/bin/bsh
/QOpenSys/usr/bin/bsh: No such file or directory

It couldn’t find /QOpenSys/usr/bin/bsh.  The bsh program is the Bourne Shell and is the environment where you enter commands like mkdir, ls, etc.  Why couldn’t it find it?  What actually happened is the chroot command caused you to enter into the chroot1 directory and make it appear as though chroot1 was the root of the IFS.  That means there wasn’t (yet) a directory structure of /QOpenSys/usr/bin nor was there a program named bsh.

For the next step, let’s create that directory structure within this new chroot environment and also copy the bsh program into it.  We’ll then see if that allows the command to run successfully.

$ mkdir -p chroot1/QOpenSys/usr/bin
$ cp /QOpenSys/usr/bin/bsh chroot1/QOpenSys/usr/bin

And now run our original chroot command again.

$ chroot chroot1 /QOpenSys/usr/bin/bsh

This time we got further.  Yet, we’re still not succeeding in getting a new shell in our new Chroot environment.  The message of “Killed” doesn’t give us much to go on.  I just happen to know you need two additional files in the Chroot environment, namely libc.a and libcrypt.a.

$ mkdir -p chroot1/usr/lib
$ cp /lib/libc.a chroot1/usr/lib
$ cp /lib/libcrypt.a  chroot1/usr/lib

Run the chroot command again to see if we can get in now.

$ chroot chroot1 /QOpenSys/usr/bin/bsh
$ pwd
$ ls
ls: not found


We successfully entered the Chroot environment.  Or rather, we changed our root to be /home/aaron/chroot1.  We can prove that by typing pwd which declares we are at the root.  Next we try to list the contents using command ls but the ls command is not found.  Why?  Because nothing will exist in this Chroot environment unless we manually add it.  Let’s use the cp command to copy it to the Chroot environment.

Side note: Use the exit command to leave the Chroot environment and return to your previous shell.

$ chroot chroot1 /QOpenSys/usr/bin/bsh
$ ls
QOpenSys  usr

It worked!  

Notice how only the directories we created are showing in the Chroot environment.

So now you’ve been introduced to the base level concept.  How can this concept be used in the real world?

Here are some useful scenarios for how Chroot environments can be used:

There are many uses for Chroot as we incrementally operate more and more in PASE.  As you can imagine, it would take a long time to create and copy all of the necessary files to author, for example, a PHP runtime environment.  That’s where the ibmichroot project comes into play.  It gives us configuration and automation to make the process of creating Chroot environments for specific purposes much more simple.

In my next article we’ll dive into how to use ibmichroot further under the covers.

Do you have more ideas on how Chroot environments on IBM i can be used?

Flavor the conversation by adding a comment below or shoot me an email at sales@krengeltech.com.

Leave a Reply

Your email address will not be published. Required fields are marked *