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 whereas all strategic cores are binary compatible to Java 1.7.
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-20.x-installer.jar
and eftlink-20.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. |
|
eftlinkChannelZeroPortNumber |
Configures EFTLink eftlinkConfig.properties ServerChannel0 property setting. Note: This setting is not applicable
when running the |
|
eftlinkChannelOnePortNumber |
Configures EFTLink eftlinkConfig.properties ServerChannel1 property setting. Note: This setting is not applicable
when running the |
|
selectedCore |
EFTLink will install and automatically configure itself to use the class path entered here. Note: This setting
is not applicable when running the |
|
Performing an Install / Upgrade
-
Unzip the
vxx.x.x.xxx.installer.zip
file somewhere other than the desired target directory which is typicallyC:\eftlink
or/opt/eftlink
for Linux. -
Make sure that Java is on the path of the system. In Linux, JAVA_HOME is also required to be set.
-
Navigate to the path where you extracted the installer zip file.
For example,
C:\<user>\Downloads
or~/Downloads
). -
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. -
Open a terminal (using elevated privilege) ensuring the directory is set to where the install/upgrader jars are located.
Running the installer:
-
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.
-
The installation will end with the OPI Service being installed.
-
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 exampleC:\xstore\keys)
.
Running the upgrader:
-
Command to launch the upgrader.
*(Windows)
eftlink-(xx.x.x.x)-upgrader.jar
or(Linux)
sudo . eftlink-(xx.x.x.x)-upgrader.jar
-
Once the upgrade is complete your eftlink installation directory should be updated but all configuration properties settings should have been retained.
-
-
Close the terminal and remove installations files / backup files if necessary.
-
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.
Manually
This section describes the installation sequence of EFTLink.
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, eftlink_v21.0.zip
, and 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. |
linux |
Folder containing files for tanuki wrapper. |
linux_64 |
Folder containing files for tanuki wrapper. |
windows |
|
windows 64 |
|
wrapper |
|
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. |
log |
Folder containing the log files. |
tmp |
Working folder for EFTLink. |
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 - Select a Core
To set an active core open a terminal and change the directory to the EFTLink installation path and type:
-
For Windows,
installcore.bat <core name>
-
For Linux run
installcore.sh <core name>
For example, installcore pointus
would set the
PointUS core as the active core.
Note:
The core name is not case sensitive in the batch file or Linux script.
The batch or script file does two things:
-
Configures EftlinkConfig.properties:
EPSCore0=manito.eft.pointus.PointUSCore
-
Copies the selected core property file from the specific core folder to the main EFTLink folder, where it will be the active file, in this instance
pointus.properties
.If this is done manually you would need to edit
EftLinkConfig.properties
.EPSCore0=
The value is the full classpath to the selected core application. These are the valid classpaths:
Table 2-3 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 - Installing as a Service
This section describes how to install EFTLink as a service.
Windows Configuration
It is possible to install EFTLink as a windows service, using a third-party wrapper. EFTLink is distributed with a version of Tanuki Software Limited Java Service Wrapper.
Follow the steps below on how to configure EFTLink to run as a Windows service.
-
Download and install Java.
Ensure you have the correct version of Java installed.
For example: if the target machine has a 64 bit OS with default 64–bit Java active but you want to use a 32 bit service wrapper, then ensure you also have the required 32 bit Java installed.
-
Installing the Service.
-
From a command line (with administrative privileges) change to the root directory for EFTLink. For example, type
cd /eftlink
. -
If not already done, run installcore.bat to install the desired core which also creates and copies the necessary wrapper to .\bin. For example, type
installcore.bat adyen
. -
To install EFTLink as a window service, type
eftlink install
.If there are problems during install, it is possible to remove the service by typing
eftlink remove
. This may be necessary if the service is previously installed in a different folder. The service may then be reinstalled at the correct location by enteringeftlink install.
-
Once installed the service can be started and stopped from a command line:
eftlink start
eftlink stop
The service can also be controlled from the Windows Services Control Panel applet ("OPI Server").
-
-
Examine the log file “Wrapper.log".
-
The log file can be found in the designated EFTLink folder\log\eftlink_wrapper.log
-
Installing, starting the service, stopping the service, and uninstalling the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.
-
Linux
It is possible to run EFTLink as a service, using a third-party wrapper. EFTLink is distributed with a version of Tanuki Software Limited Java Service Wrapper.
Note:
You may be required to give script file(s) execution rights. This can be accomplish by opening a terminal window and typing:
sudo chmod
+x <PathToFile>
For example, sudo chmod
+x /opt/eftlink/installcore.sh
Follow the steps below on how to configure EFTLink to run as a service.
-
Download and install Java:
Ensure you have the correct version of Java installed.
For example: if the target machine has a 64–bit OS with default 64 bit Java active but you want to use a 32 bit service wrapper, then ensure you also have the required 32 bit Java installed.
-
Running EFTLink.
-
From a terminal change to the directory for EFTLink.
For example, type
cd /opt/eftlink
. -
If not already done, run installcore.sh to install the desired core which also creates and copies the necessary wrapper to ./bin.
For example, type
sudo./installcore.sh/adyen
. -
To run EFTLink as a service from a terminal type the following command
sudo./eftlink.sh start
. -
To stop, check the status or to restart EFTLink from a terminal, type one of the following commands:
sudo./eftlink.sh stop
sudo./eftlink.sh status
sudo./eftlink.sh restart
sudo./eftlink.sh condrestart
-
-
Examine the log file “Wrapper.log".
-
The log file can be found in the designated EFTLink folder\log\eftlink_wrapper.log
-
Starting the service and stopping the service are all briefly logged in wrapper.log, and this can be used to diagnose any problems.
-
Step 5 - Securing Communication by Creating TLS Communication Keys
SelfSigned Certificates
The EFTLink application does not include default TLS encryption keys for secure communication between POS client and EFTLink server, so these need to be generated as part of the installation procedure. A batch file, CreateKeys.bat, and a Linux script, CreateKeys.sh is included in the EFTLink project to facilitate creation of encryption keys.
-
Locate the
CreateKeys.bat / CreateKeys.sh
file in the EFTLink folder -
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> CreateKeys.sh -e <algorithm> <bitlength> <signAlgorithm> <daysValidity>
For example,
CreateKeys.bat-e RSA 4096 SHA256withRSA 750
Table 2-4 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
-
Once encryption keys are created, four files will be present on the system in the keys subfolder of EFTLink:
pos.private.jks
to be MOVED to the POS clientpos.public.jks
- to remain on the EFTLink Servereftlink.private.jks
- to remain on the EFTLink Servereftlink.public.jks
- to be MOVED to the POS client -
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:\xstore\keys:
pos.private.jks
eftlink.public.jks
-
This will leave only the following two files on the EFTLink server in the folder [eftlink root]\keys:
eftlink.private.jks
pos.public.jks
-
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.
-
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.
-
Locate the
CreateKeys.bat / CreateKeys.sh
file in the EFTLink folder. -
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> CreateKeys.sh -s <algorithm> <bitlength> <signAlgorithm> <daysValidity>
For example,
CreateKeys.bat-s RSA 4096 SHA256withRSA 750
Table 2-5 CA 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
-
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 filePos.private.jks
- selfsigned fileEftlink.private.csr
- certificate signing requestPos.private.csr
- certificate signing requestEftlink.private.jks
- backup of selfsigned filePos.private.jks
- backup of selfsigned fileThe 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.
-
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.csrPos.private.cer.der
- signing of POS.private.csrRoot.cer
- root certificate used to signOptional Intermediate.cer
- one or more intermediate certificates -
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-6 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
-
Archive the temporary keys[date] folder to a safe location as this contains sensitive information.
-
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:\xstore\keys
:pos.private.jks
eftlink.public.jks
-
This will leave only the following two files on the EFTLink server in the folder [eftlink root]\keys:
eftlink.private.jks
pos.public.jks
-
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.
-
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.
Step 6 - Configuring the Core
See the Oracle Retail EFTLink Core Configuration Guide located on OHC
and refer to the chapter for the specific core selected.
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 onOHC
for more details. -
AJB FiPay: The
AJBComm.jar
component needs to be copied toC:\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 onOHC
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.
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.