Server Install/Config

In order for apps to use Db2 for i with Mapepire clients from their runtimes, the Daemon must be installed and started-up on each IBM i. This is a simple process and there are many ways to achieve it.

Installation

Option 1: RPM (recommended)

yum install mapepire-server

(if you need help getting started with RPMs, please see http://ibm.biz/ibmi-rpms)

Option 2: manual installation

Make a “download” directory on IBM i by running the following from an SSH terminal:

mkdir -p /opt/download

Download the distribution zip file (filename will look something like mapepire-server-v___.zip) from the release page and save it to the download directory you created. Rename the file to mapepire-server-dist.zip

If you have wget installed and have internet access, you could use wget to download the file from IBM i, for instance (replace with proper version):

cd /opt/download
wget -O mapepire-server-dist.zip https://github.com/Mapepire-IBMi/mapepire-server/releases/latest/download/mapepire-server-dist.zip

Unzip the file and reset ownership/permissions

mkdir -p /opt/mapepire
cd /opt/mapepire
jar xvf /opt/download/mapepire-server-dist.zip
chown -R qsys .

Start it up. There are more options below if you are not using Service Commander with manual installation.

cd /opt/mapepire/lib/mapepire

## Start
sc start mapepire.yaml

## Check it's running
sc check mapepire.yaml

## Stop
sc stop mapepire.yaml

## Check it's stopped
sc check mapepire.yaml

Startup

After installing the Daemon, you must start it up once. The good news, is once it has started up, it can be just left running.

Service Commander (recommended, requires RPM-installed version)

If you are running the RPM version of the mapepire server, you can install service commander (yum install service-commander) and use it to start the mapepire service:

sc start mapepire

Manual shell invocation (RPM-installed version)

nohup /QOpenSys/pkgs/bin/mapepire &

Manual shell invocation (manually-installed version)

nohup /opt/mapepire/bin/mapepire &

Configuration

Port configuration

By default, the port used by the Mapepire server is 8076. It is not recommended to change it. If needed, however, the port can be manipulated with the PORT environment variable, or if using Service Commander, by changing the port number in the check_alive field of the server definition.

scedit mapepire

TLS configuration

Option 1: Let’s Encrypt certificates

If you are using LetsEncrypt certificates, for instance generated by CertBot, the Mapepire server will automatically use the server certificate, assuming they exist at the following location used by CertBot:

/etc/letsencrypt/live/<hostname>

Option 2: Custom certificate

You can define a custom certificate by configuring a certificate store with the following requirements:

Attribute	Value
file name	`/QOpenSys/etc/mapepire/cert/server.jks`
format	JKS
store password	`mapepire`
key password	`mapepire`
certificate alias	`mapepire`

For example, the following commands will use DCM Tools and keytool to export and use a certificate from the *SYSTEM DCM store.

dcmexport --password=changeit --dcm-store=system --format=pkcs12 mystore.p12
keytool -importkeystore -srckeystore mystore.p12 -srcstoretype pkcs12 -srcstorepass changeit -srcalias "mydcmalias" -destkeystore /QOpenSys/etc/mapepire/cert/server.jks -deststoretype JKS -deststorepass mapepire -destkeypass mapepire -destalias mapepire

Option 3: Self-signed certificate

If no certificate is otherwise configured, the Mapepire server will automatically generate its own self-signed certificate!

Exit Points

Yes, Mapepire will use the same exit points as typical JDBC application. See more on this IBM Support page.

Filtering IP addresses by exit point

Unfortunately due to the project’s design, all client connections will appear as coming from 127.0.0.1. As such, user-based exit point rules will “just work” whereby IP address-based rules will require additional logic. In order to enforce IP address rules, the exit program will need to inspect the CLIENT_WRKSTNNAME client special register to extract the IP address of the client.

Connection rules via configuration file

Mapepire supports user-based and IP-based restrictions, which can be configured by the system administrator in the following configuration file:

/QOpenSys/etc/mapepire/iprules.conf

(In the future, we will also support a “drop-in” directory, allowing you to split rules into multiple files)

The format for this configuration file is as follows:

Comment lines begin with a leading #
Rules are defined in the format allow <username>@<ip-address> deny <username>@<ip-address>
The * wildcard can be used at any place in the username or IP address
For any specific connection, the last matching rule takes precedence

Example: disable logins from user profiles starting with `Q`

# Allow connections from all hosts
allow *@*

# Deny logins from users starting with the letter Q
deny q*@*

Example: only allow specific users from a specific IP range

# Deny by default
deny *@*

# Allow only appusr1 and appusr2, and only from 192.168.*.*
allow  appusr1@192.168.*
allow  appusr2@192.168.*