Axway API Gateway Installation Guide
 API Gateway
Version 7.5.2
31 March 2017
Installation Guide
Copyright © 2017 Axway
All rights reserved.
This documentation describes the following Axway software:
Axway API Gateway 7.5.2
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
11
Training services
12
Accessibility
13
Screen reader support
13
Support for high contrast and accessible use of colors
13
1 Quick start installation
14
Prerequisites
14
Install
14
Post-installation
15
2 Plan the deployment
16
Platforms
16
API Gateway components
16
Client considerations
16
Cluster considerations
16
API Gateway HA
17
Apache Cassandra HA
17
Connection to other products
3 Prerequisites
System requirements
17
18
18
Operating systems and hardware
18
Databases
19
Web browsers
20
Thick client platforms
20
Docker containers
20
Specific component requirements
20
Default ports
21
API Gateway
21
Admin Node Manager
21
Axway API Gateway 7.5.2
Installation Guide 3
Policy Studio
21
API Gateway Manager
22
API Manager
22
API Gateway Analytics
22
Software and license keys
22
Check your authorization
22
License keys
23
Cluster installations
24
Additional prerequisites
24
UNIX/Linux platforms
24
Service packs
24
Certificates
24
4 Install API Gateway
25
Prerequisites
25
Installation modes
25
Start installation
26
Installation options
26
Welcome
26
License agreement
26
Select setup type
26
Select components
27
Specify installation directory
27
Specify license file
28
Cassandra configuration
28
Set the administrator user name and password
28
Specify QuickStart Node Manager details
29
Specify QuickStart server details
29
Set the administrator user name and password for API Manager
29
Acknowledge API Gateway Analytics information
30
Installation summary
30
Installing
30
Installation complete
30
Unattended installation
30
Run the installer in unattended mode
31
Unattended mode options
32
5 Install Apache Cassandra
Install an Apache Cassandra database
34
34
Overview
34
Cassandra installation prerequisites
35
Install Apache Cassandra
36
Upgrade from Apache Cassandra version 2.2.5 to version 2.2.8
37
Manage Apache Cassandra on UNIX/Linux
40
Axway API Gateway 7.5.2
Installation Guide 4
Manage Apache Cassandra on Windows
41
Connect to API Gateway for the first time
44
Further details
44
Configure an Apache Cassandra database cluster
44
Overview
44
Cassandra in standalone mode
46
Cassandra in High Availability mode
47
Example Cassandra HA configuration in a production environment
51
Step 1 – Configure and verify the Cassandra HA cluster (non-secure)
53
Step 2 – Configure the client settings for API Gateway or API Manager
57
Step 3 – Secure the Cassandra HA configuration and verify
61
Automate API Gateway Cassandra client settings
61
Troubleshoot Cassandra HA errors
62
Further details
63
Perform essential Cassandra operations
63
Perform anti-entropy repair
63
Replace dead nodes
64
Cassandra HA backup and restore
64
Backup and disaster recovery
64
Reconfigure an existing Cassandra installation from scratch
65
Monitor the Cassandra cluster using JMX
65
Upgrade your Cassandra version
65
Further details
65
setup-cassandra script reference
66
Overview
66
Prerequisites
66
Run the setup-cassandra script
67
Configure the seed node
67
Configure additional nodes
68
Secure Cassandra HA configuration
68
Updated Cassandra configuration
70
6 Install API Gateway components
Install the API Gateway server
72
72
Overview
72
Prerequisites
72
Install the API Gateway server
73
Before you start API Gateway
73
Start API Gateway
74
Install the QuickStart tutorial
75
Overview
75
Prerequisites
75
Install the QuickStart tutorial
75
QuickStart domain configuration
76
Axway API Gateway 7.5.2
Installation Guide 5
Start the QuickStart tutorial
76
Restart the QuickStart tutorial
77
Install the Admin Node Manager
77
Overview
77
Prerequisites
77
Install the Admin Node Manager
78
Start the Admin Node Manager
78
Install Policy Studio
78
Overview
78
Prerequisites
78
Install Policy Studio
78
Start Policy Studio
79
Install Configuration Studio
80
Overview
80
Prerequisites
80
Install Configuration Studio
80
Start Configuration Studio
80
Install API Tester
81
Overview
81
Prerequisites
81
Install API Tester
81
Start API Tester
81
Install API Manager
82
Overview
82
Prerequisites
82
Install API Manager
82
Configure API Manager
83
Start API Manager
83
Install API Gateway Analytics
84
Overview
84
Prerequisites
84
Install API Gateway Analytics
84
Configure your API Gateway Analytics database
84
Start API Gateway Analytics
85
Further information
86
Configure the database for API Gateway Analytics
86
Overview
86
Prerequisites
86
Add JDBC driver files
86
Create the database
88
Set up the database tables
88
Specify options to dbsetup
88
SQL database schema scripts
90
Configure API Gateway Analytics
Axway API Gateway 7.5.2
91
Installation Guide 6
Overview
91
Prerequisites
91
Update API Gateway Analytics configuration
91
Enable metrics for your API Gateway host
95
Install the Package and Deploy tools
95
Overview
95
Prerequisites
96
Install the Package and Deploy tools
96
7 Post-installation
Verify the installation
97
97
Check the installation log
97
Start API Gateway components
97
Log in to the API Gateway tools
98
Initial configuration
98
Create a new domain
98
Set up a database for API Gateway Analytics
98
Secure API Gateway
99
Change default passwords
99
Change default certificates
99
Encrypt API Gateway configuration
99
Run as non-root on UNIX/Linux
99
Set up services
API Gateway
99
99
API Gateway Analytics
100
Apache Cassandra
100
Set up clustering
101
Next steps
101
8 Run API Management in Docker containers
Overview
Further details
102
102
103
API Management Docker topology
103
Set up your local environment
104
Docker
104
API Management
104
Python
104
Minimum disk space and memory
105
Create your API Management Docker infrastructure
105
Step 1—Build the Docker images
105
Step 2—Generate your API Management topology
106
Step 3—Run and test your API Management system
107
Customize your API Management topology in Docker
Create Docker data volumes for persistence
Axway API Gateway 7.5.2
107
108
Installation Guide 7
Delete data volumes
114
Test your API Management system
115
Deploy your Docker infrastructure to the cloud
116
Further details
116
9 Update API Gateway
117
Install a service pack
117
License acknowledgments
118
Overview
118
Acknowledgments
118
Axway API Gateway 7.5.2
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 Management 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 14 – Enables you to install quickly using standard settings.
l Plan the deployment on page 16 – Describes what you should consider when planning for deploying and configuring your system architecture.
l Prerequisites on page 18 – Describes the prerequisites for installing, including the system requirements.
l Install API Gateway on page 25 – Describes how to perform an installation using the GUI mode or unattended command-line mode.
l Install API Gateway components on page 72 – Describes how to install the API Gateway components.
l Post-installation on page 97 – 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 Management in Docker containers on page 102 – 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 117 – Describes how to apply service packs or patches to update your API Gateway installation.
Axway API Gateway 7.5.2
Installation Guide 9
Preface
API Management documentation set
Go to (missing or bad snippet) to find all documentation for this product version.
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 Management 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 (for example, all policies, filters, configuration options and so on), and how to configure them using the Policy Studio graphical tool.
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 Security Guide
Describes how to strengthen the security of API Gateway.
l API Gateway Kerberos Integration Guide
Describes how to integrate API Gateway with Kerberos SPNEGO authentication.
l API Gateway PassPort Interoperability Guide
Describes how to configure API Gateway and Axway PassPort to work together.
Axway API Gateway 7.5.2
Installation Guide 10
Preface
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 API Management 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 User Guide
Describes how to install, customize, and use the client application developer features available separately in API Portal. API Portal is an additional licensable layered product running on API Gateway. Related documentation
The following reference documents are available on the Axway Documentation portal at http://docs.axway.com:
l API Management Concepts Guide
This guide describes how API Gateway, API Manager, and API Portal are used to publish, promote, and manage APIs in a secure and scalable environment.
l API Management Plus Concepts Guide
This guide describes how AxwayAPI Management Plus is used to create APIs from cloud applications and on-premise services, control the use of APIs, and enable self-service consumption of APIs.
l Axway Supported Platforms
Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product.
l Axway Interoperability Matrix
Provides product version and interoperability information for Axway products.
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.
Axway API Gateway 7.5.2
Installation Guide 11
Preface
See "Troubleshoot your API Gateway installation" 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.2
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.2
Installation Guide 13
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 26.
For more details on API Gateway components and concepts, see the API Management Concepts Guide. Prerequisites
In preparation for a quick start installation, perform the following tasks:
1. Check that your target system meets the system requirements.
2. Download the installation setup file for your target system.
3. Obtain the necessary license keys from your Axway Account Manager.
For more information, see Prerequisites on page 18.
Install
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 26.
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.2
Installation Guide 14
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.2
Installation Guide 15
Plan the deployment
2
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 18. 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 Management Concepts Guide.
Client considerations
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 20 and Thick client platforms on page 20.
Cluster considerations
A cluster is a group of computers linked together in a network that share disk resources in a High Availability (HA) environment. The machines in a cluster cooperate to provide a set of services or resources to clients.
In a cluster configuration, if the platform supporting a set of applications fails, the functions of the applications are transferred to a backup platform. This backup (or standby) platform is ready to immediately provide support for the critical application processes normally assured b y the principal platform. In most cluster solutions, when the original platform recovers from failure, it recovers application processes from the secondary system that has temporarily acted as the active system.
Axway API Gateway 7.5.2
Installation Guide 16
2 Plan the deployment
API Gateway HA
For resilient API Gateway and API Manager HA configuration, a minimum of at least two active API Gateway instances at any time, with a third and fourth in passive mode, is recommended. For details on configuring API Gateway high availability, see the API Gateway Administrator Guide. 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 the following:
l Install an Apache Cassandra database on page 34
l Configure an Apache Cassandra database cluster on page 44
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.2 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.2
Installation Guide 17
Prerequisites
3
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 18
l Default ports on page 21
l Software and license keys on page 22
l Additional prerequisites on page 24
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 Management 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
Supported versions
Hardware prerequisites
Linux
l CentOS 6.x, 7.x
l Supports 64-bit Linux running on 64-bit hardware
l Oracle Linux 6.x, 7.x
l Red Hat Enterprise Linux 6.x, 7.x
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.2
Installation Guide 18
3 Prerequisites
Platform
Supported versions
Hardware prerequisites
Windows
l Windows Server 2012 R2
l Supports 32-bit Windows on both 32-bit hardware and 64bit hardware
l Windows Server 2012
l Windows 10
l Windows 8.1
l Intel Core or AMD Opteron at 2Ghz with Dual Core or faster
l Windows 7
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. Databases
API Gateway Analytics supports the following databases:
l MySQL Server 5.6, 5.7
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 84.
Axway API Gateway 7.5.2
Installation Guide 19
3 Prerequisites
API Gateway and API Manager support Apache Cassandra version 2.2.5 for internal data storage. For more details, see Install an Apache Cassandra database on page 34. 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
Docker containers
The following components support Docker version 1.12:
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.12.x. For more details, see Run API Management in Docker containers on page 102.
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 20.
Axway API Gateway 7.5.2
Installation Guide 20
3 Prerequisites
Component
Requirements
API
Gateway
Manager
API Gateway Manager is a web-based client and supports the web browsers listed in Web browsers on page 20.
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 18.
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 20.
API
Manager
API Manager is a browser-based client and supports the same browsers as API Gateway Manager. See Web browsers on page 20.
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
Axway API Gateway 7.5.2
Installation Guide 21
3 Prerequisites
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/
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.
Axway API Gateway 7.5.2
Installation Guide 22
3 Prerequisites
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 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
l Visual Mapper
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 77.
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.
Axway API Gateway 7.5.2
Installation Guide 23
3 Prerequisites
Cluster installations
API Gateway supports cluster installations. 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. 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.2, download and apply them when the installation completes. For more information on applying a service pack, see Update API Gateway on page 117.
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.2
Installation Guide 24
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 18 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 26
l Installation options on page 26
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 30
Axway API Gateway 7.5.2
Installation Guide 25
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.2_Install_win-x86-32_BN<YYYYMMDD>.exe
Linux
APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.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 26.
Tip
To run the setup in unattended mode, see Unattended installation on page 30.
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.2
Installation Guide 26
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 81.
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 98. 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.2
Installation Guide 27
4 Install API Gateway
Windows
C:\Axway-7.5.2
UNIX/Linux
/opt/Axway-7.5.2
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 to install the Cassandra server (for example: c:\cassandra).
l JRE Location:
Enter the directory of your Java Runtime Environment used by Cassandra. Defaults to the JRE provided by API Gateway (for example, C:\Axway-7.5.2\apigateway\Win32\jre).
Note
In a production system, it is recommended to use a 64-bit JRE with Cassandra. For more details, see Install an Apache Cassandra database on page 34.
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. Caution
Ensure that you remember these credentials or you will not be able to log in to Policy Studio or API Gateway Manager.
Axway API Gateway 7.5.2
Installation Guide 28
4 Install API Gateway
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. Caution
Ensure that you remember these credentials or you will not be able to log in to API Manager.
Axway API Gateway 7.5.2
Installation Guide 29
4 Install API Gateway
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.2
Installation Guide 30
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.
The following example shows how to install all API Gateway components (excluding API Manager) in unattended mode:
UNIX/Linux
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --mode unattended
--setup_type standard
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--prefix /opt/Axway-7.5.2
--cassandraInstalldir opt/db/cassandra
--cassandraJDK opt/jre
--startCassandra 1
Windows
APIGateway_7.5.2_Install_win-x86-32_BN<YYYYMMDD>.exe --mode unattended
--setup_type standard
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--prefix C:\Axway-7.5.2
--cassandraInstalldir c:\cassandra
--cassandraJDK c:\jre
--startCassandra 1
The following example shows how to install all API Gateway components, including API Manager, in unattended mode:
UNIX/Linux
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --mode unattended
--setup_type complete
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--apimgmtLicenseFilePath mymgmtlicense.lic
Axway API Gateway 7.5.2
Installation Guide 31
4 Install API Gateway
--prefix /opt/Axway-7.5.2
--cassandraInstalldir /opt/db/cassandra
--cassandraJDK /opt/jre
--startCassandra 1
Windows
APIGateway_7.5.2_Install_win-x86-32_BN<YYYYMMDD>.exe --mode unattended
--setup_type complete
--licenseFilePath mylicense.lic
--analyticsLicenseFilePath myanalyticslicense.lic
--apimgmtLicenseFilePath mymgmtlicense.lic
--prefix C:\Axway-7.5.2
--cassandraInstalldir c:\cassandra
--cassandraJDK c:\jre
--startCassandra 1
The components are installed in the background, in the directory specified by the --prefix option.
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:
UNIX/Linux
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --help
Windows
APIGateway_7.5.2_Install_win-x86-32_BN<YYYYMMDD>.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.
Axway API Gateway 7.5.2
Installation Guide 32
4 Install API Gateway
Option
Description
--setup_type
Specify a setup type.
--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.
--cassandraJDK
Specify the location of your Java runtime for Apache Cassandra. For example, opt/jre on UNIX/Linux, or c:\jre on Windows.
--startCassandra
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.2
Specify options in a properties file. For more information on option files, go to:
http://installbuilder.bitrock.com/docs/installbuilderuserguide.html
Installation Guide 33
Install Apache Cassandra
5
This topic describes how to use the API Gateway installer to install the Apache Cassandra database, and how to configure 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 34
l Configure an Apache Cassandra database cluster on page 44
l Perform essential Cassandra operations on page 63
l setup-cassandra script reference on page 66
Install an Apache Cassandra database
Overview
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.5 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 on page 37.
Axway API Gateway 7.5.2
Installation Guide 34
5 Install Apache Cassandra
Upgrade API Gateway from earlier versions
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.
Cassandra installation prerequisites
This section describes Cassandra-specific prerequisites in addition to the general API Gateway Prerequisites on page 18.
Production environment requirements
API Gateway supports the following in production:
l Operating systems:
o All supported Linux platforms (see System requirements on page 18)
o Windows 2012 Server only
l Cassandra:
o Cassandra version 2.2.8 or 2.2.5 on Linux and Windows
o 64-bit JRE version 8 on Linux and Windows
Note
On Linux, the default API Gateway installation includes a 64-bit JRE. On Windows, API Gateway includes a d efault 32-bit JRE, which is suitable for development only. In a Windows production environment, you must download and install a 64-bit JRE manually. For more details, see Install 64-bit JRE on Windows on page 35.
For details on requirements for high availability, see HA production environment requirements on page 51.
Install 64-bit JRE on Windows
The default 32-bit 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 JRE.
Note
If you select the default 32-bit JRE bundled with API Gateway, and later decide to switch to a 64-bit 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 JRE. For example:
SET JAVA_HOME=C:\Program Files\Java\jre8
Axway API Gateway 7.5.2
Installation Guide 35
5 Install Apache Cassandra
JCE policies for Cassandra SSL
If client SSL will be enabled for Cassandra, you must install the Java Cryptographic Extension (JCE) policies for your 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
Cassandra version 2.2.5 is installed by default in an API Gateway Standard or Complete setup. You can download the recommended Cassandra version 2.2.8 from http://cassandra.apache.org/download/.
For more details on API Gateway setup types, see in Installation options on page 26.
Install Cassandra in GUI mode
In GUI mode, to install Apache Cassandra only, use the steps described in Installation options on page 26 with the following selections:
l Setup Type: Select Custom.
l Select Components: Select Cassandra.
l Cassandra configuration: Configure Cassandra Installation Directory and your JRE
Location.
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 30. For example, the following command shows how to install Apache Cassandra only in unattended mode:
UNIX/Linux
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --mode unattended
--setup_type advanced
--enable-components cassandra
--disable-components apigateway,analytics,qstart,policystudio,
configurationstudio,apitester,apimgmt,packagedeploytools
--cassandraInstalldir /opt/db/cassandra
--cassandraJDK /opt/jre
--startCassandra 0
Axway API Gateway 7.5.2
Installation Guide 36
5 Install Apache Cassandra
Windows
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.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.
Next steps
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 the next sections.
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.
For details on configuring Cassandra high availability, see Configure an Apache Cassandra database cluster on page 44.
Upgrade from Apache Cassandra version 2.2.5
to version 2.2.8
This section recommends Cassandra upgrade steps from Datastax and provides additional best practices when Cassandra has been installed using the API Gateway installer.
Recommended upgrade steps from Datastax
The recommended steps on upgrading Cassandra versions are available from:
http://docs.datastax.com/en/latest-upgrade/upgrade/cassandra/upgrdCassandraDetails.html
Apache Cassandra 2.2.8 is available from:
http://cassandra.apache.org/download/
Axway API Gateway 7.5.2
Installation Guide 37
5 Install Apache Cassandra
You must repeat the upgrade steps for each node in the cluster. There should not be any downtime across the API Gateway topology. The remaining nodes in the cluster maintain data integrity even while some of the nodes are running different versions of Cassandra. However, it is recommended not to make any schema changes until the whole cluster has been upgraded.
Best practices when Cassandra installed using API
Gateway
Note
This section assumes that Apache Cassandra 2.2.5 was installed using the API Gateway version 7.5.2 installer.
Move your Cassandra data files
If you installed Cassandra with the API Gateway installer, the data files are in the CASSANDRA_
HOME directory by default. The Datastax upgrade procedure does not describe moving the data files because it is best practice to already store them in a separate directory or disk from the Cassandra node.
After stopping the Cassandra process on the node, and before configuring your new Cassandra installation, you should move your data files. For example, perform the following steps:
1. Backup your data using nodetool snapshot. This flushes all Memtables from the node to SSTables on disk. For more details, see:
http://docs.datastax.com/en/archived/cassandra/2.2/cassandra/tools/toolsSnapShot.html
2. Create the following directories in your chosen locations for your new Cassandra system:
l data: for example, /var/lib/cassandra_data/data
l commitlog: for example, /var/lib/cassandra_data/commitlog
l saved_caches: for example, /var/lib/cassandra_data/saved_caches
By default, all of these directories are stored in the CASSANDRA_HOME/data directory. However, you should store data, commit log, and saved caches files in a separate location to your Cassandra installation. For example, you could put the commit log on one disk and the data on a second disk to avoid running out of space.
3. Stop the Cassandra process on the node (see the next sections for details on UNIX/Linux and Windows).
4. Update the following configuration variables in the CASSANDRA_
HOME/conf/cassandra.yaml file with your new locations: l data_file_directories
l commitlog_directory
l saved_caches_directory
Axway API Gateway 7.5.2
Installation Guide 38
5 Install Apache Cassandra
Note
Before API Gateway 7.5.2 SP 1, using the setup-cassandra script removed all comments that included unused configuration variables. In this case, you will need to create these variables in the cassandra.yaml file when upgrading. For more details, see Update your Cassandra configuration files on page 39.
5. Copy the existing folders in $CASSANDRA_HOME/data to their new locations.
6. Restart Cassandra (see the next sections for details on UNIX/Linux and Windows).
Update your Cassandra configuration files
When upgrading Cassandra, the configuration files must be updated as outlined in the recommended Datastax upgrade steps. You must compare the new files to the old files, and update accordingly. For example, configuration settings that may need to be updated include the following:
CASSANDRA_HOME/conf
Configuration variables to update in cassandra.yaml include:
l
saved_caches_directory
l
data_file_directories
l
commitlog_directory
l
start_rpc
l
rpc_address
l
listen_address
l
seeds
l
server_encryption_options
l
client_encryption_options
The values relating to JMX settings, racks, and data centers may also need to be updated in the appropriate properties files.
CASSANDRA_HOME/bin
Ensure that the JAVA_HOME value in the cassandra.in.bat and cassandra.in.sh file specifies the correct 64-bit JRE. For more details, see Install an Apache Cassandra database on page 34.
USER_HOME/.cassandra
If SSL encryption was configured, a file called cqlshrc will have been created in the hidden
.cassandra directory in your user home folder. This may need to be updated so that [cql]
version = 3.3.1.
See also JCE policies for Cassandra SSL on page 36.
Axway API Gateway 7.5.2
Installation Guide 39
5 Install Apache Cassandra
Manage Apache Cassandra on UNIX/Linux
This section explains how to start and stop Cassandra o n UNIX/Linux.
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):
Axway API Gateway 7.5.2
Installation Guide 40
5 Install Apache Cassandra
$ ps auwx | grep cassandra
2. Run the following command:
$ 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.
Axway API Gateway 7.5.2
Installation Guide 41
5 Install Apache Cassandra
Powershell mode
To start Cassandra in the background in PowerShell mode:
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
Start Cassandra as a Windows service
Note
Ensure you are not using the default 32-bit JRE bundled with API Gateway, which cannot run Cassandra as a service. For more details, see Install 64-bit JRE on Windows on page 35.
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.
Axway API Gateway 7.5.2
Installation Guide 42
5 Install Apache Cassandra
Configuring 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:
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 42.
Axway API Gateway 7.5.2
Installation Guide 43
5 Install Apache Cassandra
Connect to API Gateway for the first time
Connecting to API Gateway depends on your installation setup type (Standard, Complete, or Custom).
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 IP 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 an Apache Cassandra database cluster on page 44.
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/
Configure an Apache Cassandra database
cluster
Overview
This topic describes how to set up an Apache Cassandra database cluster for your API Gateway Axway API Gateway 7.5.2
Installation Guide 44
5 Install Apache Cassandra
system. The following Cassandra deployment architectures are supported:
Deployment
Description
Use
Standalone
One API Gateway instance only. This is the default.
l Development environment
l Production environment with one API Gateway instance
High availability
with local storage
High availability
with remote
storage
Note
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 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.
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.
HA production environment configuration
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.2
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 details on hosting Cassandra in data centers, contact Axway Support.
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 34.
2. Start Cassandra before starting API Gateway. For details, see Install an Apache Cassandra database on page 34.
3. Start API Gateway. For details, see Install the API Gateway server on page 72.
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 44.
To use Cassandra with API Manager, run the setup-apimanager script (see Configure your API Manager settings on page 59). This is configured by default when API Manager is installed along with the QuickStart tutorial.
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:
Axway API Gateway 7.5.2
Installation Guide 46
5 Install Apache Cassandra
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 any ports in your firewall. However, the data will be stored in the DMZ. Axway recommends local Cassandra HA for ease of use and minimum cost of ownership.
The following diagram shows local Cassandra HA mode:
Axway API Gateway 7.5.2
Installation Guide 47
5 Install Apache Cassandra
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 52.
l You are not required to use the Cassandra component supplied by the API Gateway installer.
l The setup-cassandra script supplied by the API Gateway installation is not available, so you must 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.2
Installation Guide 48
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 is IP address, storage_port set to 7000
o Client-server communication: rpc_address is IP address, rpc_port of 9160
o JMX: localhost:7199
Note
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 for the first time. 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.
Axway API Gateway 7.5.2
Installation Guide 49
5 Install Apache Cassandra
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.
Configuration tools
You must 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 when installed locally and updates the cassandra.yaml configuration file. You can also edit this file manually, but this script saves time, helps prevent errors, and creates a backup of the original cassandra.yaml file.
setup-cassandra also outputs instructions for resetting the default user name and password. You can apply these now or leave until later. For more details, see setup-cassandra script reference on page 66.
Axway API Gateway 7.5.2
Installation Guide 50
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 54.
Configure Cassandra HA
The following 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).
l Ensure Cassandra is installed on each Cassandra node. For more details, see Install an Apache Cassandra database on page 34.
l Configure Cassandra on each Cassandra node. If Cassandra is local to the API Gateway instance, you can use the setup-cassandra script. Alternatively, you can configure manually by modifying cassandra.yaml. Example Cassandra HA configuration in a production environment on page 51 shows examples of both approaches.
l Ensure API Gateway is installed and configured on one API Gateway node (local or remote to Casssandra).
l Configure the Cassandra client settings in Policy Studio for the API Gateway group. Example Cassandra HA configuration in a production environment on page 51 shows the steps for both API Gateway and API Manager clients.
l Install and configure API Gateway on additional nodes as necessary.
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.2
Installation Guide 51
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: Do not use a Storage Area Network (SAN). Cassandra is designed to run on commodity distributed drives.
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 18.
o Windows Server 2012 R2 only.
l Cassandra:
o 64-bit Cassandra version 2.2.8 or 2.2.5 with 64-bit JRE (Linux and Windows). Cassandra 2.2.8 is recommended. For more details, Supported Cassandra versions on page 34.
Note
On Windows, you must download 64-bit Cassandra 2.2.8 and a 64-bit JRE manually.
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/.
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 your firewall rules allow the necessary Cassandra ports for client and server connections. API Gateway clients connect to Cassandra on port 9160. Cassandra uses port 7000 for communication between Cassandra nodes (and port 7001 if SSL is configured).
Axway API Gateway 7.5.2
Installation Guide 52
5 Install Apache Cassandra
l 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.
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.
Step 1 – Configure and verify the Cassandra
HA cluster (non-secure)
This includes the following steps:
1. Connect API Gateway to Cassandra on page 54
2. Configure the g roup keyspace and replication factor in Cassandra on page 54
3. Configure the Cassandra seed node on page 55
4. Add the seed node to the HA cluster on page 56
5. Replicate and verify the Cassandra cluster on page 57
Axway API Gateway 7.5.2
Installation Guide 53
5 Install Apache Cassandra
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 Connect to API Gateway for the first time on page 44.
Configure the group keyspace and replication factor in
Cassandra
When API Gateway connects to a Cassandra node, it creates a Cassandra keyspace and tables for data storage if these do not exist. The keyspace has a name of the form: xDOMAINID_GROUPID. This enables API Gateways in a group to share data. It also 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:
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.
Axway API Gateway 7.5.2
Installation Guide 54
5 Install Apache Cassandra
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 68.
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 specify the following settings (where ipA is the IP address of the first node):
l seed_provider, parameters, seeds: ipA
l start_rpc: true
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:
setup-cassandra --seed --own-ip=ipA --nodes=3 --cassandra-config=CONFIG_
FILE
2. Restart Cassandra. For details, see Start Cassandra as a Windows service on page 42. 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 :
Axway API Gateway 7.5.2
Installation Guide 55
5 Install Apache Cassandra
./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).
Configure the second Cassandra node (ipB)
1. On Cassandra node B, install Cassandra (see Install an Apache Cassandra database on page 34). Do not start it yet.
2. Edit cassandra.yaml manually or use the setup-cassandra script. You must specify the following settings (where ipB is the IP address of the second node):
l seed_provider, parameters, seeds: ipA
l start_rpc: true
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:
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 Start Cassandra as a Windows service on page 42.
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 34). Do not start it yet.
2. Edit cassandra.yaml manually or use the setup-cassandra script. You must specify the following settings (where ipC is the IP address of the third node):
Axway API Gateway 7.5.2
Installation Guide 56
5 Install Apache Cassandra
l seed_provider, parameters, seeds: ipA
l start_rpc: true
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 34.
4. To verify, run nodetool status. You should see three nodes reported with the correct IP addresses.
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.
Axway API Gateway 7.5.2
Installation Guide 57
5 Install Apache Cassandra
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 72.
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 adress for each Cassandra node in the cluster ( ipA, ipB and ipC in this example).
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 61.
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 26). 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 59)
2. Select Environment Configuration > Key Property Stores > API Server > Data
Sources > Cassandra Storage, click Edit.
3. In the Read Consistency Level and Write Consistency Level fields, select QUORUM:
Axway API Gateway 7.5.2
Installation Guide 58
5 Install Apache Cassandra
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 Troubleshoot Cassandra HA errors on page 62.
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 72 and Install API Manager on page 82.
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 58.
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:
Axway API Gateway 7.5.2
Installation Guide 59
5 Install Apache Cassandra
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 API Management Guide.
2. Configure the Cassandra consistency levels for your KPS Collections. For details, see Configure the API Gateway Cassandra consistency levels on page 58.
3. In the Policy Studio tree, select Server Settings > API Manager > Quota Settings, and ensure that Use Cassandra is selected. 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
Axway API Gateway 7.5.2
Installation Guide 60
5 Install Apache Cassandra
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.
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 SSL traffic encryption.
3. Enable client-to-node SSL traffic encryption.
4. Configure the cqlsh command for client-to-node SSL encryption.
For details, see Secure Cassandra HA configuration on page 68.
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:9160,ipB:9160,ipC:9160"
The script options are explained as follows:
Axway API Gateway 7.5.2
Installation Guide 61
5 Install Apache Cassandra
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.
-r, -replicationFacto
r
-h, --hosts
Enter the Cassandra replication factor. For more details, see Configure the g roup keyspace and replication factor in Cassandra on page 54.
Enter a comma-separated list of Cassandra host nodes in host:port format. For example, 127.0.0.1:9160,127.0.0.2:9160,127.0.0.3:9160.
For more details on automating API Gateway configuration, see the API Gateway DevOps Deployment Guide.
Troubleshoot Cassandra HA errors
This section explains how to troubleshoot typical Cassandra HA error messages.
All host polls marked down
When API Gateway starts up, or when configuration is redeployed, you could see the following error:
HectorException: All host pools marked down. Retry burden
pushed out to client.
This means there is a connection error between API Gateway and Cassandra. For example, if you changed the client connection configuration during the HA configuration, or due to a network or firewall issue, or because Cassandra is not available, has not been started, or is in error.
To resolve this issue:
l Check that all ports and addresses are correct in cassandra.yaml to verify that the endpoints are what you expect.
l Enable Cassandra debug logging.
l Contact your network administrator
Axway API Gateway 7.5.2
Installation Guide 62
5 Install Apache Cassandra
Further details
For details on Cassandra administration, see Perform essential Cassandra operations on page 63.
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/
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
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 weekly, at off-peak times, and stagger execution on different nodes.
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 64.
The following example crontab commands execute repair on a specified schedule:
# 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.
For more details, see:
l https://docs.datastax.com/en/cassandra/2.2/cassandra/operations/opsRepairNodesManualRep
air.html
Axway API Gateway 7.5.2
Installation Guide 63
5 Install Apache Cassandra
Replace dead nodes
For details on replacing dead Cassandra nodes, see:
l https://docs.datastax.com/en/cassandra/2.2/cassandra/operations/opsReplaceNode.html
Cassandra HA backup and restore
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
Backup and disaster recovery
You must back up the following API Gateway and Cassandra configuration and data for disaster recovery:
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.
Tip
You can perform regular API Gateway and KPS backup by running the sysupgrade
export command on all nodes. For details, see the API Gateway Upgrade Guide. Ensure that you move the apigateway/upgrade/bin/out directory to safe storage after the backup is performed. Use cron on Linux or Scheduler on Windows to perform this task regularly.
Cassandra configuration
Ensure that you back up the CASSANDRA_HOME/conf directory on all nodes.
Axway API Gateway 7.5.2
Installation Guide 64
5 Install Apache Cassandra
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 34.
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.
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 34.
Further details
For more details on Cassandra operations, see:
l http://docs.datastax.com/en/cassandra/2.2/
Axway API Gateway 7.5.2
Installation Guide 65
5 Install Apache Cassandra
setup-cassandra script reference
Overview
The setup-cassandra script provided by API Gateway enables you to configure a multi-node Cassandra cluster when Cassandra is installed locally on the same host as API Gateway. For details on supported Cassandra deployment architectures and HA production environments, you must first see Configure an Apache Cassandra database cluster on page 44.
This topic describes the setup-cassandra script used to configure a multi-node Cassandra cluster with username/password authentication enabled, and optionally enabling SSL encryption of inter-node and client-server traffic.
API Gateway provides this script to help configure a Cassandra cluster by updating your Cassandra configuration files and providing instructions to finalize the configuration. This script creates an automatic backup of the original cassandra.yaml file in the following format:
<timestamp>_cassandra.yaml.bak
You can also use the setup-cassandra script to configure SSL encryption for the client-server and inter-node communications in the cluster.
Note
setup-cassandra is available only when Cassandra is installed locally on the same host as API Gateway. You must configure Cassandra manually when it is installed remote to API Gateway. For details, see Configure an Apache Cassandra database cluster on page 44.
Prerequisites
The Cassandra cqlsh command requires Python 2.7.10 to be installed. 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 68.
Axway API Gateway 7.5.2
Installation Guide 66
5 Install Apache Cassandra
Run the setup-cassandra script
The setup-cassandra script is bundled with the API Gateway installation and located in the bin directory. To run the setup-cassandra script:
UNIX/Linux
$ cd AXWAY_HOME/apigateway/posix/bin
$ ./setup-cassandra <options>
Windows
> cd AXWAY_HOME\apigateway\win32\bin
> setup-cassandra <options>
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
Axway API Gateway 7.5.2
Installation Guide 67
5 Install Apache Cassandra
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
IP address of this Cassandra seed host (see Configure the seed node on page 67).
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 when Cassandra is installed locally on the same host as API Gateway.
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
Axway API Gateway 7.5.2
Installation Guide 68
5 Install Apache Cassandra
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:
l https://docs.datastax.com/en/cassandra/2.2/cassandra/configuration/secur
eConfigNativeAuth.html?hl=authentication
Enable node-to-node SSL traffic encryption
To configure SSL encryption, you must generate a SSL 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 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.
Axway API Gateway 7.5.2
Installation Guide 69
5 Install Apache Cassandra
Enable client-to-node SSL traffic encryption
The requirements for setting up client-to-node SSL are the same as the node-to-node 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 setupcassandra script to configure client-to-node SSL encryption, add the --enable-clientencryption 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.
Configure the cqlsh command for client-to-node SSL
encryption
When the Cassandra cluster has been configured to use client-to-node SSL encryption, you must configure all clients connecting to the cluster (including cqlsh) to use SSL.
If client-to-node SSL encryption has been enabled, the setup-cassandra script creates a configuration file ( cqlshrc) with the necessary configuration to enable SSL encryption. However, you must provide following files to confgure cqlsh for SSL:
l client-ca.pem: PEM file containing CA certificate
l cqlsh-cert.pem: PEM file containing SSL client certificate for cqlsh
l cqlsh-key.pem: PEM file containing private key of SSL 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_rpc: true
l listen_address: IP address of the node
l rpc_address: IP address of the node
Axway API Gateway 7.5.2
Installation Guide 70
5 Install Apache Cassandra
l authenticator: org.apache.cassandra.auth.PasswordAuthenticator
l authorizer: org.apache.cassandra.auth.CassandraAuthorizer
Node-to-node SSL traffic encryption
If node-to-node 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>
l truststore_password: Randomly generated password
l protocol: TLS
l store_type: JKS
l algorithm: SunX509
l require_client_auth: true
Client-to-node SSL traffic encryption
If client-to-node 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.2
Installation Guide 71
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 72
l Install the QuickStart tutorial on page 75
l Install the Admin Node Manager on page 77
l Install Policy Studio on page 78
l Install API Tester on page 81
l Install Configuration Studio on page 80
l Install API Manager on page 82
l Install API Gateway Analytics on page 84
l Install the Package and Deploy tools on page 95
For more details on API Gateway components and concepts, see the API Management Concepts Guide. Install the API Gateway server
Overview
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 Management 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 18 are met. Axway API Gateway 7.5.2
Installation Guide 72
6 Install API Gateway components
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. 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 34.
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 26, using the following selections:
l Select the Custom setup type.
l Select to install the API Gateway server component only.
To install the API Gateway server in unattended mode, follow the steps described in Unattended installation on page 30.
The following example shows how to install the API Gateway server component in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.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 34.
Axway API Gateway 7.5.2
Installation Guide 73
6 Install API Gateway components
Start API Gateway
To start the API Gateway manually, follow these 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 "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 99.
Axway API Gateway 7.5.2
Installation Guide 74
6 Install API Gateway components
Install the QuickStart tutorial
Overview
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 26.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 18 are met.
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 26, 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 30.
The following example shows how to install the API Gateway Server component and the QuickStart tutorial in unattended mode:
APIGateway_7.5.2_Install_linux-x86-32_BN20170331.run --mode unattended
--setup_type advanced --enable-components apigateway,nodemanager,qstart
--disable-components
analytics,policystudio,apitester,configurationstudio,apimgmt,cassandra,packagedeploy
tools
--licenseFilePath mylicense.lic
Axway API Gateway 7.5.2
Installation Guide 75
6 Install API Gateway components
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.
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.
Axway API Gateway 7.5.2
Installation Guide 76
6 Install API Gateway components
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
On UNIX/Linux, you must ensure that the startinstance file 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://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
Overview
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 Management Concepts Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 18 are met. Axway API Gateway 7.5.2
Installation Guide 77
6 Install API Gateway components
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 26, using the following selections:
l Select the Custom setup type.
l Select to install the Admin Node Manager component only.
To install the Admin Node Manager in unattended mode, follow the steps described in Unattended installation on page 30.
The following example shows how to install the Admin Node Manager component in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --mode unattended
--setup_type advanced
--enable-components apigateway
--disable-components analytics,qstart,policystudio,configurationstudio,
apitester,apimgmt,cassandra,packagedeploytools
Start the Admin Node Manager
For more information on starting the Admin Node Manager, see Start API Gateway on page 74.
Install Policy Studio
Overview
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 Management Concepts Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 18 are met. Install Policy Studio
To install Policy Studio in GUI mode, perform an installation following the steps described in Installation options on page 26, using the following selections:
Axway API Gateway 7.5.2
Installation Guide 78
6 Install API Gateway components
l Select the Custom setup type.
l Select to install the Policy Studio component only.
To install Policy Studio in unattended mode, follow the steps described in Unattended installation on page 30.
The following example shows how to install the Policy Studio component in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32-BN<YYYYMMDD>.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 74.
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).
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.
Axway API Gateway 7.5.2
Installation Guide 79
6 Install API Gateway components
Install Configuration Studio
Overview
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 18 are met. Install Configuration Studio
To install Configuration Studio in GUI mode, perform an installation following the steps described in Installation options on page 26, using the following selections:
l Select the Custom setup type.
l Select to install the Configuration Studio component only.
To install Configuration Studio in unattended mode, follow the steps described in Unattended installation on page 30.
The following example shows how to install the Configuration Studio component in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --mode unattended
--setup_type advanced
--enable-components configurationstudio
--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.
Axway API Gateway 7.5.2
Installation Guide 80
6 Install API Gateway components
Install API Tester
Overview
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 Management 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 18 are met. Install API Tester
To install API Tester in GUI mode, perform an installation following the steps described in Installation options on page 26, using the following selections:
l Select the Custom setup type.
l Select to install the API Tester component only.
To install API Tester in unattended mode, follow the steps described in Unattended installation on page 30.
The following example shows how to install the API Tester component in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.run --mode unattended
--setup_type advanced
--enable-components apitester
--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 74.
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).
Axway API Gateway 7.5.2
Installation Guide 81
6 Install API Gateway components
3. Run apitester.
For more details on API Tester, see the API Tester User Guide.
Install API Manager
Overview
API Manager is an additional licensed layered product running on the Axway API Gateway. For more details, see the API Manager API Management Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 18 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 and on Policy Studio nodes.
Install API Manager
To install API Manager in GUI mode, perform an installation following the steps described in Installation options on page 26, 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)
For more details, see the following: Axway API Gateway 7.5.2
Installation Guide 82
6 Install API Gateway components
l Install the API Gateway server on page 72
l Install the Admin Node Manager on page 77
l Install an Apache Cassandra database on page 34
Unattended mode
To install API Manager in unattended mode, follow the steps described in Unattended installation on page 30.
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.2_Install_linux-x86-32_BN<YYYYMMDD>.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
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 API Management 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 74.
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 API Management Guide.
Axway API Gateway 7.5.2
Installation Guide 83
6 Install API Gateway components
Install API Gateway Analytics
Overview
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 Management Concepts Guide.
Prerequisites
Ensure that all of the prerequisites detailed in Prerequisites on page 18 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 26, using the following selections:
l Select the Custom setup type.
l Select to install the API Gateway Analytics component only.
To install API Gateway Analytics in unattended mode, follow the steps described in Unattended installation on page 30.
The following example shows how to install the API Gateway Analytics component in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.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:
Axway API Gateway 7.5.2
Installation Guide 84
6 Install API Gateway components
1. Create a database instance. For more details, see Configure the database for API Gateway Analytics on page 86. 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 91.
3. Configure the database tables using the dbsetup script. For more details, see Configure the database for API Gateway Analytics on page 86.
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 91.
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
Note
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. 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 99.
Axway API Gateway 7.5.2
Installation Guide 85
6 Install API Gateway components
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 database for API Gateway
Analytics
Overview
API Gateway stores and maintains the monitoring and transaction data read by Axway API Gateway Analytics in a JDBC-compliant database. This topic describes how to create and configure a database for use with API Gateway Analytics. 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. Prerequisites
The prerequisites for setting up the database are as follows:
Install API Gateway Analytics
You must install Axway API Gateway Analytics. For details on how to install API Gateway Analytics, see Install API Gateway Analytics on page 84.
Install a JDBC database
You must install a JDBC-compliant database to store the API Gateway monitoring and transaction data. API Gateway Analytics provides setup scripts for the following databases:
l MySQL
l Microsoft SQL Server
l Oracle
l IBM DB2
For details on how to install your chosen JDBC database, see your database product documentation.
Add JDBC driver files
You must add the JDBC driver files for your chosen database to your API Gateway, API Gateway Analytics, and Policy Studio installations.
Axway API Gateway 7.5.2
Installation Guide 86
6 Install API Gateway components
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 API Gateway Analytics
To add the third-party JDBC driver files for your database to API Gateway Analytics, 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.
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 in your Policy Studio installation.
4. Click OK.
5. Restart Policy Studio using the policystudio -clean command.
Axway API Gateway 7.5.2
Installation Guide 87
6 Install API Gateway components
Create the database
API Gateway Analytics reads message metrics from a database and displays 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, 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 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. You can do this by running the dbsetup command without any options from the following API Gateway Analytics directory:
Windows
INSTALL_DIR\analytics\Win32\bin
UNIX/Linux
INSTALL_DIR/analytics/posix/bin
The following example command 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, --
Specifies the configuration passphrase (blank for zero length).
passphrase=PASSPHRASE
Axway API Gateway 7.5.2
Installation Guide 88
6 Install API Gateway components
Option
Description
--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.
--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:
Axway API Gateway 7.5.2
Installation Guide 89
6 Install API Gateway components
>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:
>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
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)
...
Axway API Gateway 7.5.2
Installation Guide 90
6 Install API Gateway components
Configure API Gateway Analytics
Overview
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. Prerequisites
The prerequisites for configuring API Gateway Analytics are as follows:
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 72.
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 95.
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 84.
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 database for API Gateway Analytics on page 86.
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.
Axway API Gateway 7.5.2
Installation Guide 91
6 Install API Gateway components
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. 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:
Databa
se
Example connection URL
Oracle
jdbc:oracle:thin:@DB_HOST:1521:reports
Microso
ft SQL
Server
jdbc:sqlserver://DB_
MySQL
jdbc:mysql://DB_HOST:3306/reports
IBM
DB2
jdbc:db2://DB_HOST:50000/reports
HOST:1433;DatabaseName=reports;integratedSecurity
=false;
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.
Axway API Gateway 7.5.2
Installation Guide 92
6 Install API Gateway components
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
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
Axway API Gateway 7.5.2
Installation Guide 93
6 Install API Gateway components
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.
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
Axway API Gateway 7.5.2
You can verify that your database connection is configured correctly by clicking the Test Connection button on the Configure Database Connection dialog. Installation Guide 94
6 Install API Gateway components
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
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 API Gateway Administrator Guide.
Install the Package and Deploy tools
Overview
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.
Axway API Gateway 7.5.2
Installation Guide 95
6 Install API Gateway components
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 18 are met.
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 26, 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 30.
For example, the following command shows how to install the API Gateway Package and Deploy tools only in unattended mode:
./APIGateway_7.5.2_Install_linux-x86-32_BN<YYYYMMDD>.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 the API Gateway DevOps Deployment Guide.
Axway API Gateway 7.5.2
Installation Guide 96
Post-installation
7
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 97
l Initial configuration on page 98
l Secure API Gateway on page 99
l Set up services on page 99
l Set up clustering on page 101
l Next steps on page 101
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 74.
l To start API Gateway Analytics, see Start API Gateway Analytics on page 85.
Axway API Gateway 7.5.2
Installation Guide 97
7 Post-installation
Log in to the API Gateway tools
l To start the Policy Studio desktop tool, see Start Policy Studio on page 79.
l To log in to the API Gateway Manager web-based administration tool, see Start API Gateway on page 74.
l To start the Configuration Studio desktop tool, see Start Configuration Studio on page 80.
l To start the API Tester desktop tool, see Start API Tester on page 81.
l To log in to the web-based API Gateway Analytics interface, see Start API Gateway Analytics on page 85.
l To log in to the API Manager web-based tool, see Start API Manager on page 83.
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 database for API Gateway Analytics on page 86.
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 91.
Axway API Gateway 7.5.2
Installation Guide 98
7 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.2
Installation Guide 99
7 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.4.1" 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 34.
Axway API Gateway 7.5.2
Installation Guide 100
7 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 Configure an Apache Cassandra database cluster on page 44.
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.2
Installation Guide 101
Run API Management in
Docker containers
8
Overview
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.
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.12.x, and includes API Gateway, API Manager and Apache Cassandra.
Axway provides Docker files and c ompose scripts to enable you to create 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, Amazon Web Services, or Microsoft Azure). By default, the API Management sample system uses CentOS Linux 7 for the base images, which you can customize to generate your API Management Docker topology.
The following diagram shows a high-level overview of the steps to create and deploy your desired API Management topology:
These steps are described in the following sections:
l Set up your local environment on page 104
l Create your API Management Docker infrastructure on page 105
l Deploy your Docker infrastructure to the cloud on page 116
Axway API Gateway 7.5.2
Installation Guide 102
8 Run API Management in Docker containers
Further details
This topic assumes that you have working knowledge of API Management architecture, Apache Cassandra, and Docker. For more details, see the following:
l API Management Concepts Guide
l Install Apache Cassandra on page 34
l https://www.docker.com/
API Management Docker topology
This section describes the default API Management topology that is generated in the 3-node sample system, which is recommended for HA:
Axway API Gateway 7.5.2
Installation Guide 103
8 Run API Management in Docker containers
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.
Set up your local environment
The following components are required on your system:
Docker
API Management supports the following:
l Docker version 1.12.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
Python
The following components are required:
l Python version 2.7.x to create Docker data volumes
l Python Requests version 2.10.x. For example, to install the latest Python requests:
Axway API Gateway 7.5.2
Installation Guide 104
8 Run API Management in Docker containers
pip install requests --upgrade
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
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:
l Step 1—Build the Docker images on page 105
l Step 2—Generate your API Management topology on page 106
l Step 3—Run and test your API Management system on page 107
Step 1—Build the Docker images
Docker images are required to generate your API Management topology. To build the Docker images, perform the following steps:
1. Unzip the file containing the Docker scripts available from Axway Support. For example:
APIGateway_7.5.2_SamplesPackageDocker_linux-x86-64_BNYYYYMMDDn
2. In the directory in which you unzipped the scripts, enter the following command:
Axway API Gateway 7.5.2
Installation Guide 105
8 Run API Management in Docker containers
./build.py --installer <API_GATEWAY_LINUX_INSTALL_FILE> --license <API_
GATEWAY_LICENSE_FILE> --clean
For example:
./build.py --installer ~/dependencies/APIGateway_7.5.2_Install_linuxx86-64_BNYYYYMMDDn.run --license mylicense.lic --clean
This command adds the following images to the local Docker registry:
cassandra
java8
gwlatest_master
gwlinux
centos
Step 2—Generate your API Management
topology
You can create different kinds of 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
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-3nodehaapimgr.json
Includes 3 API Manager, 2 Admin Node Manager, 1 Node Manager, and 3 Cassandra nodes
For example, for the recommended 3-node HA system, the following images are added to the local Docker registry:
gwlatest-3nodeha-apimgr_node3
Axway API Gateway 7.5.2
Installation Guide 106
8 Run API Management in Docker containers
gwlatest-3nodeha-apimgr_node2
gwlatest-3nodeha-apimgr_node1
The generated docker-compose.yml file is written to the composegenerated/servers directory.
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 107.
Step 3—Run and test your API Management
system
You can run and test your API Management topology images locally. 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.2) (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.2) (vshell)
root 19193 18627 23 15:37 ? 00:00:27 PortalInstance-2 (PortalGroup-1)
(7.5.2) (vshell)
Customize your API Management topology in
Docker
This section describes how to customize your Docker-based API Management topology to suit your environment.
Axway API Gateway 7.5.2
Installation Guide 107
8 Run API Management in Docker containers
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:
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
Axway API Gateway 7.5.2
Installation Guide 108
8 Run API Management in Docker containers
local
local
local
local
local
local
local
node2_USER_DATA
node3_CONF_DATA
node3_EVENTS_DATA
node3_GROUP_DATA
node3_LOGS_DATA
node3_TRACE_DATA
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
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
Axway API Gateway 7.5.2
Installation Guide 109
8 Run API Management in Docker containers
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
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)
Axway API Gateway 7.5.2
Installation Guide 110
8 Run API Management in Docker containers
- 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
- 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
Axway API Gateway 7.5.2
Installation Guide 111
8 Run API Management in Docker containers
- 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
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
Axway API Gateway 7.5.2
Installation Guide 112
8 Run API Management in Docker containers
cassandra-s1_DATA:
cassandra-s1_LOGS:
cassandra-s2_DATA:
cassandra-s2_LOGS:
external:
external:
external:
external:
true
true
true
true
Example: Persist user-defined directories for API
Gateway filters
If your policy uses a file-based API Gateway filter (for example, File Download, File Upload, or Save to File) that allows a user-defined directory such as /home/user/Downloads, 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
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:
Axway API Gateway 7.5.2
Installation Guide 113
8 Run API Management in Docker containers
# 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 107.
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
Axway API Gateway 7.5.2
Installation Guide 114
8 Run API Management in Docker containers
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 services
You can perform the following tests to check that your system is running correctly:
l Health check policy
Enter the following command to connect to the API Gateway Health Check policy:
curl http://localhost:8080/healthcheck
<status>ok</status>
l API Manager
Enter the following URL in your browser to launch the API Manager web console:
https://localhost:8075
Axway API Gateway 7.5.2
Installation Guide 115
8 Run API Management in Docker containers
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, Amazon Web Services, or Microsoft Azure.
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/
l https://azure.microsoft.com
Further details
For more details on Docker, see the following:
l https://docs.docker.com/engine/understanding-docker/
l https://docs.docker.com/engine/installation/linux/
Axway API Gateway 7.5.2
Installation Guide 116
Update API Gateway
9
This section describes how to apply service packs or patches to API Gateway components.
Install a service pack
This section describes how to install a service pack on an existing installation of API Gateway.
To install a service pack, 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 the API Gateway Administrator Guide.
3. Download the service pack 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. A service pack contains new binaries only and does not overwrite the existing configuration.
6. Restart the Node Managers and API Gateway servers.
Axway API Gateway 7.5.2
Installation Guide 117
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.2
Installation Guide 118
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