1. Framework Installation and Configuration Guide
  2. Installation

2 Installation

This chapter describes the installation of EFTLink and covers the following topics:

Skillset Required

To install EFTLink successfully system implementers must:

  • Understand the requirements of the specific EFT system being used, and the POS software that will be connecting to EFTLink.

  • Understand the configuration settings held in property files which control how EFTLink, and the selected core behave. System implementers must know how to add or modify properties within property files with their chosen text editor.

    • Java properties are case sensitive, and never contain spaces in the property name. They usually do not contain spaces in the property value – there are sometimes exceptions in lists.

    • A space is allowed before and after the = that separates the property from its value.

    • Case sensitivity does not apply to Boolean values – True is the same as true.

    • Each property = value is a separate line.

    • Lines prefixed with # are comments.

Prerequisites

EFTLink can be installed on Windows or Linux operating systems, but the procedure will differ accordingly.

Note:

Oracle Retail assumes that the retailer has ensured its Operating System has been patched with all applicable Windows updates.

POS System Requirements

The POS system should meet the following minimum requirements.

  • 256MB RAM

  • Intel Celeron 1GHz or equivalent CPU

  • 1GB disk space.

Supported Operating Systems

EFTLink is supported on the following Operating Systems:

  • Oracle Enterprise Linux 7

  • Windows POSReady 7

  • Windows 7

  • Windows 10

  • Windows 10 IOT Enterprise LTSB 2016 (1607)

Java

EFTLink framework will run with any version of Java from 1. 8. All strategic cores except for the PayByLink core are binary compatible to Java 1.7 whereas the PayByLink core requires Java 1.11.

EFTLink by default expects Java JRE to exist in the folder location C:\jre (on Windows) or /opt/jre (on a Linux kernel).

To change the default location of java you will need to update either include-eftlink-windows.conf or include-eftlink-linux.conf which are located in <installation directory>\wrapper\conf.

This may be required in situations where a specific version of JRE is required, such as where a different version of the JRE is required to that which is being used by the POS, which may also be using the location c:\jre. See the Oracle Retail EFTLink Core Configuration Guide for any core JRE requirements.

Installing EFTLink

Runnable Installer/Upgrader Jar

Note:

This section describes how to install EFTLink using the installer jar.

Follow the steps below to install EFTLink.

The eftlink-22.x-installer.jar and eftlink-22.x-upgrader.jar are runnable and if executed will perform a silent installation/upgrade by default.

To perform a silent installation requires a pre-populated ant.install.properties file to exist within the same directory as the runnable jars.

Property Settings

Lists each mandatory setting for the ant.install.properties file.

Table 2-1 Mandatory Installer Settings

Setting Description Example

installDir

Installs EFTLink to the directory specified.

Note: When upgrading EFTLink the installDir property setting must point to the existing directory where EFTLink is installed.

C\:\\eftlink

eftlinkChannelZeroPortNumber

Configures EFTLink eftlinkConfig.properties ServerChannel0 property setting.

Note: This setting is not applicable when running the eftlink-22.x-upgrader.jar.

10100

eftlinkChannelOnePortNumber

Configures EFTLink eftlinkConfig.properties ServerChannel1 property setting.

Note: This setting is not applicable when running the eftlink-22.x-upgrader.jar.

10101

selectedCore

EFTLink will install and automatically configure itself to use the class path entered here.

Note: This setting is not applicable when running the eftlink-22.x-upgrader.jar.

manito.eft.tenderretail.TenderRetailCore

Performing an Install/Upgrade

  1. Unzip the vxx.x.x.xxx.installer.zip file somewhere other than the desired target directory which is typically C:\eftlink or /opt/eftlink for Linux.

  2. Make sure that Java is on the path of the system. In Linux, JAVA_HOME is also required to be set.

  3. Navigate to the path where you extracted the installer zip file.

    For example, C:\<user>\Downloads or ~/Downloads).

  4. Review the supplied ant.install.properties file and make changes if necessary. For example, if performing an upgrade then ensure the installDir property setting points to the existing directory where EFTLink is currently installed.

  5. Open a terminal (using elevated privilege) ensuring the directory is set to where the install/upgrader jars are located.

    Running the installer:

    1. Command to launch the installer.

      *(Windows) eftlink-(xx.x.x.x)-installer.jar or

      (Linux) sudo . eftlink-(xx.x.x.x)-installer.jar

      * if preferred the installer jar has a graphical user interface which can be accessed during installation by adding "gui" to the end of the command statement (separated by a space). For example eftlink-(xx.x.x.x)-installer.jar gui.

    2. The installation will end with the OPI Service being installed.

    3. Within the EFTLink installation directory, copy from C:\<eftlink installation folder>\keys folder the pos.private.jks and eftlink.public.jks files to the POS (for example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys).

    Running the upgrader:

    1. Command to launch the upgrader.

      *(Windows) eftlink-(xx.x.x.x)-upgrader.jar or

      (Linux) sudo . eftlink-(xx.x.x.x)-upgrader.jar

    2. Once the upgrade is complete your eftlink installation directory should be updated but all configuration properties settings should have been retained.

  6. Close the terminal and remove installations files / backup files if necessary.

  7. Start EFTLink. In the terminal, navigate to the installation directory, for example, C:\eftlink or /opt/eftlink.

    *Windows: start eftlink.bat

    Linux: ./eftlink.sh start

    *In Windows, you can also start the OPI Server in the services panel.

Manual Installation

This section describes the installation sequence of EFTLink using the binary files.

Step 1 - Creating the EFTLink Folder

A folder should be created or designated for the EFTLink package. This folder can be any name and location, the only restriction is that there should be no spaces in the path. Conventionally you may wish to use the name eftlink.

Step 2 - Install the Files

EFTLink is supplied as a zip file, which, should be unzipped into the designated folder. All files needed, including the entire set of core files are included.

Once unzipped, the following files and folders should be present in the designated EFTLink folder:

Table 2-2 List of Unzipped Files and Folders

Files/Folder Comment

apidocs

Folder containing the API documentation for the framework.

cores

Each core sub-directory contains the core jar file, and reference copies of that core's property file(s).

lib

The lib folder contains supporting files for EFTLink.

linux

Folder containing files for tanuki wrapper.

linux_64

Folder containing files for tanuki wrapper.

log

Folder containing the log files.

tmp

Working folder for EFTLink.

windows

windows 64

wrapper

CardRange.xml

The default tender mapping and card identification file.

CreateKeys.bat

A batch file used to create encryption keys to ensure secure communications between POS and EFTLink.

CreateKeys.sh

A Linux script used to create encryption keys to ensure secure communications between POS and EFTLink.

eftlink.bat

A batch file used to launch the eftlink application.

eftlink.sh

A Linux script used to launch the eftlink application.

eftlink.jar

The main executable code of the EFTLink framework.

EftLinkConfig.properties

Carries the settings for the framework.

EftlinkConfig_PED_Pool.properties

Carries the framework settings for use with PED pooling mode.

EftlinkConfig_Static_Server.properties

EftlinkXstore_Mobile.properties

Eftlink-rest-api.bat

A batch file used to launch the rest API application.

Eftlink-rest-api.jar

Executable code of the rest API application.

Eftlink-rest-api.properties

Eftlink-rest-api.sh

A Linux shell script used to launch the rest API application.

Eftlink-rest-api-log4j2.xml

Log4j2 configuration file.

installcore.bat

A windows batch file script which sets one of cores (contained within the cores folder) as active.

installcore.sh

A Linux shell script which sets one of cores (contained within the cores folder) as active.

Jetty.xml

LangCN.properties

Language files.

LangDE.properties

LangEN.properties

LangES.properties

LangFR.properties

LangIT.properties

LangJP.properties

LangNL.properties

LangPT.properties

LangRU.properties

LangSV.properties

Log4j2.xml

Log4j2 configuration file.
Step 3 - Run the Installation Script

To setup EFTLink with an active core:

Table 2-3

Core Name (Case insensitive) Description

Adyen

Adyen

Cayan

Cayan

FIPay

AJB FIPay

OciusSentinel

Verifone Ocius Sentinel

OPIRetail

OPIRetail

PayByLink

PayByLink (as secondary core only)

PayPal

PayPal (supports Ewallet transactions only)

PointUS

Verifone Point (US)

SixPay

Six Payment Services MPD

SolveConnect

The Logic Group SolveConnect

TenderRetail

TenderRetail

WorldPay

WorldPay

For Windows,

  • From the run line type:<installation directory\installcore.bat  (Advanced setup)

  • From a command terminal:<installation directory\installcore.bat <CoreName>  (Legacy setup)

For Linux,

open a terminal and change the directory to the EFTLink installation path and type: installcore.sh <coreName>

Follow the on-screen instructions. The batch or script file does two things:

  • Configures EftlinkConfig.properties with the desired core(s).

  • Copies the selected core property file from the specific core folder to the main EFTLink folder, where it will be the active file.

  • Installs EFTLink as a Windows Service.

  • Creates TLS Communication Keys.

The table below lists the full classpath to the supplied core application.

Table 2-4 Core Classpath

