If you want to try a different version of CommunityPlus+ PHP without impacting your main environment, you can do so with a chroot. This is an IFS-level container. When you go into a chroot directory, it acts like a root directory (/). This lets you install multiple instances of software that must own absolute paths, such as multiple versions of a package. For example, you could install and test a leading-edge version of PHP or a new extension without affecting your main PHP installation.

Setting up the chroot

You must have *ALLOBJ and *IOSYSCFG authorities to create chroots.

The chroot setup package must be installed. Install ibmichroot using ACS’s package management window or run the following command:

$ yum install ibmichroot

Next, create the chroot under QOpenSys. Create a directory in the format /QOpenSys/chroots/CHROOT_NAME_HERE, using a name of your choice for the chroot. (Note: all paths under QOpenSys are case sensitive.) Then run the following command with your directory name:

$ chroot_setup -y /QOpenSys/chroots/CHROOT_NAME_HERE

Verify the chroot works

You can enter the chroot by entering the following command, where the first argument is the directory of the chroot, and the second argument is the program to run inside of the chroot (in this case, a shell):

$ chroot /QOpenSys/chroots/CHROOT_NAME_HERE /QOpenSys/usr/bin/sh
$ # We're in the chroot now. We can just exit to pop back out of it.
$ exit

Adding the signing key into the chroot

The CommunityPlus+ signing keys must be added into the chroot. Otherwise, you’ll get errors when trying to install the packages into the chroot.

This must be done outside the chroot. Run the following command to add the keys, substituting the directory given for the directory you use with the chroot:

$ rpm --root /QOpenSys/chroots/CHROOT_NAME_HERE --import https://repo.seidengroup.com/repos/seiden-group-signing-public.key

Adding repositories (and disabling/enabling as needed)

Packages are still managed using the system Yum. To use a repository, it must be present outside of the chroots. However, you might not want to use that repository for the system. For example, if you’re using PHP 7.4, but you want to test PHP 8.0 in a chroot, you don’t want to upgrade to PHP 8 outside the chroot just yet. Instead, you can add the repository, but then disable it immediately after. This allows you to use the repository only when needed, like installing into the chroot.

This must be done outside the chroot. For example, to add a repository and then disable it, run the following commands, substituting the repo ID and URL:

$ yum-config-manager --add-repo REPO_URL_HERE
$ yum-config-manager --disable REPO_ID_HERE

If you don’t know the ID of the repo, you can use the repolist command of yum. The IDs and descriptions of the repositories will be shown. The --all option makes it list disabled repositories in addition to enabled repositories.

$ yum repolist --all

Installing packages into the chroot

You can pass the “--installroot” flag to Yum to tell it what chroot to install into.

This must be done outside the chroot. For example, to install a package into a chroot (in this example, bash), substituting the directory given for the directory you use with the chroot:

$ yum --installroot=/QOpenSys/chroots/CHROOT_NAME_HERE install bash

Another example, installing PHP into a chroot enabling a specific repository:

$ yum --installroot=/QOpenSys/chroots/CHROOT_NAME_HERE --enablerepo=REPO_ID_HERE install "php-*"

If you need to use the rpm command directly for whatever reason, you can also make it use a chroot with the “--root” option.

$ rpm --root /QOpenSys/chroots/CHROOT_NAME_HERE -ivh test.rpm

Entering the chroot to use it

This is just like when you verified the chroot works, except now we want to use it and run programs inside of it. For example, if you installed PHP, and want to verify what version is inside of the chroot:

$ chroot /QOpenSys/chroots/CHROOT_NAME_HERE /QOpenSys/usr/bin/sh
$ # We're inside the chroot now.
$ /QOpenSys/pkgs/bin/php -v

Further steps

You will probably want to remake things like home directories inside of the chroot, or you may find some programs may not work properly. For example, the following command will remake your home directory:

$ mkdir -p $HOME
$ chmod 700 $HOME

Setting up the web server

For web servers, you have multiple options available; the PHP development server (php -S), Apache, or nginx. You can have a mix of in and out of the chroot, or choose to just run inside of the chroot. Mixing can cause you to worry about path and directory structure differences.

If you’re using a web server outside of the chroot, you may need to ensure the directory structure exists in both inside and outside of the chroot. Some methods you could do are:

  • Naively keep a copy in all locations; the files can diverge if changed, but simple to reason with.
  • Symbolic links; note that you cannot link to outside of the chroot when inside the chroot. That would violate the isolation of the chroot. You would have to make the directory in the chroot, and place links outside of it.
  • NFS mounting localhost; may be complex to set up, but means you can keep it accessible to multiple chroots. Due to the fact IBM i lacks bind mounts (that would allow putting directories elsewhere on IFS), this would be the closest alternative.
    • Export the directory you want available, and mount it inside of the chroots.

References