Access IBM i via Linux Nginx.

We have a number of clients who are running iAMP as their IBM i HTTP/PHP server. Aura have not supported iAMP for a very long time and have been reluctant to share the build process etc. so it has become time to replace with an alternative solution.

ZendServer on IBM i was one option we considered but the cost of the Enterprise solution and lack of a Community Version (No one appears to want to provide access to the free license keys) made this a difficult option for many of the small IBM i users we cater to. We have always run a Linux based Apache/PHP solution internally with Easycom as our IBM i conduit. The performance has always been better than we could get from the IBM i standalone solution and the amount of information on how to set up makes it simpler to manage. However we are seeing a lot of complexity being added to Apache2 which would make managing it in some of these smaller shops pretty hard.

We have been hearing a lot about Nginx (the link shows Nginx Plus but we install Nginx via apt which is free) and a recent update to IBM i OPS LPP made us look a little more closer at a solution which uses it. Unfortunately the IBM i implementation only goes so far with many options not available (hopefully that will change as IBM adds more to the OPS family) so we had to step back to a Linux based solution still using Easycom as the IBM i conduit and using Nginx as the webserver.

We need PHP to run under the Nginx setup which pushed us to look at the php-fpm option, it allows php to be run as a service using Nginx as the front end and php-fpm sitting as the backend PHP processor. This also ties in nicely with how we could get the Easycom support added, we can add the Easycom Linux modules to php-fpm without any changes to them.

So the final solution will be a Linux Nginx webserver sending php requests to the php-fpm service which uses Easycom for any IBM i related requests. Easycom is still going to be running native on the IBM i to service the requests from the Linux server. We did consider using the XML Service instead of Easycom but our expertise with that product is pretty minimal.

As we are going to be running the initial test set up on a Debian Container running under Proxmox we first built the container using a template which just has a base Debian9 setup. We gave it 50GB of Disk, 2GB of memory and 2 cores which is more than it required but it gives us the flexibility to do other stuff later. 

First thing we always install is webmin, this provides a pretty amazing GUI interface for managing Linux and something we have installed on every Linux instance we run. I am sure many of the clients we will set up will appreciate not having to delve into the Linux command line to carry out many of the tasks required to manage a Linux system.   

As Webmin is not part of the standard packages we have to take some additional steps to install it on the Debian instance, the best place to find the install instructions is the Wiki which has a lot of information about Webmin processes and how to use it effetively. It also caters for other Linux Distributions. The following shows the steps we took to install Webmin from a putty session connected to the server.

Start up nano or your installed editor to create a new file as below
nano /etc/apt/sources.list.d/webmin.list
Add the following content to the file, save and close.
deb http://download.webmin.com/download/repository sarge contrib
Set up the key for the repository
wget -qO – http://www.webmin.com/jcameron-key.asc | sudo apt-key add – 
Update the package tree to get the Webmin package and install.
apt-get update
apt-get install webmin
You should now be able to start your browser and link to the Webmin interface using https://ip_address:10000.

Another tool you should install is ProFTPD Server as you will need to upload and download files as part of the installation process and setting up website content etc.
apt-get install proftpd
The server is started on install so you can test by connecting using your favorite FTP Client.

We actually installed everything to support PHP7.0 from this point forward but had to walk it all back up due to a problem with the Easycom Server running on the IBM i throwing all sorts of pointer errors and command content errors. We have yet to get responses from Aura as to why, so we would suggest that for now you stick with PHP5.6 which appears to work just fine with the Easycom IBM i server. If we get any resolution we will update the information to reflect using the PHP7.0 binaries etc.


At this point I would suggest that you create a user profile using webmin to sign on with because using the root profile created with the initial install is not recommended long term. You can then use sudo (if installed) or su to change to the root profile as required.

Now we install Nginx using the package manager, we used the webmin interface but you can also use a command line in a shell to do the same thing.
apt-get -y -f install nginx
Part of the installation process starts up the nginx server using the default configuration files so using a browser session you can now use http://ip_address/ to show the initial server page.
Nginx page

Nginx Initial page


Everything looks OK at this point so next we will install the PHP part of the solution.
PHP5.6-fpm is not available for download from the Debian9 standard packages, so yet again we have to link to another repository to allow it to be installed. Use the following as a guide to install.  
apt-get install apt-transport-https lsb-release ca-certificates
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo “deb https://packages.sury.org/php/ $(lsb_release -sc) main” > /etc/apt/sources.list.d/php.list
apt-get update
apt-get install php5.6-fpm