Core Classpath

Adyen

manito.eft.adyen.AdyenCore

AJB FIPay

manito.eft.ajb.FIPayCore

Cayan

manito.eft.cayan.CayanCore

OPI Retail

oracle.eftlink.opiretail.OPIRetailCore

PayPal

oracle.eftlink.paypal.PayPalCore

Six Payment Services MPD

manito.eft.sixpay.SixpayMPDOPIClient

Tender Retail

manito.eft.tenderretail.TenderRetailCore

The Logic Group SolveConnect

manito.eft.solveconnect.SolveConnectCore

Verifone Ocius Sentinel

manito.eft.ocius_sentinel.OciusSentinelCore

Verifone Point US

manito.eft.pointus.PointUSCore

WorldPay

manito.eft.worldpay.WorldPayCore
Step 4 - Copy TLS Communication Keys

Within the EFTLink installation directory, copy from C:\<eftlink installation folder>\keys folder the * pos.private.jks and eftlink.public.jks files to the POS (for example C:\xstore\keys).

Post Installation Steps

By default, in Windows, the 'OPI Server' service is using the Local system account user. In order to ensure for EFTLink service to create dynamic key store files, a user with an administrative privilege is needed. This is only applicable for cores like PointUS and Cayan. In the services panel, right click on the OPI Server service. Select the Properties option. Select the Log on tab. Select This account:Input the user's credentials and select OK.

  • Adyen: The POS_JNI jar which is provided by Adyen is also required. This needs to be copied to C:\eftlink\cores\Adyen or /opt/eftlink/cores/Adyen for Linux. Refer to the Third Party section of the Adyen core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.

  • AJB FiPay: The AJBComm.jar component needs to be copied to C:\eftlink\cores\FIPay or /opt/eftlink/cores/FIPay for Linux. Refer to the FileSet section of the AJB core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.

  • Cayan: The merchant credentials which are supplied by Cayan team are needed to be setup. This can be done in Xstore's back office through the EFTLink Admin functions. Refer to the Account Information Entry section of the Cayan core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.

  • VerifoneUS: The PED needs to be paired with EFTLink prior to use. This can be done through Xstore's back office in the EFTLink Admin functions. Refer to the Administration Functions section of PointUS core in the Oracle Retail EFTLink Core Configuration Guide located on OHC for more details.

Altering the Windows Service

By default, EFTLink is install as a window service (OPI Server). Below commands can be run post  * installation to either alter the services state or remove it altogether. 

Windows Configuration

To stop, check the status or to restart EFTLink from a terminal, type one of the following commands:

  • eftlink.bat console - run the application with a console

  • eftlink.bat start - start eftlink once installed as a Windows service

  • eftlink.bat restart - restart eftlink once installed as a Windows service

  • eftlink.bat stop - stop eftlink once installed as a Windows service

  • eftlink.bat install - install eftlink as a Windows service

  • eftlink.bat remove - uninstall eftlink as a Windows service

  • eftlink.bat help - show this message

Linux

sudo./eftlink.sh stop - stop eftlink service

sudo./eftlink.sh status - service status

sudo./eftlink.sh restart - restart service

sudo./eftlink.sh condrestart - only starts the daemon if it is currently running

Securing Communication by Creating TLS Communication Keys

Although TLS communication Keys are generated by default. You may wish to regenerate your keys. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys.

  1. Locate the CreateKeys.bat / CreateKeys.sh file in the EFTLink folder

    .

  2. From a terminal, run the CreateKeys script file with an appropriate set of parameters to create encryption keys. 

    CreateKeys.bat	-e <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname] 
    CreateKeys.sh	-e <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname]

    For example, CreateKeys.bat-e RSA 4096 SHA256withRSA 750

    For example, CreateKeys.bat-e RSA 4096 SHA256withRSA 750 —dname

    Table 2-5 SelfSigned Certificate Parameters

    Switch Parameter Description Supported Value

    -e

    <algorithm>

    Algorithm used for TLS keys encryption.

    EC,DSA,RSA

    <bitlength>

    Number of bits - higher values equate to a higher level of encryption.

    256 (when using EC),

    1024,2048 (when using DSA),

    1024,2048,3072,4096,7680,8192,15360 (when using RSA)

    <signAlgorithm>

    Signature Algorithm used.

    SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (when using EC), SHA256withDSA (when using DSA), SHA256withRSA, SHA384withRSA, SHA512withRSA (when using RSA)

    <daysValidity>

    Number of days after creation that the certificate will remain valid.

    100 to 750 days
     

    [-dname]

    Prompt for POS and Eftlink keystores certificate Distinguished Name information.

  3. Once encryption keys are created, five files will be present on the system in the keys subfolder of EFTLink:

    pos.private.jks to be MOVED to the POS client

    pos.public.jks - to remain on the EFTLink Server

    eftlink.private.jks - to remain on the EFTLink Server

    eftlink.public.jks - to be MOVED to the POS client

    comms.keystore.properties - required to be held on both POS and EFTLink Server

  4. The following files should be REMOVED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys).

    pos.private.jks

    eftlink.public.jks

  5. The following file should be COPIED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys):

    comms.keystore.properties

  6. This will leave the following three files on the EFTLink server in the folder [eftlink root]\keys:

    eftlink.private.jks

    pos.public.jks

    comms.keystore.properties

  7. The removal of the appropriate files from the EFTLink server is to limit the availability of TLS keys only to where they are required, and in order to reduce the possibility of the keys being obtained and used to monitor traffic between POS and EFTLink server.

    These instructions are repeated by the CreateKeys script file when keys are generated.

    Note:

    From V20 onwards, expiry of TLS certificates is enforced by default. Self-signed certificates will be valid for a maximum of 750 days.

  8. Clear warnings will be placed in log files when certificates are due to expire. Expired certificates will not result in loss of communication between POS and EFTLink.

