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.

In addition, siteadd can automate setting up a web server that uses packages in the chroot, albeit without some of the isolation benefits.

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

In addition to using the command-line tools, ACS can be used to install packages inside of a chroot. Set the IFS container when launching Open Source Package Management as needed.

Entering the chroot to use it/verify function

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

However, you don’t necessarily need to be inside the chroot to use it; see below for how siteadd can use chroots.

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

Using siteadd (easy)

siteadd can create an Apache-based site that points to PHP installed in a chroot. Sites created this way are normal siteadd sites, except the path to PHP is prefixed with the chroot path. This lets you test multiple versions of PHP in parallel using a familiar Apache web server and FastCGI setup.

First, install PHP in the chroot. Then invoke siteadd with the -c flag and the full chroot path. For example, if your chroot is in /QOpenSys/chroots/php80, invoke siteadd like so:

$ addsite -c /QOpenSys/chroots/php80 -n chrphp80 -p 1999 -I

How it works: When siteadd creates settings in .ini files, it uses the full path to the PHP executable (i.e. /QOpenSys/chroots/php80/QOpenSys/pkgs/bin/php) and rewrites references as required to point to the chroot. PHP scripts will be executed as normal outside of the chroot, so that they can access /www.

Alternative approaches providing more application isolation (advanced users)

You have multiple web server options: the PHP development server (php -S), Apache, or nginx. You can have a mix of these 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