If you write modern applications that need to talk to Db2 for i, Mapepire is a game changer!
Mapepire is IBMs open source database access layer. It uses secure WebSockets so your Node.js, Python, Java or .NET Core apps can connect to Db2 without the old ODBC or JDBC drivers on the client side.
The Mapepire server (also called the daemon) runs directly on your IBM i. Once it is up and running you only need the matching client library in your application language. It is fast, cloud friendly and simple to manage.
Let's cover the full server install right now.
What you need before you start
Make sure you have these items ready:
- SSH access to your IBM i (recommended, use the Qshell or PASE environment)
- A user profile with *ALLOBJ and *IOSYSCFG special authorities (or at least enough rights to install packages and create directories under /QOpenSys and /opt)
- Internet access from your IBM i if you plan to use the yum method (most systems do these days)
- Open Source package management already set up (yum and rpm). If you have not done this yet run yum install once to initialise it or follow the IBM guide at ibm.biz/ibmi-rpms
That is it. No special hardware or extra licensed programs required.
Step 1a: Install the Mapepire server using RPM (IBM's recommended way)
Open an SSH session to your IBM i and switch to a profile with the right authorities.
Run this single command:
That pulls the latest version straight from the IBM i open source repositories and installs everything under /QOpenSys/pkgs. It also drops the necessary files into /QOpenSys/etc/mapepire for configuration.
If you prefer to manage services the easy way (and you should), also install Service Commander:
Step 1b: Install the Mapepire server using RPM (Nick Litten's recommended way)
Open IBM-i Access Client Solutions and select and download both Mapepire Server and Service Commander using the Open Source package Manager. This is by far the super easiest way of installing both packages and also easy to update in the future as new releases come out.
*boom* that was easy right?
Step 2: Start the Mapepire daemon
The daemon must be running before any client can connect. Once started it stays up until you stop it or the system IPLs. From your 5250 terminal you can STRQSH and issue these commands:
Check mapepire is alive:
You should see the service listed as running on port 8076 (the default). If you want to confirm from another machine you can use telnet or a quick client test later.
To stop mapepire later:
System command (sc) makes our lives easier!
Step 5: Basic configuration
Mapepire works out of the box for most people but here are the important settings.
Port Default is 8076. IBM recommends you leave it alone unless you have a port conflict. If you must change it use the PORT environment variable or edit the service definition with:
Security and TLSMapepire uses TLS by default. Three options exist:
- Let it auto generate a self signed certificate (quickest for testing)
- Use LetsEncrypt certificates (Mapepire looks automatically in /etc/letsencrypt/live/<your-hostname>)
- Supply your own JKS keystore at /QOpenSys/etc/mapepire/cert/server.jks with password "mapepire" and alias "mapepire"
Access control Edit the rules file to lock down who can connect:
Example to allow everything except profiles starting with Q:
allow *@*
# Deny logins from users starting with the letter Q
deny q*@*
Rules are processed top to bottom and the last matching rule wins. Use the * wildcard freely.
Mapepire also honours the normal Db2 exit points for additional security.
Step 6: Make it survive an IPL
If you use Service Commander it starts automatically after IPL. i have read, that with the manual nohup method you will need to add a startup program or use the IBM i autostart job support. But, honestly, I've never tried that because Service Commander is cleaner.
Quick verification test
Once the daemon runs you can test a connection from any client machine.
You can also start VSCode or IBM BOB and the Code for IBM-i Connection should happily start it's Mapepire server and connect.
Connection Problems?
My initial connections failed, but once I selected the default version of Java it worked OK. To check this go into the CONNECTION SETTING of your IBM-i Host System from within VSCode or IBM BOB
We will dive into writing actual client code (Node.js example) in the next lesson but for now you know the server side is ready.
That is the complete install. Mapepire is now listening for secure WebSocket connections and your modern applications can reach Db2 for i with almost zero client side setup.
If you run into any snags the official documentation lives at mapepire-ibmi.github.io/guides/sysadmin.