CA Certificates

Optionally, the EFTLink application TLS encryption keys for secure communication between POS client and EFTLink server may be signed by a CA. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys, generation of signing request and import of the signed certificates.

  1. Locate the CreateKeys.bat / CreateKeys.sh file in the EFTLink folder.

  2. From a terminal, run the CreateKeys script file with an appropriate set of parameters to create encryption keys. The parameters are like those when used to generate self-signed certificates but specify the first parameter as -s.

    CreateKeys.bat	-s <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname] 
    CreateKeys.sh	-s <algorithm> <bitlength> <signAlgorithm> <daysValidity> [-dname]

    For example,

    CreateKeys.bat-s RSA 4096 SHA256withRSA 750

    CreateKeys.bat-s RSA 4096 SHA256withRSA 750 -dname

    Table 2-6 CA Certificate Parameters

    Switch Parameter Description Supported Value

    -s

    <algorithm>

    Algorithm used for TLS keys encryption.

    EC,DSA,RSA

    <bitlength>

    Number of bits - higher values equate to a higher level of encryption.

    256 (when using EC),

    1024,2048 (when using DSA),

    1024,2048,3072,4096,7680,8192,15360 (when using RSA)

    <signAlgorithm>

    Signature Algorithm used.

    SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (when using EC), SHA256withDSA (when using DSA), SHA256withRSA, SHA384withRSA, SHA512withRSA (when using RSA)

    <daysValidity>

    Number of days after creation that the certificate will remain valid.

    100 to 750 days
     

    [-dname]

    Prompt for POS and Eftlink keystores certificate Distinguished Name information.

  3. Once encryption keys are created, a sub-folder based on the current date/time is created containing the encryption keys along with signing requests:

    For example,

    Folder name: keys20200710115046

    Eftlink.private.jks - selfsigned file

    Pos.private.jks - selfsigned file

    Eftlink.private.csr - certificate signing request

    Pos.private.csr - certificate signing request

    Eftlink.private.jks - backup of selfsigned file

    Pos.private.jks - backup of selfsigned file

    comms.keystore.properties - keystore encryption data file

    The backup files are required for the situation where a subsequent import is attempted but does not give the required results - further attempts may be made at importing the signed certificates received from the CA.

    For this reason, do not remove the backup files.

    File are held in this temporary folder rather than the keys folder as the signing process may take some time, and several sets of signed keys can be handled.

  4. Deliver to your CA the following files:

    Eftlink.private.csr

    Pos.private.csr

    In reply, you should receive the following files (filenames may vary):

    Eftlink.private.cer.der - signing of EFTLink.private.csr

    Pos.private.cer.der - signing of POS.private.csr

    Root.cer - root certificate used to sign

    Optional Intermediate.cer - one or more intermediate certificates

  5. Import the signed certificates into the keystores, by placing the signed files and root certificate (plus optional intermediate certificates) in the temporary signing keys folder keys[date] then running the following command.

    Createkeys -I <foldername> <root cert> <eftlink signed file> <pos signed file> <(optional) intermediate certificate 1><(optional) intermediate certificate 2>

    Table 2-7 Signed Files, Root Certificates and Intermediate Certificates

    Switch Parameter Description Supported

    -e

    <foldername>

    Temporary keys Subfolder name. Do not provide the full path, just the foldername.

    18 character folder name

    <root cert>

    The root certificate provided by the CA

    Security certificate

    <eftlink signed file>

    Signed file returned by CA

    Security certificate

    <pos signed file>

    Signed file returned by CA

    Security certificate

    <intermediate certificate 1>

    CA Intermediate certificate

    Optional Security certificate

    <intermediate certificate 2>

    CA Intermediate certificate

    Optional Security certificate

    For example, createkeys -i keys20200101010101 ca_root.cer eftlink.private.der.cer pos.private.der.cer ca_intermediate1.cer ca_intermediate2.cer

  6. Archive the temporary keys[date] folder to a safe location as this contains sensitive information.

  7. The following files should be REMOVED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys):

    pos.private.jks

    eftlink.public.jks

  8. The following file should be COPIED from the EFTLink system and placed on the POS in the folder [xstore root]\keys, where xstore root is the main POS client folder. For example, C:\xstoredata\xstore\keys, or prior to version 22 of Xstore in C:\xstore\keys): 

    comms.keystore.properties

  9. This will leave the following three files on the EFTLink server in the folder [eftlink root]\keys:

    eftlink.private.jks

    pos.public.jks

    comms.keystore.properties

  10. The removal of the appropriate files from the EFTLink server is to limit the availability of TLS keys only to where they are required, and to reduce the possibility of the keys being obtained and used to monitor traffic between POS and EFTLink server. These instructions are repeated by the CreateKeys script file when keys are generated.

    Note:

    From version 20 onwards, expiry of TLS certificates is enforced by default. Self-signed certificates will be valid for a maximum of 750 days.

  11. Clear warnings will be placed in log files when certificates are due to expire. Expired certificates will not result in loss of communication between POS and EFTLink.

