Monetra
®
Software Installation Guide
Install Guide v5.5
Updated September 2006
Copyright 1999-2006 Main Street Softworks, Inc.
The information contained herein is provided “As Is” without warranty of any kind, express or
implied, including but not limited to, the implied warranties of merchantability and fitness for a
particular purpose. There is no warranty that the information or the use thereof does not
infringe a patent, trademark, copyright, or trade secret.
Main Street Softworks, Inc. shall not be liable for any direct, special, incidental, or consequential
damages resulting from the use of any information contained herein, whether resulting from
breach of contract, breach of warranty, negligence, or otherwise, even if Main Street has been
advised of the possibility of such damages. Main Street reserves the right to make changes to
the information contained herein at anytime without notice. No part of this document may be
reproduced or transmitted in any form or by any means, electronic or mechanical, for any
purpose, without the express written permission of Main Street Softworks, Inc.
v5.5
Monetra Installation Guide
2
Table of Contents
1 Overview........................................................................................................................................................4
1.1 Document Revisions............................................................................................................................. 4
1.2 Related Documentation.........................................................................................................................4
2 Pre Installation .............................................................................................................................................. 5
2.1 Platform Specific Notes........................................................................................................................ 5
2.1.1 Linux............................................................................................................................................ 5
2.1.2 FreeBSD....................................................................................................................................... 5
2.1.3 Solaris...........................................................................................................................................5
2.1.4 IBM AIX...................................................................................................................................... 5
2.1.5 SCO OpenServer.......................................................................................................................... 6
2.1.6 Mac OS X.....................................................................................................................................6
2.1.7 Microsoft Windows®...................................................................................................................6
2.2 Communication Notes...........................................................................................................................6
2.2.1 Supported Internal Application Connections............................................................................... 7
2.2.2 Supported External Application Connections.............................................................................. 7
2.3 Data Storage Notes................................................................................................................................8
2.3.1 Monetra Database.........................................................................................................................8
2.3.2 SQL Database...............................................................................................................................8
2.4 Security Notes....................................................................................................................................... 8
2.4.1 IP/SSL.......................................................................................................................................... 9
2.4.2 Data Encryption............................................................................................................................9
3 Installation .................................................................................................................................................. 10
3.1 Monetra Installer Utility......................................................................................................................10
3.1.1 Table Headers.............................................................................................................................11
3.1.2 Available Functions....................................................................................................................12
3.2 Installation on Unix/Linux.................................................................................................................. 12
3.2.1 Download the Monetra Installer Utility......................................................................................12
3.2.2 Installing Software via the Console............................................................................................13
3.2.3 Installing Software via the GUI interface...................................................................................17
3.3 Installation on Mac OS X....................................................................................................................18
3.3.1 Download and Install the Monetra Installer Utility....................................................................18
3.3.2 Install Remaining Software........................................................................................................ 21
3.4 Installation on Microsoft® Windows..................................................................................................24
3.4.1 Download and Install the Monetra Installer Utility....................................................................24
3.4.2 Install Remaining Software........................................................................................................ 26
4 Upgrading.................................................................................................................................................... 29
4.1 Upgrading Monetra from a Pre 5.x series .......................................................................................... 29
4.2 Upgrading Monetra 5.x series ............................................................................................................30
4.2.1 Run the Monetra Installer...........................................................................................................30
5 Uninstallation...............................................................................................................................................31
5.1.1 Run the Monetra Installer...........................................................................................................31
v5.5
Monetra Installation Guide
3
1 Overview
1.1 Document Revisions
This document was reformatted 01/03/2006.
1.2 Related Documentation
•
•
•
Monetra Protocol Guide
Monetra Configuration Guide
Monetra Secure Implementation Guide
v5.5
Monetra Installation Guide
4
2 Pre Installation
The very first step in installing Monetra will be ensuring that your platform is ready to go. Major
points of interest include system communications, data storage and payment application
security.
2.1 Platform Specific Notes
Designed in C and conforming to POSIX standards, Monetra runs on many of today's most
advanced operating systems including Linux, FreeBSD, Mac OS X and Microsoft Windows XP. We
have outlined some notes below to point out platform-specific information you should be aware
of prior to installing Monetra.
2.1.1 Linux
Monetra is a self-contained application developed on the Linux platform and ported to other
OS’s. Multiple Linux distributions are supported (even hand crafted); its only requirement for
Linux systems is that you have one of the following versions of GLIBC on your machine:
GLIBC 2.1
GLIBC 2.2
GLIBC 2.3
http://www.gnu.org/software/libc/libc.html
2.1.2 FreeBSD
Monetra has been ported and tested to run optimally on the FreeBSD 4 and FreeBSD 5 series.
2.1.3 Solaris
Monetra has been ported and tested to run optimally on Sun Solaris 8 and Sun Solaris 9 (SPARC),
but should also operate just fine on Solaris 7.
Note:
Additional configuration may be required for this OS due to the missing random number
generator. Several free utilities are available to provide these services and are annotated in the
configuration section.
2.1.4 IBM AIX
Monetra has been ported and tested to run optimally on IBM AIX 4.3.3 and AIX 5.1
Note:
Additional configuration may be required for this OS due to the missing random number
generator. Several free utilities are available to provide these services and are annotated in the
configuration section.
v5.5
Monetra Installation Guide
5
2.1.5 SCO OpenServer
Monetra has been ported and tested to run optimally on SCO OpenServer release 5
Notes:
1) Additional configuration may be required for this OS due to the missing random number
generator. Several free utilities are available to provide these services and are annotated
in the configuration section.
2) If libsocket.so.2 does not exist on your system create a symlink to libsocket.so.1
3) For OpenServer 5.0.[4-6] the patches 'oss646b or higher', and
'oss631b or higher' may be required.
2.1.6 Mac OS X
Monetra has been ported and tested to run optimally on Mac OS X 10.2 (Jaguar) and OS X 10.3
(Panther).
Note:
As of Monetra 4.0, Panther will be the default build environment, and although we port and test
on Jaguar, you might be required to upgrade to the latest Mac platform to obtain SLA support
offerings.
2.1.7 Microsoft Windows®
Monetra has been ported and tested to run optimally on Microsoft Windows, version 95 through
XP to include Server 2000 and 2003.
Note:
As of Monetra 4.0, Windows Server 2003 will be the default build environment and although we
port and test on alternate and legacy Windows products, you might be required to upgrade to
the latest supported platform from Microsoft to obtain SLA support offerings. To remain
compliant with PCI/CISP and other security standards you must be able to provide OS level
security patches to your systems and thus, you must be running a vendor supported OS.
v5.5
Monetra Installation Guide
6
2.2 Communication Notes
Monetra is classified as a "middleware" software product. With that said, Monetra must be set
up to provide both "internal" and "external" connections. It is helpful to keep in mind what
communication functionality is required prior to setting up the engine.
2.2.1 Supported Internal Application Connections
Internal: These connections facilitate communication between Monetra and the client application
(like POS and WWW). Currently this connectivity is provided via a modular subsystem, and
supported modules include Drop File (shared directory), TCP/IP and SSL.
Connection Type
Description
DropFile
Provides a quick and reliable method to communicate with Monetra to
process transactions. Although IP or SSL connections are recommended,
the DropFile does provide for legacy application connectivity. Please
review the Monetra Secure Implementation Guide when implementing
drop files.
TCP/IP
Client applications can use standard TCP/IP socket to pass transactions
to Monetra. You will need to ensure you have an IP stack installed and
functioning on your system prior to installing Monetra.
SSL
HTTP/HTTPS
Client applications can use Secured Sockets Layer (SSL) to pass
transactions to Monetra. For an overview of SSL, please review online
F.A.Q's at http://www.monetra.com.
Client application can use our XML message format to communicate with
the Monetra server. For an overview of XML, please review the Monetra
Protocol Guide available at http://www.monetra.com.
2.2.2 Supported External Application Connections
External: These connections facilitate communication between the Monetra Payment engine and
the processing institutions. Currently Monetra can utilize modems, HTTPS (Internet) and Frame
Relay (IP) connections for outbound processing.
Connection Type
Modems
Description
Even if you plan on connecting via HTTPS or frame-relay, it is highly
recommended to configure a modem for fail-over processing. Modems
are supported as a communications link across all certified platforms.
Multiple modems can be used simultaneously and they do not have to
be of the same brand/make/model.
Please consider the following:
v5.5
•
most processing is done at 1200 bps or less so that old modems
will work great.
•
Monetra provides for configuring initialization strings on a per
modem basis (take note of your modem's init strings)
Monetra Installation Guide
7
•
Main Street has found that USR's brand of modems have been
successfully used by clients across all platforms (no, we do not
sell USR modems)
HTTPS/SSL via
Internet
Certain processors allow direct connectivity via SSL/HTTPS (Internet) for
authorization and settlement requests. Main Street can provide the
connection parameters for you, but be advised of potential security
settings (like firewall etc.) that may need adjustment. Please visit our
online F.A.Q's for more information on connecting to the processor via
the Internet.
Frame Relay (IP)
Monetra supports direct processing via dedicated circuits to multiple
processing institutions. Please be advised that these lines must be
provisioned from the chosen processor, and that Monetra may need to
be verified (tested) once in place prior to the system going live. Typical
turnaround on a dedicated ckt/Monetra setup is 60 days.
2.3 Data Storage Notes
Monetra allows you to choose between the Monetra proprietary database and an SQL database
of your choice. Both database layouts are structured the same within Monetra, so neither will
give you more functionality in Monetra than the other. Any decision between the two should be
based on redundancy/volume.
2.3.1 Monetra Database
The Monetra proprietary database is designed to be used where the use of an SQL database
server is not convenient. The internal format of this database is optimized for Monetra, and
currently allows for the highest volume per minute while executing transactions. Drawbacks to
this database are audit-level query performance and data replication provided by most SQL
databases.
2.3.2 SQL Database
SQL database support in Monetra is targeted towards high transaction load servers where
hundreds of thousands of transactions will be initiated each year (or even each month!). SQL
databases provide the speed and reliability needed to store and recall high-volume transaction
data.
Prior to installing Monetra, ensure that you have your database properly installed with the
following parameters configured:
•
•
•
Database: Create a database named “Monetra”.
Security: Set the permissions on the database and note the username and password for the
“Monetra” database (for future configuration entries).
Connection: If the database is a remote machine, note the IP address and port number used
to connect (for future configuration entries).
Note:
If you use MYSQL, please read this! SQL databases now REQUIRE Transactional Support.
Specifically, this applies to MySQL. If running MySQL v3.23.x, you MUST be using INNODB to
enable Transactional support. MySQL v4 should have this enabled by default.
v5.5
Monetra Installation Guide
8
2.4 Security Notes
Monetra provides an advanced solution for the security-conscious company. Whether it's
getting the transaction to Monetra securely or how Monetra handles that transaction once it's
been received, our primary focus while developing Monetra was the security of our clients'
customer data.
Note: Please review the Monetra Secure Implementation Guide for further information.
2.4.1 IP/SSL
If you will be running Monetra in IP mode, you may want to consider securing your
communications via (SSL) or other similar encryption schema. It is also recommended to deploy
Monetra's extended firewall rule set features as outlined in the secure implementation guide.
2.4.2 Data Encryption
Monetra fully supports strong algorithmic encryption to provided safe data storage. Multiple
algorithms and key-lengths may be used so please review the . Monetra Secure Implementation
Guide prior to setting any values.
v5.5
Monetra Installation Guide
9
3 Installation
3.1 Monetra Installer Utility
As of version 5.0, Main Street provides an advanced Installation and Update utility for all
supported platforms called the Monetra Installer. The utility is provided in both Graphical (GUI)
and command line (console) binary executable form.
The installation instructions provided in this manual describe the procedures when using the
Monetra Installer. If you have a need to install software without using the Installer Utility then
please contact support@monetra.com
Example: Screen shots of the Installer running on multiple platforms can be viewed below:
GUI Installer on Microsoft Windows
GUI Installer on Linux
v5.5
GUI Installer on Mac OS X
Console Installer on Linux
Monetra Installation Guide
10
3.1.1 Table Headers
When you are logged into the installer, you should be presented with a table displaying the
following header information: Note: Rows in GREEN indicate Installed, rows in YELLOW indicate
an upgrade is available, rows in RED indicate an available license that is not installed and rows in
GREY indicate a license that is unavailable.
LICENSEID: This is the license number on file for any particular software product.
PRODUCT: This is the friendly name of the software product as licensed.
OS: This represents the operating system and architecture of the software product licensed.
TYPE: This defines whether or not the license is REAL or a DEMO.
STATUS: This notifies user if the software is installed or not.
VER INST: This represents the software version installed on the system.
Latest Ver: This represents newest version available.
INST CNT: This represents the number of times the software has been installed/reinstalled.
3.1.2 Available Functions
The Monetra Installer utility provides for the following Functions...
INSTALL/REINSTALL: The install -reinstall button provides a means to install new products.
UNINSTALL: The Uninstall button will remove the selected software product from the
system.
UPGRADE: The upgrade button will download and upgrade the software to the most current
release based on license eligibility.
UPDATE: The license update button will download the most current license file and install it to
the system.
TRANSFER: The transfer license button will transfer one eligible license for another (For
example, this would be used to transfer a DEMO license to a REAL license).
NFO: The info button will list out all the details for a particular product/license.
v5.5
Monetra Installation Guide
11
3.2 Installation on Unix/Linux
While the instructions provided in this section are targeted towards Linux users, the information
applies to all Unix/Unix_like Operating environments.
NOTE: These instructions assume the target server has a functioning Internet connection. If you
need to download the software onto a CDROM then please contact support@monetra.com
3.2.1 Download the Monetra Installer Utility
•
Visit our website at http://www.monetra.com and log into the client section with your email
address and passcode. Choose the 'Licenses' link at the top of the page.
•
Download the Monetra Installer for your version of GLIBC (download section at top)
•
Once downloaded, extract the tarball
gunzip < monetrainstaller-linux-x86-glibc23-1.0.9.tar.gz | tar xvpf -
•
Enter directory created
cd monetrainstaller-linux-x86-glibc23-1.0.9
•
Run the monetra installer utility. Note, if you do not have a windowing environment set up
(i.e. X-Windows), then use the console application.
./monetrainstaller_console
If you do have X-Windows running you may run the graphical installer
./monetrainstaller
v5.5
Monetra Installation Guide
12
3.2.2Installing Software via the Console
The following section outlines the installation of software using the console front end to the
installer application.
STEP 1. Run the Installer Utility
Upon running the utility, the first option is to determine if you want to perform a 'Live' install
via the Internet (requires Internet connection on target server, broadband recommended) or if
you have a package already on the target server. (note: You may download packages from the
client section of our website).
v5.5
Monetra Installation Guide
13
STEP 2. Enter your Main Street Client Credentials.
When registering for any software product from Main Street (or one of our Partners) you should
have been provided with an email and pass code to access the client area of our website. The
same credentials used to access the website should be entered here.
Note: At any time you may access the client section of our website and update your company
profile.
v5.5
Monetra Installation Guide
14
STEP 3. Choose Software to Install.
If this is a new install, you will be prompted to install multiple applications. Choose YES.
Note: While applications can be installed/uninstalled and upgraded one at a time, it is easier
(on initial install) to install all of them at once.
v5.5
Monetra Installation Guide
15
STEP 4. End User License Agreement.
For each software product installed, you will be presented with an End User License Agreement.
You must accept the agreement to continue.
v5.5
Monetra Installation Guide
16
STEP 5. Finish Up.
Upon successful completion, you should get a screen similar to the following.
Thats it, you can now continue with configuring the Payment Engine, as described in the
Monetra Configuration Guide.
3.2.3 Installing Software via the GUI interface
If you choose to use the GUI application, then you may follow any of the examples provided
for Windows or Mac, outlined below.
Note: This assumes that the machine installing the Monetra Installer has the X-libraries
available.
•
If X-Windows is running on the local machine and you wish to use the GUI installer, you must
make sure that users other than yourself (i.e. root) on the same machine have access
to the display: * xhost +localhost
•
If X-Windows is running on a separate machine and you have logged in via SSH with X11forwarding enabled, you should not have to configure anything more to utilize the GUI
installer.
•
If X-Windows is running on a separate machine and you wish to use the GUI installer by
exporting the DISPLAY over your network, you need to make sure the remote machine has
permissions to send X-messages to the machine running X-Windows; and you also need to
point the DISPLAY environment variable to the proper locations. (Examples use 192.168.1.10
as remote IP running X-Windows; replace this with appropriate IP address).
* xhost +192.168.1.10 (On machine running X-Windows)
* export DISPLAY=192.168.1.10:0.0 (On machine you wish to install the Monetra installer)
v5.5
Monetra Installation Guide
17
3.3 Installation on Mac OS X
3.3.1 Download and Install the Monetra Installer Utility
Note:
This overview describes installation on the Apple Macintosh, OS X platform. Note: If you run
Microsoft Windows or Mac OS X as an operating system, you may find the most current versions
of the Monetra Installer in the General Support section of our website, under the downloads link.
Or you may find them at this URL:
Http://www.monetra.com/downloads.html
Step 1: Once the Installer has downloaded and been extracted, you should see a package file
(.pkg) name MonetraInstaller. Double click this package to install the MonetraInstaller.
Step 2: You should see a dialog box similar to the one above. Choose the Continue button.
Note: Along the way you might be prompted for your Administrative Password (while installing
software, or running tools with elevated privileges).
v5.5
Monetra Installation Guide
18
Step 3: To continue, you must Accept the License Agreement.
Step 4: You will now be asked to select a drive destination. Select a drive and click Continue.
v5.5
Monetra Installation Guide
19
Step 5: After a short installation routine is run, you should see the following message.
v5.5
Monetra Installation Guide
20
3.3.2 Install Remaining Software
Once the Monetra Installer has been setup on your system, you may now run it to install all other
Main Street software.
Note: You will need one of the following to proceed:
a) For a live install, you will need the credentials (email and passcode) that were assigned to you
by a Main Street partner or associate.
b) For an offline install, you will need the appropriate package file which can be downloaded
from the client section of our website.
Note: If this is your first time installing, and you have a package of software products, the
installer might prompt you to install all XX number of products.
Step 1: Run the Monetra Installer by navigating to the Applications directory, then inside the
Monetra folder:
Applications-->Monetra-->Monetra Installer
Step 1: When presented with the 'Welcome' screen, choose 'Next'.
v5.5
Monetra Installation Guide
21
Step 2a: If you are performing a 'Live' install, enter your email address and pass code, then
choose the 'Next' button.
Step 2b: If you are installing 'offline', choose the 'Have Disk' button.
Note: You must have already downloaded the appropriate package/files to proceed.
Step 3: If this is an initial/fresh install, you can choose to install all programs or simply
highlight the appropriate software product and choose the 'Install' button.
v5.5
Monetra Installation Guide
22
Step 4: Upon successful installation you should see the following dialog. Choose OK to exit.
At this point the Monetra Payment Engine (and associated utilities) should be installed and
ready for initial configuration.
Please reference the Monetra Configuration Guide for more details.
v5.5
Monetra Installation Guide
23
3.4 Installation on Microsoft® Windows
3.4.1 Download and Install the Monetra Installer Utility
Note:
This overview describes installation on the Microsoft Windows platform, but should be similar
across all other supported platforms. If you run Microsoft Windows or Mac OS X as an operating
system, you may find the most current versions of the Monetra Installer in the General Support
section of our website, under the downloads link. Or you may find them at this URL:
Http://www.monetra.com/downloads.html
Step 1: Double click the installer .exe file to run the installation.
Step 2: When asked to continue installation, choose Yes.
v5.5
Monetra Installation Guide
24
Step 3: To continue, you must Accept the License Agreement.
Step 4: Use the default Install path or choose an alternate and click Submit.
Step 5: After a short installation routine is run, you should see the following message.
v5.5
Monetra Installation Guide
25
3.4.2Install Remaining Software
Once the Monetra Installer has been setup on your system, you may now run it to install all other
Main Street software.
Note: You will need one of the following to proceed:
a) For a live install, you will need the credentials (email and passcode) that were assigned to you
by a Main Street partner or associate.
b) For an offline install, you will need the appropriate package file which can be downloaded
from the client section of our website.
Note: If this is your first time installing, and you have a package of software products, the
installer might prompt you to install all XX number of products.
Step 1: Run the Monetra Installer by navigating to the programs folder:
START-->Programs-->Monetra-->Monetra Installer
Step 1: When presented with the 'Welcome' screen, choose 'Next'.
v5.5
Monetra Installation Guide
26
Step 2a: If you are performing a 'Live' install, enter your email address and pass code, then
choose the 'Next' button.
Step 2b: If you are installing 'offline', choose the 'Have Disk' button.
Note: You must have already downloaded the appropriate package/files to proceed.
Step 3: If this is an initial/fresh install, you can choose to install all programs or simply
highlight the appropriate software product and choose the 'Install' button.
v5.5
Monetra Installation Guide
27
Step 4: Accept the License Agreement to continue.
Step 5: Upon successful installation you should see the following dialog. Choose OK to exit.
At this point the Monetra Payment Engine (and associated utilities) should be installed and
ready for initial configuration.
Please reference the Monetra Configuration Guide for more details.
v5.5
Monetra Installation Guide
28
4 Upgrading
4.1 Upgrading Monetra from a Pre 5.x series
If you are running a 2.0 or 2.1 series you must first upgrade to 2.1.3 for proper export.
If you are running a 2.5 series you must first upgrade to 2.5.6 for proper export.
If you are running a 3.0 series you must first upgrade to 3.0.1 for proper export.
All versions released after 3.0.1 can properly export application data.
Step 1. Settle all transactions.
Step 2. Export data
Step 3. Stop Monetra
Step 4. (optional) Back Up Monetra directories.
Step 5. Move previous Monetra/MCVE
mv /usr/local/{monetra|mcve} /usr/local/{monetra|mcve}-old
mv /etc/{monetra|mcve} /etc/{monetra|mcve}-old
Step 6. Install Monetra 5.x via the Monetra Installer utility.
Step 7. Verify configuration settings (/etc/*.conf)
Step 8. Import Data
If you have questions regarding upgrading your current software then please contact us via
support@mainstreetsoftworks.com.
v5.5
Monetra Installation Guide
29
4.2 Upgrading Monetra 5.x series
This procedure describes upgrading software via the Monetra Installer Utility using an internet
connection. If you need to upgrade outside of the installer utility, or download a package file
then please contact support@monetra.com
4.2.1 Run the Monetra Installer
The first step is to run the Monetra Installer, and log in via the supplied credentials (email, pwd)
Step 1: When inside the Installer Main View, Select the software product you would like to
upgrade by Highlighting the row. Note: If there is new software available, it will be noted in the
STATUS column.
Step 2: Click on the Upgrade button.
Step 3: A dialog box will prompt, asking for the version you would like to upgrade to (note: in
most situations, you should leave this as defaulted).
Choose your version, and hit Submit.
v5.5
Monetra Installation Guide
30
5 Uninstallation
This procedure assumes you used the Monetra Installer utility to install all software packages. If
at any time you have questions regarding un-installation of our software products, then please
contact support@monetra.com
5.1.1 Run the Monetra Installer
The first step is to run the Monetra Installer, and log in via the supplied credentials (email, pwd)
Step 1: When inside the Installer Main View, select the software product you would like to UnInstall by Highlighting the row. Note: You can verify it is installed by reviewing the STATUS
column.
Step 2: Click on the Un-install button.
Step 3: A dialog box will prompt, asking if you are sure you want to un-istall the software
product.
To completely un-install click on the Yes button.
v5.5
Monetra Installation Guide
31