Once everything is installed and you see no significant errors you can start the php-fpm service.
systemctl enable php5.6-fpm.service

Now we can look at the running processes under webmin to see that we have both nginx and the php-fpm service running.

webmin running processes

webmin processes


While both processes are now running and we can serve the initial html page from the Nginx server it does not allow any php pages to be served, the php-fpm service has to be linked to Nginx to allow this to happen.

We are going to add Nginx to the webmin interface, this will make the creation of new virtual hosts and update of current configurations a lot easier than trying to use the file manager or command line to create and update the required config files. Unfortunately it is not part of the standard webmin install so we need to add a third party module from Justin Hoffman and install into webmin, we will also need to install a couple of additional perl packages which are required for the module but not installed from any of the packages we have so far. Use the following commands to install (or the webmin interface, makes things pretty simple once you get to know it).
apt-get install libhtml-entities-numbered-perl
apt-get install libhtml-parser-perl
Upload the downloaded .gz file to the Linux Server and install to webmin using the Webmin->Webmin Configuration->Webmin modules, once it is done you will see a message with a link to take you straight to the interface, it is also linked under the Server menu list. You should see something similar to the following.

Nginx webmin interface

Nginx webmin interface


We are going to add a new Virtual Host (you could use the default configuration). Here is the configuration we created. 

vhost-setup

vhost-setup


It is all pretty self explanatory, we created a new Virtual host that will listen on port 80. The server Name (used for name based virtual hosting) is used to ensure this configuration is used whenever www.test.local requests come through. We have stated that any file which has the .php extension is passed via /var/run/php/php5.6-pfm.sock link (this is where the php5.6-fpm service will be listening.) If you get any 502 gateway errors this is where you need to start looking.

Before anything is going to work we will need to create a php file to be served, at the moment we have no content in the /var/www/test directory and the /var/www/test directory does not exist, so go ahead and create the directory and add a new file which will allow the phpinfo() function to be called. I used nano to create the file index.php with the following content.
<?php phpinfo(); ?>
Before you can point your browser at the site you will need to add an entry into your hosts file on your PC to resolve the www.test.local address to the server address, then simply point the browser at that address http://www.test.local and you should see the php information displayed such as below. Notice the Server API setting!

phpinfo output

phpinfo output

Now we will add the Easycom module to the php-fpm service so that php scripts that contain i5_toolkit requests can be processed. You will need to download the latest Linux Modules from the Aura website, make sure you download the correct version (64/32bit) and upload to the Linux Server. Then you need to extract the files, here is the command we used with the download we received.

tar -xvf EasycomPHPLinux4_0_32FR64.zi0cP7.tgz
Ours contained all of the modules for PHP5.1.0 up to PHP7.0.0 but we are only interested in the PHP5.6.0 modules. Simply copy the module ‘EasycomForPHP/PHP5.6.0/easycom.so’ to the directory used for the php5.6-fpm modules, in our case it was ‘/usr/lib/php/20131226’.
Before the module is available to the php-fpm service we have to enable it, create a new ‘/etc/php/5.6/mods-available/easycom.ini’ file with the following content. You can copy an existing one and change the name & content if you want.
; configuration for php easycom module
;priority=20
extension=easycom.so
To enable the module use the following command, all it does is add symbolic links to the relevant files.
phpenmod easycom
Now reload the php5.6-fpm service
service php5.6-fpm reload
When you the http://www.test.local/ request you should see the php info now has a new section for Easycom similar to the following.

Easycom module loaded

Easycom module loaded


Great! we now have a fully functioning website that will run on the Linux Server (Container in our instance) and talk to the IBM i via Easycom for all i5_toolkit requests.

If you want to have something similar running in your shop but still have some doubts on how to set it all up contact us to discuss the options. We are going to keep a watch on IBM and some possible new Open Source initiatives that could further simplify this process and maybe remove some of the requirements we have today, if we see anything interesting we will be writing updates to this post.

We have now migrated all of our internal web servers over to Nginx and php-fpm, at this time everything is running the same or better than when we ran it under Apache2. The first customer install has been completed successfully and testing is underway for their new application, others will be migrated pretty quickly now we have the process understood.

While many will say we are not being faithful to our IBM i roots, our view is that we need to integrate not isolate the IBM i, doing the above shows it works and works well. 

Chris…