Deploying EFTLink within a Docker Container

Prerequisites

This docker file uses an Oracle Linux OS which is held at https://container-registry.oracle.com/

Create the Docker Image

  1. Obtain the EFTlink installation file.

  2. Extract the container.zip.

  3. Copy the v22.0.0.<nnn>.zip to the extracted container folder.

  4. Copy in a jre.zip file (You can use the xstore JRE utility provided in the OracleRetailXstoreCommon_<version>_XST_0_0_0.zip) to the container folder.

  5. Either copy the container folder to your docker environment or ensure it is accessible.

  6. Within you docker environment change the working directory to the container folder.

  7. Type:

    docker build --build-arg eftlink_zip=<zip file containing eftlink build> --build-arg jre_zip=<zip file containing jre zip> --build-arg eftlink_user_uid=<user uid> --build-arg eftlink_user_gid=<user gid> -f Dockerfile -t eftlink:latest .

    For example,

    docker build --build-arg eftlink_zip=v22.0.0.326.zip --build-arg jre_zip=jre11.zip --build-arg eftlink_user_uid=9090 --build-arg eftlink_user_gid=9090 -f Dockerfile -t eftlink:latest.

Running the Docker Container

Before running the docker container you will need to copy files from a working eftlink installation and make them persistent.

If running in a docker swarm you can do this by using Docker volumes and Docker Configs or you could use a simple bind mount as shown below.

The recommended files and folders to persist are as follows:

  • EftlinkConfig.properties

  • eftlink-rest-api.properties

  • jetty.xml

  • log4j2.xml

  • eftlink-rest-api-log4j2.xml

  • keys/comms.keystore.properties

  • keys/eftlink.private.jks

  • keys/eftlink.public.jks

  • keys/pos.private.jks

  • keys/pos.public.jks

  • logs

  • core properties files for example, opiretail.properties and LangEN_OPIRetail.properties

Command example which will run a container with simple bind mounts:

docker run --name eftlink --user eftlink --publish 10100:10100 --publish 8443:8443 /

--volume <path to directory on the host machine>:/opt/eftlink/tmp /

--volume <path to directory on the host machine>:/opt/eftlink/keys

--volume <path to directory on the host machine>:/opt/eftlink/log /

--volume <path to file on the host machine>:/opt/eftlink/opiretail.properties /

--volume <path to file on the host machine>:/opt/eftlink/LangEN_OPIRetail.properties /

--volume <path to file on the host machine>:/opt/eftlink/EftlinkConfig.properties /

--volume <path to file on the host machine>:/opt/eftlink/eftlink-rest-api.properties /

--volume <path to file on the host machine>:/opt/eftlink/jetty.xml /

--tty --rm --interactive --workdir /opt/eftlink eftlink

EFTLink Advanced Configuration Features

See the Oracle Retail EFTLink Framework Advanced Features Guide located on OHC and refer to the chapter for the specific feature enrichment.