Axway API Gateway Installation Guide

Axway API Gateway Installation Guide
 API Gateway
Version 7.5.3
9 November 2017
Installation Guide
Copyright © 2017 Axway
All rights reserved.
This documentation describes the following Axway software:
Axway API Gateway 7.5.3
No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway.
This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free.
Axway recognizes the rights of the holders of all trademarks used in its publications.
The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site.
Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.
Contents
Preface
9
Who should read this guide
9
How to use this guide
9
API Management documentation set
10
API Gateway documentation
10
API Manager and API Portal documentation
11
Related documentation
11
Support services
12
Training services
12
Accessibility
13
Screen reader support
13
Support for high contrast and accessible use of colors
13
Updates and revisions
Changes in 7.5.3
1 Quick start installation
14
14
15
Before you begin
15
Installation
15
Post-installation
16
2 Prerequisites
System requirements
17
17
Operating systems and hardware
17
Databases
19
Web browsers
19
Thick client platforms
19
Docker containers
20
Specific component requirements
20
Default ports
21
API Gateway
21
Admin Node Manager
21
Policy Studio
21
API Gateway Manager
21
API Manager
21
API Gateway Analytics
22
Software and license keys
22
Check your authorization
Axway API Gateway 7.5.3
22
Installation Guide 3
License keys
22
Multiple installations
23
Additional prerequisites
23
UNIX/Linux platforms
23
Service packs
24
Certificates
24
3 Plan the deployment
25
Platforms
25
API Gateway components
25
Client components
25
High availability
25
Connection to other products
4 Install API Gateway
26
27
Prerequisites
27
Installation modes
27
Start installation
28
Installation options
28
Welcome
28
License agreement
28
Select setup type
28
Select components
29
Specify installation directory
29
Specify license file
30
Cassandra configuration
30
Set the administrator user name and password
30
Specify QuickStart Node Manager details
31
Specify QuickStart server details
31
Set the administrator user name and password for API Manager
31
Acknowledge API Gateway Analytics information
32
Installation summary
32
Installing
32
Installation complete
32
Unattended installation
32
Run the installer in unattended mode
33
Unattended mode options
34
5 Install Apache Cassandra
Install an Apache Cassandra database
37
37
Prerequisites
38
Install Apache Cassandra
39
Further details
40
Cassandra deployment architectures
Axway API Gateway 7.5.3
40
Installation Guide 4
Cassandra in standalone mode
41
Cassandra in High Availability mode
42
Configure a Cassandra HA cluster
45
Cassandra HA in a production environment
45
Upgrade from previous API Gateway version
46
Cassandra HA configuration
46
Example Cassandra HA configuration in a production environment
47
Step 1 – Configure and verify the Cassandra HA cluster (non-secure)
50
Step 2 – Configure the client settings for API Gateway or API Manager
54
Step 3 – Secure the Cassandra HA configuration and verify
58
Automate API Gateway Cassandra client settings
58
Further details
59
Manage Apache Cassandra on UNIX/Linux and Windows
59
Manage Apache Cassandra on UNIX/Linux
59
Manage Apache Cassandra on Windows
61
Connect to API Gateway for the first time
63
Further details
64
Perform essential Cassandra operations
64
Perform anti-entropy repair
64
Replace dead nodes
65
Back up and restore Cassandra data
65
Back up configuration and data for disaster recovery
65
Ensure time is in sync across the cluster
66
Reconfigure an existing Cassandra installation from scratch
67
Monitor the Cassandra cluster using JMX
67
Upgrade your Cassandra version
67
Further details
67
setup-cassandra script reference
67
Prerequisites
68
Run the setup-cassandra script
69
Configure the seed node
70
Configure additional nodes
70
Secure Cassandra HA configuration
71
Updated Cassandra configuration
73
6 Install API Gateway components
Install the API Gateway server
75
75
Prerequisites
75
Install the API Gateway server
76
Before you start API Gateway
76
Start API Gateway
76
Install the QuickStart tutorial
77
Prerequisites
77
Install the QuickStart tutorial
78
Axway API Gateway 7.5.3
Installation Guide 5
QuickStart domain configuration
78
Start the QuickStart tutorial
78
Restart the QuickStart tutorial
79
Install the Admin Node Manager
80
Prerequisites
80
Install the Admin Node Manager
80
Start the Admin Node Manager
81
Install Policy Studio
81
Prerequisites
81
Install Policy Studio
81
Start Policy Studio
81
Install Configuration Studio
82
Prerequisites
82
Install Configuration Studio
82
Start Configuration Studio
83
Install API Tester
83
Prerequisites
83
Install API Tester
83
Start API Tester
84
Install API Manager
84
Prerequisites
84
Install API Manager
85
Configure API Manager
86
Start API Manager
86
Install the Package and Deploy tools
86
Prerequisites
86
Install the Package and Deploy tools
87
7 Install and configure API Gateway Analytics
Install API Gateway Analytics
88
88
Prerequisites
88
Install API Gateway Analytics
88
Configure your API Gateway Analytics database
89
Start API Gateway Analytics
89
Further information
90
Configure the metrics database
90
Prerequisites
90
Add third-party JDBC driver files
91
Create the database
92
Set up the database tables
92
Specify options to dbsetup
93
SQL database schema scripts
95
Configure API Gateway Analytics
Prerequisites
Axway API Gateway 7.5.3
95
95
Installation Guide 6
Update API Gateway Analytics configuration
96
Enable metrics for your API Gateway host
99
8 Post-installation
Verify the installation
101
101
Check the installation log
101
Start API Gateway components
101
Log in to the API Gateway tools
102
Initial configuration
102
Create a new domain
102
Set up a database for API Gateway Analytics
102
Secure API Gateway
103
Change default passwords
103
Change default certificates
103
Encrypt API Gateway configuration
103
Run as non-root on UNIX/Linux
103
Set up services
103
API Gateway
103
API Gateway Analytics
104
Apache Cassandra
104
Set up clustering
105
Next steps
105
9 Configure API Management in multiple datacenters
Multi-datacenter deployment
106
106
Multi-datacenter deployment architecture
106
API Management data storage
108
Further details
109
Multi-datacenter configuration
109
API Management configuration
110
Configure Cassandra for multiple datacenters
111
Configure API Management in multiple datacenters
116
Optimize API Management performance in a multi-center environment
121
Configure Ehcache in multiple datacenters
123
Configure API Manager quota in multiple datacenters
127
Further details
127
Multi-datacenter failover scenarios
127
One API Gateway instance is down
128
One Cassandra node is down
128
A full datacenter is down
129
The network between both datacenters is down
131
Further details
132
Axway API Gateway 7.5.3
Installation Guide 7
10 Run API Management in Docker
133
API Management in Docker containers
134
Create Docker images using scripts
134
Run pre-built Docker images
135
API Management Docker HA topology
135
Deploy your Docker infrastructure to the cloud
137
Further information on Docker
137
Run pre-built API Management Docker images
137
Prerequisites
137
Run pre-built API Management images in a developement or test environment
138
Test the API Management system
138
Generate API Management Docker images
139
Set up your local environment
139
Create your API Management Docker infrastructure
140
Troubleshooting
144
Customize your API Management topology in Docker
144
Create Docker data volumes for persistence
144
Delete data volumes
151
Test your API Management system
151
12 Update API Gateway
153
Install a service pack or patch
153
Resolve patch validation issues
153
Cannot validate, no checksum available
154
Content changed
154
File not found
155
Malformed file
155
Unexpected file
155
Verify which hosts have service packs or patches installed
License acknowledgments
156
157
Overview
157
Acknowledgments
157
Axway API Gateway 7.5.3
Installation Guide 8
Preface
This guide describes how to install API Gateway components on all supported platforms.
Who should read this guide
The intended audience for this guide is system engineers who are responsible for installing, configuring, and maintaining API Gateway.
Before installing API Gateway you should have an understanding of API Gateway concepts and features. For more information, see the API Gateway Concepts Guide.
Others who might find parts of this guide useful include network or systems administrators and other technical or business users.
How to use this guide
This guide should be used in conjunction with the other guides in the API Gateway documentation set.
Before you begin installing API Gateway, review this guide thoroughly. The following is a brief description of the contents of each section:
l Quick start installation on page 15 – Enables you to install quickly using standard settings.
l Plan the deployment on page 25 – Describes what you should consider when planning for deploying and configuring your system architecture.
l Prerequisites on page 17 – Describes the prerequisites for installing, including the system requirements.
l Install API Gateway on page 27 – Describes how to perform an installation using the GUI mode or unattended command-line mode.
l Install API Gateway components on page 75 – Describes how to install the API Gateway components.
l Post-installation on page 101 – Provides instructions on how to check if the installation was successful and describes additional tasks, such as securing API Gateway, that you should perform after installation.
l Run API Gateway in Docker containers – Describes how to build and run a sample multi-node API Gateway system in Docker, and how to customize this recommended API Gateway topology to suit your environment.
l Update API Gateway on page 153 – Describes how to apply service packs or patches to update your API Gateway installation.
Axway API Gateway 7.5.3
Installation Guide 9
Preface
API Management documentation set
API Gateway documentation
The API Gateway documentation set includes the following guides:
l API Gateway Installation Guide
Describes how to install API Gateway components on all platforms.
l API Gateway Upgrade Guide
Describes how to upgrade previous API Gateway versions.
l API Gateway Concepts Guide
Provides an overview of the API Gateway components, tools, and architecture.
l API Gateway Administrator Guide
Describes how to configure and manage an API Gateway domain.
l API Gateway Policy Developer Guide
Describes the main API Gateway features and how to configure them using the Policy Studio graphical tool.
l API Gateway Policy Developer Filter Reference
Describes the filters that you can use when developing policies in Policy Studio, and how to configure them.
l API Gateway DevOps Deployment Guide
Describes how to promote and deploy API Gateway configuration between different environments (for example, development, testing, and production).
l API Gateway OAuth User Guide
Describes how to configure API Gateway for OAuth 2.0 and OpenID Connect.
l API Gateway Developer Guide
Describes how to extend, leverage, and customize API Gateway.
l API Gateway Key Property Store User Guide
Describes how to use the Key Property Store (KPS) to configure and manage data referenced from policies running on API Gateway.
l API Gateway Appliance Installation and Administration Guide
Describes how to install, configure, and administer the API Gateway Appliance.
l API Gateway Kerberos Integration Guide
Describes how to integrate API Gateway with Kerberos SPNEGO authentication.
l API Gateway Authentication and Authorization Integration Guide
Describes how to integrate API Gateway with Identity Management systems (for example, LDAP servers, CA Siteminder, and so on).
Axway API Gateway 7.5.3
Installation Guide 10
Preface
l API Gateway PassPort Interoperability Guide
Describes how to configure API Gateway and Axway PassPort to work together.
l API Gateway Sentinel Interoperability Guide
Describes how to configure API Gateway and Axway Sentinel to work together.
l API Gateway Validation Authority Interoperability Guide
Describes how to configure API Gateway and Axway Validation Authority to work together.
API Manager and API Portal documentation
The API Manager and API Portal documentation set includes the following guides:
l API Manager User Guide
Describes how to use the API management features available separately in API Manager. API Manager is an additional licensable layered product running on API Gateway.
l API Portal Installation and Upgrade Guide
Describes how to install or upgrade API Portal. API Portal is an additional layered product running on API Gateway. l API Portal Administrator Guide
Describes how to customize and manage API Portal.
l API Portal User Guide
Describes how to use API Portal.
Related documentation
The API Management Plus solution enables you to create, publish, promote, and manage Application Programming Interfaces (APIs) in a secure and scalable environment. For more information, see the API Management Plus Getting Started Guide.
The following reference documents are available on the Axway Documentation portal at http://docs.axway.com:
l Supported Platforms
Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product.
l Interoperability Matrix
Provides product version and interoperability information for Axway products.
Axway API Gateway 7.5.3
Installation Guide 11
Preface
Support services
The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements.
Email [email protected] or visit Axway Support at https://support.axway.com.
See "Get help with API Gateway" in the API Gateway Administrator Guide for the information that you should be prepared to provide when you contact Axway Support.
Training services
Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: http://www.axway.com/support-services/training
Axway API Gateway 7.5.3
Installation Guide 12
Accessibility
Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features:
l Screen reader support on page 13
l Support for high contrast and accessible use of colors on page 13
Screen reader support
l Alternative text is provided for images whenever necessary. l The PDF documents are tagged to provide a logical reading order.
Support for high contrast and accessible use of
colors
l The documentation can be used in high-contrast mode.
l There is sufficient contrast between the text and the background color.
l The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway API Gateway 7.5.3
Installation Guide 13
Updates and revisions
Updates and revisions
This guide includes the following documentation changes.
Changes in 7.5.3
l Updated the system requirements with the latest details on supported versions.
l Added new topics on configuring API Management in multiple datacenters:
o Multi-datacenter deployment architecture
o Multi-datacenter configuration
o Multi-datacenter failover scenarios
l Updated the Apache Cassandra topics with support for Cassandra version 2.2.8 and the native Datastax client (replacing the Hector client used in previous versions).
l The section on upgrading from Cassandra version 2.2.5 to Cassandra 2.2.8 has moved from the topic on installing Cassandra to the API Gateway Upgrade Guide.
l Updated the topic on the setup-cassandra script with automatic backup of cassandra.yaml, and for use with remote Cassandra deployments.
l Restructured the Cassandra topics, adding separate new topics for:
o Cassandra deployment architecture
o Manage Cassandra on UNIX/Linux and Windows
l Restructured the topic on Docker containers, adding separate new topics for:
o Docker deployment architecture
o Run pre-built Docker images (for development and test only)
o Generate Docker images for HA production environments
o Customize your API Management Docker environment
l Updated the post-installation topic with details on running API Gateway Analytics as a service on Windows.
l Updated the topic on API Gateway Analytics configuration with clarification on the characters supported by the username and password provided to the configureserver script.
l Updated the topic on system requirements with support for the MariaDB database.
Axway API Gateway 7.5.3
Installation Guide 14
Quick start installation
1
This topic describes how to perform a quick start installation of API Gateway. A quick start installation is a simple, standard installation of API Gateway (for example, for a demonstration or proof of concept).
The API Gateway installer provides a default Standard installation option, which installs the following API Gateway components:
l API Gateway Server
l QuickStart Tutorial
l API Gateway Analytics
l Policy Studio
l Configuration Studio
l Package and deployment tools
The Standard option also installs an external Apache Cassandra database, which is used to store API Gateway and API Manager data. For more details, see Installation options on page 28.
For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Before you begin
In preparation for a quick start installation, perform the following tasks:
1. Check that your target system meets the system requirements. For more details, see Prerequisites on page 17.
2. Download the installation setup file for your target system.
3. Obtain the necessary license keys from your Axway Account Manager.
Installation
Locate and run the installation setup file. The installer launches in GUI mode by default. Follow the instructions on each window, accepting the default selections at each step. For more information on starting the installer, see Start installation on page 28.
When installation is complete, the Cassandra database, API Gateway instance, and Admin Node Manager processes are started, the QuickStart tutorial is launched in a browser window, and the Policy Studio desktop tool is started.
Axway API Gateway 7.5.3
Installation Guide 15
1 Quick start installation
Post-installation
You can use the QuickStart tutorial to invoke some example APIs and to monitor the API Gateway using API Gateway Manager. For more information on using API Gateway Manager, see the API Gateway Administrator Guide.
You can use the Policy Studio desktop tool to virtualize APIs and develop policies (for example, to enforce security, compliance, and operational requirements). To begin developing policies in Policy Studio, you must first open or create a new project. For example, follow these steps to create a new project from a running API Gateway instance:
1. When Policy Studio starts up, select File > New Project. 2. In the New Project dialog, enter a name for the project and click Next.
3. Select From a running API Gateway instance and click Next.
4. In the Open Connection dialog, select the Admin Node Manager session to connect to, enter the administrator user name and password that you specified during installation and click OK. 5. In the Download Options dialog, select the QuickStart Group and the QuickStart Server instance to download its configuration.
6. Click Finish.
For more information on using Policy Studio, see the API Gateway Policy Developer Guide.
Axway API Gateway 7.5.3
Installation Guide 16
2
Prerequisites
This topic describes the prerequisites for installing API Gateway. This includes the system requirements, any platform-specific preparation, required software and licenses, pre-installation tasks, and so on. You must ensure that your target system meets all of the prerequisites before installing API Gateway.
This topic includes the following:
l System requirements on page 17
l Default ports on page 21
l Software and license keys on page 22
l Additional prerequisites on page 23
System requirements
This section describes the supported platforms and other system requirements for Axway API Gateway, and specific requirements for API Gateway components. For more details on API Gateway components, see the API Gateway Concepts Guide. This section describes the requirements for specific API Gateway components (for example, P olicy Studio). For more details on appliance components, see the API Gateway Appliance Installation and Administration Guide. Operating systems and hardware
This section describes the operating system requirements for API Gateway. Platform
Linux
Supported versions
l CentOS 6.x, 7.x
l Oracle Linux 6.x, 7.x
l Red Hat Enterprise Linux 6.x, 7.x
Hardware prerequisites
l Supports 64-bit Linux running on 64-bit hardware
l Intel Core or AMD Opteron at 2Ghz with Dual Core or faster
l SUSE Linux Enterprise Server 11.x, 12.x
API Gateway might not run on systems that do not meet these requirements (see Note below).
Axway API Gateway 7.5.3
Installation Guide 17
2 Prerequisites
Platform
Supported versions
Windows
l Windows Server 2012 R2
l Windows Server 2012
l Windows 10
l Windows 8.1
Hardware prerequisites
l Supports 32-bit Windows on both 32-bit hardware and 64bit hardware
l Intel Core or AMD Opteron at 2Ghz with Dual Core or faster
Windows Server 2012 R2 is recommended in a production environment.
Note
When new Linux kernels and distributions are released, Axway modifies and tests its products for stability and reliability on these platforms. Axway makes every effort to add support for new kernels and distributions in a timely manner. However, until a kernel or distribution is added to this list, its use with API Gateway is not supported. Axway endeavors to support any generally popular Linux distribution on a release that the vendor still supports. Disk space and RAM requirements
The disk space and RAM requirements for UNIX/Linux and Windows platforms are:
l Disk space:
o Minimum 4 GB, 50 GB recommended on Windows and Linux
l Physical memory:
o Minimum 4 GB on Windows
o Minimum 8 GB on Linux
UNIX/Linux permissions
Note
UNIX/Linux platforms also require the following:
l Minimum 500 MB available in the /tmp d irectory and writable permissions on the /tmp , /var/tmp , and /usr/tmp directories.
l noexec must not be set on /tmp. If noexec is set, you must remount /tmp with noexec disabled. Axway API Gateway 7.5.3
Installation Guide 18
2 Prerequisites
Databases
This section describes the supported database versions.
Relational databases
API Gateway Analytics and API Manager support the following relational databases to store metrics data:
l MySQL Server 5.6, 5.7
l MariaDB 5.5, 10.1
l Microsoft SQL Server 2012, 2014
l Oracle 11.2, 12.1
l IBM DB2 10.5
For more details, see Install API Gateway Analytics on page 88.
Apache Cassandra
API Gateway and API Manager support Apache Cassandra version 2.2.8 and 2.2.5 for internal data storage. For more details, see Install an Apache Cassandra database on page 37.
Web browsers
API Gateway Manager and other browser-based client components support the following browsers:
l Internet Explorer 11
l Firefox 13.0 or higher
l Safari 5.1.7 or higher
l Google Chrome 19 or higher
l Microsoft Edge (on Windows 10 only)
Thick client platforms
Policy Studio runs on the same platforms as API Gateway with the following additional requirements on Linux and UNIX: l X-Windows environment
l GTK+ 2
Axway API Gateway 7.5.3
Installation Guide 19
2 Prerequisites
Docker containers
The following components support Docker version 1.13:
l API Manager
l API Gateway
Note
This applies to the API Gateway instance, Admin Node Manager, and Node Manager only. API Gateway Analytics does not support Docker.
Axway supports CentOS Linux version 7 only as the base image for Docker containers, and supports deployment on any host operating system or cloud provider supported by Docker version 1.13.x. For more details, see API Management in Docker containers on page 134.
Specific component requirements
This section describes requirements for specific API Gateway components. Component
Requirements
Policy
Studio
Policy Studio is a thick client and supports the platforms described in Thick client platforms on page 19.
API
API Gateway Manager is a web-based client and supports the web browsers listed in Web browsers on page 19.
Gateway
Manager
API
Gateway
Analytics
The API Gateway Analytics server component has the same operating system and hardware requirements as API Gateway. See Operating systems and hardware on page 17.
API Gateway Analytics requires a database. For database requirements, see Databases on page 19.
The browser-based client component supports the same browsers as API Gateway Manager. See Web browsers on page 19.
API
Manager
Axway API Gateway 7.5.3
API Manager is a browser-based client and supports the same browsers as API Gateway Manager. See Web browsers on page 19.
Installation Guide 20
2 Prerequisites
Default ports
This section describes the default ports used by API Gateway components.
API Gateway
The d efault ports used by API Gateway are as follows: l Traffic port: 8080 ( between clients and API Gateway) l Management port: 8085 ( between API Gateway and Admin Node Manager) Admin Node Manager
The d efault port used by the Admin Node Manager for monitoring and management of API Gateway instances is 8
090. Policy Studio
The default URL address used by the P olicy Studio tool to connect to the Admin Node Manager is as follows: https://localhost:8090/api
API Gateway Manager
The default URL address used by the API Gateway Manager web console to connect to the Admin Node Manager is as follows: https://localhost:8090/
API Manager
The default URL a
ddress used by the API Manager web console for API management is as follows: https://localhost:8075/
Axway API Gateway 7.5.3
Installation Guide 21
2 Prerequisites
API Gateway Analytics
The default p ort used by API Gateway Analytics for reporting, monitoring, and management is 8040 . The default URL address used by the API Gateway Analytics web console is as follows: http://localhost:8040/
Software and license keys
Axway products are delivered electronically from Axway Support at https://support.axway.com, the Axway support website. A welcome email notifies you that your products are ready for download. In the case where the product is delivered on an appliance, you must wait for the physical delivery of the hardware.
When you are ready, perform the following tasks:
1. Check your authorization.
2. Check the hardware and system requirements.
3. Obtain license keys.
4. Download the installation setup file from Axway Support at https://support.axway.com.
5. Install products.
Check your authorization
Verify that you can access Axway Support at https://support.axway.com b y going to https://support.axway.com and logging in. If you do not have an account, follow the instructions in your welcome email.
Log in to download or access:
l The product installation package
l Product documentation
l Product updates, including patches and service packs
l Product announcements
l The support case center, to open a new case or to track opened cases
You can also access other resources, such as articles in the Knowledge Base, the Axway User Forum, and documentation for all Axway products.
License keys
API Gateway requires the following license keys.
Axway API Gateway 7.5.3
Installation Guide 22
2 Prerequisites
Axway license file
You must have a valid Axway license file to install the following API Gateway components: l API Gateway Server
l API Gateway Analytics
l API Manager
You can obtain an evaluation trial license to enable you to evaluate the API Gateway features. However, you must have a full license to enable all API Gateway features for use in a non-evaluation environment (for example, development, testing, or production). To obtain an evaluation trial license or a full license, contact your Axway Account Manager.
Note
You can install an Admin Node Manager in isolation without an API Gateway license. For more information, see Install the Admin Node Manager on page 80.
McAfee license file
You must have a valid McAfee license file to use the McAfee Anti-Virus filter.
FIPS-compliant mode license file
You must have a valid Axway FIPS-compliant mode license file to run API Gateway in FIPS-compliant mode.
Multiple installations
API Gateway requires a minimum of two installations for high availability (HA). Make sure that you obtain license keys for all of the API Gateway instances that you are installing.
Additional prerequisites
This section lists additional prerequisites for installing API Gateway.
UNIX/Linux platforms
The following prerequisites apply when installing API Gateway on UNIX/Linux platforms.
Executable permission
On UNIX/Linux, you must ensure that the installation executable has the appropriate permissions in your environment. For example, you can use the chmod command to update the file permissions. Axway API Gateway 7.5.3
Installation Guide 23
2 Prerequisites
Service packs
Service packs for API Gateway are available from Axway Support at https://support.axway.com. If any service packs are available for API Gateway 7.5.3, download and apply them when the installation completes. For more information on applying a service pack, see Update API Gateway on page 153.
Certificates
API Gateway uses Secure Sockets Layer (SSL) for communications between all processes in a domain (for example, internal management traffic between the Admin Node Manager and API Gateway instances).
Certificates are not required during installation; however, certificates will be required after installation to secure API Gateway domains. For more information on configuring and securing API Gateway domains, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.3
Installation Guide 24
Plan the deployment
3
This topic discusses how to plan your deployment. For more information on planning an API Gateway system, and how API Gateway interacts with existing infrastructure, see the API Gateway Administrator Guide.
Platforms
For more information on the exact platforms that Axway supports for API Gateway, see System requirements on page 17.
API Gateway components
Before installing API Gateway you need to consider which components you require. Some components, for example, API Gateway Analytics, have additional requirements, such as a database. For more information, see Specific component requirements on page 20.
For more information on API Gateway components, see the API Gateway Concepts Guide.
Client components
API Gateway includes the Policy Studio developer tool, a thick client that is supported on UNIX/Linux and Windows. It also includes several web-based tools (for example, API Gateway Manager and API Gateway Analytics). For more details on supported thick client platforms and supported web browsers, see Web browsers on page 19 and Thick client platforms on page 19.
High availability
The following components have specific requirements for high availability (HA):
API Gateway HA
For resilient API Gateway and API Manager HA configuration, a minimum of at least two API Gateway instances is required. For details on configuring API Gateway high availability, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.3
Installation Guide 25
3 Plan the deployment
Apache Cassandra HA
In addition, the Apache Cassandra database is required to store data for the API Manager component. You can also use Cassandra to store data for API Gateway components such as the Key Property Store, OAuth, and API keys. For Cassandra HA c onfiguration, a minimum of three Cassandra nodes is required. For more details, see Install Apache Cassandra on page 37.
Multiple datacenters
For details on how to configure different types of API Gateway and API Manager data in a multidatacenter environment, see Configure API Management in multiple datacenters on page 106.
Connection to other products
API Gateway supports integration with a wide range of Axway products (for example, Axway PassPort) and third-party p roducts (for example, LDAP, JMS, or database providers). The requirements for a deployment of API Gateway with such an integration differs based on the specific product being integrated. For more details on a particular integration, see the appropriate integration or interoperability guide, available from Axway Support at https://support.axway.com (login required).
For more details on the versions of Axway products that API Gateway 7.5.3 interoperates with, see the following:
l API Gateway PassPort Interoperability Guide
l API Gateway Sentinel Interoperability Guide
l API Gateway Validation Authority Interoperability Guide
All of these guides are available on Axway Support at https://support.axway.com.
Axway API Gateway 7.5.3
Installation Guide 26
Install API Gateway
4
This section describes how to use the API Gateway installer. The installer is supported on the following platforms:
l Windows
l UNIX/Linux
Prerequisites
l You have downloaded the installation setup file for your target operating system from Axway Support at https://support.axway.com.
The download instructions are in the welcome letter that Axway sent you in an email message.
l You have obtained a valid Axway license file for API Gateway, and optionally API Gateway Analytics and API Manager. Also, if you intend to run API Gateway in FIPS-compliant mode, you have ensured that your license file allows this. You can obtain the required licenses from your Axway Account Manager.
l You have obtained a valid McAfee license file if you intend to use the McAfee Anti-Virus filter.
l You have reviewed the prerequisites and system requirements in Prerequisites on page 17 and have ensured that your target system is suitable.
Installation modes
The API Gateway installer has the following installation modes:
l GUI mode
l Unattended command-line mode
The following sections describe how to start the installer in GUI mode and the options that you are presented with when performing a GUI mode installation:
l Start installation on page 28
l Installation options on page 28
The following section describes how to start the installer in unattended mode and the command-line options for the unattended mode: l Unattended installation on page 32
Axway API Gateway 7.5.3
Installation Guide 27
4 Install API Gateway
Start installation
To run the API Gateway installer in the default GUI mode, locate and run the setup file for your operating system. For example:
Windows
APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe
Linux
APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run
Follow the instructions on each window to complete the installation. For more information on the options available during GUI mode installation, see Installation options on page 28.
Tip
To run the setup in unattended mode, see Unattended installation on page 32.
Installation options
When you run the installation setup file it launches in GUI mode by default. The following sections detail the installation options in GUI mode.
Welcome
When you run the setup file in GUI mode, you are presented with an introductory welcome window. Click Next to continue with the installation.
License agreement
Read the Axway standard license terms, and click I accept the agreement to accept the terms. You cannot proceed with the installation until you make a selection. If you click I do not accept
the agreement, the installer exits.
Click Next to continue. Select setup type
You can install API Gateway using the following setup types:
Axway API Gateway 7.5.3
Installation Guide 28
4 Install API Gateway
Standard
Select this option to install all API Gateway components without API Manager. This includes API Gateway Analytics, the QuickStart tutorial, Apache Cassandra database, package and deployment tools, Policy Studio, and Configuration Studio.
Complete
Select this option to install all API Gateway components with API Manager. This includes API Manager, API Gateway Analytics, the QuickStart tutorial, Apache Cassandra database, package and deployment tools, Policy Studio, and Configuration Studio. Custom
Select this option to customize which components are installed. You must select this option if you are upgrading from a previous API Gateway version. For more details, see the API Gateway Upgrade Guide.
Note
The API Tester component is deprecated, and is only installed in a Custom setup. For more details, see Install API Tester on page 83.
QuickStart tutorial
The Standard and Complete setup types install the QuickStart tutorial by default, or you can select to install it during the Custom setup type. This installs a preconfigured domain and API Gateway instance. If you do not install the QuickStart tutorial, you must configure a domain and API Gateway instance when the installation is complete. For more details, see Initial configuration on page 102. Click Next to continue.
Select components
This window is only displayed during an Custom installation.
Select the components to be installed, and deselect those that are not to be installed. The following components are selected by default: l API Gateway Server
l Admin Node Manager
l Policy Studio desktop tool
Click Next to continue.
Specify installation directory
Enter a location or click the browse button to specify the directory where the API Gateway components are to be installed, for example:
Axway API Gateway 7.5.3
Installation Guide 29
4 Install API Gateway
Windows
C:\Axway-7.5.3
UNIX/Linux
/opt/Axway-7.5.3
Click Next to continue.
Specify license file
Enter a location or click the browse button to specify a valid Axway license file. For more details, see Software and license keys on page 22. Note
API Gateway, API Gateway Analytics, and API Manager each require a valid Axway license file. If you have separate license files (one for API Gateway, one for API Gateway Analytics, and another for API Manager), specify the API Gateway license at this step, and you will be prompted for the API Gateway Analytics and API Manager license files at a later step. Alternatively, you can specify a single license file that covers all licensed components.
Cassandra configuration
If you selected to install an Apache Cassandra database, configure the following settings:
l Installation Directory:
Enter the directory in which to install the Cassandra server (for example: /opt/db/cassandra or C:\cassandra).
l JRE Location:
Enter the directory of the Oracle Java Runtime Environment used by Cassandra. Defaults to the Oracle JRE provided by API Gateway:
o UNIX/Linux: INSTALL_DIR/apigateway/Linux.x86_64/jre/bin
o Windows: INSTALL_DIR\apigateway\Win32\jre
Note
OpenJDK is not supported. In a production system, it is recommended to use a 64-bit Oracle JRE with Cassandra. For more details, see Install an Apache Cassandra database on page 37.
Set the administrator user name and password
It is important to secure your API Gateway system to protect it from internal and external threats. This window enables you to set the administrator user name and password. This administrator account is used to log in to Policy Studio and API Gateway Manager. These administrator credentials are also used by managedomain when connecting to an Admin Node Manager.
Select the check box to set the user name and password for the administrator account and enter a user name and password in the fields. Axway API Gateway 7.5.3
Installation Guide 30
4 Install API Gateway
Caution
Ensure that you remember these credentials or you will not be able to log in to Policy Studio or API Gateway Manager.
This option is selected by default, to ensure that you set your own administrator user name and password. To use a default administrator user name and password, you must deselect the check box. The default credentials are available from your Axway Account Manager. Click Next to continue.
Specify QuickStart Node Manager details
This window is only displayed if you selected to install the QuickStart tutorial.
Configure the following settings for the Node Manager:
l Host Name or IP Address:
Select a host address from the list (defaults to the installation host name).
l Local Management Port:
Enter the local port used to manage the Node Manager. Defaults to 8090.
Click Next to continue.
Specify QuickStart server details
This window is only displayed if you selected to install the QuickStart tutorial.
Configure the following settings:
l Local Management Port:
Enter the local port that the Node Manager uses to manage the API Gateway instance. Defaults to 8085. l External Traffic Port:
Enter the port that the API Gateway uses for message traffic from external clients. Defaults to 8080. Click Next to continue.
Set the administrator user name and password
for API Manager
It is important to secure your API Manager system to protect it from internal and external threats. This window enables you to set the API administrator user name and password. This administrator account is used to log in to the API Manager web console.
Select the check box to set the user name and password for the API administrator account and enter a user name and password in the fields. Axway API Gateway 7.5.3
Installation Guide 31
4 Install API Gateway
Caution
Ensure that you remember these credentials or you will not be able to log in to API Manager.
This option is selected by default, to ensure that you set your own API administrator user name and password. To use a default API administrator user name and password, you must deselect the check box. The default credentials are available from your Axway Account Manager. Click Next to continue.
Acknowledge API Gateway Analytics
information
This window is only displayed if you selected to install API Gateway Analytics.
An information window is displayed to remind you that you must perform additional steps before you start API Gateway Analytics. Review the information and click Next to continue.
Installation summary
The installer displays a summary of the components that will be installed on your system.
Review the information and click Next to begin installing.
Installing
A progress window is displayed showing the progress of the installation. When the installation is complete, click Next to continue.
Installation complete
A window is displayed to indicate that the installation is complete. If you selected to install Policy Studio you can select the option to Launch Axway Policy Studio. The URL of the Admin Node Manager is displayed (for example, https://127.0.0.1:8090). You can go to this URL in your browser to access the API Gateway Manager tools. Click Finish to complete the installation. Policy Studio is launched if you selected that option. If you selected to install the QuickStart tutorial, it is also launched in a browser window.
Unattended installation
This topic explains how to run the API Gateway installer in unattended mode on UNIX/Linux and Windows. It also describes each of the available command options.
Axway API Gateway 7.5.3
Installation Guide 32
4 Install API Gateway
Run the installer in unattended mode
You can run the API Gateway installer in unattended mode on the command line. Perform the following steps:
1. Change to the directory where the setup file is located.
2. Run the setup file with the --mode unattended option.
Standard setup without API Manager
The following example shows how to install all API Gateway components (excluding API Manager) in unattended mode:
UNIX/Linux
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type standard
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--prefix /opt/Axway-7.5.3
--cassandraInstalldir opt/db/cassandra
--cassandraJDK opt/jre
--startCassandra 1
Windows
APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe --mode unattended
--setup_type standard
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--prefix C:\Axway-7.5.3
--cassandraInstalldir c:\cassandra
--cassandraJDK c:\jre
--startCassandra 1
Axway API Gateway 7.5.3
Installation Guide 33
4 Install API Gateway
Complete setup with API Manager
The following example shows how to install all API Gateway components, including API Manager, in unattended mode:
UNIX/Linux
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type complete
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--apimgmtLicenseFilePath mymgmtlicense.lic
--prefix /opt/Axway-7.5.3
--cassandraInstalldir /opt/db/cassandra
--cassandraJDK /opt/jre
--startCassandra 1
Windows
APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe --mode unattended
--setup_type complete
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--apimgmtLicenseFilePath mymgmtlicense.lic
--prefix C:\Axway-7.5.3
--cassandraInstalldir c:\cassandra
--cassandraJDK c:\jre
--startCassandra 1
The components are installed in the background, in the directory specified by the --prefix option.
Custom setup
The topics on installing each API Gateway component show how to use the --setup_type
advanced option to install a custom setup in unattended mode. For example, see Install the API Gateway server on page 75.
Unattended mode options
For a description of all the available command-line options and their default settings, run the setup file with the --help option. This outputs the help text in a separate console. For example:
Axway API Gateway 7.5.3
Installation Guide 34
4 Install API Gateway
UNIX/Linux
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --help
Windows
APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe --help
The following table summarizes some of the more common options:
Option
Description
--help
Display available options and default settings.
--mode
Specify an installation mode.
--setup_type
Specify a setup type ( standard, complete, or advanced)
--enable-components
Specify a comma-separated list of components to enable.
--disable-components
Specify a comma-separated list of components to disable.
--prefix
Specify an API Gateway installation directory.
--licenseFilePath
Specify the path to a license file.
--apimgmtLicenseFilePath
Specify the path to an API Manager license file.
--
Specify the path to an API Gateway Analytics license file.
analyticsLicenseFilePath
--unattendedmodeui
Specify different levels of user interaction when installing on Windows or on a UNIX/Linux system with X-Windows.
--cassandraInstalldir
Specify the Apache Cassandra installation directory. For example, opt/db/cassandra on UNIX/Linux, or c:\cassandra on Windows.
Axway API Gateway 7.5.3
Installation Guide 35
4 Install API Gateway
Option
Description
--cassandraJDK
Specify the location of your Oracle Java Runtime Environment for Apache Cassandra. For example, opt/jre on UNIX/Linux, or c:\jre on Windows. The default values are :
l UNIX/Linux: INSTALL_
DIR/apigateway/Linux.x86_
64/jre/bin
l Windows: INSTALL_
DIR\apigateway\Win32\jre
Note
--startCassandra
OpenJDK is not supported.
Specify whether the Apache Cassandra server starts after the installer completes. Set to 1 to start Cassandra after installation, or set to 0 if you do not want Cassandra to start.
--optionfile
Axway API Gateway 7.5.3
Specify options in a properties file. For more information on option files, go to:
http://installbuilder.bitrock.com/docs/installbuilderuserguide.html
Installation Guide 36
Install Apache Cassandra
5
This topic describes how to use the API Gateway installer to install the Apache Cassandra database, and how to configure and manage a multi-node Cassandra cluster for high availability. Cassandra is required for API Manager and optional for some API Gateway components (for example, OAuth, API keys, and custom KPS).
This topic includes the following:
l Install an Apache Cassandra database on page 37
l Cassandra deployment architectures on page 40
l Configure a Cassandra HA cluster on page 45
l Manage Apache Cassandra on UNIX/Linux and Windows on page 59
l Perform essential Cassandra operations on page 64
l setup-cassandra script reference on page 67
Install an Apache Cassandra database
Apache Cassandra is required to store data for API Manager (for example, API catalog, quotas, and client registry) or API Gateway client registry (API key and OAuth). In addition, Cassandra is optional to store data for the following API Gateway components:
l Custom KPS table definitions and data
l OAuth token stores
Note
You must ensure that Cassandra is installed and running to use API Manager or API Gateway client registry.
You can use the API Gateway installer to install Cassandra version 2.2.8 in GUI mode or unattended mode. Alternatively, you can download Apache Cassandra, or use an existing Cassandra installation.
Supported Cassandra versions
API Gateway supports Apache Cassandra versions 2.2.8 and 2.2.5. For more details on Apache Cassandra, see http://cassandra.apache.org/.
Cassandra 2.2.8 is the recommended version. Cassandra 2.2.5 is supported by API Gateway for backwards compatibility.
For details on upgrading your Cassandra version, see "Upgrade from Apache Cassandra version 2.2.5 to version 2.2.8" in the API Gateway Upgrade Guide.
Axway API Gateway 7.5.3
Installation Guide 37
5 Install Apache Cassandra
Upgrade from earlier API Gateway versions
API Gateway version 7.5.3 includes the Datastax Cassandra client, which uses a default port of 9042 to communicate with Cassandra over the Cassandra native protocol. Earlier API Gateway versions included the Hector Cassandra client, which used a default port of 9160 to communicate with Cassandra over the Apache Thrift protocol.
In API Gateway version 7.5.1 or later, Cassandra runs externally to the API Gateway process. In earlier API Gateway versions, Cassandra was embedded in the API Gateway process.
For details on upgrading from an earlier API Gateway version, see the API Gateway Upgrade Guide.
Prerequisites
This section describes Cassandra-specific prerequisites in addition to the general API Gateway Prerequisites on page 17.
Production environment requirements
API Gateway supports the following in production:
l Operating systems:
o All supported Linux platforms (see System requirements on page 17)
o Windows 2012 Server only
l Cassandra:
o Cassandra version 2.2.8 or 2.2.5 on Linux and Windows
o 64-bit Oracle JRE version 8 on Linux and Windows (OpenJDK is not supported)
Note
On Linux, the default API Gateway installation includes a 64-bit Oracle JRE ( apigateway/Linux.x86_64/jre/bin). On Windows, API Gateway includes a 32-bit Oracle JRE ( apigateway\Win32\jre), which is suitable for development only. In a Windows production environment, you must download and install a 64-bit Oracle JRE manually. For more details, see Install a 64-bit Oracle JRE on Windows on page 38.
For details on requirements for high availability, see HA production environment requirements on page 47.
Install a 64-bit Oracle JRE on Windows
The default 32-bit Oracle JRE bundled with API Gateway on Windows limits the memory available to Cassandra on 64-bit systems, and cannot run Cassandra as a Windows service. In a production environment, you must download and install a separate 64-bit Oracle JRE.
Axway API Gateway 7.5.3
Installation Guide 38
5 Install Apache Cassandra
Note
If you select the default 32-bit Oracle JRE bundled with API Gateway, and later decide to switch to a 64-bit Oracle JRE, you must edit your CASSANDRA_
HOME\bin\cassandra.in.bat script, and change the JAVA_HOME variable at the top of the file to point to the new Oracle JRE. For example:
SET JAVA_HOME=C:\Program Files\Java\jre8
JCE policies for Cassandra TLS/SSL
If client TLS/SSL will be enabled for Cassandra, you must install the Java Cryptographic Extension (JCE) policies for your Oracle JRE. For example, you can download the Java 8 JCE policies from: http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html
Install Apache Cassandra
Note
Apache Cassandra 2.2.8 is installed by default in an API Gateway Standard or Complete setup. For more details, see in Installation options on page 28.
Install Cassandra in GUI mode
In GUI mode, to install Apache Cassandra only, use the steps described in Installation options on page 28 with the following selections:
l Setup Type: Select Custom.
l Select Components: Select Cassandra.
l Cassandra configuration: Enter your Cassandra Installation Directory and your JRE
Location. For more details, see Cassandra configuration on page 30.
Install Cassandra in unattended mode
To install Apache Cassandra using the API Gateway installer in unattended mode, follow the steps described in Unattended installation on page 32. For example, the following command shows how to install Apache Cassandra only in unattended mode:
UNIX/Linux
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components cassandra
--disable-components apigateway,analytics,qstart,policystudio,
configurationstudio,apitester,apimgmt,packagedeploytools
Axway API Gateway 7.5.3
Installation Guide 39
5 Install Apache Cassandra
--cassandraInstalldir /opt/db/cassandra
--cassandraJDK /opt/jre
--startCassandra 0
Windows
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components cassandra
--disable-components apigateway,analytics,qstart,policystudio,
configurationstudio,apitester,apimgmt,packagedeploytools
--cassandraInstalldir c:\cassandra
--cassandraJDK c:\jre
--startCassandra 0
Note
To keep your Cassandra installation after API Gateway is uninstalled, you must ensure that you first install Cassandra only. For example, perform the following steps:
1. Run the API Gateway installer, and select Cassandra only.
2. Run the API Gateway installer, and select API Gateway components to install.
Then when API Gateway is uninstalled, Cassandra remains installed.
Further details
For more details on Apache Cassandra, see the following:
l http://cassandra.apache.org/
l http://docs.datastax.com/en/cassandra/2.2/
Cassandra deployment architectures
This topic describes the Cassandra deployment architectures supported by API Gateway. The following table provides a summary:
Deployment
Description
Standalone
One API Gateway instance only. This is the default.
Use
l Development environment
l Production environment with one API Gateway instance
Axway API Gateway 7.5.3
Installation Guide 40
5 Install Apache Cassandra
Deployment
Description
High availability
with local storage
Multiple API Gateway instances in a group, each API Gateway instance on different hosts, with a Cassandra storage node local to each API Gateway host.
l Pre-production environment
Multiple API Gateway instances in a group, each API Gateway instance on different hosts, with Cassandra storage nodes on remote hosts.
l Pre-production environment High availability
with remote
storage
Note
Use
l Production environment l Production environment You can use one Cassandra cluster to store data from one or multiple API Gateway groups and one or multiple API Gateway domains. Your Cassandra topology does not need to match your API Gateway topology.
Multiple API Gateway groups can also be deployed on the same host, each host running an API Gateway instance for each group. This applies to both local and remote storage.
For details on hosting Cassandra in datacenters, see Configure API Management in multiple datacenters on page 106.
Cassandra in standalone mode
Cassandra is configured in non-HA standalone mode when deployed alongside a single API Gateway instance on the same host (for example, in a demonstration or development environment with one API Gateway instance). This is the default mode.
To configure Cassandra in standalone mode, perform the following steps:
1. Ensure Cassandra is installed on the local node (along with API Gateway). For details, see Install an Apache Cassandra database on page 37.
2. Start Cassandra before starting API Gateway. For details, see Manage Apache Cassandra on UNIX/Linux and Windows on page 59.
3. Start API Gateway. For details, see Install the API Gateway server on page 75.
The next steps depend on your installation setup type:
l In a Standard or Complete setup (which include the QuickStart tutorial), the default configuration attempts to connect to Cassandra running on localhost.
l In a Custom setup without the QuickStart tutorial, you must configure the connection in Policy Studio. For more details, see Connect to API Gateway for the first time on page 63.
To use Cassandra with API Manager, run the setup-apimanager script (see Configure your API Manager settings on page 56). This is configured by default when API Manager is installed along with the QuickStart tutorial.
Axway API Gateway 7.5.3
Installation Guide 41
5 Install Apache Cassandra
To use Cassandra with OAuth, run DeployOAuthConfig (see "Deploy OAuth configuration" in the API Gateway OAuth User Guide).
The following diagram shows Cassandra in standalone mode with a default Standard setup:
Cassandra in High Availability mode
For both local and remote Cassandra HA, Cassandra runs on multiple hosts. This section describes both scenarios.
HA with local storage
In local Cassandra HA, Cassandra runs alongside API Gateway on the same host. This means that you do not need to provision separate host machines for Cassandra and API Gateway, or open ports in your firewall. However, the data will be stored in the DMZ. Local Cassandra HA enables minimum cost of ownership.
The following diagram shows local Cassandra HA mode:
Axway API Gateway 7.5.3
Installation Guide 42
5 Install Apache Cassandra
Note
In this example, one of the Cassandra nodes runs without an API Gateway instance on the same host. This is because the minimum deployment architecture includes two API Gateway hosts and three Cassandra hosts. If you have three API Gateway instances, all Cassandra nodes are local.
HA with remote storage
In remote Cassandra HA, Cassandra runs on a different host from API Gateway. The main differences when installing and configuring remote Cassandra are:
l You must provision separate host machines for Cassandra and API Gateway. However, the data can be stored outside the DMZ, and there might be improved performance.
l You might need to open ports in the firewall to connect to Cassandra outside the DMZ. For more details, see Network requirements on page 49.
l You are not required to use the Cassandra component supplied by the API Gateway installer.
l You can configure the remote node using the setup-cassandra script supplied by the API Gateway installation. For more details, see setup-cassandra script reference on page 67. Alternatively, you can perform all necessary Cassandra configuration changes manually.
l You must update the API Gateway Cassandra client settings in Policy Studio to connect to the remote Cassandra host nodes.
The following diagram shows remote Cassandra HA mode:
Axway API Gateway 7.5.3
Installation Guide 43
5 Install Apache Cassandra
Cassandra HA configuration
You can use a local or remote Cassandra HA configuration. The example Cassandra HA configuration in the diagrams consists of the following:
l Three Cassandra nodes in a single cluster.
l Three host machines with network addresses: ipA (seed node), ipB, and ipC.
l Replication factor of 3. Each node holds 100% of the data.
l Default values in cassandra.yaml for:
o Server-server communication: listen_address set to IP address
storage_port set to 7000
ssl_storage_port: 7001 (when TLS v1.2 is configured)
o Client-server communication:
native_transport_port of 9042
o JMX monitoring on localhost:7199
Note
Axway API Gateway 7.5.3
Installation Guide 44
5 Install Apache Cassandra
l ipA, ipB, and ipC are placeholders for real host machines on your network. You can specify IP addresses or host names.
l You must have at least one designated seed node. Seeds nodes are required at runtime when a node is added to the cluster. You can add more or change designation later.
l You can change the server-server port, but it must be the same across the cluster.
l For Cassandra administration, you must gain local access to the host machine (for example, using SSH) to perform administration tasks. This includes using nodetool to access the Cassandra cluster over JMX.
API Gateway configuration
API Gateway acts as a client of the Cassandra cluster as follows:
l Client failover: API Gateway can fail over to any of the Cassandra nodes for service. Each API Gateway is configured with the connection details of each Cassandra host.
l Strong consistency: Cassandra read and write consistency levels are both set to QUORUM. This, along with the replication factor of 3, enables full availability in the event of one node loss.
Note
You can have any number of API Gateway instances (all running either locally or remote to Cassandra). However, you must have at least two API Gateway instances for HA. This also applies to API Manager.
For more details on Cassandra HA configuration, see Configure a Cassandra HA cluster on page 45.
Configure a Cassandra HA cluster
This topic describes how to set up an Apache Cassandra database cluster for high availability of your API Gateway system. It describes the necessary configuration steps and provides examples from a production environment.
Cassandra HA in a production environment
To tolerate the loss of one Cassandra node and to ensure 100% data consistency, API Gateway requires the following cluster configuration in a HA production environment:
l Three Cassandra nodes (with one seed node)
l QUORUM consistency to ensure that you are reading from a quorum of Cassandra nodes (two) every time
l Replication factor set to 3 so each node holds 100% of the data and you can tolerate the loss of one node
Axway API Gateway 7.5.3
Installation Guide 45
5 Install Apache Cassandra
If one Cassandra node fails, the cluster continues with two nodes to be HA, consistent, and read/write. There is no availability with one node and QUORUM consistency. This configuration applies in all supported use cases (for example, API Manager and API Gateway custom KPS, OAuth, and client registry data).
Note
Eventual consistency is not supported in a production environment (due to a risk of stale and incomplete data).
For more details, see Example Cassandra HA configuration in a production environment on page 47.
For details on hosting Cassandra in datacenters, see Configure API Management in multiple datacenters on page 106.
Upgrade from previous API Gateway version
When upgrading from a previous API Gateway version, you need only one Cassandra node in the cluster to receive upgraded data. After upgrade, you can then add more nodes to this cluster to provide high availability (HA), and configure TLS security. For more details, see the API Gateway Upgrade Guide.
Cassandra HA configuration
Use the following tools to configure Cassandra and the API Gateway Cassandra client:
Tool
Description
nodetool
Located in CASSANDRA_HOME/bin. This tool is required run most Cassandra administration operations. nodetool runs locally by default against a Cassandra node.
cqlsh
Located in CASSANDRA_HOME/bin. This tool provides a query language interface to Cassandra. Cassandra Query Language (CQL) is similar in syntax to SQL. You can use tab completion with cqlsh (for example, press Tab to complete keyspace, table, and command names, and so on).
setupcassandra
Located in GATEWAY_INSTALL_DIR/bin. This script helps with Cassandra configuration and updates the cassandra.yaml configuration file. You can edit this file manually, but this script saves time, helps prevent errors, and creates a backup of the original cassandra.yaml file. setupcassandra also outputs instructions for resetting the default user name and password. You can use this script when Cassandra installed locally or remote to API Gateway. For more details, see setup-cassandra script reference on page 67.
Axway API Gateway 7.5.3
Installation Guide 46
5 Install Apache Cassandra
Tool
Description
Policy Studio
Policy Studio enables you to configure API Gateway and API Manager as clients of Cassandra. It also enables you to configure KPS table definitions created in back-end storage, if they do not exist (for example, in Cassandra or a relational database). For Cassandra, these tables are created in a group keyspace with an initial replication factor of 1. For more details, see Configure the g roup keyspace and replication factor in Cassandra on page 50.
The following general guidelines apply to configuring Cassandra HA:
l Decide on the number Cassandra nodes and the number of API Gateway nodes (local or remote). Axway recommends to configure a Cassandra HA cluster with three Cassandra nodes, and least two API Gateway instances (local or remote). For details, see Cassandra deployment architectures on page 40.
l Ensure Cassandra is installed on each Cassandra node. For more details, see Install an Apache Cassandra database on page 37.
l Configure Cassandra on each Cassandra node. You can configure automatically using the setup-cassandra script. Alternatively, you can configure manually by modifying cassandra.yaml. Example Cassandra HA configuration in a production environment on page 47 shows examples of both approaches.
l Ensure API Gateway is installed and configured on one API Gateway node (local or remote to Cassandra). For more details, see Install the API Gateway server on page 75.
l Configure the Cassandra client settings in Policy Studio for the API Gateway group. Example Cassandra HA configuration in a production environment on page 47 shows the steps for both API Gateway and API Manager clients.
l Install and configure API Gateway on additional nodes as necessary. For more details, see Install the API Gateway server on page 75.
Example Cassandra HA configuration in a
production environment
This section describes an example Cassandra HA configuration supported by Axway in a production environment.
Note
In this section, API Gateway and API Manager are both clients of Cassandra, and all API Gateway steps refer to both API Gateway and API Manager. API Manager is used only when additional API Manager-specific configuration is required.
HA production environment requirements
The following system requirements apply for Cassandra HA in a production environment:
Axway API Gateway 7.5.3
Installation Guide 47
5 Install Apache Cassandra
Hardware requirements
l Nodes: Three Cassandra nodes (one seed node).
l IP address: One IP address per Cassandra node.
l Disk space and memory: Depend on how much data you plan to store and how often this data changes:
o KPS data and API Manager data consume small amounts of data (mostly read configuration data), and should not be an issue.
o OAuth token use can be large, depending on the frequency of token generation and token time-to-live.
o Double the amount of estimated storage: Needed for Cassandra to perform automatic compaction of data.
l Storage: Cassandra is designed to run on commodity distributed drives. Storage Area Network (SAN) is not recommended or supported in a production environment.
For more details, see the API Management Capacity Planning Guide (available when logged into the Axway documentation website). Software requirements
API Gateway supports the following systems in production:
l Operating systems:
o All Linux platforms supported by API Gateway. For more details, see System requirements on page 17.
o Windows Server 2012 R2 is recommended.
l Cassandra:
o 64-bit Cassandra version 2.2.8 or 2.2.5 with 64-bit Oracle JRE on Linux and Windows (OpenJDK is not supported). Cassandra 2.2.8 is recommended. For more details, Supported Cassandra versions on page 37.
Note
You must download a 64-bit Oracle JRE manually on UNIX/Linux when Cassandra is remote to API Gateway. This also applies on Windows when Cassandra is remote or local (see Install a 64-bit Oracle JRE on Windows on page 38).
l Python:
o cqlsh uses Python 2.7.10
o nodetool uses Python 2.6 or 2.7
For more details, see https://www.python.org/.
Axway API Gateway 7.5.3
Installation Guide 48
5 Install Apache Cassandra
Network requirements
l All Cassandra nodes can connect to each other: o Ensure you can ping from each node to each other node.
o Ensure that your firewall rules allow the necessary Cassandra ports for client and server connections. API Gateway clients connect to Cassandra over the Cassandra native protocol on port 9042 by default. Cassandra uses port 7000 by default for communication between Cassandra nodes (and port 7001 when TLS/SSL is configured).
l Use a time service such as NTP to ensure that time is in sync in the cluster. For more details, see Ensure time is in sync across the cluster on page 66.
Note
Earlier API Gateway versions used a default port of 9160 to communicate with Cassandra over the Apache Thrift protocol. This protocol is not supported in API Gateway version 7.5.3 or later. However, if necessary, after upgrade, you can configure Cassandra and API Gateway to use port 9160 to communicate over the Cassandra native protocol.
Start with one Cassandra seed node
You must always start with one Cassandra node (non-HA). You can test API Gateway functionality and become familiar with Cassandra using one node, before growing the system for HA.
When upgrading from previous API Gateway versions ( with embedded Cassandra), you must upgrade to one node only. After upgrade, you can then grow the system for HA. You do not need to start with three nodes, or start from scratch to achieve HA. For more details on upgrade, see the API Gateway Upgrade Guide.
Note
Cassandra scales horizontally. This means that each node must have equal resources. Each node must run on the same hardware (CPU, disk, memory, and network) and on the same operating system. This is intentional so that nodes do not starve or out-compete other nodes, and so that you can easily add, remove and replace nodes, especially in cloud environments.
For example, do not run some nodes with less or more memory than other nodes, or some nodes on Windows and some on Linux, or some nodes on SUSE Linux and some on CentOS Linux.
Cassandra HA configuration steps
The high-level approach to Cassandra HA configuration is as follows:
1. Configure and verify the Cassandra HA cluster (non-secured).
2. Configure the API Gateway or API Manager client and verify.
3. Secure the Cassandra HA configuration and verify.
These steps are described in detail in the sections that follow.
Axway API Gateway 7.5.3
Installation Guide 49
5 Install Apache Cassandra
Step 1 – Configure and verify the Cassandra
HA cluster (non-secure)
This includes the following steps:
1. Connect API Gateway to Cassandra on page 50
2. Configure the g roup keyspace and replication factor in Cassandra on page 50
3. Configure the Cassandra seed node on page 51
4. Add the seed node to the HA cluster on page 52
5. Replicate and verify the Cassandra cluster on page 54
Connect API Gateway to Cassandra
If you installed a Standard or Complete setup, Cassandra is installed on the same host, and listens on localhost by default. API Gateway runs on the same host and connects to Cassandra by default. If you installed a Custom setup, and did not select the Quickstart tutorial, see Install an Apache Cassandra database on page 37.
Configure the group keyspace and replication factor in
Cassandra
If you have created a KPS collection or set up API Manager (which creates KPS collections), API Gateway creates a Cassandra keyspace and tables for data storage when it connects to a Cassandra node, if these do not exist.
By default, the created Cassandra keyspace has a name in the form of xDOMAINID_GROUPID. This enables API Gateways in a group to share data and enables a single Cassandra cluster to host data from multiple API Gateway domains (for example, development, test, and staging).
Configure the API Gateway keyspace and replication factor
Initially, the keyspace has a default Replication Factor (RF) of 1. You must increase this for HA configuration. Perform the following steps:
1. Use cqlsh to verify that the keyspace has been created and to view its replication factor. For example:
$ ./cqlsh ipA
describe x83709115_c70d_4996_83ad_339407e1117d_group_2;
The following text is output at the start:
Axway API Gateway 7.5.3
Installation Guide 50
5 Install Apache Cassandra
CREATE KEYSPACE x83709115_c70d_4996_83ad_339407e1117d_group_2 WITH
replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} AND
durable_writes = true;
2. Update the replication factor to 3, for example:
ALTER KEYSPACE x83709115_c70d_4996_83ad_339407e1117d_group_2 WITH
REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 3 };
3. Rerun the describe command in step 1. The RF should now be 3.
Note
You must repeat these steps for each API Gateway group.
Configure the system_auth keyspace replication factor
When Cassandra authentication is enabled, you must also replicate the system_auth keyspace so that API Gateway can communicate with the cluster (for example, if a node in the cluster goes down):
ALTER KEYSPACE "system_auth" WITH REPLICATION = { 'class':
'SimpleStrategy', 'replication_factor': 3 };
QUIT
For more details, see Secure Cassandra HA configuration on page 71.
Configure the Cassandra seed node
Perform the following steps on the Cassandra seed node ( ipA in this example):
1. Update CASSANDRA_HOME/conf/cassandra.yaml manually or with the setup-
cassandra script. You must ensure that the following settings are set (where ipA is the IP address of the first node):
l seed_provider, parameters, seeds: ipA
l start_native_transport: true
l native_transport_port: 9042
l listen_address: ipA
l rpc_address: ipA
l authenticator: org.apache.cassandra.auth.PasswordAuthenticator
l authorizer: org.apache.cassandra.auth.CassandraAuthorizer
For example, to set these with the setup-cassandra script:
Axway API Gateway 7.5.3
Installation Guide 51
5 Install Apache Cassandra
setup-cassandra --seed --own-ip=ipA --nodes=3 --cassandra-config=CONFIG_
FILE
2. Restart Cassandra. For details, see Install an Apache Cassandra database on page 37. You must always start the seed node first. For example, use the following command:
/opt/cassandra/bin/cassandra
3. To verify, run nodetool status. You should see the correct IP address output. One node only should be output.
Note
The default username/password is cassandra/ cassandra. You must specify these credentials when running Cassandra tools such as cqlsh. For example :
./cqlsh ipA -u cassandra -p cassandra
Add the seed node to the HA cluster
You now must add two more Cassandra nodes in turn. The steps are similar to configuring the seed node, except the seed is now the first node ( ipA). Note
You must first have at least one designated seed node. Seeds nodes are required at runtime when a node is added to the cluster. You can add more or change designation later.
Configure the second Cassandra node (ipB)
1. On Cassandra node B, install Cassandra (see Install an Apache Cassandra database on page 37). Do not start it yet.
2. Edit cassandra.yaml manually or use the setup-cassandra script. You must ensure that the following settings are set (where ipB is the IP address of the second node):
l seed_provider, parameters, seeds: ipA
l start_native_transport: true
l native_transport_port: 9042
l listen_address: ipB
l rpc_address: ipB
l authenticator: org.apache.cassandra.auth.PasswordAuthenticator
l authorizer: org.apache.cassandra.auth.CassandraAuthorizer
For example, to set these with the setup-cassandra script:
Axway API Gateway 7.5.3
Installation Guide 52
5 Install Apache Cassandra
setup-cassandra --seed-ip=ipA --own-ip=ipB --cassandra-config=CONFIG_
FILE
3. Start Cassandra, for example:
/opt/cassandra/bin/cassandra
This node should join the cluster after obtaining information from the seed node. For more details, see Install an Apache Cassandra database on page 37.
4. To verify, run nodetool status. You should see two nodes reported with the correct IP addresses.
Configure the third Cassandra node (ipC)
1. On Cassandra node C, install Cassandra (see Install an Apache Cassandra database on page 37). Do not start it yet.
2. Edit cassandra.yaml manually or use the setup-cassandra script. You must ensure that the following settings are set ( where ipC is the IP address of the third node):
l seed_provider, parameters, seeds: ipA
l start_native_transport: true
l native_transport_port: 9042
l listen_address: ipC
l rpc_address: ipC
l authenticator: org.apache.cassandra.auth.PasswordAuthenticator
l authorizer: org.apache.cassandra.auth.CassandraAuthorizer
For example, to set these with the setup-cassandra script:
setup-cassandra --seed-ip=ipA --own-ip=ipC --cassandra-config=CONFIG_
FILE
3. Start Cassandra. For example:
/opt/cassandra/bin/cassandra
This node should join the cluster after obtaining information from the seed node. For more details, see Install an Apache Cassandra database on page 37.
4. To verify, run nodetool status. You should see three nodes reported with the correct IP addresses.
Axway API Gateway 7.5.3
Installation Guide 53
5 Install Apache Cassandra
Replicate and verify the Cassandra cluster
To replicate data correctly around the cluster after this cluster configuration change, go to each node in turn, and run nodetool repair.
To verify, go to each node in turn, and run the following command for each group:
nodetool status keyspace_name
For example:
nodetool status x83709115_c70d_4996_83ad_339407e1117d_group_2
You should see three nodes with ownership of 100%.
Step 2 – Configure the client settings for API
Gateway or API Manager
Note
You need at least two API Gateways in a group for HA.
Configure API Gateway Cassandra client settings
To update the Cassandra client configuration for API Gateway, perform the following steps:
Configure the API Gateway domain
1. Ensure API Gateway has been installed on the API Gateway 1 and API Gateway 2 nodes. For details, see Install the API Gateway server on page 75.
2. Ensure an API Gateway domain has been created on the API Gateway 1 node using managedomain. For more details, see "Configure an API Gateway domain" in the API Gateway Administrator Guide.
Configure the API Gateway Cassandra client connection
1. In Policy Studio, open your API Gateway group configuration.
2. Select Server Settings > Cassandra > Authentication, and enter your Cassandra user name and password (both default to cassandra).
3. Select Server Settings > Cassandra > Hosts, and add an address for each Cassandra node in the cluster ( ipA, ipB and ipC in this example).
Axway API Gateway 7.5.3
Installation Guide 54
5 Install Apache Cassandra
Tip
You can automate these steps by running the updateCassandraSettings.py script against a deployment package ( .fed). For more details, see Automate API Gateway Cassandra client settings on page 58.
Configure the API Gateway Cassandra consistency levels
1. Ensure that the API Server KPS collection has been created under Environment
Configuration > Key Property Stores. This is required to configure Cassandra consistency levels, and is created automatically if you installed the Complete setup type (see Installation options on page 28). If you installed the Custom or Standard setup, run one of the following scripts to create the required KPS collections:
l DeployOAuthConfig (see "Deploy OAuth configuration" in the API Gateway OAuth User Guide)
l setup-apimanager (see Configure your API Manager settings on page 56)
2. Select Environment Configuration > Key Property Stores > API Server > Data
Sources > Cassandra Storage, and click Edit.
3. In the Read Consistency Level and Write Consistency Level fields, select QUORUM:
4. Repeat this step for each KPS collection using Cassandra (for example, Key Property Stores > OAuth, or API Portal for API Manager). This also applies to any custom KPS collections that you have created.
5. If you are using OAuth and Cassandra, you must also configure q uorum consistency for all OAuth2 stores under Libraries > OAuth2 Stores:
l Access Token Stores > OAuth Access Token Store
l Authorization Code Stores > Authz Code Store
l Client Access Token Stores > OAuth Client Access Token Store
Note
By default, OAuth uses EhCache instead of Cassandra. For more details on OAuth, see the API Gateway OAuth User Guide.
Deploy the configuration
1. Click Deploy in the toolbar to deploy this configuration to the API Gateway group.
2. Restart each API Gateway in the group.
For details on any connection errors between API Gateway and Cassandra, see Configure a Cassandra HA cluster on page 45.
Axway API Gateway 7.5.3
Installation Guide 55
5 Install Apache Cassandra
Configure API Manager Cassandra client settings
To update the Cassandra client configuration for API Manager, perform the following steps:
Configure your API Gateway settings
1. Ensure the API Gateway and API Manager components have been installed on the API Gateway 1 and API Gateway 2 nodes. These can be local or remote to Cassandra installations. For details, see Install the API Gateway server on page 75 and Install API Manager on page 84.
2. Ensure an API Gateway domain has been created on the API Gateway 1 node using managedomain. For details on managedomain, see the API Gateway Administrator Guide.
3. Create an API Gateway group and first instance on API Gateway 1 using managedomain.
4. Start the first API Gateway instance in the group. For example:
startinstance -n "my_gw_server_1" -g "my_group"
5. Configure the Cassandra connection on the API Gateway 1 node. For details, see Configure the API Gateway Cassandra client connection on page 54.
Configure your API Manager settings
1. Configure API Manager on the first API Gateway instance in the group. For example, run setup-apimanager for the API Gateway instance:
setup-apimanager --name "SERVER_INSTANCE_NAME" --group "GROUP_NAME" -portalport “API_MANAGER_LISTEN_PORT” --trafficport “API_MANAGER_TRAFFIC_
PORT”
For more details on setup-apimanager, see the API Manager User Guide.
2. Configure the Cassandra consistency levels for your KPS Collections. For details, see Configure the API Gateway Cassandra consistency levels on page 55.
3. In the Policy Studio tree, select Server Settings > API Manager > Quota Settings, and ensure that Use Cassandra is selected. Axway API Gateway 7.5.3
Installation Guide 56
5 Install Apache Cassandra
4. Under Cassandra consistency levels, in both the Read and Write fields, select QUORUM:
5. Add the API Gateway 2 host machine to the domain using managedomain.
6. Create the second API Gateway instance in the same group on the API Gateway 2 node.
Note
Do not start this instance, and do not run setup-apimanager on this instance.
7. Before starting the second API Manager-enabled instance, ensure that each instance has unique ports in the envSettings.props file. For example:
i. Edit the envSettings.props file for the API Gateway instance in the following directory:
INSTALL_DIR/apigateway/groups/<group-n>/<instancem>/conf/envSettings.props
ii. Add the API Manager ports. For example, the defaults are:
#API Manager Port
env.PORT.APIPORTAL=8075
#API Manager Traffic Port
env.PORT.PORTAL.TRAFFIC=8065
8. Start the second API Gateway instance. For example:
startinstance -n "my_gw_server_2" -g "my_group"
On startup, this instance receives the API Manager configuration for the group. It now shares the same KPS and Cassandra configuration and data, and uses the ports specified in the envSettings.props file.
Axway API Gateway 7.5.3
Installation Guide 57
5 Install Apache Cassandra
Step 3 – Secure the Cassandra HA configuration
and verify
To secure your Cassandra HA configuration, perform the following steps:
1. Reset your default user name and password.
2. Enable node-to-node traffic encryption.
3. Enable client-to-node traffic encryption.
4. Configure the cqlsh command for client-to-node traffic encryption.
For details, see Secure Cassandra HA configuration on page 71.
Note
nodetool can normally run on any machine against any Cassandra node. For improved security, you might have locked down JMX for localhost access only. In such cases, you could use ssh to access that machine, and then run nodetool.
Automate API Gateway Cassandra client
settings
You can automate your API Gateway Cassandra client configuration by running the updateCassandraSettings.py script against a specified API Gateway deployment package ( .fed). For example:
1. Go to the following directory error:
INSTALL_DIR/apigateway/samples/scripts
2. Enter the following command:
run cassandra/updateCassandraSettings.py -f /opt/apigateway/conf/my_
deployment.fed -r 3 -H "ipA:9042,ipB:9042,ipC:9042"
The script options are explained as follows:
Option
Description
-f, --file
Enter the API Gateway deployment ( .fed) to be updated. The default is INSTALL_
DIR/system/conf/templates/FactoryConfiguratio
n-VordelGateway.fed. If you do not specify a .fed file, you must back up this file before running the script.
Axway API Gateway 7.5.3
Installation Guide 58
5 Install Apache Cassandra
Option
Description
-r, --
Enter the Cassandra replication factor. For more details, see Configure the g roup keyspace and replication factor in Cassandra on page 50.
replicationFacto
r
-h, --hosts
Enter a comma-separated list of Cassandra host nodes in host:port format. For example, 127.0.0.1:9042,127.0.0.2:9042,127.0.0.3:9042.
For more details on automating API Gateway configuration, see the API Gateway DevOps Deployment Guide.
Further details
For details on Cassandra administration, see Perform essential Cassandra operations on page 64.
For more details on Cassandra cluster configuration and its impact on your system, see the following:
l http://www.ecyrd.com/cassandracalculator/
l http://docs.datastax.com/en/cassandra/2.2/
Manage Apache Cassandra on UNIX/Linux and
Windows
When you select to install Cassandra using the API Gateway installer as part of a Standard or Complete setup, Cassandra starts automatically. To start or stop Cassandra manually or as a service, perform the steps described in this topic.
Note
Before starting Cassandra, you must ensure that your JAVA_HOME environment variable is set to the JRE Location that you selected when installing Cassandra. See Install an Apache Cassandra database on page 37.
For details on configuring Cassandra high availability, see Configure a Cassandra HA cluster on page 45.
Manage Apache Cassandra on UNIX/Linux
This section explains how to start and stop Cassandra o n UNIX/Linux.
Axway API Gateway 7.5.3
Installation Guide 59
5 Install Apache Cassandra
Start Apache Cassandra on UNIX/Linux
To start Cassandra in the background:
1. Open a command prompt, and change to the following directory:
$ cd CASSANDRA_HOME/bin
2. Run the following command:
$ ./cassandra
To start Cassandra in the foreground, run the following command:
$ ./cassandra -f
For more details, see https://wiki.apache.org/cassandra/RunningCassandra.
Start Cassandra as a service on UNIX/Linux
To install Cassandra as a service on UNIX/Linux, you must install and configure appropriate startup script for your system. For example, see the following example startup scripts:
l CentOS:
https://support.axway.com/kb/178063/language/en
l Debian:
https://github.com/apache/cassandra/blob/cassandra-2.2/debian/init
When startup scripts are configured, you can then start Cassandra as a service.
Note
You must have root or sudo permissions to start Cassandra as a service.
For example, typically the command to start Cassandra as a service is as follows:
$ sudo service cassandra start
Stop Cassandra on UNIX/Linux
1. Find the Cassandra Java process ID (PID):
$ ps auwx | grep cassandra
2. Run the following command:
Axway API Gateway 7.5.3
Installation Guide 60
5 Install Apache Cassandra
$ sudo kill pid
Stop Cassandra as a service on UNIX/Linux
You must have root or sudo permissions to stop the Cassandra service as follows:
$ sudo service cassandra stop
Manage Apache Cassandra on Windows
This section explains how to start and stop Cassandra on Windows.
Start Apache Cassandra on Windows
Modern Windows versions support the new PowerShell command-line interpreter. The Cassandra installation provides the old .bat startup file and the new .ps1 startup file.
When you run the cassandra command in CASSANDRA_HOME\bin, it can run in legacy startup mode or new startup mode depending on the PowerShell script execution policy setting. If this policy is set to Unrestricted, the new PowerShell startup script runs. Otherwise, the legacy startup script runs. There are differences in the startup behavior and command line options depending on the type of startup. This topic shows both legacy and new startup modes.
Legacy mode
To start Cassandra in the foreground in legacy mode:
1. Open a command prompt, and change to the following directory:
> cd CASSANDRA_HOME\bin
2. Run the following command:
> cassandra
Note
If you use legacy mode, you cannot start Cassandra in the background from the command line. If you already have PowerShell mode enabled, you must enter cassandra
LEGACY to run in legacy mode.
Powershell mode
To start Cassandra in the background in PowerShell mode:
1. Open a command prompt, and change to the following directory:
Axway API Gateway 7.5.3
Installation Guide 61
5 Install Apache Cassandra
> cd CASSANDRA_HOME\bin
2. Run the following command:
> cassandra
To start Cassandra in the foreground, run the following command:
> cassandra -f
Start Cassandra as a Windows service
Note
Ensure that you are not using the default 32-bit Oracle JRE bundled with API Gateway, which cannot run Cassandra as a service. For more details, see Install a 64-bit Oracle JRE on Windows on page 38.
You can install and run Cassandra as a service as follows:
1. Download the latest version of Apache Commons Daemon for Windows from: http://www.apache.org/dist/commons/daemon/binaries/windows/
2. Create a daemon directory in CASSANDRA_HOME\bin (for example, CASSANDRA_
HOME\bin\daemon).
3. Extract the relevant prunsrv.exe. For example, on a 64 bit Windows machine, extract prunsrv.exe from commons-daemon-1.0.15-bin-windows.zip\amd64, and copy it to CASSANDRA_HOME\bin\daemon.
4. Start a command prompt as administrator user, and change directory to CASSANDRA_
HOME\bin.
5. To install Cassandra as a service, run the following command: l Legacy mode: cassandra.bat install
l PowerShell mode: cassandra.bat -install
Tip
This creates a cassandra service, configured to start in manual mode. To change the startup mode to auto, use the Windows sc command. For example:
sc config cassandra start= auto
The space character after the = sign is required.
Configure startup dependencies
If you also installed API Gateway as a service, you can modify its service entry to depend on newly created cassandra service, so the API Gateway is started after Cassandra is started. You can use the sc command to configure such dependencies as follows:
Axway API Gateway 7.5.3
Installation Guide 62
5 Install Apache Cassandra
sc config [service name] depend= <Dependencies(separated by /(forward
slash))>
Note
There must be no space between depend and the = character.
For example, if the API Gateway is called QuickStart Server, and it belongs to a group called QuickStart Group, its service name is “QuickStart Server (QuickStart
Group)”, and the command is:
sc config "QuickStart Server (QuickStart Group)" depend= cassandra
Stop Cassandra on Windows
You can stop Cassandra on Windows in legacy or PowerShell mode.
Legacy mode
In legacy mode, you cannot start Cassandra in the background on the command line. To stop Cassandra running in the foreground, enter Ctrl-C in the console.
PowerShell mode
When Cassandra starts in a background mode, it creates a pid.txt file in CASSANDRA_HOME that contains the process ID of Cassandra running in background. Use this process ID to terminate the Cassandra process with the taskkill command. For example:
> cd c:\cassandra
> type pid.txt
1564
> taskkill /F /PID 156
Stop Cassandra as a Windows service
If you install Cassandra as a Windows service, you can stop Cassandra using the Windows Service Manager (Run > service.msc), or alternatively from the command line using sc.exe. For more details, see Start Cassandra as a Windows service on page 62.
Connect to API Gateway for the first time
Connecting to API Gateway depends on your installation setup type (Standard, Complete, or Custom).
Axway API Gateway 7.5.3
Installation Guide 63
5 Install Apache Cassandra
Standard or Complete setup
If you installed a default Standard or Complete setup (both include the QuickStart tutorial), Cassandra is installed on the same host, and listens on localhost by default. API Gateway runs on the same host and connects to Cassandra by default.
Custom setup
If you installed a Custom setup, and did not select the Quickstart tutorial, you must update the API Gateway Cassandra client configuration as follows:
1. Open the API Gateway group configuration in Policy Studio.
2. Select Server Settings > Cassandra > Authentication, and set the Cassandra username/password (default is cassandra/ cassandra).
3. Select Server Settings > Cassandra > Hosts. Add an address for the Cassandra node. You can enter an IP address or host name.
4. Deploy the configuration to the API Gateway group.
For more details on configuring Server Settings in the Policy Studio client, see the API Gateway Administrator Guide. For details on updating the Cassandra server configuration, see Configure a Cassandra HA cluster on page 45.
Further details
For more details on Apache Cassandra, see the following: l http://cassandra.apache.org/
l http://docs.datastax.com/en/cassandra/2.2/
Perform essential Cassandra operations
There are many possible Cassandra administration operations. This section covers the minimum essential operations that are required to maintain a healthy Cassandra HA cluster.
Perform anti-entropy repair
Cassandra is inherently HA, so when a node is absent from a cluster for a time, it can be brought back into the cluster and becomes eventually consistent by design. Node repair is required after reintegration into the cluster. Axway API Gateway 7.5.3
Installation Guide 64
5 Install Apache Cassandra
The nodetool repair command repairs inconsistencies across all Cassandra replica nodes for a given range of data. Most importantly, it ensures that deleted data remains deleted in a distributed system. You should execute this command at least weekly, at off-peak times, and stagger execution on different nodes.
For example, the following crontab commands execute nodetool repair on specified schedules in test and production environments:
# Every 10 mins. NB: TEST ONLY, not for production.
$ crontab
*/10 * * * * /home/cassandra/bin/nodetool repair >>
/home/cassandra/logs/repair.log
# Every week at 3am on a Sunday
$ crontab
0 2 * 0 /home/cassandra/bin/nodetool repair >>
/home/cassandra/logs/repair.log
On Windows 2012 Server, you can use Windows Task Scheduler.
Note
If a node is down for more than 10 days, it must not join the existing cluster. It should be replaced instead. See Replace dead nodes on page 65.
For more details on nodetool repair, see:
l https://docs.datastax.com/en/cassandra/2.2/cassandra/operations/opsRepairNodesManualRe
pair.html
Replace dead nodes
If a node is down for more than 10 days, it should be replaced. For details on replacing dead Cassandra nodes, see:
l https://docs.datastax.com/en/cassandra/2.2/cassandra/operations/opsReplaceNode.html
Back up and restore Cassandra data
To backup and restore Cassandra data (online and HA), use the following instructions:
l https://docs.datastax.com/en/cassandra/2.2/cassandra/operations/opsBackupRestore.html
Back up configuration and data for disaster
recovery
You must back up the following API Gateway and Cassandra configuration and data for disaster recovery:
Axway API Gateway 7.5.3
Installation Guide 65
5 Install Apache Cassandra
API Gateway group configuration data
Back up the API Gateway group configuration data in apigateway/groups/<groupname>/conf. This contains the API Gateway, API Manager and KPS configuration data. Ensure that you back up these important files.
API Gateway KPS data
Ensure that you back up KPS data regularly on all nodes using the kpsadmin tool. This backs up API Manager and customer KPS data to simple, portable JSON files. These are also independent of Cassandra and Cassandra versions. For more details, see the API Gateway Key Property Store User Guide.
Cassandra configuration
Ensure that you back up the CASSANDRA_HOME/conf directory on all nodes.
Cassandra data
With Cassandra, any node in the system can act as a live backup when replacing a dead node. Data can be restored without affecting availability using Cassandra HA backup and restore. However, it still makes sense to make a regular hard file system backup of the data on all nodes for disaster recovery use cases. Cassandra data resides in CASSANDRA_HOME/data. You should back up this directory on all nodes.
Note
You must stop the Cassandra server before taking a file system backup. This ensures that files are not locked and that all data is flushed to disk. For details, see Install an Apache Cassandra database on page 37.
Ensure time is in sync across the cluster
You should use a time service such as NTP to ensure that time is in sync in the cluster. For example, OAuth Tokens are removed by Cassandra when expired, based upon the time-to-live value set when created. If Cassandra nodes run on servers that are not synchronized, the tokens are removed at different times, and the data is no longer fully synchronized.
Note
You must ensure that the NTP server is on a physical machine, and not a virtual machine, in the datacenter.
For more details, see https://blog.logentries.com/2014/03/synchronizing-clocks-in-a-cassandracluster-pt-2-solutions/
Axway API Gateway 7.5.3
Installation Guide 66
5 Install Apache Cassandra
Reconfigure an existing Cassandra installation
from scratch
There is no need to reinstall Cassandra from scratch. You can just move Cassandra data files and restore the cassandra.yaml configuration file if necessary. Preform the following steps:
1. Stop Cassandra. For details, see Install an Apache Cassandra database on page 37.
2. Move CASSANDRA_HOME/data to CASSANDRA_HOME/data/OLD-DATA-DATE.
3. Restore cassandra.yaml in CASSANDRA_HOME/conf if necessary.
Monitor the Cassandra cluster using JMX
For details on how to monitor and manage performance in a Cassandra cluster using Java Management Extensions (JMX), see the following:
l http://docs.datastax.com/en/archived/cassandra/2.2/cassandra/operations/opsMonitoring.ht
ml
Upgrade your Cassandra version
For details on upgrading your Cassandra version, see Supported Cassandra versions on page 37.
Further details
For more details on Cassandra operations, see:
l http://docs.datastax.com/en/cassandra/2.2/
setup-cassandra script reference
The setup-cassandra script provided by API Gateway enables you to configure a multi-node Cassandra HA cluster automatically. You can use this script when Cassandra is installed locally along with API Gateway, or installed remotely on a different node. For details on supported Cassandra deployment architectures and HA production environments, see Configure a Cassandra HA cluster on page 45.
API Gateway provides the setup-cassandra script to help configure a Cassandra cluster by updating your Cassandra configuration files and providing instructions to finalize the configuration. This script also creates an automatic backup of the original cassandra.yaml file in the following format:
Axway API Gateway 7.5.3
Installation Guide 67
5 Install Apache Cassandra
<timestamp>_cassandra.yaml.bak
This topic describes how to run the setup-cassandra script, and how to configure a multinode Cassandra cluster with username/password authentication enabled. It also describes how to configure TLS v1.2 encryption for client-server and inter-node communications in the cluster.
Prerequisites
The following prerequisites apply for the setup-cassandra script:
Python
The Cassandra cqlsh command requires Python version 2.7.10 to be installed on the node. For example, this command enables you to set up the seed node and change the default user name and password.
User name and password authentication
User name and password authentication for clients connecting to the cluster is enabled by the setup-cassandra script by default. However, you must change the default user name and password created by Cassandra on startup to further secure the installation. The script provides instructions describing how to change the default user name and password and replicate the system_auth keyspace using the cqlsh command.
For more details, see Secure Cassandra HA configuration on page 71.
Remote Cassandra HA nodes
setup-cassandra is available by default when Cassandra is installed locally on the same node as API Gateway. You can also configure remote Cassandra nodes to use the setup-cassandra script supplied by the API Gateway installation. Alternatively, you can perform all necessary Cassandra configuration changes manually. For details, see Configure a Cassandra HA cluster on page 45.
To configure a remote Cassandra node to use the setup-cassandra script, perform the following steps:
1. Ensure that the JAVA_HOME environment variable is set on the remote Cassandra node. 2. Ensure that Python is installed and added to your PATH environment variable on the remote Cassandra node.
3. Change to the following directory on the local API Gateway node:
AXWAY_HOME/apigateway/system/lib/jython/
Axway API Gateway 7.5.3
Installation Guide 68
5 Install Apache Cassandra
4. Copy the setup-cassandra.py file to your chosen directory on the remote Cassandra node.
Run the setup-cassandra script
The instructions for running the setup-cassandra script depend on whether the node is local or remote to API Gateway.
Run setup-cassandra on local API Gateway node
The setup-cassandra script is bundled with the API Gateway installation and located in the bin directory. To run this script on a local node:
UNIX/Linux
$ cd AXWAY_HOME/apigateway/posix/bin
$ ./setup-cassandra <options>
Windows
> cd AXWAY_HOME\apigateway\win32\bin
> setup-cassandra <options>
Run setup-cassandra on remote Cassandra node
On a remote Cassandra node, you first must ensure that the setup-cassandra script has been configured as described in Remote Cassandra HA nodes on page 68. To run this script on a remote node:
UNIX/Linux
$ ./setup-cassandra.py <options>
Windows
> setup-cassandra.py <options>
Axway API Gateway 7.5.3
Installation Guide 69
5 Install Apache Cassandra
Note
The example commands in this topic assume that Cassandra is installed locally on an API Gateway node.
Configure the seed node
To configure Cassandra to run as the cluster seed node, run the setup-cassandra script with the following options:
setup-cassandra --seed --own-ip=<OWN_IP> --nodes=<NUMBER_OF_NODES> -cassandra-config=<CONFIG_FILE>
These options are described as follows:
OWN_IP
IP address of this Cassandra host. Cassandra uses this IP address for communicating with other nodes in the cluster and for receiving client connections.
NODES
Total number of the nodes in the Cassandra cluster.
CONFIG_FILE
Full path to cassandra.yaml configuration file. Typically the path is <CASSANDRA_INSTALL_
DIR>/conf/cassandra.yaml.
For example:
setup-cassandra --seed --own-ip=ipA --nodes=3 --cassandraconfig=/opt/cassandra/conf/cassandra.yaml
Configure additional nodes
To configure Cassandra on the remaining cluster nodes, run the setup-cassandra script with the following options:
setup-cassandra --seed-ip=<SEED_IP> --own-ip=<OWN_IP> --cassandraconfig=<CONFIG_FILE>
These options are described as follows:
SEED_IP
Axway API Gateway 7.5.3
IP address of the Cassandra seed host (see Configure the seed node on page 70).
Installation Guide 70
5 Install Apache Cassandra
OWN_IP
IP address of this Cassandra host. Cassandra uses this IP address for communicating with other nodes in the cluster and for receiving client connections.
CONFIG_
Full path to cassandra.yaml configuration file. Typically the path is FILE
<CASSANDRA_INSTALL_DIR>/conf/cassandra.yaml.
For example:
setup-cassandra --seed-ip=ipA --own-ip=ipB --cassandraconfig=/opt/cassandra/conf/cassandra.yaml
Secure Cassandra HA configuration
This section explains how to use the setup-cassandra script to secure your Cassandra HA configuration. The examples assume that Cassandra is installed locally on the same host as API Gateway. See also Run setup-cassandra on remote Cassandra node on page 69.
Reset your default user name and password
You can use the setup-cassandra script to reset the default user name and password ( cassandra/ cassandra). Run this command to see the instructions that you need to follow. For example, on the seed node the instructions are as follows:
./setup-cassandra --seed --own-ip=ipA --nodes=3 --cassandra
config=/opt/cassandra/conf/cassandra.yaml
Connect to Cassandra with cqlsh and run following commands to create an
alternative superuser account:
CREATE USER admin WITH PASSWORD 'amujsa26al2ns' SUPERUSER;QUIT
PLEASE MAKE A NOTE OF USERNAME AND PASSWORD FOR THE NEW SUPERUSER
ACCOUNT:
USERNAME: admin PASSWORD: amujsa26al2ns
Connect to Cassandra using newly created account to lock out the default
Cassandra superuser account and update "system_auth" keyspace
replication factor:
/opt/cassandra/bin/cqlsh -u admin -p amujsa26al2ns node1 ALTER USER
cassandra WITH PASSWORD
'g5q5h4h3bf1pnh2nsra9iucd82d7f1jams468vhaiimtibtuqpf' NOSUPERUSER;
ALTER KEYSPACE "system_auth" WITH REPLICATION = { 'class':
'SimpleStrategy', 'replication_factor': 3 }; QUIT
Note
If you are setting up a Cassandra HA cluster, you must replicate the system_auth keyspace as shown in this example. This enables API Gateway to communicate with the cluster if a node goes down. For more details, see:
Axway API Gateway 7.5.3
Installation Guide 71
5 Install Apache Cassandra
l https://docs.datastax.com/en/cassandra/2.2/cassandra/configuration/secu
reConfigNativeAuth.html?hl=authentication
Enable node-to-node traffic encryption
To configure TLS v1.2 encryption, you must generate a private key and certificate for every Cassandra node in the cluster. You must also obtain the certificate for the Certification Authority (CA) used to generate the node certificate. You can use Policy Studio to create the necessary certificates and keys or any other suitable method for generating certificates.
You must export and save the node certificate and private key as a PKCS12 file named server.p12, and save the CA certificate as a PEM file named ( server-ca.pem). You must place these files into the same directory where you run the setup-cassandra script from.
To use the setup-cassandra script to configure node-to-node TLS/SSL encryption, add the -enable-server-encryption option. For example:
setup-cassandra --seed-ip=ipA --own-ip=ipB --cassandraconfig=/opt/cassandra/conf/cassandra.yaml --enable-server-encryption
After you run the setup-cassandra script, it provides instructions for converting the keys and certificates to a format required by Cassandra. After you perform these instructions, you can remove the server.p12 and server-ca.pem files from the system.
Caution
Anyone with a private key or certificate signed by server-ca.pem can connect to the cluster. You should limit the use of this CA to signing the node certificates only. In particular, do not use the same CA to sign client-to-node certificates.
Enable client-to-node traffic encryption
The requirements for setting up client-to-node TLS/SSL encryption are the same as the node-tonode TLS/SSL requirements. However, you must save the CA certificate/private key and node certificate in client-ca.pem and client.p12 files respectively. For example, to instruct the setup-cassandra script to configure client-to-node encryption, add the --enableclient-encryption option to script arguments:
setup-cassandra --seed-ip=ipA --own-ip=ipB --cassandraconfig=/opt/cassandra/conf/cassandra.yaml --enable-client-encryption
After you run the setup-cassandra script, it provides instructions for converting the keys and certificates to a format required by Cassandra. After you perform these instructions, you can remove the client.p12 and client-ca.pem files from the system.
Axway API Gateway 7.5.3
Installation Guide 72
5 Install Apache Cassandra
Configure the cqlsh command for client-to-node traffic
encryption
When the Cassandra cluster has been configured to use client-to-node TLS/SSL encryption, you must configure all clients connecting to the cluster (including cqlsh) to use TLS/SSL.
If client-to-node TLS/SSL encryption has been enabled, the setup-cassandra script creates a configuration file ( cqlshrc) with the necessary configuration to enable TLS/SSL encryption. However, you must provide following files to configure cqlsh for TLS/SSL:
l client-ca.pem: PEM file containing CA certificate
l cqlsh-cert.pem: PEM file containing client certificate for cqlsh
l cqlsh-key.pem: PEM file containing private key of client certificate for cqlsh
Updated Cassandra configuration
This section shows the updates that the setup-cassandra script makes to the cassandra.yaml configuration file: General settings
l seed_provider, parameters, seeds: <IP address of seed node>
l start_native_transport: true
l native_transport_port: 9042
l listen_address: IP address of the node
l rpc_address: IP address of the node
l authenticator: org.apache.cassandra.auth.PasswordAuthenticator
l authorizer: org.apache.cassandra.auth.CassandraAuthorizer
Node-to-node traffic encryption
If node-to-node TLS/SSL traffic encryption is enabled:
l server_encryption_options: Specified options
l internode_encryption: all
l keystore: <server-keystore.jks>
l keystore_password: Randomly generated password
l truststore: <server-truststore.jks>
Axway API Gateway 7.5.3
Installation Guide 73
5 Install Apache Cassandra
l truststore_password: Randomly generated password
l protocol: TLS
l store_type: JKS
l algorithm: SunX509
l require_client_auth: true
Client-to-node traffic encryption
If client-to-node TLS/SSL traffic encryption is enabled:
l client_encryption_options: Specified options
l enabled: true
l optional: false
l keystore: <client-truststore.jks>
l keystore_password: Randomly generated password
l truststore: <client-truststore.jks>
l truststore_password: Randomly generated password
l protocol: TLS
l store_type: JKS
l algorithm: SunX509
l require_client_auth: true
Axway API Gateway 7.5.3
Installation Guide 74
Install API Gateway
components
6
This topic describes how to install each API Gateway component separately. The API Gateway installer enables you to perform the following:
l Install the API Gateway server on page 75
l Install the QuickStart tutorial on page 77
l Install the Admin Node Manager on page 80
l Install Policy Studio on page 81
l Install API Tester on page 83
l Install Configuration Studio on page 82
l Install API Manager on page 84
l Install the Package and Deploy tools on page 86
l Install API Gateway Analytics on page 88
For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Install the API Gateway server
The API Gateway server is the main runtime environment consisting of an API Gateway instance and a Node Manager. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Note
It is not necessary to install the API Gateway server on the API Gateway appliance because this component is preinstalled on the appliance. Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway license file
You must have a valid Axway license file to install the API Gateway server. Also, if you intend to run API Gateway in FIPS-compliant mode, ensure that your license file allows this. To obtain an evaluation trial license or a full license, contact your Axway Account Manager. Axway API Gateway 7.5.3
Installation Guide 75
6 Install API Gateway components
Note
If you are using Apache Cassandra, before starting API Gateway, you must first ensure that Cassandra is installed and running. For more details, see Install an Apache Cassandra database on page 37.
Install the API Gateway server
To install the API Gateway server in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the API Gateway server component.
To install the API Gateway server in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the API Gateway server component in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components apigateway
--disable-components nodemanager,qstart,analytics,policystudio,
apitester,configurationstudio,apimgmt,cassandra,packagedeploytools
--licenseFilePath mylicense.lic
Before you start API Gateway
Note
Before you can start the API Gateway, you must first use the managedomain script to create a new domain that includes an API Gateway instance. If you installed the QuickStart tutorial, a sample API Gateway domain is automatically configured in your installation. Otherwise, you must first create a new domain. For more details, see the API Gateway Administrator Guide. If you installed the QuickStart tutorial, the QuickStart server and Admin Node Manager start automatically. Otherwise, you must start them manually.
If you installed Apache Cassandra, before starting API Gateway, you must first ensure that your Apache Cassandra server is running. For more details, see Install an Apache Cassandra database on page 37.
Start API Gateway
To start the API Gateway manually, follow these steps:
1. Open a command prompt in the following directory:
Axway API Gateway 7.5.3
Installation Guide 76
6 Install API Gateway components
Windows
INSTALL_DIR\apigateway\Win32\bin
UNIX/Linux
INSTALL_DIR/apigateway/posix/bin
2. Run the startinstance command, for example:
startinstance -n "Server1" -g "Group1"
Note
On UNIX/Linux, you must ensure that the startinstance has execute permissions. 3. To manage and monitor the API Gateway, you must ensure that the Admin Node Manager is running. Use the nodemanager command to start the Admin Node Manager from the same directory. 4. To launch API Gateway Manager, enter the following address in your browser:
https://HOST:8090/
HOST refers to the host name or IP address of the machine on which API Gateway is running (for example, https://localhost:8090/).
5. Enter the administrator user name and password. This is the administrator user name and password you entered during installation.
Note
You can encrypt all sensitive API Gateway configuration data with an encryption passphrase. For example, you can specify this passphrase in your API Gateway configuration file, or on the command line when the API Gateway is starting up. For more details, see the API Gateway Administrator Guide. Start as a service
You can also run API Gateway instances and Node Managers as services. For more information, see Set up services on page 103.
Install the QuickStart tutorial
The API Gateway QuickStart tutorial demonstrates the main API Gateway features and tools, and enables you to invoke some example APIs and to monitor the API Gateway using API Gateway Manager.
Tip
The QuickStart tutorial is automatically installed as part of a default Standard or Complete setup. For more details, For more details, see Installation options on page 28.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met.
Axway API Gateway 7.5.3
Installation Guide 77
6 Install API Gateway components
Install the QuickStart tutorial
Note
The QuickStart tutorial depends on the API Gateway Server. You cannot install the QuickStart tutorial without the API Gateway Server.
To install the API Gateway Server and the QuickStart tutorial in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the API Gateway Server, Admin Node Manager, and QuickStart tutorial components.
To install the API Gateway Server, Admin Node Manager, and QuickStart tutorial in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the API Gateway Server component and the QuickStart tutorial in unattended mode:
APIGateway_7.5.3_Install_linux-x86-32_BN20171109.run --mode unattended
--setup_type advanced --enable-components apigateway,nodemanager,qstart
--disable-components
analytics,policystudio,apitester,configurationstudio,apimgmt,cassandra,packagedeploy
tools
--licenseFilePath mylicense.lic
QuickStart domain configuration
When the QuickStart tutorial is installed, a sample API Gateway domain is automatically configured in your installation. This includes a QuickStart Server API Gateway instance that runs in a QuickStart Group group. The QuickStart server and Admin Node Manager start automatically when installation is complete.
Start the QuickStart tutorial
The QuickStart tutorial launches automatically in your browser when installation is complete. Follow the instructions in your browser to perform the steps in the tutorial.
Axway API Gateway 7.5.3
Installation Guide 78
6 Install API Gateway components
For example, the following screen shows invoking a sample API in the tutorial:
You can click the Try it button to invoke the sample API. This displays a JSON list of available products. You can click the Show Me button to view the traffic monitored by the API Gateway in the API Gateway Manager.
Restart the QuickStart tutorial
At any point, if you need to restart the QuickStart tutorial, perform the following steps:
1. Open a command prompt in the following directory:
Windows
INSTALL_DIR\apigateway\Win32\bin
UNIX/Linux
INSTALL_DIR/apigateway/posix/bin
2. Run the startinstance command, for example:
startinstance -n "QuickStart Server" -g "QuickStart Group"
Note
Axway API Gateway 7.5.3
On UNIX/Linux, you must ensure that the startinstance file has execute permissions. Installation Guide 79
6 Install API Gateway components
3. To manage and monitor the API Gateway, you must ensure that the Admin Node Manager is running. Use the nodemanager command to start the Admin Node Manager from the same directory. 4. To launch API Gateway Manager, enter the following address in your browser:
https://127.0.0.1:8090/
5. Enter the administrator user name and password. This is the administrator user name and password you entered during installation. 6. To launch the QuickStart tutorial, enter the following address in your browser:
http://127.0.0.1:8080/quickstart/index.html?mgr=8090
Install the Admin Node Manager
You can install an Admin Node Manager component in isolation without an API Gateway license. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install the Admin Node Manager
To install the Admin Node Manager in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the Admin Node Manager component.
To install the Admin Node Manager in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the Admin Node Manager component in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components apigateway
--disable-components analytics,qstart,policystudio,configurationstudio,
apitester,apimgmt,cassandra,packagedeploytools
Axway API Gateway 7.5.3
Installation Guide 80
6 Install API Gateway components
Start the Admin Node Manager
For more information on starting the Admin Node Manager, see Start API Gateway on page 76.
Install Policy Studio
Policy Studio is a graphical IDE that enables developers to virtualize APIs and develop policies to enforce security, compliance, and operational requirements. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install Policy Studio
To install Policy Studio in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the Policy Studio component.
To install Policy Studio in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the Policy Studio component in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32-BN<n>.run --mode unattended
--setup_type advanced
--enable-components policystudio
--disable-components analytics,nodemanager,apigateway,qstart,
apitester,configurationstudio,apimgmt,cassandra,packagedeploytools
Start Policy Studio
Note
Before starting Policy Studio, ensure both the Admin Node Manager and the API Gateway instance are running. For more details, see Start API Gateway on page 76.
If you did not select to launch Policy Studio after installation, perform the following steps:
1. Open a command prompt.
2. Change to your Policy Studio installation directory (for example, INSTALL_
DIR\policystudio).
Axway API Gateway 7.5.3
Installation Guide 81
6 Install API Gateway components
3. Run policystudio.
4. When Policy Studio starts up, select File > New Project. 5. In the New Project dialog, enter a name for the project and click Next.
6. Select From a running API Gateway instance and click Next.
Tip
You can also create configuration projects from .fed files or from existing configurations. For more information, see the API Gateway Policy Developer Guide.
7. In the Open Connection dialog, select the Admin Node Manager session to connect to, enter the administrator user name and password that you specified during installation and click OK. 8. In the Download Options dialog, select a group and an API Gateway instance to download its configuration.
9. If a passphrase has been set, enter it in the Passphrase field, and click Finish. Alternatively, if no passphrase has been set, click Finish. For more details on setting a passphrase, see the API Gateway Administrator Guide.
Install Configuration Studio
Configuration Studio is a graphical tool that enables administrators to configure environmentspecific properties to deploy APIs and policies in non-development environments. For more details, see the API Gateway DevOps Deployment Guide. Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install Configuration Studio
To install Configuration Studio in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the Configuration Studio component.
To install Configuration Studio in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the Configuration Studio component in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components configurationstudio
Axway API Gateway 7.5.3
Installation Guide 82
6 Install API Gateway components
--disable-components analytics,nodemanager,apigateway,qstart,
apitester,policystudio,apimgmt,cassandra,packagedeploytools
Start Configuration Studio
To start Configuration Studio after installation, perform the following steps:
1. Open a command prompt.
2. Change to your Configuration Studio installation directory (for example, INSTALL_
DIR\configurationstudio).
3. Run configurationstudio.
For more details on Configuration Studio, see the API Gateway DevOps Deployment Guide.
Install API Tester
API Tester is a graphical tool that enables you to test API functionality, performance, and security. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide .
Note
API Tester is deprecated and will be removed in a future release. API Tester is no longer installed in a Standard or Complete setup, and is only installed in a Custom setup.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install API Tester
To install API Tester in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the API Tester component.
To install API Tester in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the API Tester component in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components apitester
Axway API Gateway 7.5.3
Installation Guide 83
6 Install API Gateway components
--disable-components analytics,nodemanager,apigateway,qstart,policystudio,
configurationstudio,apimgmt,cassandra,packagedeploytools
Start API Tester
Note
Before starting API Tester, ensure that the Admin Node Manager and the API Gateway instance are running. For more details, see Start API Gateway on page 76.
To start API Tester after installation, perform the following steps:
1. Open a command prompt.
2. Change to your API Tester installation directory (for example, INSTALL_DIR\apitester).
3. Run apitester.
For more details on API Tester, see the API Tester User Guide.
Install API Manager
API Manager is an additional licensed layered product running on the Axway API Gateway. For more details, see the API Manager User Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway license file
You must have a valid Axway license file to install API Manager. To obtain an evaluation trial license or a full license, contact your Axway Account Manager.
Note
Your API Gateway installation must also be licensed. If you do not have a license for API Gateway, you cannot install API Manager.
Domains with multiple nodes
In an API Gateway domain environment with multiple machine nodes, API Manager must be installed on API Gateway instance nodes.
Axway API Gateway 7.5.3
Installation Guide 84
6 Install API Gateway components
Apache Cassandra
The Apache Cassandra database is required to store API Manager data. You can install Cassandra separately before installing API Manager, or when installing API Manager. For more details, see Install Apache Cassandra on page 37.
Install API Manager
To install API Manager in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the following components:
o API Manager
o API Gateway Server
o Admin Node Manager
o Cassandra (if not already installed separately before API Manager)
For more details, see the following: l Install the API Gateway server on page 75
l Install the Admin Node Manager on page 80
l Install an Apache Cassandra database on page 37
Unattended mode
To install API Manager in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the API Manager, API Gateway Server, Admin Node Manager, and Cassandra components in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components apimgmt,apigateway,nodemanager,cassandra
--disable-components qstart,analytics,policystudio,configurationstudio,
apitester,packagedeploytools
--licenseFilePath mylicense.lic
--apimgmtLicenseFilePath mymgmtlicense.lic
Axway API Gateway 7.5.3
Installation Guide 85
6 Install API Gateway components
Configure API Manager
If you selected to install the QuickStart tutorial, API Manager is configured by default. If you did not install the QuickStart tutorial, you must configure API Manager. For more details, see the API Manager User Guide.
Start API Manager
Note
Before starting API Manager, ensure that Apache Cassandra, the Admin Node Manager and API Gateway instance are running. For more details, see Start API Gateway on page 76.
When API Manager is configured, you can use the following URL to log into the API Manager web console:
https://HOST:8075
The default URL is:
https://localhost:8075
Enter your API administrator user credentials. This is the API administrator user name and password you entered during installation. For more information on using API Manager, see the API Manager User Guide.
Install the Package and Deploy tools
You can use the API Gateway Package and Deploy tools to automate processes in your API Gateway system for continuous integration. For example, this includes generating API Gateway configuration packages from API team development projects, and building and deploying c onfigurations to API Gateway group instances. You can install the Package and Deploy tools component without an API Gateway license.
For more details on API Gateway configuration packages, see the API Gateway DevOps Deployment Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met.
Axway API Gateway 7.5.3
Installation Guide 86
6 Install API Gateway components
Install the Package and Deploy tools
To install the Package and Deploy tools in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the Package and Deploy Tools component.
To install the Package and Deploy tools component in unattended mode, follow the steps described in Unattended installation on page 32.
For example, the following command shows how to install the API Gateway Package and Deploy tools only in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components packagedeploytools
--disable-components apigateway, analytics,qstart,policystudio,
configurationstudio,apitester,apimgmt,cassandra
For details on using the Package and Deploy tools to automate processes for continuous integration, see "Upgrade an API Gateway project" in the API Gateway DevOps Deployment Guide.
Axway API Gateway 7.5.3
Installation Guide 87
7
Install and configure API
Gateway Analytics
This topic describes how to use the API Gateway installer to install API Gateway Analytics, and how to configure a your metrics database and API Gateway Analytics.
Note
API Gateway Analytics is deprecated and will be removed in a future release.
This topic includes the following:
l Install API Gateway Analytics on page 88
l Configure the metrics database on page 90
l Configure API Gateway Analytics on page 95
Install API Gateway Analytics
API Gateway Analytics is a server runtime and web-based console for analyzing and reporting on API use over extended periods of time. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Note
API Gateway Analytics is deprecated and will be removed in a future release.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway license file
You must have a valid Axway license file to install API Gateway Analytics. To obtain an evaluation trial license or a full license, contact your Axway Account Manager.
Install API Gateway Analytics
To install API Gateway Analytics in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections:
l Select the Custom setup type.
l Select to install the API Gateway Analytics component.
Axway API Gateway 7.5.3
Installation Guide 88
7 Install and configure API Gateway Analytics
To install API Gateway Analytics in unattended mode, follow the steps described in Unattended installation on page 32.
The following example shows how to install the API Gateway Analytics component in unattended mode:
./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended
--setup_type advanced
--enable-components analytics
--disable-components nodemanager,apigateway,qstart,policystudio,
apitester,configurationstudio,apimgmt,cassandra,packagedeploytools
--analyticsLicenseFilePath myanalyticslicense.lic
Configure your API Gateway Analytics database
Note
Before starting API Gateway Analytics, you must perform the following steps:
1. Create a database instance. For more details, see Configure the metrics database on page 90. Alternatively, if you already have an existing database, skip to the next step.
2. Update your API Gateway Analytics configuration with the database details using the configureserver script. For more details, see Configure API Gateway Analytics on page 95.
3. Configure the database tables using the dbsetup script. For more details, see Configure the metrics database on page 90.
4. Enable writing of metrics from your API Gateway instance to the database using the managedomain tool. For more details, see Configure API Gateway Analytics on page 95.
Start API Gateway Analytics
To start API Gateway Analytics, perform the following steps:
1. Start the API Gateway Analytics server using the analytics script in the bin directory of your API Gateway Analytics installation. 2. To launch API Gateway Analytics, enter the following address in your browser:
http://HOST:8040/
HOST refers to the host name or IP address of the machine on which API Gateway Analytics is running (for example, https://localhost:8040/).
3. Enter the API Gateway Analytics user name and password. Note
Axway API Gateway 7.5.3
This is not the same as the API Gateway Manager user name and password. You can edit the API Gateway Analytics user in Policy Studio under the Environment
Configuration > Users and Groups > Users node. Installation Guide 89
7 Install and configure API Gateway Analytics
Note
API Gateway Analytics produces reports based on metrics stored by API Gateway when processing messages. To produce a graph showing the number of connections made by API Gateway to a service, you must first configure a policy that routes messages to that service. When this policy is configured, send messages through the policy so they are routed to the target service. If you change to another database that has a different set of remote hosts or clients configured, you must restart API Gateway and API Gateway Analytics. Start as a service
You can also run API Gateway Analytics as a service. For more information, see Set up services on page 103.
Further information
For more details on topics such as using Policy Studio to configure policies, set up scheduled reports, view monitoring data in API Gateway Analytics, or purge the metrics database, see the API Gateway Policy Developer Guide and the API Gateway Administrator Guide.
Configure the metrics database
API Gateway stores and maintains the monitoring and transaction data read by API Gateway Analytics and API Manager in a JDBC-compliant database. This topic describes how to create and configure a database for use with API Gateway Analytics or API Manager monitoring. It describes the prerequisites and shows an example of creating a database. It also shows how to setup the database tables or upgrade them from a previous version.
Note
API Gateway Analytics is deprecated and will be removed in a future release.
Prerequisites
The prerequisites for setting up the database are as follows:
Install API Gateway Analytics or API Manager
You must install API Gateway Analytics or API Manager. For more details, see
l Install API Gateway Analytics on page 88
l Install API Manager on page 84
Axway API Gateway 7.5.3
Installation Guide 90
7 Install and configure API Gateway Analytics
Install a JDBC database
You must install a JDBC-compliant database to store the monitoring and transaction data. Axway provides setup scripts for the following databases:
l MySQL or MariaDB
l Microsoft SQL Server
l Oracle
l IBM DB2
For details on supported database versions, see System requirements on page 17. For details on how to install your chosen JDBC database, see your database product documentation.
Add third-party JDBC driver files
You must add the JDBC driver files for your chosen third-party database to your API Gateway, Policy Studio, and API Gateway Analytics installations as appropriate.
Add JDBC drivers to API Gateway
To add the third-party JDBC driver files for your database to API Gateway, perform the following steps:
1. Add the binary files for your database driver as follows:
l Add .jar files to the following directories:
o INSTALL_DIR/apigateway/ext/lib
o INSTALL_DIR/apigateway/groups/GROUP-ID/INSTANCE-
ID/ext/lib
l Add .dll files to the INSTALL_DIR\apigateway\Win32\lib directory.
l Add .so files to the INSTALL_DIR/apigateway/platform/lib directory.
2. Restart API Gateway.
Add JDBC drivers to Policy Studio
To add third-party binaries to Policy Studio, perform the following steps:
1. Select Window > Preferences > Runtime Dependencies from the Policy Studio main menu.
2. Click Add to select a JAR file to add to the list of dependencies.
3. Click Apply when finished. A copy of the JAR file is added to the plugins directory Axway API Gateway 7.5.3
Installation Guide 91
7 Install and configure API Gateway Analytics
in your Policy Studio installation.
4. Click OK.
5. Restart Policy Studio using the policystudio -clean command.
Add JDBC drivers to API Gateway Analytics
To add the third-party JDBC driver files for your database to API Gateway Analytics (if installed), perform the following steps:
1. Add the binary files for your database driver as follows:
l Add .jar files to the INSTALL_DIR/analytics/ext/lib directory.
l Add .dll files to the INSTALL_DIR\analytics\Win32\lib directory.
l Add .so files to the INSTALL_DIR/analytics/platform/lib
directory.
2. Restart API Gateway Analytics.
Create the database
API Gateway Analytics and API Manager monitoring read message metrics from a database and display this information in a visual format to administrators. This is the same database in which API Gateway stores its message metrics and audit trail data. You must first create this database using the third-party database of your choice (MySQL or MariaDB, Microsoft SQL Server, Oracle, or IBM DB2). For details on how to do this, see the product documentation for your chosen database.
The following example shows creating a MySQL or MariaDB database:
mysql> CREATE DATABASE reports;
Query OK, 1 row affected (0.00 sec)
In this example, the database is named reports, but you can use any appropriate name. Set up the database tables
When you have created the database, the next step is to set up the database tables.
API Gateway Analytics
You can do this by running the dbsetup command without any options from the following API Gateway Analytics directory:
Windows
Axway API Gateway 7.5.3
INSTALL_DIR\analytics\Win32\bin
Installation Guide 92
7 Install and configure API Gateway Analytics
UNIX/Linux
Note
INSTALL_DIR/analytics/posix/bin
You do not need to run dbsetup again for API Manager monitoring if it has already been run for API Gateway Analytics.
API Manager
For API Manager monitoring, you can run the dbsetup command from the following API Gateway directory:
Windows
INSTALL_DIR\apigateway\Win32\bin
UNIX/Linux
INSTALL_DIR/apigateway/posix/bin
The following example command applies to both API Gateway Analytics and API Manager monitoring, and shows setting up new database tables:
>dbsetup.bat
New databaseSchema successfully upgraded to:001-topology
Specify options to dbsetup
Note
When you specify command-line arguments to dbsetup, the script does not run interactively. You should run dbsetup without any options to create the database tables.
You can specify the following options to the dbsetup command:
Option
Description
-h, --help
Displays help message and exits.
-p PASSPHRASE, -passphrase=PASSPHRASE
Specifies the configuration passphrase (blank for zero length).
--dbname=DBNAME
Specifies the database name (mutually exclusive with --
dburl,--dbuser, and --dbpass).
--dburl=DBURL
Specifies the database URL.
--dbuser=DBUSER
Specifies the database user.
--dbpass=DBPASS
Specifies the database passphrase.
Axway API Gateway 7.5.3
Installation Guide 93
7 Install and configure API Gateway Analytics
Option
Description
--reinstall
Forces a reinstall of the database, dropping all data.
--stop=STOP
Stops the database upgrade after the named upgrade.
dbsetup examples
The following are some examples of using dbsetup command options.
Connect to a named database
You can use the --dbname option to connect to a named database connection configured under the External Connections node in the Policy Studio tree. For example:
>dbsetup.bat --dbname=Oracle
Current schema version:001-initial
Latest schema version:001-topology
Schema successfully upgraded to:001-topology
Connect to a database URL
You can use the --dburl option to manually connect to a database instance directly using a URL. For example:
>dbsetup.bat --dburl=jdbc:mysql://localhost/reports
--dbuser=root --dbpass=admin
Current schema version:001-initial
Latest schema version:001-topology
Schema successfully upgraded to:001-topology
Install a database
You can also use the --dburl option to set up a newly created database instance where none already exists. For example:
>dbsetup.bat --dburl=jdbc:mysql://localhost/reports
--dbuser=root --dbpass=admin
New database
Schema successfully upgraded to:001-topology
Reinstall a database
You can use the --reinstall option to wipe and reinstall a database. For example:
Axway API Gateway 7.5.3
Installation Guide 94
7 Install and configure API Gateway Analytics
>dbsetup.bat --dburl=jdbc:mysql://localhost/reports
--dbuser=root --dbpass=admin
--reinstall
Re-installing database...
Schema successfully upgraded to:001-topology
SQL database schema scripts
As an alternative to using the dbsetup command, API Gateway Analytics also provides separate SQL schema scripts to set up the database tables for each of the supported databases. However, these scripts set up new tables only, and do not perform any upgrades of existing tables. These scripts are provided in the INSTALL_DIR/system/conf/sql directory in the following subdirectories:
l /mysql
l /mssql
l /oracle
l /db2
Note
The scripts in the /mysql folder apply to both MySQL and MariaDB.
You can run the SQL commands in the analytics.sql file in the appropriate directory for your database. The following example shows creating the tables for a MySQL database: mysql> \. C:\axway\analytics\system\conf\sql\mysql\analytics.sql
Query OK, 0 rows affected, 1 warning (0.00 sec)
Query OK, 0 rows affected, 1 warning (0.00 sec)
...
Configure API Gateway Analytics
This topic describes how to update an API Gateway Analytics configuration (for example, the API Gateway Analytics port, database connection, and user credentials) before starting API Gateway Analytics. You can use the configureserver script (recommended) to guide you through all the required steps, or you can use Policy Studio to configure the API Gateway Analytics configuration file.
Note
API Gateway Analytics is deprecated and will be removed in a future release.
Prerequisites
The prerequisites for configuring API Gateway Analytics are as follows:
Axway API Gateway 7.5.3
Installation Guide 95
7 Install and configure API Gateway Analytics
Install API Gateway
Because API Gateway Analytics reports on transactions processed by API Gateway in real time, you must first install API Gateway. For more details, see Install the API Gateway server on page 75.
Note
To view API Gateway metrics in API Gateway Analytics, you must also enable the recording of metrics. For more details, see Enable metrics for your API Gateway host on page 99.
Install API Gateway Analytics
You must install API Gateway Analytics. For details on how to install API Gateway Analytics, see Install API Gateway Analytics on page 88.
Configure a database
You must install a JDBC-compliant database to store the API Gateway monitoring and transaction data. For more details, see Configure the metrics database on page 90.
Update API Gateway Analytics configuration
By default, API Gateway Analytics is configured to read message metrics from a MySQL database stored on the local machine. You can use the configureserver command to configure API Gateway Analytics to use an alternative database, change the user credentials on the default database connection, or use a different listening port.
Update configuration on the command line
Perform the following steps to run configureserver in interactive mode:
1. Change to the following directory:
Windows
INSTALL_DIR\analytics\Win32\bin
UNIX/Linux
INSTALL_DIR/analytics/posix/bin
2. Run the configureserver command. 3. Enter the port on which the API Gateway Analytics server will listen. Defaults to 8040. If you have another process already using this port on the machine on which API Gateway Analytics is installed, configure API Gateway Analytics to listen on a different port. 4. Enter the database connection URL. Defaults to jdbc:mysql://127.0.0.1:3306/reports.
Axway API Gateway 7.5.3
Installation Guide 96
7 Install and configure API Gateway Analytics
The following table lists examples of connection URLs for the supported databases, where reports is the name of the database and DB_HOST is the IP address or host name of the machine on which the database is running:
Database
Example connection URL
Oracle
jdbc:oracle:thin:@DB_HOST:1521:reports
Microsoft
SQL Server
jdbc:sqlserver://DB_
HOST:1433;DatabaseName=reports;integratedSecu
rity=false;
MySQL/Mari
aDB
jdbc:mysql://DB_HOST:3306/reports
IBM DB2
jdbc:db2://DB_HOST:50000/reports
Note
You can use the jdbc:mysql://DB_HOST:3306/reports URL with both MySQL and MariaDB databases.
5. Enter the database user name. Defaults to root.
6. Enter the database password.
7. Enter whether API Gateway Analytics generates PDF-based reports. Defaults to N, which means that PDF reports are not generated. When set to Y, API Gateway Analytics generates PDF reports that include the same metrics displayed in the API Gateway Analytics window (for example, number of client requests, requests per service, and so on). For more details on generated PDF reports, see the API Gateway Administrator Guide.
8. Enter the user name to connect to the API Gateway Analytics process that generates PDF reports. Defaults to an administrator user.
Note
This is not the operating system user. This is the user that connects to the API Gateway Analytics web server process, which generates the PDF reports. You can add new users under the Environment Configuration > Users and Groups node in Policy Studio.
9. Enter the password to connect to the API Gateway Analytics process that generates PDF reports.
10. Enter the directory to which generated PDF reports are output (for example, c:\reports).
11. Enter whether to send generated PDF reports to email recipients. You will require an SMTP account with which to send the reports. Defaults to N.
The following command shows some example output in interactive mode:
C:\Axway\analytics\Win32\bin>configureserver.bat
Connecting to configuration at : federated:file:///C:\Axway\analytics/conf/fed/
configs.xml
Axway API Gateway 7.5.3
Installation Guide 97
7 Install and configure API Gateway Analytics
Listening port [8040]:
Configuring Database: Default Database Connection
Database URL [jdbc:mysql://127.0.0.1:3306/reports]:
Database user name [root]:
Database password []: *****
Enable report generation (Y, N) [N]: y
Report generation process connects as user name [admin]:
Report generation process connects using password []: ********
Report output directory []: c:\reports
Email reports (Y, N) [N]: y
Default email recipient []: [email protected]
Email from []: [email protected]
Choose SMTP connection type:
0) None
1) SSL
2) TLS/SSL
Choice [0]:
SMTP host []: localhost
SMTP port [25]:
SMTP user name []: jbloggs
SMTP password []: *********
Delete report file after emailing (Y, N) [Y]:
Press enter to exit...
Update configuration using command-line options
You can also run the configureserver command with various options ( --port, --dburl, --emailfrom, --emailto, --smtphost, and so on). For example, the following command configures the database connection without emailing reports:
configureserver --dburl=jdbc:mysql://127.0.0.1:3306/631v2
--dbuser=root --dbpass=changeme --no-email
The following command specifies to email reports and the associated SMTP settings:
configureserver --dburl=jdbc:mysql://127.0.0.1:3306/reports
--dbuser=root --dbpass=changeme
–-email [email protected] [email protected]
--smtptype=NONE --smtphost=192.168.0.174 --smtpport=25
--smtpuser=jbloggs --smtppass=changeme
--generate --gpass=changeme --gtemp=c:\reports
For descriptions of all available options, enter the configureserver --help command.
Note
The configureserver script does not permit the euro character ( €) when specifying username and password options. However, you can specify the pound ( £) and dollar ( $) characters instead.
Axway API Gateway 7.5.3
Installation Guide 98
7 Install and configure API Gateway Analytics
Update configuration in Policy Studio
The recommended way to configure API Gateway Analytics is using the configureserver command, which guides you through the required settings. However, you can also use the Policy Studio to configure specific settings in your API Gateway Analytics configuration file. For example, to configure the reports database, perform the following steps:
1. In your Policy Studio installation directory, run the policystudio command. 1. When Policy Studio starts up, select File > New Project.
2. In the New Project dialog, enter a name for the project and click Next.
3. Select From existing configuration and click Next.
4. Browse to the directory containing the API Gateway Analytics configuration file ( configs.xml), for example:
INSTALL_DIR/analytics/conf/fed/
5. Select Environment Configuration > External Connections in the Policy Studio tree, and expand the Database Connections tree node.
6. Right-click the Default Database Connection tree node, and select Edit.
7. The Database Connection dialog enables you to configure the database connection details. By default, the connection is configured to read metrics data from the reports database. Edit the details for the Default Database Connection on this dialog. For example, you should enter a non-default database user name and password. To connect to a database other than the default local database, right-click Database Connections in the tree, and select Add a Database Connection. For more details, see the API Gateway Policy Developer Guide.
Note
You can verify that your database connection is configured correctly by clicking the Test Connection button on the Configure Database Connection dialog. Enable metrics for your API Gateway host
Finally, you must use the managedomain tool to enable writing of metrics from the API Gateway instances on your host to the metrics database. This enables the Node Manager to process event logs from your API Gateway instances, and to write metrics data to the metrics database.
The following example uses the interactive managedomain --menu command:
Select option: 2
Select a host:
1) LinuxMint01
2) Enter host name
Enter selection from 1-2 [2]: 1
Axway API Gateway 7.5.3
Installation Guide 99
7 Install and configure API Gateway Analytics
Hit enter to continue...
Enter a new host name [LinuxMint01]:
Enter a new Node Manager name [Node Manager on LinuxMint01]:
Enter a new Node Manager port [8090]:
There is only one Node Manager in this domain so it must remain as an Admin Node
Manager
Do you want to create an init.d script for this Node Manager [n]:
Do you want to reset the passphrase for the Node Manager on this host ? [n]:
Do you wish to edit metrics configuration (y or n) ? [n]: y
Do you wish to enable metrics (y or n) ? [y]: y
Enter metrics database URL [jdbc:mysql://127.0.0.1:3306/reports]:
Enter metrics database username [root]:
Enter metrics database plaintext password [*******]:
Testing Database connectivity for : jdbc:mysql://127.0.0.1:3306/reports, user : root
Metrics database connectivity succeeded
Metrics generation enabled. All other specified metrics settings updated.
Metrics settings updated successfully. Please reboot Node Manager on completion of
this program.
Completed successfully.
For more details on configuring API Gateway for API Gateway Analytics, see the section on monitoring and reporting in the API Gateway Administrator Guide.
Axway API Gateway 7.5.3
Installation Guide 100
Post-installation
8
This topic describes various tasks that you might perform after installing API Gateway. This includes how to check if an installation has been successful, any initial configuration needed before you can start API Gateway, what you should do to secure API Gateway, and so on.
This topic includes the following:
l Post-installation on page 101
l Initial configuration on page 102
l Secure API Gateway on page 103
l Set up services on page 103
l Set up clustering on page 105
l Next steps on page 105
Verify the installation
To verify your installation, follow these guidelines:
l Check the installation results
l Start API Gateway components
l Log in to the API Gateway tools
Check the installation log
You can examine the installation log in the root directory of the installation (for example, AxwayinstallLog.log).
Start API Gateway components
l To start the API Gateway Server and Admin Node Manager, see Start API Gateway on page 76.
l To start API Gateway Analytics, see Start API Gateway Analytics on page 89.
Axway API Gateway 7.5.3
Installation Guide 101
8 Post-installation
Log in to the API Gateway tools
l To start the Policy Studio desktop tool, see Start Policy Studio on page 81.
l To log in to the API Gateway Manager web-based administration tool, see Start API Gateway on page 76.
l To start the Configuration Studio desktop tool, see Start Configuration Studio on page 83.
l To start the API Tester desktop tool, see Start API Tester on page 84.
l To log in to the web-based API Gateway Analytics interface, see Start API Gateway Analytics on page 89.
l To log in to the API Manager web-based tool, see Start API Manager on page 86.
Initial configuration
Depending on the installation options you selected, the following tasks might need to be completed before you can start API Gateway.
Create a new domain
If you did not install the QuickStart tutorial, you must use the managedomain script to create a new managed domain that includes an API Gateway instance. Note
This is required if you did not install the QuickStart tutorial.
Windows
INSTALL_DIR\apigateway\Win32\bin
UNIX/Linux
INSTALL_DIR/apigateway/posix/bin
For more details on running managedomain, see the API Gateway Administrator Guide. Set up a database for API Gateway Analytics
If you installed API Gateway Analytics, you must set up a JDBC-compliant database, before you can start API Gateway Analytics:
l First, you must install and configure a database to store the monitoring and transaction data read by API Gateway Analytics. See Configure the metrics database on page 90.
l Next, you must configure API Gateway Analytics to use this database instead of the default (a MySQL database stored on the local machine). See Configure API Gateway Analytics on page 95.
Axway API Gateway 7.5.3
Installation Guide 102
8 Post-installation
Secure API Gateway
It is important to secure your API Gateway system as soon as possible after installation, to protect the API Gateway environment from internal or external threats.
Change default passwords
If you did not set an administrator user name and password during installation, you should change the default administrator user name and password now. For more details on managing administrator users, see the API Gateway Administrator Guide.
Change default certificates
The default c ertificates used to secure API Gateway components are self-signed. You can replace these self-signed certificates with certificates issued by a Certificate Authority (CA). For more information, see the API Gateway Administrator Guide.
Encrypt API Gateway configuration
By default, API Gateway configuration is unencrypted. You can specify a passphrase to encrypt API Gateway instance configuration. For more details, see the API Gateway Administrator Guide.
Run as non-root on UNIX/Linux
In a typical deployment on Linux or UNIX, the process for the API Gateway instance runs as root, to enable the API Gateway to listen on privileged ports. However, you can run the API Gateway process as a non-root user and still allow access to privileged ports. For more details, see the API Gateway Administrator Guide.
Set up services
This section explains how to run various components as services.
API Gateway
You can run Node Managers and API Gateway instances as services using the managedomain script. To register a Node Manager or an API Gateway instance as a service on UNIX/Linux or Windows, you must run the managedomain command as root on UNIX/Linux, or Administrator on Windows. For example:
Axway API Gateway 7.5.3
Installation Guide 103
8 Post-installation
l Node Manager: Enter managedomain --menu, and choose option 2, Edit a host.
l API Gateway instance: Enter managedomain --menu, and choose option 10, Add
script or service for existing local API Gateway.
Alternatively, you can run managedomain in command mode with the --add_service option to create a service for a Node Manager or API Gateway instance.
For more details on managedomain, see the API Gateway Administrator Guide.
API Gateway Analytics
You can also run API Gateway Analytics as a service. On UNIX/Linux, you must create the script manually. A sample script and ReadMe is provided in the following directory:
INSTALL_DIR/analytics/posix/samples/etc/init.d/
On Windows, change to the following directory:
C:\INSTALL_DIR\analytics\Win32\bin
Enter the following command:
installservice.bat "C:\INSTALL_DIR\analytics" "Analytics"
"7.5.3" analytics.xml
The command options are:
<"Installation Path"><"Name"><"Version"><Configuration File>
These options are explained as follows:
l Installation Path: The path to and including API Gateway Analytics.
l Name and Version: Used to name the Windows service.
l Configuration File: This should almost always be analytics.xml. The installservice.bat script hard-codes system\conf to give the full path to the existing configuration file.
Apache Cassandra
For details on running Apache Cassandra as a service, see Install an Apache Cassandra database on page 37.
Axway API Gateway 7.5.3
Installation Guide 104
8 Post-installation
Set up clustering
To set up API Gateway for high availability, you need to configure an external Apache Cassandra database for clustering. For more information, see the following topics: l Configure a Cassandra HA cluster on page 45
l Configure API Management in multiple datacenters on page 106
Next steps
Consult the API Gateway Administrator Guide for more information on administering, managing, and troubleshooting an API Gateway system. This guide contains many topics that you will find useful after installing API Gateway. For example:
l Manage an API Gateway domain
l Configure API Gateway for high availability
l Backup and disaster recovery
l Configure scheduled reports
l Manage user access
Axway API Gateway 7.5.3
Installation Guide 105
Configure API Management in
multiple datacenters
9
This topic describes the recommended multi-datacenter configuration that applies to the various types of API Management data in storage. For each data type, it describes how data is replicated across the datacenter, the recommended configuration, and expected behavior in case of failover.
This topic includes the following:
l Multi-datacenter deployment on page 106
l Multi-datacenter configuration on page 109
l Multi-datacenter failover scenarios on page 127
Multi-datacenter deployment
This topic describes the infrastructure required for API Management multi-datacenter deployment. It describes the various types of API Management data. For example, this includes API catalog, client registry, OAuth tokens, quota, Key Property Store (KPS), and so on. It also describes where the d ata is stored. For example, this includes files on disk, Apache Cassandra database, Ehcache, or Relational Database Management System (RDBMS). For details on supported database versions, see System requirements on page 17.
Multi-datacenter deployment architecture
The following diagram shows the minimum infrastructure required for API Management multidatacenter deployment.
Axway API Gateway 7.5.3
Installation Guide 106
9 Configure API Management in multiple datacenters
This deployment architecture is described as follows:
l Each datacenter includes the same components deployed in active/active mode. Each datacenter can handle all of the traffic load and can scale in the same way. The API Gateway instances and Cassandra nodes in each datacenter are all highly available.
l API Gateway group configuration is shared across both datacenters. This means that all API Gateway instances in a group are managed as a single unit, and run the same configuration to virtualize the same APIs and execute the same policies.
l You must have at least two API Gateway instances per datacenter, at least one of which is an Admin Node Manager. However, you can configure mutliple Admin Node Managers per datacenter for high availability. For more details, see the API Gateway Administrator Guide. l The API Gateway group in the internal zone is responsible for API management. The Admin Node Manager is the central administration server responsible for all management operations. For example, this enables API Gateway administrators to perform monitoring in the API Gateway Manager web console.
l The API Gateway group in the internal zone also hosts the API Manager web console used by API administrators. For more details, see the API Manager User Guide.
l The API Gateway group in the o uter DMZ is responsible for securing traffic. The Node Manager manages local API Gateways instances on that host only.
l The Cassandra database cluster is required to store data for API Manager or API Gateway client registry (API key or OAuth). You can use Cassandra as an option to store custom KPS data and OAuth tokens. You can also use an RDBMS to store custom KPS, OAuth tokens, or metrics for API Manager or API Gateway Analytics.
Axway API Gateway 7.5.3
Installation Guide 107
9 Configure API Management in multiple datacenters
l Caching is replicated between API Gateway instances using the Ehcache distributed caching system. For more details, see "Global caches" in the API Gateway Policy Developer Guide.
API Management data storage
This section describes what API Management data can be persisted and where.
API Gateway data
Data type
Storage location
API Gateway configuration
Files on disk:
l API Gateway instance: INSTALL_
DIR/apigateway/groups/group-n/instancen/conf/fed
l Node Manager/Admin Node Manager: INSTALL_
DIR/apigateway/conf/fed
Alternatively, you can use a deployment archive ( .fed file). For more details, see the API Gateway DevOps Deployment Guide.
API Gateway logs
Files on disk:
l API Gateway instance: INSTALL_
DIR/apigateway/groups/group-n/instance-n/logs
l Node Manager/Admin Node Manager: INSTALL_
DIR/apigateway/logs
API Gateway traffic monitoring
Files on disk:
l API Gateway instance: INSTALL_
DIR/apigateway/groups/group-n/instancen/conf/opsdb.d
l Node Manager/Admin Node Manager: INSTALL_
DIR/apigateway/conf/opsdb.d
API Gateway KPS custom tables
Cassandra or RDBMS
API Gateway OAuth token store
Ehcache, Cassandra, or RDBMS.
Axway API Gateway 7.5.3
Installation Guide 108
9 Configure API Management in multiple datacenters
Data type
Storage location
API Gateway throttling counters
Ehcache
API Gateway custom cache
Ehcache
API Manager data
Data type
Storage location
API Manager catalog, client registry, web-based settings
Cassandra
API Manager quota counters
In memory, Cassandra, or RDBMS
API Manager metrics
RDBMS
Further details
For more details on concepts such as shared group configuration, Node Manager, and Admin Node Manager, see the API Gateway Concepts Guide.
For details on how to configure API Management in multiple datacenters, see l Multi-datacenter configuration on page 109
l Multi-datacenter failover scenarios on page 127
Multi-datacenter configuration
This topic describes the recommended configuration for each API Management data type. It explains the following for each data type:
l If the data can be replicated across both datacenters (for example, by deploying in both datacenters or automatic replication)
l How to configure the replication (for example, by configuring Apache Cassandra, Ehcache, or RDBMS)
l How to install and configure API Gateway and API Manager in multiple datacenters, and how to optimize performance
For details on recommended architecture, see Multi-datacenter deployment on page 106.
Axway API Gateway 7.5.3
Installation Guide 109
9 Configure API Management in multiple datacenters
API Management configuration
The recommended configuration for each data type is as follows:
API Gateway data
Data type
Replication between datacenters
API Gateway configuration
You must deploy the API Gateway group configuration in both datacenters. For details on automating deployment processes, see the API Gateway DevOps Deployment Guide.
API Gateway logs
Does not apply (local file-based data only). API Gateway traffic monitoring
Does not apply (local file-based data only). API Gateway KPS custom tables
Automatic. Axway recommends to use Cassandra with replication between datacenters. See Configure Cassandra for multiple datacenters on page 111, or your RDBMS documentation.
API Gateway OAuth token store
Axway recommends to use Ehcache, and to generate and use OAuth tokens in the same datacenter only. You should configure sticky sessions in your load balancer. See Configure Ehcache in multiple datacenters on page 123. API Gateway throttling counters
Axway recommends to configure at least one distributed cache per datacenter and to avoid replication between datacenters. You should configure sticky sessions in your load balancer. See Configure Ehcache in multiple datacenters on page 123.
API Gateway custom cache
Axway recommends to configure at least one distributed cache per datacenter and to avoid replication between datacenters. You should configure sticky sessions in your load balancer. See Configure Ehcache in multiple datacenters on page 123.
API Manager data
Data type
Replication between datacenters
API Manager catalog, client registry, webbased settings
Automatic. Axway recommends to use Cassandra with replication between datacenters. See Configure Cassandra for multiple datacenters on page 111.
Axway API Gateway 7.5.3
Installation Guide 110
9 Configure API Management in multiple datacenters
Data type
Replication between datacenters
API Manager quota counters
In memory only, or automatic when using external storage (Cassandra or RDBMS). See Configure API Manager quota in multiple datacenters on page 127.
See also Configure Cassandra for multiple datacenters on page 111, or your RDBMS documentation.
API Manager metrics
Automatic. See your RDBMS documentation.
Configure Cassandra for multiple datacenters
Cassandra is required to store data for API Manager data, and also recommended for API Gateway custom KPS tables. For details on the recommended Cassandra architecture, see Multi-datacenter deployment architecture on page 106.
Note
You must install and configure Cassandra on each node in both datacenters before installing and configuring API Gateway and API Manager.
Prerequisites
The following prerequisites apply to Cassandra in a multi-datacenter production environment:
l Ensure that Cassandra version 2.2.8 is installed. For details, see Install an Apache Cassandra database on page 37. For details on upgrading Cassandra version, see the API Gateway Upgrade Guide.
l You must have at least three Cassandra nodes per datacenter. Cassandra must be installed on each node in the cluster, but should not be started until the Cassandra cluster is fully configured. For more details, see Install an Apache Cassandra database on page 37.
l Configure JAVA_HOME to an Oracle JRE 1.8 installation (OpenJDK is not supported).
l Each Cassandra node must have Python 2.7 or higher installed.
l Time must be synchronized on all servers.
l Determine a naming convention for each datacenter and rack. You should choose the name carefully because renaming a datacenter is not possible. For example:
o DC1, DC2
o RACK1, RACK2, RACK3
l Determine the seed nodes. You must have at least two Cassandra seed nodes per datacenter.
l Choose a unique name for the Cassandra cluster.
Axway API Gateway 7.5.3
Installation Guide 111
9 Configure API Management in multiple datacenters
l To avoid firewall issues, you must open the following ports to allow bi-directional communication among the nodes:
o 7001: Cassandra TLS/SSL inter-node cluster communication
o 7199: Cassandra JMX monitoring port (only enabled on localhost for security reasons, you must use SSH to connect the machine).
o 9042: CQL native client port (only required for an API Gateway or API Manager client connection to Cassandra)
Configure your cassandra.yaml file
On each node in the cluster, you must configure the following properties in the CASSANDRA_
HOME/cassandra/conf/cassandra.yaml file:
Configure multi-datacenter settings
Configure the following settings in cassandra.yaml:
l cluster_name: Your chosen cluster name, common across both datacenters (for example, cassandra-cluster1)
l num_tokens: 256
l endpoint_snitch: GossipingPropertyFileSnitch
l -seeds: Internal IP address for all seed nodes. Each datacenter should have its own seed node IP addresses first, followed by the other datacenters seed nodes. This is critical for replication. For example:
o DC1 seed nodes: 192.168.10.1, 192.168.10.2
o DC2 seed nodes: 192.168.20.1, 192.168.20.2
o DC1 configuration: -seeds: 192.168.10.1, 192.168.10.2, 192.168.20.1, 192.168.20.2
o DC2 configuration: - seeds: 192.168.20.1, 192.168.20.2, 192.168.10.1, 192.168.10.2
l listen_address: Specify the IP address of the current node that you are configuring
l start_native_transport: true
l native_transport_port: 9042
Note
You must remove cassandra-topology.properties from cassandra/conf/. This is not needed when GossipingPropertyFileSnitch is set and could cause conflicts.
Axway API Gateway 7.5.3
Installation Guide 112
9 Configure API Management in multiple datacenters
Configure authentication settings
Axway recommends enabling authentication. Set the following properties:
l authenticator: org.apache.cassandra.auth.PasswordAuthenticator
l authorizer: org.apache.cassandra.auth.CassandraAuthorizer
Note
When these properties are set, you must change the default Cassandra user.
Configure TLS/SSL traffic encryption
Axway recommends enabling inter-node and client to node TLS/SSL encryption. API Management supports TLS v1.2.
Node-to-node encryption
To enable node-to-node TLS/SSL traffic encryption, set the following properties:
server_encryption_options:
l internode_encryption: all
l keystore: <server-keystore.jks>
l keystore_password: <MY_KEYSTORE_PASSWORD>
l truststore: <server-truststore.jks>
l truststore_password: <MY_TRUSTSTORE_PASSWORD>
l require_client_auth: true
Client-to-node encryption
To enable client-to-node SSL traffic encryption, set the following properties:
client_encryption_options:
l enabled: true
l optional: false
l keystore: <client-keystore.jks>
l keystore_password: <MY_KEYSTORE_PASSWORD>
l truststore: <client-truststore.jks>
l truststore_password: <MY_TRUSTSTORE_PASSWORD>
l require_client_auth: true
Configure your cassandra-rackdc.properties file
Configure the cassandra/conf/cassandra-rackdc.properties file with your chosen datacenter and rack names for each node, and set prefer_local=true. For example:
Axway API Gateway 7.5.3
Installation Guide 113
9 Configure API Management in multiple datacenters
Node
Setting in cassandra-rackdc.properties
DC1, node1 dc=DC1
rack=RACK1
prefer_local=true
DC1, node2 dc=DC1
rack=RACK2
prefer_local=true
DC1, node3 dc=DC1
rack=RACK3
prefer_local=true
DC2, node1 dc=DC2
rack=RACK1
prefer_local=true
DC2, node2
dc=DC2
rack=RACK2
prefer_local=true
DC2, node3 dc=DC2
rack=RACK3
prefer_local=true
Start your Cassandra nodes
When you have configured cassandra.yaml and cassandra-rackdc.properties on all nodes, you can start the seed nodes one at a time, followed by the remaining nodes in each datacenter.
For details on starting Cassandra, see Manage Apache Cassandra on UNIX/Linux and Windows on page 59.
Configure cqlsh for TSL/SSL encryption
If the Cassandra cluster has been configured to use client-to-node TSL/SSL encryption, you must configure all clients connecting to the cluster (including cqlsh) to use TSL/SSL. cqlsh is a Python-based command line client for executing Cassandra Query Language (CQL) commands.
To configure cqlsh for TSL/SSL, you must provide the following certificates in a cqlshrc file:
l certfile.pem: Contains the CA or server certificate of the Cassandra node. This is specified in <client-keystore.jks>.
Axway API Gateway 7.5.3
Installation Guide 114
9 Configure API Management in multiple datacenters
l usercert.pem: Contains the client certificate for cqlsh. This needs to be added to the Cassandra truststore: <client-truststore.jks>
l userkey.pem: Contains the private key of client certificate for cqlsh. This cannot contain a passphrase.
A sample is provided in cassandra/conf/cqlshrc.sample:
When TSL/SSL has been configured, run the following command:
./cqlsh -u cassandra -p <MY_PASSWORD> --ssl --cqlshrc=<MY_CQLSHRC_FILE>
192.168.10.1
Configure the default system_auth keyspace
When all nodes are online, if authentication is enabled, you must set the replication strategy and replication factor for the system_auth keyspace to ensure that credentials are shared across the cluster. You can do this using the cqlsh tool from the cassandra/bin/ directory.
Note
You must set the replication strategy to NetworkTopologyStrategy, and ensure the replication factor is set to the number of nodes per datacenter (for example, 3).
Naming is case sensitive and the keyspace definition must use the snitch-configured datacenter names used in cassandra-rackdc.properties.
For example, on Cassandra node 1 in DC1, perform the following steps: 1. Navigate to the cassandra/bin/ directory
2. Log into cqlsh using with the IP address the current node. For example:
./cqlsh -u cassandra -p cassandra 192.168.10.1
3. Run the following command:
ALTER KEYSPACE "system_auth" WITH REPLICATION = {'class' :
'NetworkTopologyStrategy', 'DC1' : <n>, 'DC2' : <n>};
In this example, <n> is the number of nodes per datacenter.
4. Run nodetool repair on each node as follows:
./nodetool repair system_auth
5. Change the default Cassandra user. For more details, see:
https://docs.datastax.com/en/cassandra/2.2/cassandra/configuration/secureConfigNativeAuth.ht
ml?hl=authentication
Axway API Gateway 7.5.3
Installation Guide 115
9 Configure API Management in multiple datacenters
Configure API Management in multiple
datacenters
When the Cassandra cluster has been setup, you can proceed with installing API Gateway and API Manager. You must have at least two API Gateway instances per datacenter.
Configure the first API Gateway node
On the first API Gateway host in DC1, perform the following steps:
1. Install API Gateway and API Manager using the API Gateway installer. Do not select Cassandra, which has already been installed. For more details, see Install API Manager on page 84.
2. Register the Admin Node Manager using the managedomain command in INSTALL_
DIR/apigateway/posix/bin. For details, see the API Gateway Administrator Guide.
3. Start the Admin Node Manager using the nodemanager command.
4. Add the API Gateway instance and group using the managedomain command.
5. Before starting the API Gateway instance, add the Cassandra host names and IP addresses as environment variables in your envSettings.props file located in INSTALL_
DIR/apigateway/conf. For example:
env.CASS.NAME1=Host 10.1
env.CASS.NAME2=Host 10.2
env.CASS.NAME3=Host 10.3
env.CASS.HOST1=192.168.10.1
env.CASS.HOST2=192.168.10.2
env.CASS.HOST3=192.168.10.3
6. Start the API Gateway using the startinstance command in INSTALL_
DIR/apigateway/posix/bin.
7. Configure the API Gateway to connect to the Cassandra cluster. In the Policy Studio tree, select Server Settings > Cassandra, and configure the following:
l Keyspace: Name of the API Gateway Cassandra keyspace to be created when deployed. Defaults to x${DOMAINID}_${GROUPID}.
l Hosts: Add the environment variable settings variables that you set in envSettings.props. For example:
l Authentication: Enter the Cassandra user name and password that you configured earlier (see Configure the default system_auth keyspace on page 115).
Axway API Gateway 7.5.3
Installation Guide 116
9 Configure API Management in multiple datacenters
l Security: Select Enable SSL, and select a trusted c ertificate and client certificate. For example:
For more details, see the API Gateway Administrator Guide.
8. Click Deploy in the toolbar to deploy the updated configuration.
9. Run setup-apimanager in INSTALL_DIR/apigateway/posix/bin, and specify the API Gateway group and instance names and ports. For example:
setup-apimanager --name "SERVER_INSTANCE_NAME" --group "GROUP_NAME" -portalport “API_MANAGER_LISTEN_PORT” --trafficport “API_MANAGER_TRAFFIC_
PORT”
For more details, see the API Manager User Guide.
10. For all KPS collections, update the read and write consistency levels to LOCAL_QUORUM. For example, in the Policy Studio tree, select Environment Configuration > Key Property
Stores > API Server > Data Sources > Cassandra Storage, and click Edit.
Repeat this step for each KPS collection using Cassandra (for example, Key Property Stores > OAuth and API Portal for API Manager). This also applies to any custom KPS collections that you have created.
Axway API Gateway 7.5.3
Installation Guide 117
9 Configure API Management in multiple datacenters
Update the Cassandra replication settings for the new
API Gateway keyspace
When the new API Gateway keyspace has been deployed, you must update its replication strategy and replication factor in the same way as the default system_auth keyspace. This time instead of the system_auth keyspace name, use the name of the newly created keyspace.
Perform the following steps:
1. On Cassandra node 1 in DC1, navigate to the CASSANDRA_HOME/cassandra/bin/ directory.
2. Log into cqlsh using with the IP address the current node. For example:
./cqlsh 192.168.10.1
3. Run the following command:
ALTER KEYSPACE "<KEYSPACE_NAME>" WITH REPLICATION = {'class' :
'NetworkTopologyStrategy', 'DC1' : 3, 'DC2' : 3};
4. On each node, run nodetool repair.
Tip
In a production environment, you should schedule weekly node repairs as a best practice. For more details, see Perform essential Cassandra operations on page 64.
Configure the remaining API Gateway nodes
When the API Gateway keyspace has been deployed and its replication updated, you can register the remaining hosts and add API Gateway instances using the managedomain command. Alternatively, you can do this using the API Gateway Manager web console. Note
You should always add one API Gateway instance at a time to the group.
For more details on registering hosts and adding API Gateway instances, see the API Gateway Administrator Guide.
Configure the API Gateway environment variables in DC1
For each additional API Gateway instance in DC1, add the following to envSettings.props before starting the instance:
env.CASS.NAME1=Host 10.1
env.CASS.NAME2=Host 10.2
env.CASS.NAME3=Host 10.3
env.CASS.HOST1=192.168.10.1
env.CASS.HOST2=192.168.10.2
env.CASS.HOST3=192.168.10.3
Axway API Gateway 7.5.3
Installation Guide 118
9 Configure API Management in multiple datacenters
# API Manager Port
env.PORT.APIPORTAL=8075
# API Manager Traffic Port
env.PORT.PORTAL.TRAFFIC=8065
Configure the API Gateway environment variables in DC2
For each API Gateway instance in DC2, add the following settings to envSettings.props before starting the instance:
env.CASS.NAME1=Host 20.1
env.CASS.NAME2=Host 20.2
env.CASS.NAME3=Host 20.3
env.CASS.HOST1=192.168.20.1
env.CASS.HOST2=192.168.20.2
env.CASS.HOST3=192.168.20.3
# API Manager Port
env.PORT.APIPORTAL=8075
# API Manager Traffic Port
env.PORT.PORTAL.TRAFFIC=8065
Add the load balancer host to API Management
whitelists
For each API Gateway host, you must add the external load balancer host to the whitelists for the Node Manager and API Manager to ensure that it will be accepted in the datacenter.
Add load balancer host to Node Manager whitelist
You can do this by creating an API Gateway project based on the Node Manager configuration and adding the external load balancer host to the Node Manager whitelist as a servlet property:
1. In Policy Studio, select File > New Project.
2. Enter a project Name, and click Next.
3. Select From existing configuration for the project starting point, and click Next.
4. Click the browse button, select the following directory, and click Finish:
INSTALL_DIR/apigateway/conf/fed
5. In the Policy Studio tree, select Environment Configuration > Listeners > Node
Manager > Management Services > Paths.
Axway API Gateway 7.5.3
Installation Guide 119
9 Configure API Management in multiple datacenters
6. In the pane on the right, right-click the api servlet, and select Edit.
7. In the Servlet dialog, click Add, and enter the following in the Properties dialog:
l Name: CsrfProtectionFilterFactory.refererWhitelist
l Value: https://LB_HOSTNAME:8090
8. Right-click the AppInfo Service servlet, click Edit, and add the same whitelist setting as a property (see previous step).
9. When complete, the configuration is automatically saved to the apiprojects directory used by Policy Studio for your project. To get the Node Manager to read this change, you must copy the contents of your apiprojects subdirectory to apigateway/conf/fed.
10. Finally, you must restart the Node Manager for the configuration changes to be picked up.
The following shows an example of configuring the api servlet setting in Policy Studio:
Note
You must ensure that every Node Manager has been updated to accept the load balancer host name. You can also add multiple load balancer hosts to the whitelist. For example:
l Name: CsrfProtectionFilterFactory.refererWhitelist
l Value: https://dc1-lb.example.com:8090|https://dc2-
lb.example.com:8090
Add load balancer host to API Manager whitelist
You can do this by creating a new project from an API Gateway instance and adding the external load balancer host to the API Manager whitelist as a servlet property:
1. In Policy Studio, select File > New Project from an API Gateway instance.
2. Enter a project Name, and click Next.
Axway API Gateway 7.5.3
Installation Guide 120
9 Configure API Management in multiple datacenters
3. In the Connection Details for the datacenter, enter the load balancer host name in the Host field and your credentials, and click Next.
4. Select the server instance in the datacenter that you wish to update, and click Finish.
5. In the Policy Studio tree, select Environment Configuration > Listeners > API Gateway > API Portal > Paths.
6. In the pane on the right, right-click the API Portal v1.2 (‘v1.2’) servlet, and select Edit.
7. In the Servlet dialog, click Add and enter the following in the Properties dialog:
l Name: CsrfProtectionFilterFactory.refererWhitelist
l Value: https://<LB_HOSTNAME>:8075
8. Right-click the API Portal v1.3 (‘v1.3’) servlet, click Edit, and add the same whitelist property (see previous step).
9. When complete, d eploy the configuration to all API Gateways using the load balancer that you added to the whitelist.
The following shows an example of configuring the API Portal v1.2 (‘v1.2’) servlet setting in Policy Studio:
Optimize API Management performance in a
multi-center environment
This section explains how to configure various API Gateway settings to optimize API Gateway and API Manager performance in a multi-center environment.
Increase maximum received bytes per transaction to
optimize API Manager
You can configure global API Gateway settings under the Server Settings node in Policy Studio. Axway API Gateway 7.5.3
Installation Guide 121
9 Configure API Management in multiple datacenters
In a multi-datacenter environment with a large number of APIs and a large volume of data, you may need to increase the value of Maximum received bytes per transaction to optimize the performance of the API Manager web console (for example, when viewing APIs in the API catalog). The default value is 10 MB ( 10485760 bytes). For example, might need to double this setting, depending on the number of APIs and the volume of data in your multi-datacenter environment.
To configure this setting, in the Policy Studio tree, select the Server Settings node, and click General in the right pane. To confirm updates, click Apply changes at the bottom right.
After changing any settings, you must deploy to the API Gateway for the changes to be enforced. Click the Deploy button in the toolbar, or press F6.
Increase API Manager polling time and events time for
Cassandra replication
When API Manager is deployed in multiple datacenters, and changes to data stored in Cassandra are replicated across datacenters, there is a small risk that the API Gateway runtime in the datacenter where the data is replicated to might operate with outdated data. In this case, to update the data, you must restart all API Gateway instances in the affected datacenter.
To minimize this risk, you can use the esexplorer tool to increase the polling time in milliseconds in each API Gateway instance in the datacenter where the data is replicated to. The polling time value must be balanced with the need of having updated data in real time in the API Gateway runtime environment.
You must also change the Time To Live (TTL) of the API Manager events table to be consistent with Cassandra for failover situations. Cassandra uses a default value of three hours in its hinted handoff configuration.
To configure the API Manager polling time and events table settings, perform the following steps:
1. Change to the following directory:
INSTALL_DIR/apigateway/posix/bin
2. Enter the esexplorer command.
3. Select Store > Connect, and browse to the following file:
INSTALL_DIR/apigateway/groups/<group-name>/conf/<groupid>/configs.xml
4. Select System Components > Portal Config in the tree on the left.
5. Select the vapiPollerPeriodMs setting in the pane on the right. Double-click the default value of 200, and enter a value in the range of 1000 to 30000 milliseconds.
Note
Axway API Gateway 7.5.3
As a general rule, the higher the value of the polling time setting, the lower the risk of outdated data in the API Gateway runtime. However, it will take longer to update the data in the replicated datacenter.
Installation Guide 122
9 Configure API Management in multiple datacenters
6. Select the vapiEventTTLMs setting on the right, and double-click to enter a value of 10800000 milliseconds (3 hours). This is consistent with the default value of the max_
hint_window_in_ms setting in the cassandra.yaml file.
7. When you have completed these settings, you can open the updated API Gateway project in Policy Studio and deploy the updates to all the API Gateway instances in the affected datacenter.
Increase Node Manager timeout for longer API
Gateway startup
In a multi-datacenter environment, it may take longer for API Gateway to start. By default, the API Gateway active timeout is set to 4 mins, however, it may take longer for an API Gateway instance to start up in a multi-datacenter environment. For example, this may result in the Node Manager throwing a 503 error saying that the API Gateway cannot restart.
To configure the Node Manager timeout for longer startup time, perform the following steps:
1. Change to the following directory:
INSTALL_DIR/apigateway/posix/bin
2. Enter the esexplorer command.
3. Select Store > Connect, and browse to the following file:
INSTALL_DIR/apigateway/conf/fed/configs.xml
4. Select Default System Settings in the tree on the left.
5. Select the activeTimeout setting in the pane on the right. Double-click the default value of 240000 (4 minutes), and enter a higher value to better suit your multi-datacenter environment.
6. Select the maxTransTimeout setting on the right, and double-click to enter a higher value to suit your environment.
7. To update to all Node Managers in the group, you can copy the contents o f the updated apigateway/conf/fed directory to the same directory on each node. Alternatively, you can run the esexplorer tool on each node to update the Node Manager settings.
Configure Ehcache in multiple datacenters
Caching is replicated between API Gateway instances in each datacenter using the Ehcache distributed caching system. In the distributed cache, there is no master cache controlling all caches. Instead, each cache is a peer that needs to know where all the other peers are located. The examples in this section shows distributed caches for OAuth and Throttling. The cache settings are the same in both cases.
Note
Axway API Gateway 7.5.3
Installation Guide 123
9 Configure API Management in multiple datacenters
l API Gateway only supports the RMICacheReplicatorFactory in Ehcache. Other replication factories are not supported.
l You should configure at least one distributed cache per datacenter, and should not replicate Ehcache information between datacenters. You should also configure sticky sessions in your load balancer environment to optimize performance.
Configure a distributed cache in each datacenter
In a distributed cache, each API Gateway has its own local copy of the cache but registers a cache event listener that replicates messages to the other caches so that events on a single cache are duplicated across all other caches.
To add a distributed cache, perform the following steps:
1. Select the Environment Configuration > Libraries > Caches tree node, and clicking the Add button at the bottom right.
2. Select Add Distributed Cache from the menu, and configure the following settings on the Configure Distributed Cache dialog:
l Cache name: Enter a name for the distributed cache (for example, OAuth or Throttling).
l Event Listener: Properties: Enter the following setting using environment variables for the replication settings:
replicateAsynchronously=${env.CACHE.ASYNC.REPLICATIO
N},
asynchronousReplicationIntervalMillis=${env.CACHE.ASYN
C.INTERVAL}, replicatePuts=true,
replicateUpdates=true, replicateUpdatesViaCopy=true,
replicateRemovals=true
Note
It is recommended to set replicateAsynchronously to true. The default asychronousReplicationIntervaleMillis value is 1000 ms if not specified. It is recommended to set this to the minimum of 10 ms. You can leave all other settings on this dialog as default. For example, the required settings are displayed as follows in Policy Studio:
Axway API Gateway 7.5.3
Installation Guide 124
9 Configure API Management in multiple datacenters
When the OAuth distributed cache has been configured, it can then be used by the OAuth Access Token Stores. For example, select Environment Configuration > Libraries > OAuth2 Stores > Access Token Stores > OAuth Access Token Stores, and right click to select Edit Access
Token Store. Select Store in a cache, and click the browse button to select the OAuth distributed cache.
If the OAuth distributed cache is to be used by API Manager, you must also add it in Server
Settings > API Manager > OAuth Access Token Stores.
Similarly, when a throttling distributed cache has been configured, it can then be used by the API Gateway Throttling filter. For more details, see the API Gateway Policy Developer Filter Reference.
Configure distributed cache settings for peer discovery
in each datacenter
To configure g lobal distributed cache settings for peer discovery, perform the following steps:
1. In Policy Studio, select the Server Settings node , and click General > Cache.
2. Configure the following settings: l Peer provider class: Properties: Enter the following setting using an environment variable for the cache URLs:
peerDiscovery=manual,timeToLive=1,rmiURLs=${env.CACHE.
RMI.URL}
Axway API Gateway 7.5.3
Installation Guide 125
9 Configure API Management in multiple datacenters
l Peer listener class: Properties: Enter the following setting using environment variables for the hosts and ports:
hostName=${env.CACHE.HOST},port=${env.CACHE.PORT},remoteObject
Port=${env.CACHE.REMOTE.OBJECT.PORT}
socketTimeoutMillis=120000
You can leave all other settings as default. For example, the required settings are displayed as follows in Policy Studio:
Set the environment variables on each API Gateway
host
You must set the environment variables used in the distributed cache in the following file on each host machine:
INSTALL_DIR/apigateway/conf/envSettings.props
For example:
env.CACHE.RMI.URL=//192.168.10.11:40001/OAuth|//192.168.10.11:4
0001/Throttle
env.CACHE.HOST=192.168.10.10
env.CACHE.PORT=40001
env.CACHE.REMOTE.OBJECT.PORT=40002
env.CACHE.ASYNC.REPLICATION=true
env.CACHE.ASYNC.INTERVAL=10
Note
The env.CACHE.RMI.URL environment variable should only include URLs for host machines in the same datacenter.
For more details, see "Global caches" in the API Gateway Policy Developer Guide.
Tip
For recommendations on Ehcache security, see the following:
https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/rmi_security_recommendations.html
Axway API Gateway 7.5.3
Installation Guide 126
9 Configure API Management in multiple datacenters
Configure API Manager quota in multiple
datacenters
API Manager quotas enable you to manage the maximum message traffic rate that can be sent by applications to APIs for back-end protection. You can use the Server Settings > API Manager > Quota Settings in Policy Studio to configure how API Manager quota information is stored. By default, quotas are stored in external storage, and automatically adapt to the configured KPS storage mechanism. However, you can also explicitly configure a storage mechanism of Cassandra, RDBMS, or in memory only.
Note
The following general guidelines apply to API Manager quotas :
l Storing quota in memory only means that the quota calculation is performed by each API Gateway instance in each group between datacenters. If the quota duration is less than 30 seconds, in memory only is automatically activated.
l Axway recommends using the API Manager system quota (stored in Cassandra) when the backend is shared between datacenters. Axway recommends the API Gateway Throttling filter (stored in Ehcache) for back-end protection per datacenter.
For more details on configuring quotas in API Manager, see the API Manager User Guide.
Further details
For more details on the use of API Gateway environment variables in envSettings.props, see the API Gateway DevOps Deployment Guide.
For more details on Cassandra and Ehcache, see the following:
l http://ehcache.org/
l http://cassandra.apache.org/
l http://docs.datastax.com/en/cassandra/2.2/
For more details on how to configure API Management in multiple datacenters, see:
l Multi-datacenter deployment on page 106
l Multi-datacenter failover scenarios on page 127
Multi-datacenter failover scenarios
This topic describes expected behavior in a multi-datacenter deployment in case of failover. It explains how the system will behave in each of the following scenarios:
l One API Gateway instance is down
l One Apache Cassandra node is down
Axway API Gateway 7.5.3
Installation Guide 127
9 Configure API Management in multiple datacenters
l A full datacenter is down
l The network between two datacenters is down
One API Gateway instance is down
In this case, one API Gateway instance is down in DC 1:
The following applies in this scenario:
l API requests can no longer be serviced by the API Gateway instance that is not running in DC 1.
l API requests will be serviced by the remaining API Gateway instance in DC 1.
l You must restart the API Gateway instance that is not running in DC 1. For more details, see Start API Gateway on page 76.
One Cassandra node is down
In this case, one Cassandra node is down in DC 1:
Axway API Gateway 7.5.3
Installation Guide 128
9 Configure API Management in multiple datacenters
The following applies in this scenario:
l Cassandra is inherently HA and can tolerate the loss of one Cassandra node only in a datacenter (DC 1 in this case). This ensures 100% data consistency when Cassandra is configured for multiple datacenters. For more details, see Configure Cassandra for multiple datacenters on page 111.
l You must restart the Cassandra node that is not running in DC 1. For details, see Manage Apache Cassandra on UNIX/Linux and Windows on page 59.
Note
When a node has been absent from a cluster for a time, it is brought back into the cluster after restart, and becomes eventually consistent by design. Node repair is required after reintegration into the cluster. For more details, see Perform essential Cassandra operations on page 64.
A full datacenter is down
In this case, DC 1 is down:
Axway API Gateway 7.5.3
Installation Guide 129
9 Configure API Management in multiple datacenters
The following applies in this scenario:
l API requests can no longer be serviced by DC 1
l API requests are automatically directed to DC 2 by the load balancer
l API Manager quotas remain the same but over less servers
l You should not deploy updates for the following file-based data types to the API Gateway group:
o API Gateway configuration
o API Gateway KPS custom table structure
Note
There is a risk that end-users may need to re-initiate sessions using the following data types stored in Ehcache:
l API Gateway OAuth token store
l API Gateway custom cache
Restart the datacenter
To restart the datacenter:
1. Restart each of the Cassandra nodes. For details, see Manage Apache Cassandra on UNIX/Linux and Windows on page 59.
2. When all Cassandra nodes are running normally and have synchronized with the rest of the cluster in DC2, you can restart the API Gateways. For details, see Start API Gateway on page 76. The API Gateway should not be restarted prior to a successful restart of all Cassandra nodes.
Note
You should run the nodetool repair command on each of the three Cassandra nodes in DC 1 when the datacenter has been down for more than two hours.
Axway API Gateway 7.5.3
Installation Guide 130
9 Configure API Management in multiple datacenters
The network between both datacenters is down
In this case, the network between DC 1 and DC 2 is down, while both datacenters remain active:
The following applies in this scenario:
l OAuth or throttling data stored in Ehcache per datacenter is not affected
l You should not deploy updates for the following file-based data types to the API Gateway group:
o API Gateway configuration
o API Gateway KPS custom table structure
l For the following data types stored in Cassandra, both datacenters are not synchronized until the network recovers, and then automatically resynchronize:
o API Manager catalog, client registry, web-based settings
o API Gateway KPS custom table structure
l For the following file based data types, a single API Gateway Manager web console cannot access both datacenters while the network is down, and can only access each datacenter separately:
o API Gateway logs
o API Gateway traffic monitoring
Note
If the network connection has been down for more than two hours, the following steps are recommended:
l Run nodetool repair on each of the six nodes in the Cassandra cluster to ensure that the data has synchronized. For more details, see Perform essential Cassandra operations on page 64.
Axway API Gateway 7.5.3
Installation Guide 131
9 Configure API Management in multiple datacenters
l Restart the API Gateway instances to resynchronize data from Cassandra (potentially in both datacenters if Cassandra changes have occurred in both datacenters).
It may take a minute for newly created, deleted, or updated APIs in one datacenter to synchronize successfully with the other datacenter.
Further details
For more details on how to configure API Management in multiple datacenters, see:
l Multi-datacenter deployment on page 106
l Multi-datacenter configuration on page 109
Axway API Gateway 7.5.3
Installation Guide 132
Run API Management in
Docker
10
This topic describes how to run a multi-node Axway API Management system in Docker, and how to customize the recommended default topology to suit your environment.
This topic includes the following:
l API Management in Docker containers on page 134
l Run pre-built API Management Docker images on page 137
l Generate API Management Docker images on page 139
l Customize your API Management topology in Docker on page 144
Axway API Gateway 7.5.3
Installation Guide 133
API Management in Docker containers
This topic describes how to run a multi-node Axway API Management system in Docker. It provides an overview of the main steps and describes the recommended default topology.
Docker containers wrap software in a complete file system that contains everything required to run (for example, code, runtime, system tools, and system libraries). This guarantees that the software always runs the same way, regardless of environment. For more details, see https://www.docker.com.
Running your API Management system in Docker makes it easy to quickly build, test, and run API Management solutions in containers for standalone or high availability (HA) deployment. The API Management sample system supports Docker version 1.13.x, and includes API Gateway, API Manager, and Apache Cassandra. For details onAPI Portal Docker support, see the API Portal Installation and Upgrade Guide.
This topic assumes that you have working knowledge of API Management architecture, Apache Cassandra, and Docker. For more details, see the following:
l API Gateway Concepts Guide
l Install Apache Cassandra on page 37
l https://www.docker.com/
Create Docker images using scripts
Axway provides Docker files and c ompose scripts to enable you to create custom Docker images for API Gateway, API Manager, and Apache Cassandra. You can deploy these images in Docker containers on any host operating system or cloud platform that supports Docker ( for example, IBM Bluemix or Amazon Web Services). The API Management sample system supports both CentOS Linux 7 and Red Hat Enterprise Linux 7 base images, which you can customize to generate your API Management Docker topology.
Note
Generating custom Docker images using scripts is the recommended approach in an HA production environment.
The following diagram shows a high-level overview of the steps to create and deploy your desired API Management topology:
Axway API Gateway 7.5.3
Installation Guide 134
These steps are described in the following sections:
l Set up your local environment on page 139
l Create your API Management Docker infrastructure on page 140
l Deploy your Docker infrastructure to the cloud on page 137
Run pre-built Docker images
Axway also provides pre-built Docker images (CentOS Linux 7 base image only), which you can download from Axway Support.
Note
These pre-built CentOS 7 Docker images are recommended for development and test purposes in an standalone environment only, and are not designed for use in an HA production environment. For production environments, see Create Docker images using scripts on page 134.
For more details, see Run pre-built API Management Docker images on page 137.
API Management Docker HA topology
This section describes the default API Management topology that is generated in the 3-node sample system, which is recommended for an HA production environment:
Axway API Gateway 7.5.3
Installation Guide 135
This sample topology includes the following:
l Three Docker containers each including API Gateway, API Manager, and an Admin Node Manager or Node Manager.
l Three Docker containers each including Apache Cassandra for HA. Each API Gateway node is aware of all three nodes in the Cassandra cluster, and does not map to a single Cassandra node. The Cassandra cluster has a replication factor of 3 and quorum consistency. This ensures that reads and writes are consistent and tolerates the loss of one node, which is recommended for API Management HA.
l Multiple Docker data volumes per container to manage persistence of API Gateway and Cassandra configuration data.
Axway provides scripts to build Docker images and generate a docker-compose.yml configuration for running the API Management solution on a single host. You can specify which components are included in the solution: API Gateway, API Manager, Admin Node Manager, and Node Manager (non-admin). You can also configure Docker data volumes for persistence. For more details, see Generate API Management Docker images on page 139.
Axway API Gateway 7.5.3
Installation Guide 136
Deploy your Docker infrastructure to the cloud
For details on how to deploy your Docker infrastructure in the cloud, see the product documentation for your chosen third-party cloud platform. For example, this includes Platform as a Service (PaaS) environments such as IBM Bluemix or Amazon Web Services.
For more details, see the following:
l https://www.docker.com/products/overview
l http://www.ibm.com/cloud-computing/bluemix/
l https://aws.amazon.com/
Further information on Docker
For more details on Docker, see the following:
l https://docs.docker.com/engine/understanding-docker/
l https://docs.docker.com/engine/installation/linux/
Run pre-built API Management Docker images
Axway provides the following pre-built Docker images with CentOS Linux 7 as the base O/S:
l CentOS 7 with API Gateway and API Manager installed and configured
l CentOS 7 with Apache Cassandra and customizations for API Manager
l CentOS 7 with API Portal installed and configured
This topic explains how to run the API Gateway and API Manager image and the Cassandra image. For details on the API Portal image, see the API Portal Installation and Upgrade Guide.
Note
These pre-built Docker images are recommended for development and test purposes in an standalone environment only, and are not designed for use in an HA production environment. For production environments, see Generate API Management Docker images on page 139.
Prerequisites
The following components are required on your system:
l Docker version 1.13.x
l Docker Compose version 1.8.0.x
l API Gateway 7.5.3 Docker images available from Axway Support
l API Gateway license file
Axway API Gateway 7.5.3
Installation Guide 137
Note
Docker images require an API Gateway license that is not restricted to a specific host name. For more details, contact your Axway account manager.
Run pre-built API Management images in a
developement or test environment
Perform the following steps:
1. Download the following file from Axway Support and extract to the current directory:
APIGateway_7.5.3_DockerImage_Topology_linux-x86-64_BN<n>.tar.gz
2. Provide a license file in current directory (for example, my-apigateway-license.lic).
3. Load the Cassandra Docker image:
docker load < ./cassandra_centos-latest.tar.gz
4. Load the API Gateway Docker image:
docker load < ./gwlatest-1node-node1-centos-latest.tar.gz
5. Set the APIGW_LICENSE variable:
export APIGW_LICENSE="$(cat ./my-apigateway-license.lic | gzip |
base64)"
6. Run the Docker images:
docker-compose up
Test the API Management system
You can view and test the API Management sample system by accessing the following web consoles in a browser:
l API Gateway Manager
https://<docker-host-name>:8090
l API Manager
https://<docker-host-name>:8075
For more details on using these tools, see the following:
Axway API Gateway 7.5.3
Installation Guide 138
l API Gateway Administrator Guide
l API Manager User Guide
Generate API Management Docker images
This topic describes how to generate and configure custom API Management Docker images using scripts. This approach is recommended in a production environment for high availability. For details on how to download and run pre-built Docker images in a development or test environment, see Run pre-built API Management Docker images on page 137.
Set up your local environment
The following components are required on your system:
Docker
API Management supports the following:
l Docker version 1.13.x
l Docker Compose version 1.8.0.x
API Management
The following components are required:
l API Gateway Linux installer available from Axway Support
l API Gateway Docker scripts available as a separate zip file from Axway Support
l API Gateway license file
Note
Docker images require an API Gateway license that is not restricted to a specific host name. For more details, contact your Axway account manager.
Specify an API Gateway license file
For details on how to specify a license file, see Step 1—Build your Docker images on page 141. You can also set the APIGW_LICENSE variable on the host machine that runs the Docker daemon. For example, this is useful when running a pre-built Docker image in a development environment. For details, see Run pre-built API Management Docker images on page 137.
The following command shows an example of setting this variable:
export APIGW_LICENSE="$(cat /path/to/license/my-apigateway-license.lic |
Axway API Gateway 7.5.3
Installation Guide 139
gzip | base64)
Note
If the APIGW_LICENSE environment variable is set, and a license file named lic.lic already exists in the container, the environment variable overrides the license file at runtime. If a license file does not exist, a new lic.lic file is created and populated with the value of this variable (in compressed and base-64 decoded format).
If this variable is not set or invalid, and there is no license file in the container, the API Gateway fails to start up.
Python
Python version 2.7.x is required to create Docker data volumes. For more details, see Customize your API Management topology in Docker on page 144.
Minimum disk space and memory
The following are required for the 3-node sample architecture:
l At least 100 GB of disk space
l At least 16 GB of RAM
Tip
On Linux systems, the free -h command provides human-readable information about the amount of free and used memory in the system. You can also use other tools such as top and vm_stat to get this information. See also Troubleshooting on page 144.
Create your API Management Docker
infrastructure
When you have set up your environment, the steps to create your API Management Docker infrastructure are as follows:
These steps are described in the following sections:
Axway API Gateway 7.5.3
Installation Guide 140
l Step 1—Build your Docker images on page 141
l Step 2—Generate your API Management topology on page 142
l Step 3—Run and test your API Management system on page 143
Step 1—Build your Docker images
Docker images are required to generate your API Management topology. To build your Docker images, perform the following steps:
1. Unzip the file containing the Docker scripts available from Axway Support. For example:
APIGateway_7.5.3_SamplesPackageDocker_linux-x86-64_BN<n>
2. In the directory in which you unzipped the scripts, use the build.py command to build your images:
./build.py --installer <API_GATEWAY_LINUX_INSTALL_FILE> --license <API_
GATEWAY_LICENSE_FILE> --baseos <BASE_O/S> --sp <OPTIONAL_SERVICE_PACK_
FILE> --clean
The parameters are described as follows:
Parameter
--
Description
Specify the API Gateway Linux installer file. This parameter is required.
installer
--license
Specify the API Gateway license file. This parameter is required.
--baseos
Specify one of the following operating systems for the container base image:
l centos: CentOS Linux 7
l rhel: Red Hat Enterprise Linux 7
Defaults to centos.
--sp
Specify an optional API Gateway service pack file if needed.
--clean
Removes the static images from the local Docker registry.
The following command shows an example with Red Hat Enterprise Linux 7 as the base image:
./build.py --installer ~/dependencies/APIGateway_7.5.3_Install_linuxx86-64_BNn.run --license lic.lic --baseos redhat --clean
This command builds the following images to the local Docker registry:
Axway API Gateway 7.5.3
Installation Guide 141
apigw_linux64_redhat
cassandra_redhat
gwredhat
registry.access.redhat.com/rhel7
Step 2—Generate your API Management topology
You can create different kinds of API Management topology images using the following command:
./compose.py --config <API_GATEWAY_JSON_TOPOLOGY_FILE>
For example:
./compose.py --config sample-compose-config/gwlatest-3nodeha-apimgr.json
Note
If the --baseos parameter was supplied to build.py, it must also be supplied to the compose.py script. For example:
./compose.py --config sample-compose-config/gwlatest-3nodeha-apimgr.json
--baseos redhat
The following default JSON topology files are available in the sample-compose-config subdirectory:
JSON topology file
Description
gwlatest-1node-
Includes 1 API Manager, 1 Admin Node Manager, and 3 Cassandra nodes
apimgr.json
gwlatest-2nodehaapimgr.json
gwlatest-3nodehaapimgr.json
Includes 2 API Manager, 1 Admin Node Manager, 1 Node Manager, and 3 Cassandra nodes
Includes 3 API Manager, 2 Admin Node Manager, 1 Node Manager, and 3 Cassandra nodes
For example, for the recommended three-node HA system, the following images are added to the local Docker registry:
gwlatest-3nodeha-apimgr_node3
gwlatest-3nodeha-apimgr_node2
gwlatest-3nodeha-apimgr_node1
The generated docker-compose.yml file is written to the composegenerated/servers directory.
Axway API Gateway 7.5.3
Installation Guide 142
For details on how to customize the docker-compose.yml file for the d efault 3-node system to suit your environment, see Customize your API Management topology in Docker on page 144.
Cassandra consistency levels
Tip
The consistency levels in the JSON topology file are set to QUORUM by default. However, for a development or test configuration running against one-node Cassandra only, the consistency level should be set to ONE (because QUORUM requires 3 nodes at least). For each node, the default settings in the topology file are as follows:
"readConsistencyLevel" : "QUORUM",
"writeConsistencyLevel" : "QUORUM",
Step 3—Run and test your API Management system
You can run and test your API Management topology images locally, or you can copy the images and docker-compose.yml to your Docker-compatible system.
Run docker-compose up to launch containers from the runtime images. For example:
docker-compose -f compose-generated/servers/gwlatest-3nodehaapimgr/docker-compose.yml up -d
Tip
You can omit -d to view output o n stdout instead.
You must wait for the services in containers to start. For example:
ps -ef | grep vshell
root 19048 18558 11 15:36 ? 00:00:18 Node Manager on node1 ( Node
Manager Group) (7.5.3) (vshell)root 19081 18627 12 15:36 ? 00:00:19 Node
Manager on node2 ( Node Manager Group) (7.5.2) (vshell)
root 19159 18558 23 15:37 ? 00:00:27 PortalInstance-1 (PortalGroup-1)
(7.5.3) (vshell)
root 19193 18627 23 15:37 ? 00:00:27 PortalInstance-2 (PortalGroup-1)
(7.5.3) (vshell)
Further information
For details on how to create Docker data volumes for persistence, see Customize your API Management topology in Docker on page 144.
Axway API Gateway 7.5.3
Installation Guide 143
Troubleshooting
If a container dies, this is most often due to insufficient memory being available. For details, see Minimum disk space and memory on page 140.
For example, you can run the following command on the host operating system to diagnose why a process died:
dmesg | grep -E -i -B100 'killed process'
Customize your API Management topology in
Docker
This topic describes how to customize your Docker-based API Management topology to suit your environment. For example, you can do this by creating Docker data volumes for persistence and editing your docker-compose.yml file to suit your environment.
Create Docker data volumes for persistence
You must create Docker data volumes to persist API Management and Cassandra configuration data. For example, this includes transaction, audit, trace, and user data. This is required for the API Gateway, Node Manager, and Cassandra on each node. This section shows how to do this for the recommended sample 3-node HA system.
Perform the following steps:
1. Create a Docker data volume for each configuration to persist. For example:
cd src/util
# Create volumes for node1, node2, and node3
./volume.py --create --nodeName node1
./volume.py --create --nodeName node2
./volume.py --create --nodeName node3
# Create volumes for the Cassandra cluster
docker
docker
docker
docker
docker
docker
volume
volume
volume
volume
volume
volume
create
create
create
create
create
create
--name
--name
--name
--name
--name
--name
cassandra-s1_DATA
cassandra-s1_LOGS
cassandra-s2_DATA
cassandra-s2_LOGS
cassandra-m_DATA
cassandra-m_LOGS
This creates the following data volumes:
Axway API Gateway 7.5.3
Installation Guide 144
docker volume ls
DRIVER VOLUME NAME
local cassandra-m_DATA
local cassandra-m_LOGS
local cassandra-s1_DATA
local cassandra-s1_LOGS
local cassandra-s2_DATA
local cassandra-s2_LOGS
local node1_CONF_DATA
local node1_EVENTS_DATA
local node1_GROUP_DATA
local node1_LOGS_DATA
local node1_TRACE_DATA
local node1_USER_DATA
local node2_CONF_DATA
local node2_EVENTS_DATA
local node2_GROUP_DATA
local node2_LOGS_DATA
local node2_TRACE_DATA
local node2_USER_DATA
local node3_CONF_DATA
local node3_EVENTS_DATA
local node3_GROUP_DATA
local node3_LOGS_DATA
local node3_TRACE_DATA
local node3_USER_DATA
2. Enable the volumes for each API Gateway node in the generated docker-compose.yml file. For example:
version: '2'
services:
node1:
image: gwlatest-3nodeha-apimgr_node1
links:
cassandra-m
cassandra-s1
cassandra-s2
volumes:
# Configuring volume for Node Manager conf (modified using API
Gateway Manager web application)
- node1_CONF_DATA:/opt/Axway/apigateway/conf
# Configuring volume for Node Manager trace (modified using API
Gateway Manager web application)
- node1_TRACE_DATA:/opt/Axway/apigateway/trace
# Configuring volume for Node Manager logs (includes Domain and
Axway API Gateway 7.5.3
Installation Guide 145
Transaction logs modified using API Gateway Manager web application)
- node1_LOGS_DATA:/opt/Axway/apigateway/logs
# Configuring volume for Node Manager events (modified using API
Gateway Manager web application)
- node1_EVENTS_DATA:/opt/Axway/apigateway/events
# Configuring volume for API Gateway Group Configuration, data,
logging and trace.
- node1_GROUP_DATA:/opt/Axway/apigateway/groups
# Configuring volume for API Gateway user data eg. ActiveMQ, Filebased filters, Ehcache, etc.
- node1_USER_DATA:/custom_path/to/userdata/
hostname: node1
environment:
- START_BACKOFF_SECS=180 # starts after Cassandra cluster and 30s
after previous instance
- CASSANDRA_HOSTS=cassandra-m,cassandra-s1,cassandra-s2
privileged: true
node2:
image: gwlatest-3nodeha-apimgr_node2
links:
- cassandra-m
- cassandra-s1
- cassandra-s2
volumes:
# Configuring volume for Node Manager conf (modified using API
Gateway Manager web application)
- node2_CONF_DATA:/opt/Axway/apigateway/conf
# Configuring volume for Node Manager trace (modified using API
Gateway Manager web application)
- node2_TRACE_DATA:/opt/Axway/apigateway/trace
# Configuring volume for Node Manager logs (includes Domain and
Transaction logs modified using API Gateway Manager web application)
- node2_LOGS_DATA:/opt/Axway/apigateway/logs
# Configuring volume for Node Manager events (modified using API
Gateway Manager web application)
- node2_EVENTS_DATA:/opt/Axway/apigateway/events
# Configuring volume for API Gateway Group Configuration, data,
logging and trace.
- node2_GROUP_DATA:/opt/Axway/apigateway/groups
# Configuring volume for API Gateway user data eg. ActiveMQ, Filebased filters, Ehcache etc
- node2_USER_DATA:/custom_path/to/userdata/
hostname: node2
environment:
- START_BACKOFF_SECS=210 # starts after Cassandra cluster and 30s
after previous instance
- CASSANDRA_HOSTS=cassandra-m,cassandra-s1,cassandra-s2
Axway API Gateway 7.5.3
Installation Guide 146
privileged: true
node3:
image: gwlatest-3nodeha-apimgr_node3
links:
- cassandra-m
- cassandra-s1
- cassandra-s2
volumes:
# Configuring volume for Node Manager conf (modified using API
Gateway Manager web application)
- node3_CONF_DATA:/opt/Axway/apigateway/conf
# Configuring volume for Node Manager trace (modified using API
Gateway Manager web application)
- node3_TRACE_DATA:/opt/Axway/apigateway/trace
# Configuring volume for Node Manager logs (includes Domain and
Transaction logs modified using API Gateway Manager web application)
- node3_LOGS_DATA:/opt/Axway/apigateway/logs
# Configuring volume for Node Manager events (modified using API
Gateway Manager web application)
- node3_EVENTS_DATA:/opt/Axway/apigateway/events
# Configuring volume for API Gateway Group Configuration, data,
logging and trace.
- node3_GROUP_DATA:/opt/Axway/apigateway/groups
# Configuring volume for API Gateway user data eg. ActiveMQ, Filebased filters, Ehcache etc
- node3_USER_DATA:/custom_path/to/userdata/
hostname: node3
environment:
- START_BACKOFF_SECS=240 # starts after Cassandra cluster and 30s
after previous instance
- CASSANDRA_HOSTS=cassandra-m,cassandra-s1,cassandra-s2
privileged: true
Note
You should store all user data in a centralized location for convenience. In the volumes section of docker-compose.yml, update <custom_path/to/userdata> as appropriate.
3. Enable the volumes for each Cassandra node in the generated docker-compose.yml file. For example:
cassandra-m:
image: cassandra
environment:
- START_BACKOFF_SECS=0 # prevents race between nodes joining the
cluster
- SEEDS=cassandra-m
Axway API Gateway 7.5.3
Installation Guide 147
- MAX_HEAP_SIZE=1G
- HEAP_NEWSIZE=400m
volumes:
# Cassandra data volume
- cassandra-m_DATA:/opt/cassandra/data
# Cassandra logs volume
- cassandra-m_LOGS:/opt/cassandra/logs
image: cassandra
hostname: cassandra-m
restart: on-failure:2
cassandra-s1:
image: cassandra
environment:
- START_BACKOFF_SECS=60 # prevents race between nodes joining the
cluster
- SEEDS=cassandra-m
- MAX_HEAP_SIZE=1G
- HEAP_NEWSIZE=400m
volumes:
# Cassandra data volume
- cassandra-s1_DATA:/opt/cassandra/data
# Cassandra logs volume
- cassandra-s1_LOGS:/opt/cassandra/logs
image: cassandra
hostname: cassandra-s1
restart: on-failure:2
cassandra-s2:
image: cassandra
environment:
- START_BACKOFF_SECS=120 # prevents race between nodes joining the
cluster
- SEEDS=cassandra-m
- MAX_HEAP_SIZE=1G
- HEAP_NEWSIZE=400m
volumes:
# Cassandra data volume
- cassandra-s2_DATA:/opt/cassandra/data
# Cassandra logs volume
- cassandra-s2_LOGS:/opt/cassandra/logs
image: cassandra
hostname: cassandra-s2
restart: on-failure:2
volumes:
node1_CONF_DATA: external: true
Axway API Gateway 7.5.3
Installation Guide 148
node1_TRACE_DATA: external: true
node1_LOGS_DATA: external: true
node1_EVENTS_DATA: external: true
node1_GROUP_DATA: external: true
node1_USER_DATA: external: true
node2_CONF_DATA: external: true
node2_TRACE_DATA: external: true
node2_LOGS_DATA: external: true
node2_EVENTS_DATA: external: true
node2_GROUP_DATA: external: true
node2_USER_DATA: external: true
node3_CONF_DATA: external: true
node3_TRACE_DATA: external: true
node3_LOGS_DATA: external: true
node3_EVENTS_DATA: external: true
node3_GROUP_DATA: external: true
node3_USER_DATA: external: true
cassandra-m_DATA: external: true
cassandra-m_LOGS: external: true
cassandra-s1_DATA: external: true
cassandra-s1_LOGS: external: true
cassandra-s2_DATA: external: true
cassandra-s2_LOGS: external: true
Example: Persist user-defined directories for API
Gateway filters
If your policy uses a file-based API Gateway filter that allows a user-defined directory such as /home/user/Downloads (for example, File Download, File Upload, or Save to File), you can specify this in the Docker container. For example:
1. Create a volume for the user data (for example, GatewayNODE2_userdata) on the host:
./volume.py --create --nodeName GatewayNODE2_userdata
2. Get the full path of the volume created on the host. For example:
docker volume inspect --name GatewayNODE2_userdata
/var/lib/docker/volumes/GatewayNODE2_userdata/_data
3. Update the volume entry in the docker-compose.yml file. For example:
volumes:
# Configuring volume for API Gateway user data (eg., ActiveMQ, Filebased filters, Ehcache, etc.)
- /var/lib/docker/volumes/GatewayNODE2_userdata/_
data:/home/user/Downloads
Axway API Gateway 7.5.3
Installation Guide 149
Example: Persist user-defined directories using the
Directory Scanner
Alternatively, you can configure persistence using the Directory Scanner in Policy Studio. This enables you to specify multiple directory locations on disk ( for example, Input, Processing and Response directories). This is available under the Environment Configuration > Listeners > API Gateway > Directory Scanner node in the Policy Studio tree.
You can use either of the following approaches:
l Create a directory inside the container (for example, /home/userdata/DirectoryScanner), and set it as the directory path for all. You must update the entry in docker-compose.yml as follows:
volumes:
# Configuring volume for API Gateway user data (eg., ActiveMQ, Filebased filters, Ehcache, etc.)
- /var/lib/docker/volumes/GatewayNODE1_userdata/_
data:/home/userdata/DirectoryScanner
l Create nested directories inside the container, for example:
/home/userdata/DirectoryScanner/Input
/home/userdata/DirectoryScanner/Processing
/home/userdata/DirectoryScanner/Response
Add a corresponding entry in docker-compose.yml:
- /var/lib/docker/volumes/GatewayNODE1_userdata/_
data:/home/userdata/DirectoryScanner
And create multiple volumes with a one-to-one mapping with each container path in dockercompose.yml:
volumes:
- /var/lib/docker/volumes/GatewayNODE1_userdata1/_
data:/home/userdata/DirectoryScanner/Input
- /var/lib/docker/volumes/GatewayNODE1_userdata2/_
data:/home/userdata/DirectoryScanner/Processing
- /var/lib/docker/volumes/GatewayNODE1_userdata3/_
data:/home/userdata/DirectoryScanner/Response
Finally, to bring the system up, see Step 3—Run and test your API Management system on page 143.
Axway API Gateway 7.5.3
Installation Guide 150
Delete data volumes
You can delete data volumes as needed. For example:
./volume.py --delete --nodeName node1
./volume.py --delete --nodeName node2
./volume.py --delete --nodeName node3
docker volume rm cassandra-s1_DATA
docker volume rm cassandra-s1_LOGS
docker volume rm cassandra-s2_DATA
docker volume rm cassandra-s2_LOGS
docker volume rm cassandra-m_DATA
docker volume rm cassandra-m_LOGS
Test your API Management system
This section explains how to verify that your customized configuration is working correctly.
Configure hosts and ports
To configure specific host names and expose specific ports for test purposes, edit the dockercompose.yml file in compose-generated/servers. For example:
version: '2'
services:
node1:
image: gwlatest-2nodeha-apimgr_node1
hostname: node1 privileged: true
ports:
- "8075:8075"
- "8090:8090"
- "8080:8080"
node2:
image: gwlatest-2nodeha-apimgr_node
links:
- node1:node1
hostname: node2
privileged: true
...
Connect to API Management services
You can perform the following tests to check that your system is running correctly:
Axway API Gateway 7.5.3
Installation Guide 151
l Health check policy
Enter the following command to connect to the API Gateway Health Check policy:
curl http://<docker-host-name>:8080/healthcheck
<status>ok</status>
l API Gateway Manager
Enter the following URL in a browser to launch the API Gateway Manager web console:
https://<docker-host-name>:8090
l API Manager
Enter the following URL to launch the API Manager web console:
https://<docker-host-name>:8075
Axway API Gateway 7.5.3
Installation Guide 152
Update API Gateway
12
This section describes how to apply service packs or patches to API Gateway components.
Install a service pack or patch
This section describes how to install a service pack or patch on an existing installation of API Gateway.
To install a service pack or patch, follow these general guidelines:
1. Stop any Node Managers and API Gateway servers.
2. Back up your existing installation. For more information on backing up, see "API Gateway backup and disaster recovery" in the API Gateway Administrator Guide.
3. Download the service pack or patch and the associated Readme from Axway Support at https://support.axway.com.
4. Review the Readme for any specific installation instructions.
5. Unzip and extract the service pack or patch. A service pack or patch contains new binaries only and does not overwrite the existing configuration.
6. Restart the Node Managers and API Gateway servers.
7. To verify that the service pack or patch have been installed correctly, run the managedomain
--version command. For more information on running the managedomain --version command, see "Get help with API Gateway" in the API Gateway Administrator Guide.
Resolve patch validation issues
You can use the managedomain --version command to list and validate the patches installed. This command uses the information in the in the META-INF/<patch>.id file to validate the patch. For more information on running the managedomain --version command, see "Get help with API Gateway" in the API Gateway Administrator Guide.
A patch that validates successfully is listed with no messages. If patch validation fails, a status message is displayed for each patch entry that failed to validate in the following format:
<status>: <patch_entry>: <message>
The possible message statuses are:
Axway API Gateway 7.5.3
Installation Guide 153
12 Update API Gateway
Status
Description
Error
An error has been detected for the <patch_entry>. You must take some action to fix the error.
Info
An informational message about the <patch_entry>. This does not usually require any corrective action.
Warning
A warning message about the <patch_entry>. Warnings indicate potential problems which might require you to take some action.
The <patch_entry> indicates the file or directory within the patch to which the message applies.
Some common messages, along with descriptions and suggested actions, are detailed in the following tables.
Cannot validate, no checksum available
Status
Info
Message
Cannot validate, no checksum available
Description
The <patch_entry> does not have a checksum value assigned in the METAINF/<patch>.id file. Action
No action required if the <patch_entry> is a directory.
Content changed
Status
Warning
Message
Content changed
Description
The <patch_entry> checksum value differs from the one configured in the META-INF/<patch>.id file. This indicates that the file on disk has changed since the patch was installed. Action
No action is required if the <patch_entry> indicates a configuration file that you have customized after patch installation.
If the <patch_entry> does not indicate a configuration file that you have customized, check if there are two patches installed that patch the same file. You might be able to remove one of the patches (unless it also patches other files). If this is not the case, reinstall the patch.
Axway API Gateway 7.5.3
Installation Guide 154
12 Update API Gateway
File not found
Status
Error
Message
File not found
Description
An expected <patch_entry> cannot be found in the installation directory. This might indicate a partially removed patch, for example, a patched JAR file has been removed, but not the related META-INF/<patch>.id file. Action
If you meant to delete the patch, remove the patch .id file to delete it completely. If you did not mean to delete the patch, reinstall it.
Malformed file
Status
Error
Message
Malformed file
Description
Either a <patch_entry> is misconfigured with more than one checksum value or the META-INF/<patch>.id file is malformed.
Action
Reinstall the patch, as the .id file might have been corrupted in some way.
Unexpected file
Status
N/A
Message
Unexpected file
Description
A <patch_entry> was found in the installation directory but is not expected based on the information in the META-INF/<patch>.id file. You might have removed a META-INF/<patch>.id file, but not the patch JAR files. Action
Remove the JAR file. Alternatively, if you think you mistakenly deleted the .id file, reinstall the patch.
Axway API Gateway 7.5.3
Installation Guide 155
12 Update API Gateway
Verify which hosts have service packs or
patches installed
In a multi-host environment, service packs and patches are installed on a host-by-host basis. In this scenario, you can use the API Gateway Manager web console to verify exactly which hosts have service packs or patches installed.
For example, you could upgrade host 1 to version 7.5.3 SP1, while host 2 remains at 7.5.3 for a period of testing. However, a system should run the same version across all hosts. You can use the API Gateway Manager topology and grid views to verify that all hosts in the system are running the same version and service pack. If a version mismatch is identified, you should ensure that the required service pack is installed on hosts that are running older versions. For more details, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.3
Installation Guide 156
License acknowledgments
Overview
Axway API Gateway uses several third-party toolkits to perform specific types of processing. In accordance with the Licensing Agreements for these toolkits, the relevant acknowledgments are listed below.
Acknowledgments
Apache Software Foundation:
This product includes software developed by the Apache Software Foundation.
OpenSSL Project:
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit.
Eric Young:
This product includes cryptographic software written by Eric Young ([email protected]).
James Cooper:
This product includes software developed by James Cooper.
iconmonstr:
This product includes graphic icons developed by iconmonstr.
Axway API Gateway 7.5.3
Installation Guide 157
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement