API Gateway Version November Installation Guide

Transcription

1 API Gateway Version November 2017 Installation Guide

2 Copyright 2017 Axway All rights reserved. This documentation describes the following Axway software: Axway API Gateway 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.

3 Contents Preface 9 Who should read this guide 9 How to use this guide 9 API Management documentation set 10 API Gateway documentation 10 API Manager and API Portal documentation 11 Related documentation 11 Support services 12 Training services 12 Accessibility 13 Screen reader support 13 Support for high contrast and accessible use of colors 13 Updates and revisions 14 Changes in Quick start installation 15 Before you begin 15 Installation 15 Post-installation 16 2 Prerequisites 17 System requirements 17 Operating systems and hardware 17 Databases 19 Web browsers 19 Thick client platforms 19 Docker containers 20 Specific component requirements 20 Default ports 21 API Gateway 21 Admin Node Manager 21 Policy Studio 21 API Gateway Manager 21 API Manager 21 API Gateway Analytics 22 Software and license keys 22 Check your authorization 22 Axway API Gateway Installation Guide 3

4 License keys 22 Multiple installations 23 Additional prerequisites 23 UNIX/Linux platforms 23 Service packs 24 Certificates 24 3 Plan the deployment 25 Platforms 25 API Gateway components 25 Client components 25 High availability 25 Connection to other products 26 4 Install API Gateway 27 Prerequisites 27 Installation modes 27 Start installation 28 Installation options 28 Welcome 28 License agreement 28 Select setup type 28 Select components 29 Specify installation directory 29 Specify license file 30 Cassandra configuration 30 Set the administrator user name and password 30 Specify QuickStart Node Manager details 31 Specify QuickStart server details 31 Set the administrator user name and password for API Manager 31 Acknowledge API Gateway Analytics information 32 Installation summary 32 Installing 32 Installation complete 32 Unattended installation 32 Run the installer in unattended mode 33 Unattended mode options 34 5 Install Apache Cassandra 37 Install an Apache Cassandra database 37 Prerequisites 38 Install Apache Cassandra 39 Further details 40 Cassandra deployment architectures 40 Axway API Gateway Installation Guide 4

5 Cassandra in standalone mode 41 Cassandra in High Availability mode 42 Configure a Cassandra HA cluster 45 Cassandra HA in a production environment 45 Upgrade from previous API Gateway version 46 Cassandra HA configuration 46 Example Cassandra HA configuration in a production environment 47 Step 1 Configure and verify the Cassandra HA cluster (non-secure) 50 Step 2 Configure the client settings for API Gateway or API Manager 54 Step 3 Secure the Cassandra HA configuration and verify 58 Automate API Gateway Cassandra client settings 58 Further details 59 Manage Apache Cassandra on UNIX/Linux and Windows 59 Manage Apache Cassandra on UNIX/Linux 59 Manage Apache Cassandra on Windows 61 Connect to API Gateway for the first time 63 Further details 64 Perform essential Cassandra operations 64 Perform anti-entropy repair 64 Replace dead nodes 65 Back up and restore Cassandra data 65 Back up configuration and data for disaster recovery 65 Ensure time is in sync across the cluster 66 Reconfigure an existing Cassandra installation from scratch 67 Monitor the Cassandra cluster using JMX 67 Upgrade your Cassandra version 67 Further details 67 setup-cassandra script reference 67 Prerequisites 68 Run the setup-cassandra script 69 Configure the seed node 70 Configure additional nodes 70 Secure Cassandra HA configuration 71 Updated Cassandra configuration 73 6 Install API Gateway components 75 Install the API Gateway server 75 Prerequisites 75 Install the API Gateway server 76 Before you start API Gateway 76 Start API Gateway 76 Install the QuickStart tutorial 77 Prerequisites 77 Install the QuickStart tutorial 78 Axway API Gateway Installation Guide 5

6 QuickStart domain configuration 78 Start the QuickStart tutorial 78 Restart the QuickStart tutorial 79 Install the Admin Node Manager 80 Prerequisites 80 Install the Admin Node Manager 80 Start the Admin Node Manager 81 Install Policy Studio 81 Prerequisites 81 Install Policy Studio 81 Start Policy Studio 81 Install Configuration Studio 82 Prerequisites 82 Install Configuration Studio 82 Start Configuration Studio 83 Install API Tester 83 Prerequisites 83 Install API Tester 83 Start API Tester 84 Install API Manager 84 Prerequisites 84 Install API Manager 85 Configure API Manager 86 Start API Manager 86 Install the Package and Deploy tools 86 Prerequisites 86 Install the Package and Deploy tools 87 7 Install and configure API Gateway Analytics 88 Install API Gateway Analytics 88 Prerequisites 88 Install API Gateway Analytics 88 Configure your API Gateway Analytics database 89 Start API Gateway Analytics 89 Further information 90 Configure the metrics database 90 Prerequisites 90 Add third-party JDBC driver files 91 Create the database 92 Set up the database tables 92 Specify options to dbsetup 93 SQL database schema scripts 95 Configure API Gateway Analytics 95 Prerequisites 95 Axway API Gateway Installation Guide 6

7 Update API Gateway Analytics configuration 96 Enable metrics for your API Gateway host 99 8 Post-installation 101 Verify the installation 101 Check the installation log 101 Start API Gateway components 101 Log in to the API Gateway tools 102 Initial configuration 102 Create a new domain 102 Set up a database for API Gateway Analytics 102 Secure API Gateway 103 Change default passwords 103 Change default certificates 103 Encrypt API Gateway configuration 103 Run as non-root on UNIX/Linux 103 Set up services 103 API Gateway 103 API Gateway Analytics 104 Apache Cassandra 104 Set up clustering 105 Next steps Configure API Management in multiple datacenters 106 Multi-datacenter deployment 106 Multi-datacenter deployment architecture 106 API Management data storage 108 Further details 109 Multi-datacenter configuration 109 API Management configuration 110 Configure Cassandra for multiple datacenters 111 Configure API Management in multiple datacenters 116 Optimize API Management performance in a multi-center environment 121 Configure Ehcache in multiple datacenters 123 Configure API Manager quota in multiple datacenters 127 Further details 127 Multi-datacenter failover scenarios 127 One API Gateway instance is down 128 One Cassandra node is down 128 A full datacenter is down 129 The network between both datacenters is down 131 Further details 132 Axway API Gateway Installation Guide 7

8 10 Run API Management in Docker 133 API Management in Docker containers 134 Create Docker images using scripts 134 Run pre-built Docker images 135 API Management Docker HA topology 135 Deploy your Docker infrastructure to the cloud 137 Further information on Docker 137 Run pre-built API Management Docker images 137 Prerequisites 137 Run pre-built API Management images in a developement or test environment 138 Test the API Management system 138 Generate API Management Docker images 139 Set up your local environment 139 Create your API Management Docker infrastructure 140 Troubleshooting 144 Customize your API Management topology in Docker 144 Create Docker data volumes for persistence 144 Delete data volumes 151 Test your API Management system Update API Gateway 153 Install a service pack or patch 153 Resolve patch validation issues 153 Cannot validate, no checksum available 154 Content changed 154 File not found 155 Malformed file 155 Unexpected file 155 Verify which hosts have service packs or patches installed 156 License acknowledgments 157 Overview 157 Acknowledgments 157 Axway API Gateway Installation Guide 8

9 Preface This guide describes how to install API Gateway components on all supported platforms. Who should read this guide The intended audience for this guide is system engineers who are responsible for installing, configuring, and maintaining API Gateway. Before installing API Gateway you should have an understanding of API Gateway concepts and features. For more information, see the API Gateway Concepts Guide. Others who might find parts of this guide useful include network or systems administrators and other technical or business users. How to use this guide This guide should be used in conjunction with the other guides in the API Gateway documentation set. Before you begin installing API Gateway, review this guide thoroughly. The following is a brief description of the contents of each section: Quick start installation on page 15 Enables you to install quickly using standard settings. Plan the deployment on page 25 Describes what you should consider when planning for deploying and configuring your system architecture. Prerequisites on page 17 Describes the prerequisites for installing, including the system requirements. Install API Gateway on page 27 Describes how to perform an installation using the GUI mode or unattended command-line mode. Install API Gateway components on page 75 Describes how to install the API Gateway components. Post-installation on page 101 Provides instructions on how to check if the installation was successful and describes additional tasks, such as securing API Gateway, that you should perform after installation. Run API Gateway in Docker containers Describes how to build and run a sample multi-node API Gateway system in Docker, and how to customize this recommended API Gateway topology to suit your environment. Update API Gateway on page 153 Describes how to apply service packs or patches to update your API Gateway installation. Axway API Gateway Installation Guide 9

10 Preface API Management documentation set API Gateway documentation The API Gateway documentation set includes the following guides: API Gateway Installation Guide Describes how to install API Gateway components on all platforms. API Gateway Upgrade Guide Describes how to upgrade previous API Gateway versions. API Gateway Concepts Guide Provides an overview of the API Gateway components, tools, and architecture. API Gateway Administrator Guide Describes how to configure and manage an API Gateway domain. API Gateway Policy Developer Guide Describes the main API Gateway features and how to configure them using the Policy Studio graphical tool. API Gateway Policy Developer Filter Reference Describes the filters that you can use when developing policies in Policy Studio, and how to configure them. API Gateway DevOps Deployment Guide Describes how to promote and deploy API Gateway configuration between different environments (for example, development, testing, and production). API Gateway OAuth User Guide Describes how to configure API Gateway for OAuth 2.0 and OpenID Connect. API Gateway Developer Guide Describes how to extend, leverage, and customize API Gateway. 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. API Gateway Appliance Installation and Administration Guide Describes how to install, configure, and administer the API Gateway Appliance. API Gateway Kerberos Integration Guide Describes how to integrate API Gateway with Kerberos SPNEGO authentication. API Gateway Authentication and Authorization Integration Guide Describes how to integrate API Gateway with Identity Management systems (for example, LDAP servers, CA Siteminder, and so on). Axway API Gateway Installation Guide 10

11 Preface API Gateway PassPort Interoperability Guide Describes how to configure API Gateway and Axway PassPort to work together. API Gateway Sentinel Interoperability Guide Describes how to configure API Gateway and Axway Sentinel to work together. 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: API Manager User Guide Describes how to use the API management features available separately in API Manager. API Manager is an additional licensable layered product running on API Gateway. API Portal Installation and Upgrade Guide Describes how to install or upgrade API Portal. API Portal is an additional layered product running on API Gateway. API Portal Administrator Guide Describes how to customize and manage API Portal. API Portal User Guide Describes how to use API Portal. Related documentation The API Management Plus solution enables you to create, publish, promote, and manage Application Programming Interfaces (APIs) in a secure and scalable environment. For more information, see the API Management Plus Getting Started Guide. The following reference documents are available on the Axway Documentation portal at Supported Platforms Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product. Interoperability Matrix Provides product version and interoperability information for Axway products. Axway API Gateway Installation Guide 11

12 Preface Support services The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements. support@axway.com or visit Axway Support at See "Get help with API Gateway" in the API Gateway Administrator Guide for the information that you should be prepared to provide when you contact Axway Support. Training services Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: Axway API Gateway Installation Guide 12

13 Accessibility Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features: Screen reader support on page 13 Support for high contrast and accessible use of colors on page 13 Screen reader support Alternative text is provided for images whenever necessary. The PDF documents are tagged to provide a logical reading order. Support for high contrast and accessible use of colors The documentation can be used in high-contrast mode. There is sufficient contrast between the text and the background color. The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway API Gateway Installation Guide 13

14 Updates and revisions Updates and revisions This guide includes the following documentation changes. Changes in Updated the system requirements with the latest details on supported versions. Added new topics on configuring API Management in multiple datacenters: o o o Multi-datacenter deployment architecture Multi-datacenter configuration Multi-datacenter failover scenarios Updated the Apache Cassandra topics with support for Cassandra version and the native Datastax client (replacing the Hector client used in previous versions). The section on upgrading from Cassandra version to Cassandra has moved from the topic on installing Cassandra to the API Gateway Upgrade Guide. Updated the topic on the setup-cassandra script with automatic backup of cassandra.yaml, and for use with remote Cassandra deployments. Restructured the Cassandra topics, adding separate new topics for: o o Cassandra deployment architecture Manage Cassandra on UNIX/Linux and Windows Restructured the topic on Docker containers, adding separate new topics for: o o o o Docker deployment architecture Run pre-built Docker images (for development and test only) Generate Docker images for HA production environments Customize your API Management Docker environment Updated the post-installation topic with details on running API Gateway Analytics as a service on Windows. Updated the topic on API Gateway Analytics configuration with clarification on the characters supported by the username and password provided to the configureserver script. Updated the topic on system requirements with support for the MariaDB database. Axway API Gateway Installation Guide 14

15 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: API Gateway Server QuickStart Tutorial API Gateway Analytics Policy Studio Configuration Studio Package and deployment tools The Standard option also installs an external Apache Cassandra database, which is used to store API Gateway and API Manager data. For more details, see Installation options on page 28. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Before you begin In preparation for a quick start installation, perform the following tasks: 1. Check that your target system meets the system requirements. For more details, see Prerequisites on page Download the installation setup file for your target system. 3. Obtain the necessary license keys from your Axway Account Manager. Installation Locate and run the installation setup file. The installer launches in GUI mode by default. Follow the instructions on each window, accepting the default selections at each step. For more information on starting the installer, see Start installation on page 28. When installation is complete, the Cassandra database, API Gateway instance, and Admin Node Manager processes are started, the QuickStart tutorial is launched in a browser window, and the Policy Studio desktop tool is started. Axway API Gateway Installation Guide 15

16 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 Installation Guide 16

17 Prerequisites 2 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: System requirements on page 17 Default ports on page 21 Software and license keys on page 22 Additional prerequisites on page 23 System requirements This section describes the supported platforms and other system requirements for Axway API Gateway, and specific requirements for API Gateway components. For more details on API Gateway components, see the API Gateway Concepts Guide. This section describes the requirements for specific API Gateway components (for example, Policy 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 CentOS 6.x, 7.x Oracle Linux 6.x, 7.x Red Hat Enterprise Linux 6.x, 7.x SUSE Linux Enterprise Server 11.x, 12.x Supports 64-bit Linux running on 64-bit hardware Intel Core or AMD Opteron at 2Ghz with Dual Core or faster API Gateway might not run on systems that do not meet these requirements (see below). Axway API Gateway Installation Guide 17

18 2 Prerequisites Platform Supported versions Hardware prerequisites Windows Windows Server 2012 R2 Windows Server 2012 Windows 10 Windows 8.1 Windows Server 2012 R2 is recommended in a production environment. Supports 32-bit Windows on both 32-bit hardware and 64- bit hardware Intel Core or AMD Opteron at 2Ghz with Dual Core or faster 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: Disk space: o Minimum 4 GB, 50 GB recommended on Windows and Linux Physical memory: o o Minimum 4 GB on Windows Minimum 8 GB on Linux UNIX/Linux permissions UNIX/Linux platforms also require the following: Minimum 500 MB available in the /tmp directory and writable permissions on the /tmp, /var/tmp, and /usr/tmp directories. noexec must not be set on /tmp. If noexec is set, you must remount /tmp with noexec disabled. Axway API Gateway Installation Guide 18

19 2 Prerequisites Databases This section describes the supported database versions. Relational databases API Gateway Analytics and API Manager support the following relational databases to store metrics data: MySQL Server 5.6, 5.7 MariaDB 5.5, 10.1 Microsoft SQL Server 2012, 2014 Oracle 11.2, 12.1 IBM DB For more details, see Install API Gateway Analytics on page 88. Apache Cassandra API Gateway and API Manager support Apache Cassandra version and for internal data storage. For more details, see Install an Apache Cassandra database on page 37. Web browsers API Gateway Manager and other browser-based client components support the following browsers: Internet Explorer 11 Firefox 13.0 or higher Safari or higher Google Chrome 19 or higher 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: X-Windows environment GTK+ 2 Axway API Gateway Installation Guide 19

20 2 Prerequisites Docker containers The following components support Docker version 1.13: API Manager API Gateway This applies to the API Gateway instance, Admin Node Manager, and Node Manager only. API Gateway Analytics does not support Docker. Axway supports CentOS Linux version 7 only as the base image for Docker containers, and supports deployment on any host operating system or cloud provider supported by Docker version 1.13.x. For more details, see API Management in Docker containers on page 134. Specific component requirements This section describes requirements for specific API Gateway components. Component Policy Studio API Gateway Manager API Gateway Analytics API Manager Requirements Policy Studio is a thick client and supports the platforms described in Thick client platforms on page 19. API Gateway Manager is a web-based client and supports the web browsers listed in Web browsers on page 19. The API Gateway Analytics server component has the same operating system and hardware requirements as API Gateway. See Operating systems and hardware on page 17. API Gateway Analytics requires a database. For database requirements, see Databases on page 19. The browser-based client component supports the same browsers as API Gateway Manager. See Web browsers on page 19. API Manager is a browser-based client and supports the same browsers as API Gateway Manager. See Web browsers on page 19. Axway API Gateway Installation Guide 20

21 2 Prerequisites Default ports This section describes the default ports used by API Gateway components. API Gateway The default ports used by API Gateway are as follows: Traffic port: 8080 (between clients and API Gateway) Management port: 8085 (between API Gateway and Admin Node Manager) Admin Node Manager The default port used by the Admin Node Manager for monitoring and management of API Gateway instances is Policy Studio The default URL address used by the Policy Studio tool to connect to the Admin Node Manager is as follows: 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: API Manager The default URL address used by the API Manager web console for API management is as follows: Axway API Gateway Installation Guide 21

22 2 Prerequisites API Gateway Analytics The default port used by API Gateway Analytics for reporting, monitoring, and management is The default URL address used by the API Gateway Analytics web console is as follows: Software and license keys Axway products are delivered electronically from Axway Support at the Axway support website. A welcome 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 5. Install products. Check your authorization Verify that you can access Axway Support at by going to and logging in. If you do not have an account, follow the instructions in your welcome . Log in to download or access: The product installation package Product documentation Product updates, including patches and service packs Product announcements The support case center, to open a new case or to track opened cases You can also access other resources, such as articles in the Knowledge Base, the Axway User Forum, and documentation for all Axway products. License keys API Gateway requires the following license keys. Axway API Gateway Installation Guide 22

23 2 Prerequisites Axway license file You must have a valid Axway license file to install the following API Gateway components: API Gateway Server API Gateway Analytics API Manager You can obtain an evaluation trial license to enable you to evaluate the API Gateway features. However, you must have a full license to enable all API Gateway features for use in a non-evaluation environment (for example, development, testing, or production). To obtain an evaluation trial license or a full license, contact your Axway Account Manager. You can install an Admin Node Manager in isolation without an API Gateway license. For more information, see Install the Admin Node Manager on page 80. McAfee license file You must have a valid McAfee license file to use the McAfee Anti-Virus filter. FIPS-compliant mode license file You must have a valid Axway FIPS-compliant mode license file to run API Gateway in FIPS-compliant mode. Multiple installations API Gateway requires a minimum of two installations for high availability (HA). Make sure that you obtain license keys for all of the API Gateway instances that you are installing. Additional prerequisites This section lists additional prerequisites for installing API Gateway. UNIX/Linux platforms The following prerequisites apply when installing API Gateway on UNIX/Linux platforms. Executable permission On UNIX/Linux, you must ensure that the installation executable has the appropriate permissions in your environment. For example, you can use the chmod command to update the file permissions. Axway API Gateway Installation Guide 23

24 2 Prerequisites Service packs Service packs for API Gateway are available from Axway Support at If any service packs are available for API Gateway 7.5.3, download and apply them when the installation completes. For more information on applying a service pack, see Update API Gateway on page 153. Certificates API Gateway uses Secure Sockets Layer (SSL) for communications between all processes in a domain (for example, internal management traffic between the Admin Node Manager and API Gateway instances). Certificates are not required during installation; however, certificates will be required after installation to secure API Gateway domains. For more information on configuring and securing API Gateway domains, see the API Gateway Administrator Guide. Axway API Gateway Installation Guide 24

25 Plan the deployment 3 This topic discusses how to plan your deployment. For more information on planning an API Gateway system, and how API Gateway interacts with existing infrastructure, see the API Gateway Administrator Guide. Platforms For more information on the exact platforms that Axway supports for API Gateway, see System requirements on page 17. API Gateway components Before installing API Gateway you need to consider which components you require. Some components, for example, API Gateway Analytics, have additional requirements, such as a database. For more information, see Specific component requirements on page 20. For more information on API Gateway components, see the API Gateway Concepts Guide. Client components API Gateway includes the Policy Studio developer tool, a thick client that is supported on UNIX/Linux and Windows. It also includes several web-based tools (for example, API Gateway Manager and API Gateway Analytics). For more details on supported thick client platforms and supported web browsers, see Web browsers on page 19 and Thick client platforms on page 19. High availability The following components have specific requirements for high availability (HA): API Gateway HA For resilient API Gateway and API Manager HA configuration, a minimum of at least two API Gateway instances is required. For details on configuring API Gateway high availability, see the API Gateway Administrator Guide. Axway API Gateway Installation Guide 25

26 3 Plan the deployment Apache Cassandra HA In addition, the Apache Cassandra database is required to store data for the API Manager component. You can also use Cassandra to store data for API Gateway components such as the Key Property Store, OAuth, and API keys. For Cassandra HA configuration, a minimum of three Cassandra nodes is required. For more details, see Install Apache Cassandra on page 37. Multiple datacenters For details on how to configure different types of API Gateway and API Manager data in a multidatacenter environment, see Configure API Management in multiple datacenters on page 106. Connection to other products API Gateway supports integration with a wide range of Axway products (for example, Axway PassPort) and third-party products (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 (login required). For more details on the versions of Axway products that API Gateway interoperates with, see the following: API Gateway PassPort Interoperability Guide API Gateway Sentinel Interoperability Guide API Gateway Validation Authority Interoperability Guide All of these guides are available on Axway Support at Axway API Gateway Installation Guide 26

27 Install API Gateway 4 This section describes how to use the API Gateway installer. The installer is supported on the following platforms: Windows UNIX/Linux Prerequisites You have downloaded the installation setup file for your target operating system from Axway Support at The download instructions are in the welcome letter that Axway sent you in an message. 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. You have obtained a valid McAfee license file if you intend to use the McAfee Anti-Virus filter. You have reviewed the prerequisites and system requirements in Prerequisites on page 17 and have ensured that your target system is suitable. Installation modes The API Gateway installer has the following installation modes: GUI mode 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: Start installation on page 28 Installation options on page 28 The following section describes how to start the installer in unattended mode and the command-line options for the unattended mode: Unattended installation on page 32 Axway API Gateway Installation Guide 27

28 4 Install API Gateway Start installation To run the API Gateway installer in the default GUI mode, locate and run the setup file for your operating system. For example: Windows APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe Linux APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run Follow the instructions on each window to complete the installation. For more information on the options available during GUI mode installation, see Installation options on page 28. Tip To run the setup in unattended mode, see Unattended installation on page 32. Installation options When you run the installation setup file it launches in GUI mode by default. The following sections detail the installation options in GUI mode. Welcome When you run the setup file in GUI mode, you are presented with an introductory welcome window. Click Next to continue with the installation. License agreement Read the Axway standard license terms, and click I accept the agreement to accept the terms. You cannot proceed with the installation until you make a selection. If you click I do not accept the agreement, the installer exits. Click Next to continue. Select setup type You can install API Gateway using the following setup types: Axway API Gateway Installation Guide 28

29 4 Install API Gateway Standard Complete Custom 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. 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. 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. The API Tester component is deprecated, and is only installed in a Custom setup. For more details, see Install API Tester on page 83. QuickStart tutorial The Standard and Complete setup types install the QuickStart tutorial by default, or you can select to install it during the Custom setup type. This installs a preconfigured domain and API Gateway instance. If you do not install the QuickStart tutorial, you must configure a domain and API Gateway instance when the installation is complete. For more details, see Initial configuration on page 102. Click Next to continue. Select components This window is only displayed during an Custom installation. Select the components to be installed, and deselect those that are not to be installed. The following components are selected by default: API Gateway Server Admin Node Manager 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 Installation Guide 29

30 4 Install API Gateway Windows C:\Axway UNIX/Linux /opt/axway 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. 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: Installation Directory: Enter the directory in which to install the Cassandra server (for example: /opt/db/cassandra or C:\cassandra). JRE Location: Enter the directory of the Oracle Java Runtime Environment used by Cassandra. Defaults to the Oracle JRE provided by API Gateway: o o UNIX/Linux: INSTALL_DIR/apigateway/Linux.x86_64/jre/bin Windows: INSTALL_DIR\apigateway\Win32\jre OpenJDK is not supported. In a production system, it is recommended to use a 64-bit Oracle JRE with Cassandra. For more details, see Install an Apache Cassandra database on page 37. Set the administrator user name and password It is important to secure your API Gateway system to protect it from internal and external threats. This window enables you to set the administrator user name and password. This administrator account is used to log in to Policy Studio and API Gateway Manager. These administrator credentials are also used by managedomain when connecting to an Admin Node Manager. Select the check box to set the user name and password for the administrator account and enter a user name and password in the fields. Axway API Gateway Installation Guide 30

31 4 Install API Gateway Caution Ensure that you remember these credentials or you will not be able to log in to Policy Studio or API Gateway Manager. This option is selected by default, to ensure that you set your own administrator user name and password. To use a default administrator user name and password, you must deselect the check box. The default credentials are available from your Axway Account Manager. Click Next to continue. Specify QuickStart Node Manager details This window is only displayed if you selected to install the QuickStart tutorial. Configure the following settings for the Node Manager: Host Name or IP Address: Select a host address from the list (defaults to the installation host name). Local Management Port: Enter the local port used to manage the Node Manager. Defaults to 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: Local Management Port: Enter the local port that the Node Manager uses to manage the API Gateway instance. Defaults to External Traffic Port: Enter the port that the API Gateway uses for message traffic from external clients. Defaults to Click Next to continue. Set the administrator user name and password for API Manager It is important to secure your API Manager system to protect it from internal and external threats. This window enables you to set the API administrator user name and password. This administrator account is used to log in to the API Manager web console. Select the check box to set the user name and password for the API administrator account and enter a user name and password in the fields. Axway API Gateway Installation Guide 31

32 4 Install API Gateway Caution Ensure that you remember these credentials or you will not be able to log in to API Manager. This option is selected by default, to ensure that you set your own API administrator user name and password. To use a default API administrator user name and password, you must deselect the check box. The default credentials are available from your Axway Account Manager. Click Next to continue. Acknowledge API Gateway Analytics information This window is only displayed if you selected to install API Gateway Analytics. An information window is displayed to remind you that you must perform additional steps before you start API Gateway Analytics. Review the information and click Next to continue. Installation summary The installer displays a summary of the components that will be installed on your system. Review the information and click Next to begin installing. Installing A progress window is displayed showing the progress of the installation. When the installation is complete, click Next to continue. Installation complete A window is displayed to indicate that the installation is complete. If you selected to install Policy Studio you can select the option to Launch Axway Policy Studio. The URL of the Admin Node Manager is displayed (for example, 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 Installation Guide 32

33 4 Install API Gateway Run the installer in unattended mode You can run the API Gateway installer in unattended mode on the command line. Perform the following steps: 1. Change to the directory where the setup file is located. 2. Run the setup file with the --mode unattended option. Standard setup without API Manager The following example shows how to install all API Gateway components (excluding API Manager) in unattended mode: UNIX/Linux./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended --setup_type standard --licensefilepath mylicense.lic --analyticslicensefilepath myanalyticslicense.lic --prefix /opt/axway cassandrainstalldir opt/db/cassandra --cassandrajdk opt/jre --startcassandra 1 Windows APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe --mode unattended --setup_type standard --licensefilepath mylicense.lic --analyticslicensefilepath myanalyticslicense.lic --prefix C:\Axway cassandrainstalldir c:\cassandra --cassandrajdk c:\jre --startcassandra 1 Axway API Gateway Installation Guide 33

34 4 Install API Gateway Complete setup with API Manager The following example shows how to install all API Gateway components, including API Manager, in unattended mode: UNIX/Linux./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended --setup_type complete --licensefilepath mylicense.lic --analyticslicensefilepath myanalyticslicense.lic --apimgmtlicensefilepath mymgmtlicense.lic --prefix /opt/axway cassandrainstalldir /opt/db/cassandra --cassandrajdk /opt/jre --startcassandra 1 Windows APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe --mode unattended --setup_type complete --licensefilepath mylicense.lic --analyticslicensefilepath myanalyticslicense.lic --apimgmtlicensefilepath mymgmtlicense.lic --prefix C:\Axway cassandrainstalldir c:\cassandra --cassandrajdk c:\jre --startcassandra 1 The components are installed in the background, in the directory specified by the --prefix option. Custom setup The topics on installing each API Gateway component show how to use the --setup_type advanced option to install a custom setup in unattended mode. For example, see Install the API Gateway server on page 75. Unattended mode options For a description of all the available command-line options and their default settings, run the setup file with the --help option. This outputs the help text in a separate console. For example: Axway API Gateway Installation Guide 34

35 4 Install API Gateway UNIX/Linux./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --help Windows APIGateway_7.5.3_Install_win-x86-32_BN<n>.exe --help The following table summarizes some of the more common options: Option --help Description Display available options and default settings. --mode Specify an installation mode. --setup_type --enable-components Specify a setup type (standard, complete, or advanced) Specify a comma-separated list of components to enable. --disable-components --prefix Specify a comma-separated list of components to disable. Specify an API Gateway installation directory. --licensefilepath Specify the path to a license file. --apimgmtlicensefilepath Specify the path to an API Manager license file. -- analyticslicensefilepath Specify the path to an API Gateway Analytics license file. --unattendedmodeui --cassandrainstalldir Specify different levels of user interaction when installing on Windows or on a UNIX/Linux system with X-Windows. Specify the Apache Cassandra installation directory. For example, opt/db/cassandra on UNIX/Linux, or c:\cassandra on Windows. Axway API Gateway Installation Guide 35

36 4 Install API Gateway Option --cassandrajdk Description Specify the location of your Oracle Java Runtime Environment for Apache Cassandra. For example, opt/jre on UNIX/Linux, or c:\jre on Windows. The default values are : UNIX/Linux: INSTALL_ DIR/apigateway/Linux.x86_ 64/jre/bin Windows: INSTALL_ DIR\apigateway\Win32\jre OpenJDK is not supported. --startcassandra --optionfile 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. Specify options in a properties file. For more information on option files, go to: Axway API Gateway Installation Guide 36

37 Install Apache Cassandra 5 This topic describes how to use the API Gateway installer to install the Apache Cassandra database, and how to configure and manage a multi-node Cassandra cluster for high availability. Cassandra is required for API Manager and optional for some API Gateway components (for example, OAuth, API keys, and custom KPS). This topic includes the following: Install an Apache Cassandra database on page 37 Cassandra deployment architectures on page 40 Configure a Cassandra HA cluster on page 45 Manage Apache Cassandra on UNIX/Linux and Windows on page 59 Perform essential Cassandra operations on page 64 setup-cassandra script reference on page 67 Install an Apache Cassandra database Apache Cassandra is required to store data for API Manager (for example, API catalog, quotas, and client registry) or API Gateway client registry (API key and OAuth). In addition, Cassandra is optional to store data for the following API Gateway components: Custom KPS table definitions and data OAuth token stores 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 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 and For more details on Apache Cassandra, see Cassandra is the recommended version. Cassandra is supported by API Gateway for backwards compatibility. For details on upgrading your Cassandra version, see "Upgrade from Apache Cassandra version to version 2.2.8" in the API Gateway Upgrade Guide. Axway API Gateway Installation Guide 37

38 5 Install Apache Cassandra Upgrade from earlier API Gateway versions API Gateway version includes the Datastax Cassandra client, which uses a default port of 9042 to communicate with Cassandra over the Cassandra native protocol. Earlier API Gateway versions included the Hector Cassandra client, which used a default port of 9160 to communicate with Cassandra over the Apache Thrift protocol. In API Gateway version or later, Cassandra runs externally to the API Gateway process. In earlier API Gateway versions, Cassandra was embedded in the API Gateway process. For details on upgrading from an earlier API Gateway version, see the API Gateway Upgrade Guide. Prerequisites This section describes Cassandra-specific prerequisites in addition to the general API Gateway Prerequisites on page 17. Production environment requirements API Gateway supports the following in production: Operating systems: o All supported Linux platforms (see System requirements on page 17) o Windows 2012 Server only Cassandra: o o Cassandra version or on Linux and Windows 64-bit Oracle JRE version 8 on Linux and Windows (OpenJDK is not supported) On Linux, the default API Gateway installation includes a 64-bit Oracle JRE (apigateway/linux.x86_64/jre/bin). On Windows, API Gateway includes a 32-bit Oracle JRE (apigateway\win32\jre), which is suitable for development only. In a Windows production environment, you must download and install a 64-bit Oracle JRE manually. For more details, see Install a 64-bit Oracle JRE on Windows on page 38. For details on requirements for high availability, see HA production environment requirements on page 47. Install a 64-bit Oracle JRE on Windows The default 32-bit Oracle JRE bundled with API Gateway on Windows limits the memory available to Cassandra on 64-bit systems, and cannot run Cassandra as a Windows service. In a production environment, you must download and install a separate 64-bit Oracle JRE. Axway API Gateway Installation Guide 38

39 5 Install Apache Cassandra If you select the default 32-bit Oracle JRE bundled with API Gateway, and later decide to switch to a 64-bit Oracle JRE, you must edit your CASSANDRA_ HOME\bin\cassandra.in.bat script, and change the JAVA_HOME variable at the top of the file to point to the new Oracle JRE. For example: SET JAVA_HOME=C:\Program Files\Java\jre8 JCE policies for Cassandra TLS/SSL If client TLS/SSL will be enabled for Cassandra, you must install the Java Cryptographic Extension (JCE) policies for your Oracle JRE. For example, you can download the Java 8 JCE policies from: Install Apache Cassandra Apache Cassandra is installed by default in an API Gateway Standard or Complete setup. For more details, see in Installation options on page 28. Install Cassandra in GUI mode In GUI mode, to install Apache Cassandra only, use the steps described in Installation options on page 28 with the following selections: Setup Type: Select Custom. Select Components: Select Cassandra. Cassandra configuration: Enter your Cassandra Installation Directory and your JRE Location. For more details, see Cassandra configuration on page 30. Install Cassandra in unattended mode To install Apache Cassandra using the API Gateway installer in unattended mode, follow the steps described in Unattended installation on page 32. For example, the following command shows how to install Apache Cassandra only in unattended mode: UNIX/Linux./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended --setup_type advanced --enable-components cassandra --disable-components apigateway,analytics,qstart,policystudio, configurationstudio,apitester,apimgmt,packagedeploytools Axway API Gateway Installation Guide 39

40 5 Install Apache Cassandra --cassandrainstalldir /opt/db/cassandra --cassandrajdk /opt/jre --startcassandra 0 Windows./APIGateway_7.5.3_Install_linux-x86-32_BN<n>.run --mode unattended --setup_type advanced --enable-components cassandra --disable-components apigateway,analytics,qstart,policystudio, configurationstudio,apitester,apimgmt,packagedeploytools --cassandrainstalldir c:\cassandra --cassandrajdk c:\jre --startcassandra 0 To keep your Cassandra installation after API Gateway is uninstalled, you must ensure that you first install Cassandra only. For example, perform the following steps: 1. Run the API Gateway installer, and select Cassandra only. 2. Run the API Gateway installer, and select API Gateway components to install. Then when API Gateway is uninstalled, Cassandra remains installed. Further details For more details on Apache Cassandra, see the following: Cassandra deployment architectures This topic describes the Cassandra deployment architectures supported by API Gateway. The following table provides a summary: Deployment Description Use Standalone One API Gateway instance only. This is the default. Development environment Production environment with one API Gateway instance Axway API Gateway Installation Guide 40

41 5 Install Apache Cassandra Deployment Description Use High availability with local storage Multiple API Gateway instances in a group, each API Gateway instance on different hosts, with a Cassandra storage node local to each API Gateway host. Pre-production environment Production environment High availability with remote storage Multiple API Gateway instances in a group, each API Gateway instance on different hosts, with Cassandra storage nodes on remote hosts. Pre-production environment Production environment You can use one Cassandra cluster to store data from one or multiple API Gateway groups and one or multiple API Gateway domains. Your Cassandra topology does not need to match your API Gateway topology. Multiple API Gateway groups can also be deployed on the same host, each host running an API Gateway instance for each group. This applies to both local and remote storage. For details on hosting Cassandra in datacenters, see Configure API Management in multiple datacenters on page 106. Cassandra in standalone mode Cassandra is configured in non-ha standalone mode when deployed alongside a single API Gateway instance on the same host (for example, in a demonstration or development environment with one API Gateway instance). This is the default mode. To configure Cassandra in standalone mode, perform the following steps: 1. Ensure Cassandra is installed on the local node (along with API Gateway). For details, see Install an Apache Cassandra database on page Start Cassandra before starting API Gateway. For details, see Manage Apache Cassandra on UNIX/Linux and Windows on page Start API Gateway. For details, see Install the API Gateway server on page 75. The next steps depend on your installation setup type: In a Standard or Complete setup (which include the QuickStart tutorial), the default configuration attempts to connect to Cassandra running on localhost. In a Custom setup without the QuickStart tutorial, you must configure the connection in Policy Studio. For more details, see Connect to API Gateway for the first time on page 63. To use Cassandra with API Manager, run the setup-apimanager script (see Configure your API Manager settings on page 56). This is configured by default when API Manager is installed along with the QuickStart tutorial. Axway API Gateway Installation Guide 41

42 5 Install Apache Cassandra To use Cassandra with OAuth, run DeployOAuthConfig (see "Deploy OAuth configuration" in the API Gateway OAuth User Guide). The following diagram shows Cassandra in standalone mode with a default Standard setup: Cassandra in High Availability mode For both local and remote Cassandra HA, Cassandra runs on multiple hosts. This section describes both scenarios. HA with local storage In local Cassandra HA, Cassandra runs alongside API Gateway on the same host. This means that you do not need to provision separate host machines for Cassandra and API Gateway, or open ports in your firewall. However, the data will be stored in the DMZ. Local Cassandra HA enables minimum cost of ownership. The following diagram shows local Cassandra HA mode: Axway API Gateway Installation Guide 42

43 5 Install Apache Cassandra In this example, one of the Cassandra nodes runs without an API Gateway instance on the same host. This is because the minimum deployment architecture includes two API Gateway hosts and three Cassandra hosts. If you have three API Gateway instances, all Cassandra nodes are local. HA with remote storage In remote Cassandra HA, Cassandra runs on a different host from API Gateway. The main differences when installing and configuring remote Cassandra are: 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. You might need to open ports in the firewall to connect to Cassandra outside the DMZ. For more details, see Network requirements on page 49. You are not required to use the Cassandra component supplied by the API Gateway installer. You can configure the remote node using the setup-cassandra script supplied by the API Gateway installation. For more details, see setup-cassandra script reference on page 67. Alternatively, you can perform all necessary Cassandra configuration changes manually. 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 Installation Guide 43

44 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: Three Cassandra nodes in a single cluster. Three host machines with network addresses: ipa (seed node), ipb, and ipc. Replication factor of 3. Each node holds 100% of the data. Default values in cassandra.yaml for: o o o Server-server communication: listen_address set to IP address storage_port set to 7000 ssl_storage_port: 7001 (when TLS v1.2 is configured) Client-server communication: native_transport_port of 9042 JMX monitoring on localhost:7199 Axway API Gateway Installation Guide 44

45 5 Install Apache Cassandra ipa, ipb, and ipc are placeholders for real host machines on your network. You can specify IP addresses or host names. You must have at least one designated seed node. Seeds nodes are required at runtime when a node is added to the cluster. You can add more or change designation later. You can change the server-server port, but it must be the same across the cluster. 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: 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. 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. You can have any number of API Gateway instances (all running either locally or remote to Cassandra). However, you must have at least two API Gateway instances for HA. This also applies to API Manager. For more details on Cassandra HA configuration, see Configure a Cassandra HA cluster on page 45. Configure a Cassandra HA cluster This topic describes how to set up an Apache Cassandra database cluster for high availability of your API Gateway system. It describes the necessary configuration steps and provides examples from a production environment. Cassandra HA in a production environment To tolerate the loss of one Cassandra node and to ensure 100% data consistency, API Gateway requires the following cluster configuration in a HA production environment: Three Cassandra nodes (with one seed node) QUORUM consistency to ensure that you are reading from a quorum of Cassandra nodes (two) every time 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 Installation Guide 45

46 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). Eventual consistency is not supported in a production environment (due to a risk of stale and incomplete data). For more details, see Example Cassandra HA configuration in a production environment on page 47. For details on hosting Cassandra in datacenters, see Configure API Management in multiple datacenters on page 106. Upgrade from previous API Gateway version When upgrading from a previous API Gateway version, you need only one Cassandra node in the cluster to receive upgraded data. After upgrade, you can then add more nodes to this cluster to provide high availability (HA), and configure TLS security. For more details, see the API Gateway Upgrade Guide. Cassandra HA configuration Use the following tools to configure Cassandra and the API Gateway Cassandra client: Tool nodetool cqlsh setupcassandra Description Located in CASSANDRA_HOME/bin. This tool is required run most Cassandra administration operations. nodetool runs locally by default against a Cassandra node. 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). Located in GATEWAY_INSTALL_DIR/bin. This script helps with Cassandra configuration and updates the cassandra.yaml configuration file. You can edit this file manually, but this script saves time, helps prevent errors, and creates a backup of the original cassandra.yaml file.setupcassandra also outputs instructions for resetting the default user name and password. You can use this script when Cassandra installed locally or remote to API Gateway. For more details, see setup-cassandra script reference on page 67. Axway API Gateway Installation Guide 46

47 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 group keyspace and replication factor in Cassandra on page 50. The following general guidelines apply to configuring Cassandra HA: Decide on the number Cassandra nodes and the number of API Gateway nodes (local or remote). Axway recommends to configure a Cassandra HA cluster with three Cassandra nodes, and least two API Gateway instances (local or remote). For details, see Cassandra deployment architectures on page 40. Ensure Cassandra is installed on each Cassandra node. For more details, see Install an Apache Cassandra database on page 37. Configure Cassandra on each Cassandra node. You can configure automatically using the setup-cassandra script. Alternatively, you can configure manually by modifying cassandra.yaml. Example Cassandra HA configuration in a production environment on page 47 shows examples of both approaches. Ensure API Gateway is installed and configured on one API Gateway node (local or remote to Cassandra). For more details, see Install the API Gateway server on page 75. Configure the Cassandra client settings in Policy Studio for the API Gateway group. Example Cassandra HA configuration in a production environment on page 47 shows the steps for both API Gateway and API Manager clients. Install and configure API Gateway on additional nodes as necessary. For more details, see Install the API Gateway server on page 75. Example Cassandra HA configuration in a production environment This section describes an example Cassandra HA configuration supported by Axway in a production environment. 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 Installation Guide 47

48 5 Install Apache Cassandra Hardware requirements Nodes: Three Cassandra nodes (one seed node). IP address: One IP address per Cassandra node. Disk space and memory: Depend on how much data you plan to store and how often this data changes: o o o KPS data and API Manager data consume small amounts of data (mostly read configuration data), and should not be an issue. OAuth token use can be large, depending on the frequency of token generation and token time-to-live. Double the amount of estimated storage: Needed for Cassandra to perform automatic compaction of data. Storage: Cassandra is designed to run on commodity distributed drives. Storage Area Network (SAN) is not recommended or supported in a production environment. For more details, see the API Management Capacity Planning Guide (available when logged into the Axway documentation website). Software requirements API Gateway supports the following systems in production: Operating systems: o o All Linux platforms supported by API Gateway. For more details, see System requirements on page 17. Windows Server 2012 R2 is recommended. Cassandra: o 64-bit Cassandra version or with 64-bit Oracle JRE on Linux and Windows (OpenJDK is not supported). Cassandra is recommended. For more details, Supported Cassandra versions on page 37. You must download a 64-bit Oracle JRE manually on UNIX/Linux when Cassandra is remote to API Gateway. This also applies on Windows when Cassandra is remote or local (see Install a 64-bit Oracle JRE on Windows on page 38). Python: o cqlsh uses Python o nodetool uses Python 2.6 or 2.7 For more details, see Axway API Gateway Installation Guide 48

49 5 Install Apache Cassandra Network requirements All Cassandra nodes can connect to each other: o o Ensure you can ping from each node to each other node. Ensure that your firewall rules allow the necessary Cassandra ports for client and server connections. API Gateway clients connect to Cassandra over the Cassandra native protocol on port 9042 by default. Cassandra uses port 7000 by default for communication between Cassandra nodes (and port 7001 when TLS/SSL is configured). Use a time service such as NTP to ensure that time is in sync in the cluster. For more details, see Ensure time is in sync across the cluster on page 66. Earlier API Gateway versions used a default port of 9160 to communicate with Cassandra over the Apache Thrift protocol. This protocol is not supported in API Gateway version or later. However, if necessary, after upgrade, you can configure Cassandra and API Gateway to use port 9160 to communicate over the Cassandra native protocol. Start with one Cassandra seed node You must always start with one Cassandra node (non-ha). You can test API Gateway functionality and become familiar with Cassandra using one node, before growing the system for HA. When upgrading from previous API Gateway versions (with embedded Cassandra), you must upgrade to one node only. After upgrade, you can then grow the system for HA. You do not need to start with three nodes, or start from scratch to achieve HA. For more details on upgrade, see the API Gateway Upgrade Guide. Cassandra scales horizontally. This means that each node must have equal resources. Each node must run on the same hardware (CPU, disk, memory, and network) and on the same operating system. This is intentional so that nodes do not starve or out-compete other nodes, and so that you can easily add, remove and replace nodes, especially in cloud environments. For example, do not run some nodes with less or more memory than other nodes, or some nodes on Windows and some on Linux, or some nodes on SUSE Linux and some on CentOS Linux. Cassandra HA configuration steps The high-level approach to Cassandra HA configuration is as follows: 1. Configure and verify the Cassandra HA cluster (non-secured). 2. Configure the API Gateway or API Manager client and verify. 3. Secure the Cassandra HA configuration and verify. These steps are described in detail in the sections that follow. Axway API Gateway Installation Guide 49

50 5 Install Apache Cassandra Step 1 Configure and verify the Cassandra HA cluster (non-secure) This includes the following steps: 1. Connect API Gateway to Cassandra on page Configure the group keyspace and replication factor in Cassandra on page Configure the Cassandra seed node on page Add the seed node to the HA cluster on page Replicate and verify the Cassandra cluster on page 54 Connect API Gateway to Cassandra If you installed a Standard or Complete setup, Cassandra is installed on the same host, and listens on localhost by default. API Gateway runs on the same host and connects to Cassandra by default. If you installed a Custom setup, and did not select the Quickstart tutorial, see Install an Apache Cassandra database on page 37. Configure the group keyspace and replication factor in Cassandra If you have created a KPS collection or set up API Manager (which creates KPS collections), API Gateway creates a Cassandra keyspace and tables for data storage when it connects to a Cassandra node, if these do not exist. By default, the created Cassandra keyspace has a name in the form of xdomainid_groupid. This enables API Gateways in a group to share data and enables a single Cassandra cluster to host data from multiple API Gateway domains (for example, development, test, and staging). Configure the API Gateway keyspace and replication factor Initially, the keyspace has a default Replication Factor (RF) of 1. You must increase this for HA configuration. Perform the following steps: 1. Use cqlsh to verify that the keyspace has been created and to view its replication factor. For example: $./cqlsh ipa describe x _c70d_4996_83ad_339407e1117d_group_2; The following text is output at the start: Axway API Gateway Installation Guide 50

51 5 Install Apache Cassandra CREATE KEYSPACE x _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 x _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. You must repeat these steps for each API Gateway group. Configure the system_auth keyspace replication factor When Cassandra authentication is enabled, you must also replicate the system_auth keyspace so that API Gateway can communicate with the cluster (for example, if a node in the cluster goes down): ALTER KEYSPACE "system_auth" WITH REPLICATION = { 'class': 'SimpleStrategy', 'replication_factor': 3 }; QUIT For more details, see Secure Cassandra HA configuration on page 71. Configure the Cassandra seed node Perform the following steps on the Cassandra seed node (ipa in this example): 1. Update CASSANDRA_HOME/conf/cassandra.yaml manually or with the setupcassandra script. You must ensure that the following settings are set (where ipa is the IP address of the first node): seed_provider, parameters, seeds: ipa start_native_transport: true native_transport_port: 9042 listen_address: ipa rpc_address: ipa authenticator: org.apache.cassandra.auth.passwordauthenticator authorizer: org.apache.cassandra.auth.cassandraauthorizer For example, to set these with the setup-cassandra script: Axway API Gateway Installation Guide 51

52 5 Install Apache Cassandra setup-cassandra --seed --own-ip=ipa --nodes=3 --cassandra-config=config_ FILE 2. Restart Cassandra. For details, see Install an Apache Cassandra database on page 37. You must always start the seed node first. For example, use the following command: /opt/cassandra/bin/cassandra 3. To verify, run nodetool status. You should see the correct IP address output. One node only should be output. The default username/password is cassandra/cassandra. You must specify these credentials when running Cassandra tools such as cqlsh. For example :./cqlsh ipa -u cassandra -p cassandra Add the seed node to the HA cluster You now must add two more Cassandra nodes in turn. The steps are similar to configuring the seed node, except the seed is now the first node (ipa). You must first have at least one designated seed node. Seeds nodes are required at runtime when a node is added to the cluster. You can add more or change designation later. Configure the second Cassandra node (ipb) 1. On Cassandra node B, install Cassandra (see Install an Apache Cassandra database on page 37). Do not start it yet. 2. Edit cassandra.yaml manually or use the setup-cassandra script. You must ensure that the following settings are set (where ipb is the IP address of the second node): seed_provider, parameters, seeds: ipa start_native_transport: true native_transport_port: 9042 listen_address: ipb rpc_address: ipb authenticator: org.apache.cassandra.auth.passwordauthenticator authorizer: org.apache.cassandra.auth.cassandraauthorizer For example, to set these with the setup-cassandra script: Axway API Gateway Installation Guide 52

53 5 Install Apache Cassandra setup-cassandra --seed-ip=ipa --own-ip=ipb --cassandra-config=config_ FILE 3. Start Cassandra, for example: /opt/cassandra/bin/cassandra This node should join the cluster after obtaining information from the seed node. For more details, see Install an Apache Cassandra database on page To verify, run nodetool status. You should see two nodes reported with the correct IP addresses. Configure the third Cassandra node (ipc) 1. On Cassandra node C, install Cassandra (see Install an Apache Cassandra database on page 37). Do not start it yet. 2. Edit cassandra.yaml manually or use the setup-cassandra script. You must ensure that the following settings are set (where ipc is the IP address of the third node): seed_provider, parameters, seeds: ipa start_native_transport: true native_transport_port: 9042 listen_address: ipc rpc_address: ipc authenticator: org.apache.cassandra.auth.passwordauthenticator 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 To verify, run nodetool status. You should see three nodes reported with the correct IP addresses. Axway API Gateway Installation Guide 53

54 5 Install Apache Cassandra Replicate and verify the Cassandra cluster To replicate data correctly around the cluster after this cluster configuration change, go to each node in turn, and run nodetool repair. To verify, go to each node in turn, and run the following command for each group: nodetool status keyspace_name For example: nodetool status x _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 You need at least two API Gateways in a group for HA. Configure API Gateway Cassandra client settings To update the Cassandra client configuration for API Gateway, perform the following steps: Configure the API Gateway domain 1. Ensure API Gateway has been installed on the API Gateway 1 and API Gateway 2 nodes. For details, see Install the API Gateway server on page Ensure an API Gateway domain has been created on the API Gateway 1 node using managedomain. For more details, see "Configure an API Gateway domain" in the API Gateway Administrator Guide. Configure the API Gateway Cassandra client connection 1. In Policy Studio, open your API Gateway group configuration. 2. Select Server Settings > Cassandra > Authentication, and enter your Cassandra user name and password (both default to cassandra). 3. Select Server Settings > Cassandra > Hosts, and add an address for each Cassandra node in the cluster (ipa, ipb and ipc in this example). Axway API Gateway Installation Guide 54

55 5 Install Apache Cassandra Tip You can automate these steps by running the updatecassandrasettings.py script against a deployment package (.fed). For more details, see Automate API Gateway Cassandra client settings on page 58. Configure the API Gateway Cassandra consistency levels 1. Ensure that the API Server KPS collection has been created under Environment Configuration > Key Property Stores. This is required to configure Cassandra consistency levels, and is created automatically if you installed the Complete setup type (see Installation options on page 28). If you installed the Custom or Standard setup, run one of the following scripts to create the required KPS collections: DeployOAuthConfig (see "Deploy OAuth configuration" in the API Gateway OAuth User Guide) setup-apimanager (see Configure your API Manager settings on page 56) 2. Select Environment Configuration > Key Property Stores > API Server > Data Sources > Cassandra Storage, and click Edit. 3. In the Read Consistency Level and Write Consistency Level fields, select QUORUM: 4. Repeat this step for each KPS collection using Cassandra (for example, Key Property Stores > OAuth, or API Portal for API Manager). This also applies to any custom KPS collections that you have created. 5. If you are using OAuth and Cassandra, you must also configure quorum consistency for all OAuth2 stores under Libraries > OAuth2 Stores: Access Token Stores > OAuth Access Token Store Authorization Code Stores > Authz Code Store Client Access Token Stores > OAuth Client Access Token Store By default, OAuth uses EhCache instead of Cassandra. For more details on OAuth, see the API Gateway OAuth User Guide. Deploy the configuration 1. Click Deploy in the toolbar to deploy this configuration to the API Gateway group. 2. Restart each API Gateway in the group. For details on any connection errors between API Gateway and Cassandra, see Configure a Cassandra HA cluster on page 45. Axway API Gateway Installation Guide 55

56 5 Install Apache Cassandra Configure API Manager Cassandra client settings To update the Cassandra client configuration for API Manager, perform the following steps: Configure your API Gateway settings 1. Ensure the API Gateway and API Manager components have been installed on the API Gateway 1 and API Gateway 2 nodes. These can be local or remote to Cassandra installations. For details, see Install the API Gateway server on page 75 and Install API Manager on page Ensure an API Gateway domain has been created on the API Gateway 1 node using managedomain. For details on managedomain, see the API Gateway Administrator Guide. 3. Create an API Gateway group and first instance on API Gateway 1 using managedomain. 4. Start the first API Gateway instance in the group. For example: startinstance -n "my_gw_server_1" -g "my_group" 5. Configure the Cassandra connection on the API Gateway 1 node. For details, see Configure the API Gateway Cassandra client connection on page 54. Configure your API Manager settings 1. Configure API Manager on the first API Gateway instance in the group. For example, run setup-apimanager for the API Gateway instance: setup-apimanager --name "SERVER_INSTANCE_NAME" --group "GROUP_NAME" -- portalport API_MANAGER_LISTEN_PORT --trafficport API_MANAGER_TRAFFIC_ PORT For more details on setup-apimanager, see the API Manager User Guide. 2. Configure the Cassandra consistency levels for your KPS Collections. For details, see Configure the API Gateway Cassandra consistency levels on page In the Policy Studio tree, select Server Settings > API Manager > Quota Settings, and ensure that Use Cassandra is selected. Axway API Gateway Installation Guide 56

57 5 Install Apache Cassandra 4. Under Cassandra consistency levels, in both the Read and Write fields, select QUORUM: 5. Add the API Gateway 2 host machine to the domain using managedomain. 6. Create the second API Gateway instance in the same group on the API Gateway 2 node. 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= Start the second API Gateway instance. For example: startinstance -n "my_gw_server_2" -g "my_group" On startup, this instance receives the API Manager configuration for the group. It now shares the same KPS and Cassandra configuration and data, and uses the ports specified in the envsettings.props file. Axway API Gateway Installation Guide 57

58 5 Install Apache Cassandra Step 3 Secure the Cassandra HA configuration and verify To secure your Cassandra HA configuration, perform the following steps: 1. Reset your default user name and password. 2. Enable node-to-node traffic encryption. 3. Enable client-to-node traffic encryption. 4. Configure the cqlsh command for client-to-node traffic encryption. For details, see Secure Cassandra HA configuration on page 71. nodetool can normally run on any machine against any Cassandra node. For improved security, you might have locked down JMX for localhost access only. In such cases, you could use ssh to access that machine, and then run nodetool. Automate API Gateway Cassandra client settings You can automate your API Gateway Cassandra client configuration by running the updatecassandrasettings.py script against a specified API Gateway deployment package (.fed). For example: 1. Go to the following directory error: INSTALL_DIR/apigateway/samples/scripts 2. Enter the following command: run cassandra/updatecassandrasettings.py -f /opt/apigateway/conf/my_ deployment.fed -r 3 -H "ipa:9042,ipb:9042,ipc:9042" The script options are explained as follows: Option Description -f, --file Enter the API Gateway deployment (.fed) to be updated. The default is INSTALL_ DIR/system/conf/templates/FactoryConfiguratio n-vordelgateway.fed. If you do not specify a.fed file, you must back up this file before running the script. Axway API Gateway Installation Guide 58

59 5 Install Apache Cassandra Option -r, -- replicationfacto r Description Enter the Cassandra replication factor. For more details, see Configure the group keyspace and replication factor in Cassandra on page 50. -h, --hosts Enter a comma-separated list of Cassandra host nodes in host:port format. For example, :9042, :9042, :9042. For more details on automating API Gateway configuration, see the API Gateway DevOps Deployment Guide. Further details For details on Cassandra administration, see Perform essential Cassandra operations on page 64. For more details on Cassandra cluster configuration and its impact on your system, see the following: Manage Apache Cassandra on UNIX/Linux and Windows When you select to install Cassandra using the API Gateway installer as part of a Standard or Complete setup, Cassandra starts automatically. To start or stop Cassandra manually or as a service, perform the steps described in this topic. Before starting Cassandra, you must ensure that your JAVA_HOME environment variable is set to the JRE Location that you selected when installing Cassandra. See Install an Apache Cassandra database on page 37. For details on configuring Cassandra high availability, see Configure a Cassandra HA cluster on page 45. Manage Apache Cassandra on UNIX/Linux This section explains how to start and stop Cassandra on UNIX/Linux. Axway API Gateway Installation Guide 59

60 5 Install Apache Cassandra Start Apache Cassandra on UNIX/Linux To start Cassandra in the background: 1. Open a command prompt, and change to the following directory: $ cd CASSANDRA_HOME/bin 2. Run the following command: $./cassandra To start Cassandra in the foreground, run the following command: $./cassandra -f For more details, see 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: CentOS: Debian: When startup scripts are configured, you can then start Cassandra as a service. You must have root or sudo permissions to start Cassandra as a service. For example, typically the command to start Cassandra as a service is as follows: $ sudo service cassandra start Stop Cassandra on UNIX/Linux 1. Find the Cassandra Java process ID (PID): $ ps auwx grep cassandra 2. Run the following command: Axway API Gateway Installation Guide 60

61 5 Install Apache Cassandra $ sudo kill pid Stop Cassandra as a service on UNIX/Linux You must have root or sudo permissions to stop the Cassandra service as follows: $ sudo service cassandra stop Manage Apache Cassandra on Windows This section explains how to start and stop Cassandra on Windows. Start Apache Cassandra on Windows Modern Windows versions support the new PowerShell command-line interpreter. The Cassandra installation provides the old.bat startup file and the new.ps1 startup file. When you run the cassandra command in CASSANDRA_HOME\bin, it can run in legacy startup mode or new startup mode depending on the PowerShell script execution policy setting. If this policy is set to Unrestricted, the new PowerShell startup script runs. Otherwise, the legacy startup script runs. There are differences in the startup behavior and command line options depending on the type of startup. This topic shows both legacy and new startup modes. Legacy mode To start Cassandra in the foreground in legacy mode: 1. Open a command prompt, and change to the following directory: > cd CASSANDRA_HOME\bin 2. Run the following command: > cassandra If you use legacy mode, you cannot start Cassandra in the background from the command line. If you already have PowerShell mode enabled, you must enter cassandra LEGACY to run in legacy mode. Powershell mode To start Cassandra in the background in PowerShell mode: 1. Open a command prompt, and change to the following directory: Axway API Gateway Installation Guide 61

62 5 Install Apache Cassandra > cd CASSANDRA_HOME\bin 2. Run the following command: > cassandra To start Cassandra in the foreground, run the following command: > cassandra -f Start Cassandra as a Windows service Ensure that you are not using the default 32-bit Oracle JRE bundled with API Gateway, which cannot run Cassandra as a service. For more details, see Install a 64-bit Oracle JRE on Windows on page 38. You can install and run Cassandra as a service as follows: 1. Download the latest version of Apache Commons Daemon for Windows from: 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 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: Legacy mode: cassandra.bat install PowerShell mode: cassandra.bat -install Tip This creates a cassandra service, configured to start in manual mode. To change the startup mode to auto, use the Windows sc command. For example: sc config cassandra start= auto The space character after the = sign is required. Configure startup dependencies If you also installed API Gateway as a service, you can modify its service entry to depend on newly created cassandra service, so the API Gateway is started after Cassandra is started. You can use the sc command to configure such dependencies as follows: Axway API Gateway Installation Guide 62

63 5 Install Apache Cassandra sc config [service name] depend= <Dependencies(separated by /(forward slash))> There must be no space between depend and the = character. For example, if the API Gateway is called QuickStart Server, and it belongs to a group called QuickStart Group, its service name is QuickStart Server (QuickStart Group), and the command is: sc config "QuickStart Server (QuickStart Group)" depend= cassandra Stop Cassandra on Windows You can stop Cassandra on Windows in legacy or PowerShell mode. Legacy mode In legacy mode, you cannot start Cassandra in the background on the command line. To stop Cassandra running in the foreground, enter Ctrl-C in the console. PowerShell mode When Cassandra starts in a background mode, it creates a pid.txt file in CASSANDRA_HOME that contains the process ID of Cassandra running in background. Use this process ID to terminate the Cassandra process with the taskkill command. For example: > cd c:\cassandra > type pid.txt 1564 > taskkill /F /PID 156 Stop Cassandra as a Windows service If you install Cassandra as a Windows service, you can stop Cassandra using the Windows Service Manager (Run > service.msc), or alternatively from the command line using sc.exe. For more details, see Start Cassandra as a Windows service on page 62. Connect to API Gateway for the first time Connecting to API Gateway depends on your installation setup type (Standard, Complete, or Custom). Axway API Gateway Installation Guide 63

64 5 Install Apache Cassandra Standard or Complete setup If you installed a default Standard or Complete setup (both include the QuickStart tutorial), Cassandra is installed on the same host, and listens on localhost by default. API Gateway runs on the same host and connects to Cassandra by default. Custom setup If you installed a Custom setup, and did not select the Quickstart tutorial, you must update the API Gateway Cassandra client configuration as follows: 1. Open the API Gateway group configuration in Policy Studio. 2. Select Server Settings > Cassandra > Authentication, and set the Cassandra username/password (default is cassandra/cassandra). 3. Select Server Settings > Cassandra > Hosts. Add an address for the Cassandra node. You can enter an IP address or host name. 4. Deploy the configuration to the API Gateway group. For more details on configuring Server Settings in the Policy Studio client, see the API Gateway Administrator Guide. For details on updating the Cassandra server configuration, see Configure a Cassandra HA cluster on page 45. Further details For more details on Apache Cassandra, see the following: Perform essential Cassandra operations There are many possible Cassandra administration operations. This section covers the minimum essential operations that are required to maintain a healthy Cassandra HA cluster. Perform anti-entropy repair Cassandra is inherently HA, so when a node is absent from a cluster for a time, it can be brought back into the cluster and becomes eventually consistent by design. Node repair is required after reintegration into the cluster. Axway API Gateway Installation Guide 64

65 5 Install Apache Cassandra The nodetool repair command repairs inconsistencies across all Cassandra replica nodes for a given range of data. Most importantly, it ensures that deleted data remains deleted in a distributed system. You should execute this command at least weekly, at off-peak times, and stagger execution on different nodes. For example, the following crontab commands execute nodetool repair on specified schedules in test and production environments: # Every 10 mins. NB: TEST ONLY, not for production. $ crontab */10 * * * * /home/cassandra/bin/nodetool repair >> /home/cassandra/logs/repair.log # Every week at 3am on a Sunday $ crontab 0 2 * 0 /home/cassandra/bin/nodetool repair >> /home/cassandra/logs/repair.log On Windows 2012 Server, you can use Windows Task Scheduler. If a node is down for more than 10 days, it must not join the existing cluster. It should be replaced instead. See Replace dead nodes on page 65. For more details on nodetool repair, see: pair.html Replace dead nodes If a node is down for more than 10 days, it should be replaced. For details on replacing dead Cassandra nodes, see: Back up and restore Cassandra data To backup and restore Cassandra data (online and HA), use the following instructions: Back up configuration and data for disaster recovery You must back up the following API Gateway and Cassandra configuration and data for disaster recovery: Axway API Gateway Installation Guide 65

66 5 Install Apache Cassandra API Gateway group configuration data Back up the API Gateway group configuration data in apigateway/groups/<groupname>/conf. This contains the API Gateway, API Manager and KPS configuration data. Ensure that you back up these important files. API Gateway KPS data Ensure that you back up KPS data regularly on all nodes using the kpsadmin tool. This backs up API Manager and customer KPS data to simple, portable JSON files. These are also independent of Cassandra and Cassandra versions. For more details, see the API Gateway Key Property Store User Guide. Cassandra configuration Ensure that you back up the CASSANDRA_HOME/conf directory on all nodes. Cassandra data With Cassandra, any node in the system can act as a live backup when replacing a dead node. Data can be restored without affecting availability using Cassandra HA backup and restore. However, it still makes sense to make a regular hard file system backup of the data on all nodes for disaster recovery use cases. Cassandra data resides in CASSANDRA_HOME/data. You should back up this directory on all nodes. You must stop the Cassandra server before taking a file system backup. This ensures that files are not locked and that all data is flushed to disk. For details, see Install an Apache Cassandra database on page 37. Ensure time is in sync across the cluster You should use a time service such as NTP to ensure that time is in sync in the cluster. For example, OAuth Tokens are removed by Cassandra when expired, based upon the time-to-live value set when created. If Cassandra nodes run on servers that are not synchronized, the tokens are removed at different times, and the data is no longer fully synchronized. You must ensure that the NTP server is on a physical machine, and not a virtual machine, in the datacenter. For more details, see Axway API Gateway Installation Guide 66

67 5 Install Apache Cassandra Reconfigure an existing Cassandra installation from scratch There is no need to reinstall Cassandra from scratch. You can just move Cassandra data files and restore the cassandra.yaml configuration file if necessary. Preform the following steps: 1. Stop Cassandra. For details, see Install an Apache Cassandra database on page 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: ml Upgrade your Cassandra version For details on upgrading your Cassandra version, see Supported Cassandra versions on page 37. Further details For more details on Cassandra operations, see: setup-cassandra script reference The setup-cassandra script provided by API Gateway enables you to configure a multi-node Cassandra HA cluster automatically. You can use this script when Cassandra is installed locally along with API Gateway, or installed remotely on a different node. For details on supported Cassandra deployment architectures and HA production environments, see Configure a Cassandra HA cluster on page 45. API Gateway provides the setup-cassandra script to help configure a Cassandra cluster by updating your Cassandra configuration files and providing instructions to finalize the configuration. This script also creates an automatic backup of the original cassandra.yaml file in the following format: Axway API Gateway Installation Guide 67

68 5 Install Apache Cassandra <timestamp>_cassandra.yaml.bak This topic describes how to run the setup-cassandra script, and how to configure a multinode Cassandra cluster with username/password authentication enabled. It also describes how to configure TLS v1.2 encryption for client-server and inter-node communications in the cluster. Prerequisites The following prerequisites apply for the setup-cassandra script: Python The Cassandra cqlsh command requires Python version to be installed on the node. For example, this command enables you to set up the seed node and change the default user name and password. User name and password authentication User name and password authentication for clients connecting to the cluster is enabled by the setup-cassandra script by default. However, you must change the default user name and password created by Cassandra on startup to further secure the installation. The script provides instructions describing how to change the default user name and password and replicate the system_auth keyspace using the cqlsh command. For more details, see Secure Cassandra HA configuration on page 71. Remote Cassandra HA nodes setup-cassandra is available by default when Cassandra is installed locally on the same node as API Gateway. You can also configure remote Cassandra nodes to use the setup-cassandra script supplied by the API Gateway installation. Alternatively, you can perform all necessary Cassandra configuration changes manually. For details, see Configure a Cassandra HA cluster on page 45. To configure a remote Cassandra node to use the setup-cassandra script, perform the following steps: 1. Ensure that the JAVA_HOME environment variable is set on the remote Cassandra node. 2. Ensure that Python is installed and added to your PATH environment variable on the remote Cassandra node. 3. Change to the following directory on the local API Gateway node: AXWAY_HOME/apigateway/system/lib/jython/ Axway API Gateway Installation Guide 68

69 5 Install Apache Cassandra 4. Copy the setup-cassandra.py file to your chosen directory on the remote Cassandra node. Run the setup-cassandra script The instructions for running the setup-cassandra script depend on whether the node is local or remote to API Gateway. Run setup-cassandra on local API Gateway node The setup-cassandra script is bundled with the API Gateway installation and located in the bin directory. To run this script on a local node: UNIX/Linux $ cd AXWAY_HOME/apigateway/posix/bin $./setup-cassandra <options> Windows > cd AXWAY_HOME\apigateway\win32\bin > setup-cassandra <options> Run setup-cassandra on remote Cassandra node On a remote Cassandra node, you first must ensure that the setup-cassandra script has been configured as described in Remote Cassandra HA nodes on page 68. To run this script on a remote node: UNIX/Linux $./setup-cassandra.py <options> Windows > setup-cassandra.py <options> Axway API Gateway Installation Guide 69

70 5 Install Apache Cassandra The example commands in this topic assume that Cassandra is installed locally on an API Gateway node. Configure the seed node To configure Cassandra to run as the cluster seed node, run the setup-cassandra script with the following options: setup-cassandra --seed --own-ip=<own_ip> --nodes=<number_of_nodes> -- cassandra-config=<config_file> These options are described as follows: OWN_IP NODES IP address of this Cassandra host. Cassandra uses this IP address for communicating with other nodes in the cluster and for receiving client connections. Total number of the nodes in the Cassandra cluster. CONFIG_FILE Full path to cassandra.yaml configuration file. Typically the path is <CASSANDRA_INSTALL_ DIR>/conf/cassandra.yaml. For example: setup-cassandra --seed --own-ip=ipa --nodes=3 --cassandraconfig=/opt/cassandra/conf/cassandra.yaml Configure additional nodes To configure Cassandra on the remaining cluster nodes, run the setup-cassandra script with the following options: setup-cassandra --seed-ip=<seed_ip> --own-ip=<own_ip> --cassandraconfig=<config_file> These options are described as follows: SEED_IP IP address of the Cassandra seed host (see Configure the seed node on page 70). Axway API Gateway Installation Guide 70

71 5 Install Apache Cassandra OWN_IP CONFIG_ FILE IP address of this Cassandra host. Cassandra uses this IP address for communicating with other nodes in the cluster and for receiving client connections. Full path to cassandra.yaml configuration file. Typically the path is <CASSANDRA_INSTALL_DIR>/conf/cassandra.yaml. For example: setup-cassandra --seed-ip=ipa --own-ip=ipb --cassandraconfig=/opt/cassandra/conf/cassandra.yaml Secure Cassandra HA configuration This section explains how to use the setup-cassandra script to secure your Cassandra HA configuration. The examples assume that Cassandra is installed locally on the same host as API Gateway. See also Run setup-cassandra on remote Cassandra node on page 69. Reset your default user name and password You can use the setup-cassandra script to reset the default user name and password (cassandra/cassandra). Run this command to see the instructions that you need to follow. For example, on the seed node the instructions are as follows:./setup-cassandra --seed --own-ip=ipa --nodes=3 --cassandra config=/opt/cassandra/conf/cassandra.yaml Connect to Cassandra with cqlsh and run following commands to create an alternative superuser account: CREATE USER admin WITH PASSWORD 'amujsa26al2ns' SUPERUSER;QUIT PLEASE MAKE A NOTE OF USERNAME AND PASSWORD FOR THE NEW SUPERUSER ACCOUNT: USERNAME: admin PASSWORD: amujsa26al2ns Connect to Cassandra using newly created account to lock out the default Cassandra superuser account and update "system_auth" keyspace replication factor: /opt/cassandra/bin/cqlsh -u admin -p amujsa26al2ns node1 ALTER USER cassandra WITH PASSWORD 'g5q5h4h3bf1pnh2nsra9iucd82d7f1jams468vhaiimtibtuqpf' NOSUPERUSER; ALTER KEYSPACE "system_auth" WITH REPLICATION = { 'class': 'SimpleStrategy', 'replication_factor': 3 }; QUIT If you are setting up a Cassandra HA cluster, you must replicate the system_auth keyspace as shown in this example. This enables API Gateway to communicate with the cluster if a node goes down. For more details, see: Axway API Gateway Installation Guide 71

72 5 Install Apache Cassandra reconfignativeauth.html?hl=authentication Enable node-to-node traffic encryption To configure TLS v1.2 encryption, you must generate a private key and certificate for every Cassandra node in the cluster. You must also obtain the certificate for the Certification Authority (CA) used to generate the node certificate. You can use Policy Studio to create the necessary certificates and keys or any other suitable method for generating certificates. You must export and save the node certificate and private key as a PKCS12 file named server.p12, and save the CA certificate as a PEM file named (server-ca.pem). You must place these files into the same directory where you run the setup-cassandra script from. To use the setup-cassandra script to configure node-to-node TLS/SSL encryption, add the -- enable-server-encryption option. For example: setup-cassandra --seed-ip=ipa --own-ip=ipb --cassandraconfig=/opt/cassandra/conf/cassandra.yaml --enable-server-encryption After you run the setup-cassandra script, it provides instructions for converting the keys and certificates to a format required by Cassandra. After you perform these instructions, you can remove the server.p12 and server-ca.pem files from the system. Caution Anyone with a private key or certificate signed by server-ca.pem can connect to the cluster. You should limit the use of this CA to signing the node certificates only. In particular, do not use the same CA to sign client-to-node certificates. Enable client-to-node traffic encryption The requirements for setting up client-to-node TLS/SSL encryption are the same as the node-tonode TLS/SSL requirements. However, you must save the CA certificate/private key and node certificate in client-ca.pem and client.p12 files respectively. For example, to instruct the setup-cassandra script to configure client-to-node encryption, add the --enableclient-encryption option to script arguments: setup-cassandra --seed-ip=ipa --own-ip=ipb --cassandraconfig=/opt/cassandra/conf/cassandra.yaml --enable-client-encryption After you run the setup-cassandra script, it provides instructions for converting the keys and certificates to a format required by Cassandra. After you perform these instructions, you can remove the client.p12 and client-ca.pem files from the system. Axway API Gateway Installation Guide 72

73 5 Install Apache Cassandra Configure the cqlsh command for client-to-node traffic encryption When the Cassandra cluster has been configured to use client-to-node TLS/SSL encryption, you must configure all clients connecting to the cluster (including cqlsh) to use TLS/SSL. If client-to-node TLS/SSL encryption has been enabled, the setup-cassandra script creates a configuration file (cqlshrc) with the necessary configuration to enable TLS/SSL encryption. However, you must provide following files to configure cqlsh for TLS/SSL: client-ca.pem: PEM file containing CA certificate cqlsh-cert.pem: PEM file containing client certificate for cqlsh cqlsh-key.pem: PEM file containing private key of client certificate for cqlsh Updated Cassandra configuration This section shows the updates that the setup-cassandra script makes to the cassandra.yaml configuration file: General settings seed_provider, parameters, seeds: <IP address of seed node> start_native_transport: true native_transport_port: 9042 listen_address: IP address of the node rpc_address: IP address of the node authenticator: org.apache.cassandra.auth.passwordauthenticator authorizer: org.apache.cassandra.auth.cassandraauthorizer Node-to-node traffic encryption If node-to-node TLS/SSL traffic encryption is enabled: server_encryption_options: Specified options internode_encryption: all keystore: <server-keystore.jks> keystore_password: Randomly generated password truststore: <server-truststore.jks> Axway API Gateway Installation Guide 73

74 5 Install Apache Cassandra truststore_password: Randomly generated password protocol: TLS store_type: JKS algorithm: SunX509 require_client_auth: true Client-to-node traffic encryption If client-to-node TLS/SSL traffic encryption is enabled: client_encryption_options: Specified options enabled: true optional: false keystore: <client-truststore.jks> keystore_password: Randomly generated password truststore: <client-truststore.jks> truststore_password: Randomly generated password protocol: TLS store_type: JKS algorithm: SunX509 require_client_auth: true Axway API Gateway Installation Guide 74

75 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: Install the API Gateway server on page 75 Install the QuickStart tutorial on page 77 Install the Admin Node Manager on page 80 Install Policy Studio on page 81 Install API Tester on page 83 Install Configuration Studio on page 82 Install API Manager on page 84 Install the Package and Deploy tools on page 86 Install API Gateway Analytics on page 88 For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Install the API Gateway server The API Gateway server is the main runtime environment consisting of an API Gateway instance and a Node Manager. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. It is not necessary to install the API Gateway server on the API Gateway appliance because this component is preinstalled on the appliance. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway license file You must have a valid Axway license file to install the API Gateway server. Also, if you intend to run API Gateway in FIPS-compliant mode, ensure that your license file allows this. To obtain an evaluation trial license or a full license, contact your Axway Account Manager. Axway API Gateway Installation Guide 75

76 6 Install API Gateway components If you are using Apache Cassandra, before starting API Gateway, you must first ensure that Cassandra is installed and running. For more details, see Install an Apache Cassandra database on page 37. Install the API Gateway server To install the API Gateway server in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the API Gateway server component. To install the API Gateway server in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the API Gateway server component in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components apigateway --disable-components nodemanager,qstart,analytics,policystudio, apitester,configurationstudio,apimgmt,cassandra,packagedeploytools --licensefilepath mylicense.lic Before you start API Gateway Before you can start the API Gateway, you must first use the managedomain script to create a new domain that includes an API Gateway instance. If you installed the QuickStart tutorial, a sample API Gateway domain is automatically configured in your installation. Otherwise, you must first create a new domain. For more details, see the API Gateway Administrator Guide. If you installed the QuickStart tutorial, the QuickStart server and Admin Node Manager start automatically. Otherwise, you must start them manually. If you installed Apache Cassandra, before starting API Gateway, you must first ensure that your Apache Cassandra server is running. For more details, see Install an Apache Cassandra database on page 37. Start API Gateway To start the API Gateway manually, follow these steps: 1. Open a command prompt in the following directory: Axway API Gateway Installation Guide 76

77 6 Install API Gateway components Windows INSTALL_DIR\apigateway\Win32\bin UNIX/Linux INSTALL_DIR/apigateway/posix/bin 2. Run the startinstance command, for example: startinstance -n "Server1" -g "Group1" 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: HOST refers to the host name or IP address of the machine on which API Gateway is running (for example, 5. Enter the administrator user name and password. This is the administrator user name and password you entered during installation. You can encrypt all sensitive API Gateway configuration data with an encryption passphrase. For example, you can specify this passphrase in your API Gateway configuration file, or on the command line when the API Gateway is starting up. For more details, see the API Gateway Administrator Guide. Start as a service You can also run API Gateway instances and Node Managers as services. For more information, see Set up services on page 103. Install the QuickStart tutorial The API Gateway QuickStart tutorial demonstrates the main API Gateway features and tools, and enables you to invoke some example APIs and to monitor the API Gateway using API Gateway Manager. Tip The QuickStart tutorial is automatically installed as part of a default Standard or Complete setup. For more details, For more details, see Installation options on page 28. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway API Gateway Installation Guide 77

78 6 Install API Gateway components Install the QuickStart tutorial The QuickStart tutorial depends on the API Gateway Server. You cannot install the QuickStart tutorial without the API Gateway Server. To install the API Gateway Server and the QuickStart tutorial in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the API Gateway Server, Admin Node Manager, and QuickStart tutorial components. To install the API Gateway Server, Admin Node Manager, and QuickStart tutorial in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the API Gateway Server component and the QuickStart tutorial in unattended mode: APIGateway_7.5.3_Install_linux-x86-32_BN run --mode unattended --setup_type advanced --enable-components apigateway,nodemanager,qstart --disable-components analytics,policystudio,apitester,configurationstudio,apimgmt,cassandra,packagedeploy tools --licensefilepath mylicense.lic QuickStart domain configuration When the QuickStart tutorial is installed, a sample API Gateway domain is automatically configured in your installation. This includes a QuickStart Server API Gateway instance that runs in a QuickStart Group group. The QuickStart server and Admin Node Manager start automatically when installation is complete. Start the QuickStart tutorial The QuickStart tutorial launches automatically in your browser when installation is complete. Follow the instructions in your browser to perform the steps in the tutorial. Axway API Gateway Installation Guide 78

79 6 Install API Gateway components For example, the following screen shows invoking a sample API in the tutorial: You can click the Try it button to invoke the sample API. This displays a JSON list of available products. You can click the Show Me button to view the traffic monitored by the API Gateway in the API Gateway Manager. Restart the QuickStart tutorial At any point, if you need to restart the QuickStart tutorial, perform the following steps: 1. Open a command prompt in the following directory: Windows INSTALL_DIR\apigateway\Win32\bin UNIX/Linux INSTALL_DIR/apigateway/posix/bin 2. Run the startinstance command, for example: startinstance -n "QuickStart Server" -g "QuickStart Group" On UNIX/Linux, you must ensure that the startinstance file has execute permissions. Axway API Gateway Installation Guide 79

80 6 Install API Gateway components 3. To manage and monitor the API Gateway, you must ensure that the Admin Node Manager is running. Use the nodemanager command to start the Admin Node Manager from the same directory. 4. To launch API Gateway Manager, enter the following address in your browser: 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: Install the Admin Node Manager You can install an Admin Node Manager component in isolation without an API Gateway license. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install the Admin Node Manager To install the Admin Node Manager in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the Admin Node Manager component. To install the Admin Node Manager in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the Admin Node Manager component in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components apigateway --disable-components analytics,qstart,policystudio,configurationstudio, apitester,apimgmt,cassandra,packagedeploytools Axway API Gateway Installation Guide 80

81 6 Install API Gateway components Start the Admin Node Manager For more information on starting the Admin Node Manager, see Start API Gateway on page 76. Install Policy Studio Policy Studio is a graphical IDE that enables developers to virtualize APIs and develop policies to enforce security, compliance, and operational requirements. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install Policy Studio To install Policy Studio in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the Policy Studio component. To install Policy Studio in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the Policy Studio component in unattended mode:./apigateway_7.5.3_install_linux-x86-32-bn<n>.run --mode unattended --setup_type advanced --enable-components policystudio --disable-components analytics,nodemanager,apigateway,qstart, apitester,configurationstudio,apimgmt,cassandra,packagedeploytools Start Policy Studio Before starting Policy Studio, ensure both the Admin Node Manager and the API Gateway instance are running. For more details, see Start API Gateway on page 76. If you did not select to launch Policy Studio after installation, perform the following steps: 1. Open a command prompt. 2. Change to your Policy Studio installation directory (for example, INSTALL_ DIR\policystudio). Axway API Gateway Installation Guide 81

82 6 Install API Gateway components 3. Run policystudio. 4. When Policy Studio starts up, select File > New Project. 5. In the New Project dialog, enter a name for the project and click Next. 6. Select From a running API Gateway instance and click Next. Tip You can also create configuration projects from.fed files or from existing configurations. For more information, see the API Gateway Policy Developer Guide. 7. In the Open Connection dialog, select the Admin Node Manager session to connect to, enter the administrator user name and password that you specified during installation and click OK. 8. In the Download Options dialog, select a group and an API Gateway instance to download its configuration. 9. If a passphrase has been set, enter it in the Passphrase field, and click Finish. Alternatively, if no passphrase has been set, click Finish. For more details on setting a passphrase, see the API Gateway Administrator Guide. Install Configuration Studio Configuration Studio is a graphical tool that enables administrators to configure environmentspecific properties to deploy APIs and policies in non-development environments. For more details, see the API Gateway DevOps Deployment Guide. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install Configuration Studio To install Configuration Studio in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the Configuration Studio component. To install Configuration Studio in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the Configuration Studio component in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components configurationstudio Axway API Gateway Installation Guide 82

83 6 Install API Gateway components --disable-components analytics,nodemanager,apigateway,qstart, apitester,policystudio,apimgmt,cassandra,packagedeploytools Start Configuration Studio To start Configuration Studio after installation, perform the following steps: 1. Open a command prompt. 2. Change to your Configuration Studio installation directory (for example, INSTALL_ DIR\configurationstudio). 3. Run configurationstudio. For more details on Configuration Studio, see the API Gateway DevOps Deployment Guide. Install API Tester API Tester is a graphical tool that enables you to test API functionality, performance, and security. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. API Tester is deprecated and will be removed in a future release. API Tester is no longer installed in a Standard or Complete setup, and is only installed in a Custom setup. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Install API Tester To install API Tester in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the API Tester component. To install API Tester in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the API Tester component in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components apitester Axway API Gateway Installation Guide 83

84 6 Install API Gateway components --disable-components analytics,nodemanager,apigateway,qstart,policystudio, configurationstudio,apimgmt,cassandra,packagedeploytools Start API Tester Before starting API Tester, ensure that the Admin Node Manager and the API Gateway instance are running. For more details, see Start API Gateway on page 76. To start API Tester after installation, perform the following steps: 1. Open a command prompt. 2. Change to your API Tester installation directory (for example, INSTALL_DIR\apitester). 3. Run apitester. For more details on API Tester, see the API Tester User Guide. Install API Manager API Manager is an additional licensed layered product running on the Axway API Gateway. For more details, see the API Manager User Guide. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway license file You must have a valid Axway license file to install API Manager. To obtain an evaluation trial license or a full license, contact your Axway Account Manager. Your API Gateway installation must also be licensed. If you do not have a license for API Gateway, you cannot install API Manager. Domains with multiple nodes In an API Gateway domain environment with multiple machine nodes, API Manager must be installed on API Gateway instance nodes. Axway API Gateway Installation Guide 84

85 6 Install API Gateway components Apache Cassandra The Apache Cassandra database is required to store API Manager data. You can install Cassandra separately before installing API Manager, or when installing API Manager. For more details, see Install Apache Cassandra on page 37. Install API Manager To install API Manager in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the following components: o o o o API Manager API Gateway Server Admin Node Manager Cassandra (if not already installed separately before API Manager) For more details, see the following: Install the API Gateway server on page 75 Install the Admin Node Manager on page 80 Install an Apache Cassandra database on page 37 Unattended mode To install API Manager in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the API Manager, API Gateway Server, Admin Node Manager, and Cassandra components in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components apimgmt,apigateway,nodemanager,cassandra --disable-components qstart,analytics,policystudio,configurationstudio, apitester,packagedeploytools --licensefilepath mylicense.lic --apimgmtlicensefilepath mymgmtlicense.lic Axway API Gateway Installation Guide 85

86 6 Install API Gateway components Configure API Manager If you selected to install the QuickStart tutorial, API Manager is configured by default. If you did not install the QuickStart tutorial, you must configure API Manager. For more details, see the API Manager User Guide. Start API Manager Before starting API Manager, ensure that Apache Cassandra, the Admin Node Manager and API Gateway instance are running. For more details, see Start API Gateway on page 76. When API Manager is configured, you can use the following URL to log into the API Manager web console: The default URL is: Enter your API administrator user credentials. This is the API administrator user name and password you entered during installation. For more information on using API Manager, see the API Manager User Guide. Install the Package and Deploy tools You can use the API Gateway Package and Deploy tools to automate processes in your API Gateway system for continuous integration. For example, this includes generating API Gateway configuration packages from API team development projects, and building and deploying configurations to API Gateway group instances. You can install the Package and Deploy tools component without an API Gateway license. For more details on API Gateway configuration packages, see the API Gateway DevOps Deployment Guide. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway API Gateway Installation Guide 86

87 6 Install API Gateway components Install the Package and Deploy tools To install the Package and Deploy tools in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the Package and Deploy Tools component. To install the Package and Deploy tools component in unattended mode, follow the steps described in Unattended installation on page 32. For example, the following command shows how to install the API Gateway Package and Deploy tools only in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components packagedeploytools --disable-components apigateway, analytics,qstart,policystudio, configurationstudio,apitester,apimgmt,cassandra For details on using the Package and Deploy tools to automate processes for continuous integration, see "Upgrade an API Gateway project" in the API Gateway DevOps Deployment Guide. Axway API Gateway Installation Guide 87

88 Install and configure API Gateway Analytics 7 This topic describes how to use the API Gateway installer to install API Gateway Analytics, and how to configure a your metrics database and API Gateway Analytics. API Gateway Analytics is deprecated and will be removed in a future release. This topic includes the following: Install API Gateway Analytics on page 88 Configure the metrics database on page 90 Configure API Gateway Analytics on page 95 Install API Gateway Analytics API Gateway Analytics is a server runtime and web-based console for analyzing and reporting on API use over extended periods of time. For more details on API Gateway components and concepts, see the API Gateway Concepts Guide. API Gateway Analytics is deprecated and will be removed in a future release. Prerequisites Ensure that all of the prerequisites detailed in Prerequisites on page 17 are met. Axway license file You must have a valid Axway license file to install API Gateway Analytics. To obtain an evaluation trial license or a full license, contact your Axway Account Manager. Install API Gateway Analytics To install API Gateway Analytics in GUI mode, perform an installation following the steps described in Installation options on page 28, using the following selections: Select the Custom setup type. Select to install the API Gateway Analytics component. Axway API Gateway Installation Guide 88

89 7 Install and configure API Gateway Analytics To install API Gateway Analytics in unattended mode, follow the steps described in Unattended installation on page 32. The following example shows how to install the API Gateway Analytics component in unattended mode:./apigateway_7.5.3_install_linux-x86-32_bn<n>.run --mode unattended --setup_type advanced --enable-components analytics --disable-components nodemanager,apigateway,qstart,policystudio, apitester,configurationstudio,apimgmt,cassandra,packagedeploytools --analyticslicensefilepath myanalyticslicense.lic Configure your API Gateway Analytics database Before starting API Gateway Analytics, you must perform the following steps: 1. Create a database instance. For more details, see Configure the metrics database on page 90. Alternatively, if you already have an existing database, skip to the next step. 2. Update your API Gateway Analytics configuration with the database details using the configureserver script. For more details, see Configure API Gateway Analytics on page Configure the database tables using the dbsetup script. For more details, see Configure the metrics database on page Enable writing of metrics from your API Gateway instance to the database using the managedomain tool. For more details, see Configure API Gateway Analytics on page 95. Start API Gateway Analytics To start API Gateway Analytics, perform the following steps: 1. Start the API Gateway Analytics server using the analytics script in the bin directory of your API Gateway Analytics installation. 2. To launch API Gateway Analytics, enter the following address in your browser: HOST refers to the host name or IP address of the machine on which API Gateway Analytics is running (for example, 3. Enter the API Gateway Analytics user name and password. 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. Axway API Gateway Installation Guide 89

90 7 Install and configure API Gateway Analytics API Gateway Analytics produces reports based on metrics stored by API Gateway when processing messages. To produce a graph showing the number of connections made by API Gateway to a service, you must first configure a policy that routes messages to that service. When this policy is configured, send messages through the policy so they are routed to the target service. If you change to another database that has a different set of remote hosts or clients configured, you must restart API Gateway and API Gateway Analytics. Start as a service You can also run API Gateway Analytics as a service. For more information, see Set up services on page 103. Further information For more details on topics such as using Policy Studio to configure policies, set up scheduled reports, view monitoring data in API Gateway Analytics, or purge the metrics database, see the API Gateway Policy Developer Guide and the API Gateway Administrator Guide. Configure the metrics database API Gateway stores and maintains the monitoring and transaction data read by API Gateway Analytics and API Manager in a JDBC-compliant database. This topic describes how to create and configure a database for use with API Gateway Analytics or API Manager monitoring. It describes the prerequisites and shows an example of creating a database. It also shows how to setup the database tables or upgrade them from a previous version. API Gateway Analytics is deprecated and will be removed in a future release. Prerequisites The prerequisites for setting up the database are as follows: Install API Gateway Analytics or API Manager You must install API Gateway Analytics or API Manager. For more details, see Install API Gateway Analytics on page 88 Install API Manager on page 84 Axway API Gateway Installation Guide 90

91 7 Install and configure API Gateway Analytics Install a JDBC database You must install a JDBC-compliant database to store the monitoring and transaction data. Axway provides setup scripts for the following databases: MySQL or MariaDB Microsoft SQL Server Oracle IBM DB2 For details on supported database versions, see System requirements on page 17. For details on how to install your chosen JDBC database, see your database product documentation. Add third-party JDBC driver files You must add the JDBC driver files for your chosen third-party database to your API Gateway, Policy Studio, and API Gateway Analytics installations as appropriate. Add JDBC drivers to API Gateway To add the third-party JDBC driver files for your database to API Gateway, perform the following steps: 1. Add the binary files for your database driver as follows: Add.jar files to the following directories: o o INSTALL_DIR/apigateway/ext/lib INSTALL_DIR/apigateway/groups/GROUP-ID/INSTANCE- ID/ext/lib Add.dll files to the INSTALL_DIR\apigateway\Win32\lib directory. Add.so files to the INSTALL_DIR/apigateway/platform/lib directory. 2. Restart API Gateway. Add JDBC drivers to Policy Studio To add third-party binaries to Policy Studio, perform the following steps: 1. Select Window > Preferences > Runtime Dependencies from the Policy Studio main menu. 2. Click Add to select a JAR file to add to the list of dependencies. 3. Click Apply when finished. A copy of the JAR file is added to the plugins directory Axway API Gateway Installation Guide 91

92 7 Install and configure API Gateway Analytics in your Policy Studio installation. 4. Click OK. 5. Restart Policy Studio using the policystudio -clean command. Add JDBC drivers to API Gateway Analytics To add the third-party JDBC driver files for your database to API Gateway Analytics (if installed), perform the following steps: 1. Add the binary files for your database driver as follows: Add.jar files to the INSTALL_DIR/analytics/ext/lib directory. Add.dll files to the INSTALL_DIR\analytics\Win32\lib directory. Add.so files to the INSTALL_DIR/analytics/platform/lib directory. 2. Restart API Gateway Analytics. Create the database API Gateway Analytics and API Manager monitoring read message metrics from a database and display this information in a visual format to administrators. This is the same database in which API Gateway stores its message metrics and audit trail data. You must first create this database using the third-party database of your choice (MySQL or MariaDB, Microsoft SQL Server, Oracle, or IBM DB2). For details on how to do this, see the product documentation for your chosen database. The following example shows creating a MySQL or MariaDB database: mysql> CREATE DATABASE reports; Query OK, 1 row affected (0.00 sec) In this example, the database is named reports, but you can use any appropriate name. Set up the database tables When you have created the database, the next step is to set up the database tables. API Gateway Analytics You can do this by running the dbsetup command without any options from the following API Gateway Analytics directory: Windows INSTALL_DIR\analytics\Win32\bin Axway API Gateway Installation Guide 92

93 7 Install and configure API Gateway Analytics UNIX/Linux INSTALL_DIR/analytics/posix/bin You do not need to run dbsetup again for API Manager monitoring if it has already been run for API Gateway Analytics. API Manager For API Manager monitoring, you can run the dbsetup command from the following API Gateway directory: Windows INSTALL_DIR\apigateway\Win32\bin UNIX/Linux INSTALL_DIR/apigateway/posix/bin The following example command applies to both API Gateway Analytics and API Manager monitoring, and shows setting up new database tables: >dbsetup.bat New databaseschema successfully upgraded to:001-topology Specify options to dbsetup 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 -h, --help Description Displays help message and exits. -p PASSPHRASE, -- passphrase=passphrase Specifies the configuration passphrase (blank for zero length). --dbname=dbname Specifies the database name (mutually exclusive with -- dburl,--dbuser, and --dbpass). --dburl=dburl Specifies the database URL. --dbuser=dbuser Specifies the database user. --dbpass=dbpass Specifies the database passphrase. Axway API Gateway Installation Guide 93

94 7 Install and configure API Gateway Analytics Option --reinstall Description Forces a reinstall of the database, dropping all data. --stop=stop Stops the database upgrade after the named upgrade. dbsetup examples The following are some examples of using dbsetup command options. Connect to a named database You can use the --dbname option to connect to a named database connection configured under the External Connections node in the Policy Studio tree. For example: >dbsetup.bat --dbname=oracle Current schema version:001-initial Latest schema version:001-topology Schema successfully upgraded to:001-topology Connect to a database URL You can use the --dburl option to manually connect to a database instance directly using a URL. For example: >dbsetup.bat --dburl=jdbc:mysql://localhost/reports --dbuser=root --dbpass=admin Current schema version:001-initial Latest schema version:001-topology Schema successfully upgraded to:001-topology Install a database You can also use the --dburl option to set up a newly created database instance where none already exists. For example: >dbsetup.bat --dburl=jdbc:mysql://localhost/reports --dbuser=root --dbpass=admin New database Schema successfully upgraded to:001-topology Reinstall a database You can use the --reinstall option to wipe and reinstall a database. For example: Axway API Gateway Installation Guide 94

95 7 Install and configure API Gateway Analytics >dbsetup.bat --dburl=jdbc:mysql://localhost/reports --dbuser=root --dbpass=admin --reinstall Re-installing database... Schema successfully upgraded to:001-topology SQL database schema scripts As an alternative to using the dbsetup command, API Gateway Analytics also provides separate SQL schema scripts to set up the database tables for each of the supported databases. However, these scripts set up new tables only, and do not perform any upgrades of existing tables. These scripts are provided in the INSTALL_DIR/system/conf/sql directory in the following subdirectories: /mysql /mssql /oracle /db2 The scripts in the /mysql folder apply to both MySQL and MariaDB. You can run the SQL commands in the analytics.sql file in the appropriate directory for your database. The following example shows creating the tables for a MySQL database: mysql> \. C:\axway\analytics\system\conf\sql\mysql\analytics.sql Query OK, 0 rows affected, 1 warning (0.00 sec) Query OK, 0 rows affected, 1 warning (0.00 sec)... Configure API Gateway Analytics This topic describes how to update an API Gateway Analytics configuration (for example, the API Gateway Analytics port, database connection, and user credentials) before starting API Gateway Analytics. You can use the configureserver script (recommended) to guide you through all the required steps, or you can use Policy Studio to configure the API Gateway Analytics configuration file. API Gateway Analytics is deprecated and will be removed in a future release. Prerequisites The prerequisites for configuring API Gateway Analytics are as follows: Axway API Gateway Installation Guide 95

96 7 Install and configure API Gateway Analytics Install API Gateway Because API Gateway Analytics reports on transactions processed by API Gateway in real time, you must first install API Gateway. For more details, see Install the API Gateway server on page 75. To view API Gateway metrics in API Gateway Analytics, you must also enable the recording of metrics. For more details, see Enable metrics for your API Gateway host on page 99. Install API Gateway Analytics You must install API Gateway Analytics. For details on how to install API Gateway Analytics, see Install API Gateway Analytics on page 88. Configure a database You must install a JDBC-compliant database to store the API Gateway monitoring and transaction data. For more details, see Configure the metrics database on page 90. Update API Gateway Analytics configuration By default, API Gateway Analytics is configured to read message metrics from a MySQL database stored on the local machine. You can use the configureserver command to configure API Gateway Analytics to use an alternative database, change the user credentials on the default database connection, or use a different listening port. Update configuration on the command line Perform the following steps to run configureserver in interactive mode: 1. Change to the following directory: Windows INSTALL_DIR\analytics\Win32\bin UNIX/Linux INSTALL_DIR/analytics/posix/bin 2. Run the configureserver command. 3. Enter the port on which the API Gateway Analytics server will listen. Defaults to 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:// :3306/reports. Axway API Gateway Installation Guide 96

97 7 Install and configure API Gateway Analytics The following table lists examples of connection URLs for the supported databases, where reports is the name of the database and DB_HOST is the IP address or host name of the machine on which the database is running: Database Oracle Example connection URL Microsoft SQL Server jdbc:sqlserver://db_ HOST:1433;DatabaseName=reports;integratedSecu rity=false; MySQL/Mari adb IBM DB2 jdbc:mysql://db_host:3306/reports jdbc:db2://db_host:50000/reports You can use the jdbc:mysql://db_host:3306/reports URL with both MySQL and MariaDB databases. 5. Enter the database user name. Defaults to root. 6. Enter the database password. 7. Enter whether API Gateway Analytics generates PDF-based reports. Defaults to N, which means that PDF reports are not generated. When set to Y, API Gateway Analytics generates PDF reports that include the same metrics displayed in the API Gateway Analytics window (for example, number of client requests, requests per service, and so on). For more details on generated PDF reports, see the API Gateway Administrator Guide. 8. Enter the user name to connect to the API Gateway Analytics process that generates PDF reports. Defaults to an administrator user. 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 recipients. You will require an SMTP account with which to send the reports. Defaults to N. The following command shows some example output in interactive mode: C:\Axway\analytics\Win32\bin>configureserver.bat Connecting to configuration at : federated:file:///c:\axway\analytics/conf/fed/ configs.xml Axway API Gateway Installation Guide 97

98 7 Install and configure API Gateway Analytics Listening port [8040]: Configuring Database: Default Database Connection Database URL [jdbc:mysql:// :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 reports (Y, N) [N]: y Default recipient []: joe@example.com from []: apigateway@axway.com 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 ing (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, -- from, -- to, --smtphost, and so on). For example, the following command configures the database connection without ing reports: configureserver --dburl=jdbc:mysql:// :3306/631v2 --dbuser=root --dbpass=changeme --no- The following command specifies to reports and the associated SMTP settings: configureserver --dburl=jdbc:mysql:// :3306/reports --dbuser=root --dbpass=changeme - -- to=joe@example.com -- from=apigateway@axway.com --smtptype=none --smtphost= smtpport=25 --smtpuser=jbloggs --smtppass=changeme --generate --gpass=changeme --gtemp=c:\reports For descriptions of all available options, enter the configureserver --help command. The configureserver script does not permit the euro character ( ) when specifying username and password options. However, you can specify the pound ( ) and dollar ($) characters instead. Axway API Gateway Installation Guide 98

99 7 Install and configure API Gateway Analytics Update configuration in Policy Studio The recommended way to configure API Gateway Analytics is using the configureserver command, which guides you through the required settings. However, you can also use the Policy Studio to configure specific settings in your API Gateway Analytics configuration file. For example, to configure the reports database, perform the following steps: 1. In your Policy Studio installation directory, run the policystudio command. 1. When Policy Studio starts up, select File > New Project. 2. In the New Project dialog, enter a name for the project and click Next. 3. Select From existing configuration and click Next. 4. Browse to the directory containing the API Gateway Analytics configuration file (configs.xml), for example: INSTALL_DIR/analytics/conf/fed/ 5. Select Environment Configuration > External Connections in the Policy Studio tree, and expand the Database Connections tree node. 6. Right-click the Default Database Connection tree node, and select Edit. 7. The Database Connection dialog enables you to configure the database connection details. By default, the connection is configured to read metrics data from the reports database. Edit the details for the Default Database Connection on this dialog. For example, you should enter a non-default database user name and password. To connect to a database other than the default local database, right-click Database Connections in the tree, and select Add a Database Connection. For more details, see the API Gateway Policy Developer Guide. You can verify that your database connection is configured correctly by clicking the Test Connection button on the Configure Database Connection dialog. Enable metrics for your API Gateway host Finally, you must use the managedomain tool to enable writing of metrics from the API Gateway instances on your host to the metrics database. This enables the Node Manager to process event logs from your API Gateway instances, and to write metrics data to the metrics database. The following example uses the interactive managedomain --menu command: Select option: 2 Select a host: 1) LinuxMint01 2) Enter host name Enter selection from 1-2 [2]: 1 Axway API Gateway Installation Guide 99

100 7 Install and configure API Gateway Analytics Hit enter to continue... Enter a new host name [LinuxMint01]: Enter a new Node Manager name [Node Manager on LinuxMint01]: Enter a new Node Manager port [8090]: There is only one Node Manager in this domain so it must remain as an Admin Node Manager Do you want to create an init.d script for this Node Manager [n]: Do you want to reset the passphrase for the Node Manager on this host? [n]: Do you wish to edit metrics configuration (y or n)? [n]: y Do you wish to enable metrics (y or n)? [y]: y Enter metrics database URL [jdbc:mysql:// :3306/reports]: Enter metrics database username [root]: Enter metrics database plaintext password [*******]: Testing Database connectivity for : jdbc:mysql:// :3306/reports, user : root Metrics database connectivity succeeded Metrics generation enabled. All other specified metrics settings updated. Metrics settings updated successfully. Please reboot Node Manager on completion of this program. Completed successfully. For more details on configuring API Gateway for API Gateway Analytics, see the section on monitoring and reporting in the API Gateway Administrator Guide. Axway API Gateway Installation Guide 100

101 Post-installation 8 This topic describes various tasks that you might perform after installing API Gateway. This includes how to check if an installation has been successful, any initial configuration needed before you can start API Gateway, what you should do to secure API Gateway, and so on. This topic includes the following: Post-installation on page 101 Initial configuration on page 102 Secure API Gateway on page 103 Set up services on page 103 Set up clustering on page 105 Next steps on page 105 Verify the installation To verify your installation, follow these guidelines: Check the installation results Start API Gateway components 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 To start the API Gateway Server and Admin Node Manager, see Start API Gateway on page 76. To start API Gateway Analytics, see Start API Gateway Analytics on page 89. Axway API Gateway Installation Guide 101

102 8 Post-installation Log in to the API Gateway tools To start the Policy Studio desktop tool, see Start Policy Studio on page 81. To log in to the API Gateway Manager web-based administration tool, see Start API Gateway on page 76. To start the Configuration Studio desktop tool, see Start Configuration Studio on page 83. To start the API Tester desktop tool, see Start API Tester on page 84. To log in to the web-based API Gateway Analytics interface, see Start API Gateway Analytics on page 89. To log in to the API Manager web-based tool, see Start API Manager on page 86. Initial configuration Depending on the installation options you selected, the following tasks might need to be completed before you can start API Gateway. Create a new domain If you did not install the QuickStart tutorial, you must use the managedomain script to create a new managed domain that includes an API Gateway instance. 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: First, you must install and configure a database to store the monitoring and transaction data read by API Gateway Analytics. See Configure the metrics database on page 90. Next, you must configure API Gateway Analytics to use this database instead of the default (a MySQL database stored on the local machine). See Configure API Gateway Analytics on page 95. Axway API Gateway Installation Guide 102

103 8 Post-installation Secure API Gateway It is important to secure your API Gateway system as soon as possible after installation, to protect the API Gateway environment from internal or external threats. Change default passwords If you did not set an administrator user name and password during installation, you should change the default administrator user name and password now. For more details on managing administrator users, see the API Gateway Administrator Guide. Change default certificates The default certificates 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 Installation Guide 103

104 8 Post-installation Node Manager: Enter managedomain --menu, and choose option 2, Edit a host. API Gateway instance: Enter managedomain --menu, and choose option 10, Add script or service for existing local API Gateway. Alternatively, you can run managedomain in command mode with the --add_service option to create a service for a Node Manager or API Gateway instance. For more details on managedomain, see the API Gateway Administrator Guide. API Gateway Analytics You can also run API Gateway Analytics as a service. On UNIX/Linux, you must create the script manually. A sample script and ReadMe is provided in the following directory: INSTALL_DIR/analytics/posix/samples/etc/init.d/ On Windows, change to the following directory: C:\INSTALL_DIR\analytics\Win32\bin Enter the following command: installservice.bat "C:\INSTALL_DIR\analytics" "Analytics" "7.5.3" analytics.xml The command options are: <"Installation Path"><"Name"><"Version"><Configuration File> These options are explained as follows: Installation Path: The path to and including API Gateway Analytics. Name and Version: Used to name the Windows service. Configuration File: This should almost always be analytics.xml. The installservice.bat script hard-codes system\conf to give the full path to the existing configuration file. Apache Cassandra For details on running Apache Cassandra as a service, see Install an Apache Cassandra database on page 37. Axway API Gateway Installation Guide 104

105 8 Post-installation Set up clustering To set up API Gateway for high availability, you need to configure an external Apache Cassandra database for clustering. For more information, see the following topics: Configure a Cassandra HA cluster on page 45 Configure API Management in multiple datacenters on page 106 Next steps Consult the API Gateway Administrator Guide for more information on administering, managing, and troubleshooting an API Gateway system. This guide contains many topics that you will find useful after installing API Gateway. For example: Manage an API Gateway domain Configure API Gateway for high availability Backup and disaster recovery Configure scheduled reports Manage user access Axway API Gateway Installation Guide 105

106 Configure API Management in 9 multiple datacenters This topic describes the recommended multi-datacenter configuration that applies to the various types of API Management data in storage. For each data type, it describes how data is replicated across the datacenter, the recommended configuration, and expected behavior in case of failover. This topic includes the following: Multi-datacenter deployment on page 106 Multi-datacenter configuration on page 109 Multi-datacenter failover scenarios on page 127 Multi-datacenter deployment This topic describes the infrastructure required for API Management multi-datacenter deployment. It describes the various types of API Management data. For example, this includes API catalog, client registry, OAuth tokens, quota, Key Property Store (KPS), and so on. It also describes where the data is stored. For example, this includes files on disk, Apache Cassandra database, Ehcache, or Relational Database Management System (RDBMS). For details on supported database versions, see System requirements on page 17. Multi-datacenter deployment architecture The following diagram shows the minimum infrastructure required for API Management multidatacenter deployment. Axway API Gateway Installation Guide 106

107 9 Configure API Management in multiple datacenters This deployment architecture is described as follows: Each datacenter includes the same components deployed in active/active mode. Each datacenter can handle all of the traffic load and can scale in the same way. The API Gateway instances and Cassandra nodes in each datacenter are all highly available. API Gateway group configuration is shared across both datacenters. This means that all API Gateway instances in a group are managed as a single unit, and run the same configuration to virtualize the same APIs and execute the same policies. You must have at least two API Gateway instances per datacenter, at least one of which is an Admin Node Manager. However, you can configure mutliple Admin Node Managers per datacenter for high availability. For more details, see the API Gateway Administrator Guide. The API Gateway group in the internal zone is responsible for API management. The Admin Node Manager is the central administration server responsible for all management operations. For example, this enables API Gateway administrators to perform monitoring in the API Gateway Manager web console. The API Gateway group in the internal zone also hosts the API Manager web console used by API administrators. For more details, see the API Manager User Guide. The API Gateway group in the outer DMZ is responsible for securing traffic. The Node Manager manages local API Gateways instances on that host only. The Cassandra database cluster is required to store data for API Manager or API Gateway client registry (API key or OAuth). You can use Cassandra as an option to store custom KPS data and OAuth tokens. You can also use an RDBMS to store custom KPS, OAuth tokens, or metrics for API Manager or API Gateway Analytics. Axway API Gateway Installation Guide 107

108 9 Configure API Management in multiple datacenters Caching is replicated between API Gateway instances using the Ehcache distributed caching system. For more details, see "Global caches" in the API Gateway Policy Developer Guide. API Management data storage This section describes what API Management data can be persisted and where. API Gateway data Data type Storage location API Gateway configuration Files on disk: API Gateway instance: INSTALL_ DIR/apigateway/groups/group-n/instancen/conf/fed Node Manager/Admin Node Manager: INSTALL_ DIR/apigateway/conf/fed Alternatively, you can use a deployment archive (.fed file). For more details, see the API Gateway DevOps Deployment Guide. API Gateway logs Files on disk: API Gateway instance: INSTALL_ DIR/apigateway/groups/group-n/instance-n/logs Node Manager/Admin Node Manager: INSTALL_ DIR/apigateway/logs API Gateway traffic monitoring Files on disk: API Gateway instance: INSTALL_ DIR/apigateway/groups/group-n/instancen/conf/opsdb.d Node Manager/Admin Node Manager: INSTALL_ DIR/apigateway/conf/opsdb.d API Gateway KPS custom tables Cassandra or RDBMS API Gateway OAuth token store Ehcache, Cassandra, or RDBMS. Axway API Gateway Installation Guide 108

109 9 Configure API Management in multiple datacenters Data type Storage location API Gateway throttling counters Ehcache API Gateway custom cache Ehcache API Manager data Data type API Manager catalog, client registry, web-based settings Storage location Cassandra API Manager quota counters API Manager metrics In memory, Cassandra, or RDBMS RDBMS Further details For more details on concepts such as shared group configuration, Node Manager, and Admin Node Manager, see the API Gateway Concepts Guide. For details on how to configure API Management in multiple datacenters, see Multi-datacenter configuration on page 109 Multi-datacenter failover scenarios on page 127 Multi-datacenter configuration This topic describes the recommended configuration for each API Management data type. It explains the following for each data type: If the data can be replicated across both datacenters (for example, by deploying in both datacenters or automatic replication) How to configure the replication (for example, by configuring Apache Cassandra, Ehcache, or RDBMS) How to install and configure API Gateway and API Manager in multiple datacenters, and how to optimize performance For details on recommended architecture, see Multi-datacenter deployment on page 106. Axway API Gateway Installation Guide 109

110 9 Configure API Management in multiple datacenters API Management configuration The recommended configuration for each data type is as follows: API Gateway data Data type API Gateway configuration API Gateway logs Replication between datacenters You must deploy the API Gateway group configuration in both datacenters. For details on automating deployment processes, see the API Gateway DevOps Deployment Guide. Does not apply (local file-based data only). API Gateway traffic monitoring Does not apply (local file-based data only). API Gateway KPS custom tables API Gateway OAuth token store Automatic. Axway recommends to use Cassandra with replication between datacenters. See Configure Cassandra for multiple datacenters on page 111, or your RDBMS documentation. Axway recommends to use Ehcache, and to generate and use OAuth tokens in the same datacenter only. You should configure sticky sessions in your load balancer. See Configure Ehcache in multiple datacenters on page 123. API Gateway throttling counters Axway recommends to configure at least one distributed cache per datacenter and to avoid replication between datacenters. You should configure sticky sessions in your load balancer. See Configure Ehcache in multiple datacenters on page 123. API Gateway custom cache Axway recommends to configure at least one distributed cache per datacenter and to avoid replication between datacenters. You should configure sticky sessions in your load balancer. See Configure Ehcache in multiple datacenters on page 123. API Manager data Data type Replication between datacenters API Manager catalog, client registry, webbased settings Automatic. Axway recommends to use Cassandra with replication between datacenters. See Configure Cassandra for multiple datacenters on page 111. Axway API Gateway Installation Guide 110

111 9 Configure API Management in multiple datacenters Data type API Manager quota counters API Manager metrics Replication between datacenters In memory only, or automatic when using external storage (Cassandra or RDBMS). See Configure API Manager quota in multiple datacenters on page 127. See also Configure Cassandra for multiple datacenters on page 111, or your RDBMS documentation. Automatic. See your RDBMS documentation. Configure Cassandra for multiple datacenters Cassandra is required to store data for API Manager data, and also recommended for API Gateway custom KPS tables. For details on the recommended Cassandra architecture, see Multi-datacenter deployment architecture on page 106. You must install and configure Cassandra on each node in both datacenters before installing and configuring API Gateway and API Manager. Prerequisites The following prerequisites apply to Cassandra in a multi-datacenter production environment: Ensure that Cassandra version is installed. For details, see Install an Apache Cassandra database on page 37. For details on upgrading Cassandra version, see the API Gateway Upgrade Guide. You must have at least three Cassandra nodes per datacenter. Cassandra must be installed on each node in the cluster, but should not be started until the Cassandra cluster is fully configured. For more details, see Install an Apache Cassandra database on page 37. Configure JAVA_HOME to an Oracle JRE 1.8 installation (OpenJDK is not supported). Each Cassandra node must have Python 2.7 or higher installed. Time must be synchronized on all servers. Determine a naming convention for each datacenter and rack. You should choose the name carefully because renaming a datacenter is not possible. For example: o o DC1, DC2 RACK1, RACK2, RACK3 Determine the seed nodes. You must have at least two Cassandra seed nodes per datacenter. Choose a unique name for the Cassandra cluster. Axway API Gateway Installation Guide 111

112 9 Configure API Management in multiple datacenters To avoid firewall issues, you must open the following ports to allow bi-directional communication among the nodes: o o o 7001: Cassandra TLS/SSL inter-node cluster communication 7199: Cassandra JMX monitoring port (only enabled on localhost for security reasons, you must use SSH to connect the machine). 9042: CQL native client port (only required for an API Gateway or API Manager client connection to Cassandra) Configure your cassandra.yaml file On each node in the cluster, you must configure the following properties in the CASSANDRA_ HOME/cassandra/conf/cassandra.yaml file: Configure multi-datacenter settings Configure the following settings in cassandra.yaml: cluster_name: Your chosen cluster name, common across both datacenters (for example, cassandra-cluster1) num_tokens: 256 endpoint_snitch: GossipingPropertyFileSnitch -seeds: Internal IP address for all seed nodes. Each datacenter should have its own seed node IP addresses first, followed by the other datacenters seed nodes. This is critical for replication. For example: o DC1 seed nodes: , o DC2 seed nodes: , o o DC1 configuration: -seeds: , , , DC2 configuration: - seeds: , , , listen_address: Specify the IP address of the current node that you are configuring start_native_transport: true native_transport_port: 9042 You must remove cassandra-topology.properties from cassandra/conf/. This is not needed when GossipingPropertyFileSnitch is set and could cause conflicts. Axway API Gateway Installation Guide 112

113 9 Configure API Management in multiple datacenters Configure authentication settings Axway recommends enabling authentication. Set the following properties: authenticator: org.apache.cassandra.auth.passwordauthenticator authorizer: org.apache.cassandra.auth.cassandraauthorizer When these properties are set, you must change the default Cassandra user. Configure TLS/SSL traffic encryption Axway recommends enabling inter-node and client to node TLS/SSL encryption. API Management supports TLS v1.2. Node-to-node encryption To enable node-to-node TLS/SSL traffic encryption, set the following properties: server_encryption_options: internode_encryption: all keystore: <server-keystore.jks> keystore_password: <MY_KEYSTORE_PASSWORD> truststore: <server-truststore.jks> truststore_password: <MY_TRUSTSTORE_PASSWORD> require_client_auth: true Client-to-node encryption To enable client-to-node SSL traffic encryption, set the following properties: client_encryption_options: enabled: true optional: false keystore: <client-keystore.jks> keystore_password: <MY_KEYSTORE_PASSWORD> truststore: <client-truststore.jks> truststore_password: <MY_TRUSTSTORE_PASSWORD> require_client_auth: true Configure your cassandra-rackdc.properties file Configure the cassandra/conf/cassandra-rackdc.properties file with your chosen datacenter and rack names for each node, and set prefer_local=true. For example: Axway API Gateway Installation Guide 113

114 9 Configure API Management in multiple datacenters Node DC1, node1 Setting in cassandra-rackdc.properties dc=dc1 rack=rack1 prefer_local=true DC1, node2 dc=dc1 rack=rack2 prefer_local=true DC1, node3 dc=dc1 rack=rack3 prefer_local=true DC2, node1 dc=dc2 rack=rack1 prefer_local=true DC2, node2 dc=dc2 rack=rack2 prefer_local=true DC2, node3 dc=dc2 rack=rack3 prefer_local=true Start your Cassandra nodes When you have configured cassandra.yaml and cassandra-rackdc.properties on all nodes, you can start the seed nodes one at a time, followed by the remaining nodes in each datacenter. For details on starting Cassandra, see Manage Apache Cassandra on UNIX/Linux and Windows on page 59. Configure cqlsh for TSL/SSL encryption If the Cassandra cluster has been configured to use client-to-node TSL/SSL encryption, you must configure all clients connecting to the cluster (including cqlsh) to use TSL/SSL. cqlsh is a Python-based command line client for executing Cassandra Query Language (CQL) commands. To configure cqlsh for TSL/SSL, you must provide the following certificates in a cqlshrc file: certfile.pem: Contains the CA or server certificate of the Cassandra node. This is specified in <client-keystore.jks>. Axway API Gateway Installation Guide 114

115 9 Configure API Management in multiple datacenters usercert.pem: Contains the client certificate for cqlsh. This needs to be added to the Cassandra truststore: <client-truststore.jks> userkey.pem: Contains the private key of client certificate for cqlsh. This cannot contain a passphrase. A sample is provided in cassandra/conf/cqlshrc.sample: When TSL/SSL has been configured, run the following command:./cqlsh -u cassandra -p <MY_PASSWORD> --ssl --cqlshrc=<my_cqlshrc_file> Configure the default system_auth keyspace When all nodes are online, if authentication is enabled, you must set the replication strategy and replication factor for the system_auth keyspace to ensure that credentials are shared across the cluster. You can do this using the cqlsh tool from the cassandra/bin/ directory. You must set the replication strategy to NetworkTopologyStrategy, and ensure the replication factor is set to the number of nodes per datacenter (for example, 3). Naming is case sensitive and the keyspace definition must use the snitch-configured datacenter names used in cassandra-rackdc.properties. For example, on Cassandra node 1 in DC1, perform the following steps: 1. Navigate to the cassandra/bin/ directory 2. Log into cqlsh using with the IP address the current node. For example:./cqlsh -u cassandra -p cassandra Run the following command: ALTER KEYSPACE "system_auth" WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'DC1' : <n>, 'DC2' : <n>}; In this example, <n> is the number of nodes per datacenter. 4. Run nodetool repair on each node as follows:./nodetool repair system_auth 5. Change the default Cassandra user. For more details, see: ml?hl=authentication Axway API Gateway Installation Guide 115

116 9 Configure API Management in multiple datacenters Configure API Management in multiple datacenters When the Cassandra cluster has been setup, you can proceed with installing API Gateway and API Manager. You must have at least two API Gateway instances per datacenter. Configure the first API Gateway node On the first API Gateway host in DC1, perform the following steps: 1. Install API Gateway and API Manager using the API Gateway installer. Do not select Cassandra, which has already been installed. For more details, see Install API Manager on page Register the Admin Node Manager using the managedomain command in INSTALL_ DIR/apigateway/posix/bin. For details, see the API Gateway Administrator Guide. 3. Start the Admin Node Manager using the nodemanager command. 4. Add the API Gateway instance and group using the managedomain command. 5. Before starting the API Gateway instance, add the Cassandra host names and IP addresses as environment variables in your envsettings.props file located in INSTALL_ DIR/apigateway/conf. For example: env.cass.name1=host 10.1 env.cass.name2=host 10.2 env.cass.name3=host 10.3 env.cass.host1= env.cass.host2= env.cass.host3= Start the API Gateway using the startinstance command in INSTALL_ DIR/apigateway/posix/bin. 7. Configure the API Gateway to connect to the Cassandra cluster. In the Policy Studio tree, select Server Settings > Cassandra, and configure the following: Keyspace: Name of the API Gateway Cassandra keyspace to be created when deployed. Defaults to x${domainid}_${groupid}. Hosts: Add the environment variable settings variables that you set in envsettings.props. For example: Authentication: Enter the Cassandra user name and password that you configured earlier (see Configure the default system_auth keyspace on page 115). Axway API Gateway Installation Guide 116

117 9 Configure API Management in multiple datacenters Security: Select Enable SSL, and select a trusted certificate and client certificate. For example: For more details, see the API Gateway Administrator Guide. 8. Click Deploy in the toolbar to deploy the updated configuration. 9. Run setup-apimanager in INSTALL_DIR/apigateway/posix/bin, and specify the API Gateway group and instance names and ports. For example: setup-apimanager --name "SERVER_INSTANCE_NAME" --group "GROUP_NAME" -- portalport API_MANAGER_LISTEN_PORT --trafficport API_MANAGER_TRAFFIC_ PORT For more details, see the API Manager User Guide. 10. For all KPS collections, update the read and write consistency levels to LOCAL_QUORUM. For example, in the Policy Studio tree, select Environment Configuration > Key Property Stores > API Server > Data Sources > Cassandra Storage, and click Edit. Repeat this step for each KPS collection using Cassandra (for example, Key Property Stores > OAuth and API Portal for API Manager). This also applies to any custom KPS collections that you have created. Axway API Gateway Installation Guide 117

118 9 Configure API Management in multiple datacenters Update the Cassandra replication settings for the new API Gateway keyspace When the new API Gateway keyspace has been deployed, you must update its replication strategy and replication factor in the same way as the default system_auth keyspace. This time instead of the system_auth keyspace name, use the name of the newly created keyspace. Perform the following steps: 1. On Cassandra node 1 in DC1, navigate to the CASSANDRA_HOME/cassandra/bin/ directory. 2. Log into cqlsh using with the IP address the current node. For example:./cqlsh Run the following command: ALTER KEYSPACE "<KEYSPACE_NAME>" WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'DC1' : 3, 'DC2' : 3}; 4. On each node, run nodetool repair. Tip In a production environment, you should schedule weekly node repairs as a best practice. For more details, see Perform essential Cassandra operations on page 64. Configure the remaining API Gateway nodes When the API Gateway keyspace has been deployed and its replication updated, you can register the remaining hosts and add API Gateway instances using the managedomain command. Alternatively, you can do this using the API Gateway Manager web console. You should always add one API Gateway instance at a time to the group. For more details on registering hosts and adding API Gateway instances, see the API Gateway Administrator Guide. Configure the API Gateway environment variables in DC1 For each additional API Gateway instance in DC1, add the following to envsettings.props before starting the instance: env.cass.name1=host 10.1 env.cass.name2=host 10.2 env.cass.name3=host 10.3 env.cass.host1= env.cass.host2= env.cass.host3= Axway API Gateway Installation Guide 118

119 9 Configure API Management in multiple datacenters # API Manager Port env.port.apiportal=8075 # API Manager Traffic Port env.port.portal.traffic=8065 Configure the API Gateway environment variables in DC2 For each API Gateway instance in DC2, add the following settings to envsettings.props before starting the instance: env.cass.name1=host 20.1 env.cass.name2=host 20.2 env.cass.name3=host 20.3 env.cass.host1= env.cass.host2= env.cass.host3= # API Manager Port env.port.apiportal=8075 # API Manager Traffic Port env.port.portal.traffic=8065 Add the load balancer host to API Management whitelists For each API Gateway host, you must add the external load balancer host to the whitelists for the Node Manager and API Manager to ensure that it will be accepted in the datacenter. Add load balancer host to Node Manager whitelist You can do this by creating an API Gateway project based on the Node Manager configuration and adding the external load balancer host to the Node Manager whitelist as a servlet property: 1. In Policy Studio, select File > New Project. 2. Enter a project Name, and click Next. 3. Select From existing configuration for the project starting point, and click Next. 4. Click the browse button, select the following directory, and click Finish: INSTALL_DIR/apigateway/conf/fed 5. In the Policy Studio tree, select Environment Configuration > Listeners > Node Manager > Management Services > Paths. Axway API Gateway Installation Guide 119

120 9 Configure API Management in multiple datacenters 6. In the pane on the right, right-click the api servlet, and select Edit. 7. In the Servlet dialog, click Add, and enter the following in the Properties dialog: Name: CsrfProtectionFilterFactory.refererWhitelist Value: 8. Right-click the AppInfo Service servlet, click Edit, and add the same whitelist setting as a property (see previous step). 9. When complete, the configuration is automatically saved to the apiprojects directory used by Policy Studio for your project. To get the Node Manager to read this change, you must copy the contents of your apiprojects subdirectory to apigateway/conf/fed. 10. Finally, you must restart the Node Manager for the configuration changes to be picked up. The following shows an example of configuring the api servlet setting in Policy Studio: You must ensure that every Node Manager has been updated to accept the load balancer host name. You can also add multiple load balancer hosts to the whitelist. For example: Name: CsrfProtectionFilterFactory.refererWhitelist Value: lb.example.com:8090 Add load balancer host to API Manager whitelist You can do this by creating a new project from an API Gateway instance and adding the external load balancer host to the API Manager whitelist as a servlet property: 1. In Policy Studio, select File > New Project from an API Gateway instance. 2. Enter a project Name, and click Next. Axway API Gateway Installation Guide 120

121 9 Configure API Management in multiple datacenters 3. In the Connection Details for the datacenter, enter the load balancer host name in the Host field and your credentials, and click Next. 4. Select the server instance in the datacenter that you wish to update, and click Finish. 5. In the Policy Studio tree, select Environment Configuration > Listeners > API Gateway > API Portal > Paths. 6. In the pane on the right, right-click the API Portal v1.2 ( v1.2 ) servlet, and select Edit. 7. In the Servlet dialog, click Add and enter the following in the Properties dialog: Name: CsrfProtectionFilterFactory.refererWhitelist Value: 8. Right-click the API Portal v1.3 ( v1.3 ) servlet, click Edit, and add the same whitelist property (see previous step). 9. When complete, deploy the configuration to all API Gateways using the load balancer that you added to the whitelist. The following shows an example of configuring the API Portal v1.2 ( v1.2 ) servlet setting in Policy Studio: Optimize API Management performance in a multi-center environment This section explains how to configure various API Gateway settings to optimize API Gateway and API Manager performance in a multi-center environment. Increase maximum received bytes per transaction to optimize API Manager You can configure global API Gateway settings under the Server Settings node in Policy Studio. Axway API Gateway Installation Guide 121

122 9 Configure API Management in multiple datacenters In a multi-datacenter environment with a large number of APIs and a large volume of data, you may need to increase the value of Maximum received bytes per transaction to optimize the performance of the API Manager web console (for example, when viewing APIs in the API catalog). The default value is 10 MB ( bytes). For example, might need to double this setting, depending on the number of APIs and the volume of data in your multi-datacenter environment. To configure this setting, in the Policy Studio tree, select the Server Settings node, and click General in the right pane. To confirm updates, click Apply changes at the bottom right. After changing any settings, you must deploy to the API Gateway for the changes to be enforced. Click the Deploy button in the toolbar, or press F6. Increase API Manager polling time and events time for Cassandra replication When API Manager is deployed in multiple datacenters, and changes to data stored in Cassandra are replicated across datacenters, there is a small risk that the API Gateway runtime in the datacenter where the data is replicated to might operate with outdated data. In this case, to update the data, you must restart all API Gateway instances in the affected datacenter. To minimize this risk, you can use the esexplorer tool to increase the polling time in milliseconds in each API Gateway instance in the datacenter where the data is replicated to. The polling time value must be balanced with the need of having updated data in real time in the API Gateway runtime environment. You must also change the Time To Live (TTL) of the API Manager events table to be consistent with Cassandra for failover situations. Cassandra uses a default value of three hours in its hinted handoff configuration. To configure the API Manager polling time and events table settings, perform the following steps: 1. Change to the following directory: INSTALL_DIR/apigateway/posix/bin 2. Enter the esexplorer command. 3. Select Store > Connect, and browse to the following file: INSTALL_DIR/apigateway/groups/<group-name>/conf/<groupid>/configs.xml 4. Select System Components > Portal Config in the tree on the left. 5. Select the vapipollerperiodms setting in the pane on the right. Double-click the default value of 200, and enter a value in the range of 1000 to milliseconds. As a general rule, the higher the value of the polling time setting, the lower the risk of outdated data in the API Gateway runtime. However, it will take longer to update the data in the replicated datacenter. Axway API Gateway Installation Guide 122

123 9 Configure API Management in multiple datacenters 6. Select the vapieventttlms setting on the right, and double-click to enter a value of milliseconds (3 hours). This is consistent with the default value of the max_ hint_window_in_ms setting in the cassandra.yaml file. 7. When you have completed these settings, you can open the updated API Gateway project in Policy Studio and deploy the updates to all the API Gateway instances in the affected datacenter. Increase Node Manager timeout for longer API Gateway startup In a multi-datacenter environment, it may take longer for API Gateway to start. By default, the API Gateway active timeout is set to 4 mins, however, it may take longer for an API Gateway instance to start up in a multi-datacenter environment. For example, this may result in the Node Manager throwing a 503 error saying that the API Gateway cannot restart. To configure the Node Manager timeout for longer startup time, perform the following steps: 1. Change to the following directory: INSTALL_DIR/apigateway/posix/bin 2. Enter the esexplorer command. 3. Select Store > Connect, and browse to the following file: INSTALL_DIR/apigateway/conf/fed/configs.xml 4. Select Default System Settings in the tree on the left. 5. Select the activetimeout setting in the pane on the right. Double-click the default value of (4 minutes), and enter a higher value to better suit your multi-datacenter environment. 6. Select the maxtranstimeout setting on the right, and double-click to enter a higher value to suit your environment. 7. To update to all Node Managers in the group, you can copy the contents of the updated apigateway/conf/fed directory to the same directory on each node. Alternatively, you can run the esexplorer tool on each node to update the Node Manager settings. Configure Ehcache in multiple datacenters Caching is replicated between API Gateway instances in each datacenter using the Ehcache distributed caching system. In the distributed cache, there is no master cache controlling all caches. Instead, each cache is a peer that needs to know where all the other peers are located. The examples in this section shows distributed caches for OAuth and Throttling. The cache settings are the same in both cases. Axway API Gateway Installation Guide 123

124 9 Configure API Management in multiple datacenters API Gateway only supports the RMICacheReplicatorFactory in Ehcache. Other replication factories are not supported. You should configure at least one distributed cache per datacenter, and should not replicate Ehcache information between datacenters. You should also configure sticky sessions in your load balancer environment to optimize performance. Configure a distributed cache in each datacenter In a distributed cache, each API Gateway has its own local copy of the cache but registers a cache event listener that replicates messages to the other caches so that events on a single cache are duplicated across all other caches. To add a distributed cache, perform the following steps: 1. Select the Environment Configuration > Libraries > Caches tree node, and clicking the Add button at the bottom right. 2. Select Add Distributed Cache from the menu, and configure the following settings on the Configure Distributed Cache dialog: Cache name: Enter a name for the distributed cache (for example, OAuth or Throttling). Event Listener: Properties: Enter the following setting using environment variables for the replication settings: replicateasynchronously=${env.cache.async.replicatio N}, asynchronousreplicationintervalmillis=${env.cache.asyn C.INTERVAL}, replicateputs=true, replicateupdates=true, replicateupdatesviacopy=true, replicateremovals=true It is recommended to set replicateasynchronously to true. The default asychronousreplicationintervalemillis value is 1000 ms if not specified. It is recommended to set this to the minimum of 10 ms. You can leave all other settings on this dialog as default. For example, the required settings are displayed as follows in Policy Studio: Axway API Gateway Installation Guide 124

125 9 Configure API Management in multiple datacenters When the OAuth distributed cache has been configured, it can then be used by the OAuth Access Token Stores. For example, select Environment Configuration > Libraries > OAuth2 Stores > Access Token Stores > OAuth Access Token Stores, and right click to select Edit Access Token Store. Select Store in a cache, and click the browse button to select the OAuth distributed cache. If the OAuth distributed cache is to be used by API Manager, you must also add it in Server Settings > API Manager > OAuth Access Token Stores. Similarly, when a throttling distributed cache has been configured, it can then be used by the API Gateway Throttling filter. For more details, see the API Gateway Policy Developer Filter Reference. Configure distributed cache settings for peer discovery in each datacenter To configure global distributed cache settings for peer discovery, perform the following steps: 1. In Policy Studio, select the Server Settings node, and click General > Cache. 2. Configure the following settings: Peer provider class: Properties: Enter the following setting using an environment variable for the cache URLs: peerdiscovery=manual,timetolive=1,rmiurls=${env.cache. RMI.URL} Axway API Gateway Installation Guide 125

126 9 Configure API Management in multiple datacenters Peer listener class: Properties: Enter the following setting using environment variables for the hosts and ports: hostname=${env.cache.host},port=${env.cache.port},remoteobject Port=${env.CACHE.REMOTE.OBJECT.PORT} sockettimeoutmillis= You can leave all other settings as default. For example, the required settings are displayed as follows in Policy Studio: Set the environment variables on each API Gateway host You must set the environment variables used in the distributed cache in the following file on each host machine: INSTALL_DIR/apigateway/conf/envSettings.props For example: env.cache.rmi.url=// :40001/oauth // :4 0001/Throttle env.cache.host= env.cache.port=40001 env.cache.remote.object.port=40002 env.cache.async.replication=true env.cache.async.interval=10 The env.cache.rmi.url environment variable should only include URLs for host machines in the same datacenter. For more details, see "Global caches" in the API Gateway Policy Developer Guide. Tip For recommendations on Ehcache security, see the following: Axway API Gateway Installation Guide 126

127 9 Configure API Management in multiple datacenters Configure API Manager quota in multiple datacenters API Manager quotas enable you to manage the maximum message traffic rate that can be sent by applications to APIs for back-end protection. You can use the Server Settings > API Manager > Quota Settings in Policy Studio to configure how API Manager quota information is stored. By default, quotas are stored in external storage, and automatically adapt to the configured KPS storage mechanism. However, you can also explicitly configure a storage mechanism of Cassandra, RDBMS, or in memory only. The following general guidelines apply to API Manager quotas : Storing quota in memory only means that the quota calculation is performed by each API Gateway instance in each group between datacenters. If the quota duration is less than 30 seconds, in memory only is automatically activated. Axway recommends using the API Manager system quota (stored in Cassandra) when the backend is shared between datacenters. Axway recommends the API Gateway Throttling filter (stored in Ehcache) for back-end protection per datacenter. For more details on configuring quotas in API Manager, see the API Manager User Guide. Further details For more details on the use of API Gateway environment variables in envsettings.props, see the API Gateway DevOps Deployment Guide. For more details on Cassandra and Ehcache, see the following: For more details on how to configure API Management in multiple datacenters, see: Multi-datacenter deployment on page 106 Multi-datacenter failover scenarios on page 127 Multi-datacenter failover scenarios This topic describes expected behavior in a multi-datacenter deployment in case of failover. It explains how the system will behave in each of the following scenarios: One API Gateway instance is down One Apache Cassandra node is down Axway API Gateway Installation Guide 127

128 9 Configure API Management in multiple datacenters A full datacenter is down The network between two datacenters is down One API Gateway instance is down In this case, one API Gateway instance is down in DC 1: The following applies in this scenario: API requests can no longer be serviced by the API Gateway instance that is not running in DC 1. API requests will be serviced by the remaining API Gateway instance in DC 1. You must restart the API Gateway instance that is not running in DC 1. For more details, see Start API Gateway on page 76. One Cassandra node is down In this case, one Cassandra node is down in DC 1: Axway API Gateway Installation Guide 128

129 9 Configure API Management in multiple datacenters The following applies in this scenario: Cassandra is inherently HA and can tolerate the loss of one Cassandra node only in a datacenter (DC 1 in this case). This ensures 100% data consistency when Cassandra is configured for multiple datacenters. For more details, see Configure Cassandra for multiple datacenters on page 111. You must restart the Cassandra node that is not running in DC 1. For details, see Manage Apache Cassandra on UNIX/Linux and Windows on page 59. When a node has been absent from a cluster for a time, it is brought back into the cluster after restart, and becomes eventually consistent by design. Node repair is required after reintegration into the cluster. For more details, see Perform essential Cassandra operations on page 64. A full datacenter is down In this case, DC 1 is down: Axway API Gateway Installation Guide 129

130 9 Configure API Management in multiple datacenters The following applies in this scenario: API requests can no longer be serviced by DC 1 API requests are automatically directed to DC 2 by the load balancer API Manager quotas remain the same but over less servers You should not deploy updates for the following file-based data types to the API Gateway group: o o API Gateway configuration API Gateway KPS custom table structure There is a risk that end-users may need to re-initiate sessions using the following data types stored in Ehcache: API Gateway OAuth token store API Gateway custom cache Restart the datacenter To restart the datacenter: 1. Restart each of the Cassandra nodes. For details, see Manage Apache Cassandra on UNIX/Linux and Windows on page When all Cassandra nodes are running normally and have synchronized with the rest of the cluster in DC2, you can restart the API Gateways. For details, see Start API Gateway on page 76. The API Gateway should not be restarted prior to a successful restart of all Cassandra nodes. You should run the nodetool repair command on each of the three Cassandra nodes in DC 1 when the datacenter has been down for more than two hours. Axway API Gateway Installation Guide 130

131 9 Configure API Management in multiple datacenters The network between both datacenters is down In this case, the network between DC 1 and DC 2 is down, while both datacenters remain active: The following applies in this scenario: OAuth or throttling data stored in Ehcache per datacenter is not affected You should not deploy updates for the following file-based data types to the API Gateway group: o o API Gateway configuration API Gateway KPS custom table structure For the following data types stored in Cassandra, both datacenters are not synchronized until the network recovers, and then automatically resynchronize: o o API Manager catalog, client registry, web-based settings API Gateway KPS custom table structure For the following file based data types, a single API Gateway Manager web console cannot access both datacenters while the network is down, and can only access each datacenter separately: o o API Gateway logs API Gateway traffic monitoring If the network connection has been down for more than two hours, the following steps are recommended: Run nodetool repair on each of the six nodes in the Cassandra cluster to ensure that the data has synchronized. For more details, see Perform essential Cassandra operations on page 64. Axway API Gateway Installation Guide 131

132 9 Configure API Management in multiple datacenters Restart the API Gateway instances to resynchronize data from Cassandra (potentially in both datacenters if Cassandra changes have occurred in both datacenters). It may take a minute for newly created, deleted, or updated APIs in one datacenter to synchronize successfully with the other datacenter. Further details For more details on how to configure API Management in multiple datacenters, see: Multi-datacenter deployment on page 106 Multi-datacenter configuration on page 109 Axway API Gateway Installation Guide 132

133 Run API Management in Docker 10 This topic describes how to run a multi-node Axway API Management system in Docker, and how to customize the recommended default topology to suit your environment. This topic includes the following: API Management in Docker containers on page 134 Run pre-built API Management Docker images on page 137 Generate API Management Docker images on page 139 Customize your API Management topology in Docker on page 144 Axway API Gateway Installation Guide 133

134 API Management in Docker containers This topic describes how to run a multi-node Axway API Management system in Docker. It provides an overview of the main steps and describes the recommended default topology. Docker containers wrap software in a complete file system that contains everything required to run (for example, code, runtime, system tools, and system libraries). This guarantees that the software always runs the same way, regardless of environment. For more details, see Running your API Management system in Docker makes it easy to quickly build, test, and run API Management solutions in containers for standalone or high availability (HA) deployment. The API Management sample system supports Docker version 1.13.x, and includes API Gateway, API Manager, and Apache Cassandra. For details onapi Portal Docker support, see the API Portal Installation and Upgrade Guide. This topic assumes that you have working knowledge of API Management architecture, Apache Cassandra, and Docker. For more details, see the following: API Gateway Concepts Guide Install Apache Cassandra on page 37 Create Docker images using scripts Axway provides Docker files and compose scripts to enable you to create custom Docker images for API Gateway, API Manager, and Apache Cassandra. You can deploy these images in Docker containers on any host operating system or cloud platform that supports Docker (for example, IBM Bluemix or Amazon Web Services). The API Management sample system supports both CentOS Linux 7 and Red Hat Enterprise Linux 7 base images, which you can customize to generate your API Management Docker topology. Generating custom Docker images using scripts is the recommended approach in an HA production environment. The following diagram shows a high-level overview of the steps to create and deploy your desired API Management topology: Axway API Gateway Installation Guide 134

135 These steps are described in the following sections: Set up your local environment on page 139 Create your API Management Docker infrastructure on page 140 Deploy your Docker infrastructure to the cloud on page 137 Run pre-built Docker images Axway also provides pre-built Docker images (CentOS Linux 7 base image only), which you can download from Axway Support. These pre-built CentOS 7 Docker images are recommended for development and test purposes in an standalone environment only, and are not designed for use in an HA production environment. For production environments, see Create Docker images using scripts on page 134. For more details, see Run pre-built API Management Docker images on page 137. API Management Docker HA topology This section describes the default API Management topology that is generated in the 3-node sample system, which is recommended for an HA production environment: Axway API Gateway Installation Guide 135

136 This sample topology includes the following: Three Docker containers each including API Gateway, API Manager, and an Admin Node Manager or Node Manager. 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. Multiple Docker data volumes per container to manage persistence of API Gateway and Cassandra configuration data. Axway provides scripts to build Docker images and generate a docker-compose.yml configuration for running the API Management solution on a single host. You can specify which components are included in the solution: API Gateway, API Manager, Admin Node Manager, and Node Manager (non-admin). You can also configure Docker data volumes for persistence. For more details, see Generate API Management Docker images on page 139. Axway API Gateway Installation Guide 136

137 Deploy your Docker infrastructure to the cloud For details on how to deploy your Docker infrastructure in the cloud, see the product documentation for your chosen third-party cloud platform. For example, this includes Platform as a Service (PaaS) environments such as IBM Bluemix or Amazon Web Services. For more details, see the following: Further information on Docker For more details on Docker, see the following: Run pre-built API Management Docker images Axway provides the following pre-built Docker images with CentOS Linux 7 as the base O/S: CentOS 7 with API Gateway and API Manager installed and configured CentOS 7 with Apache Cassandra and customizations for API Manager CentOS 7 with API Portal installed and configured This topic explains how to run the API Gateway and API Manager image and the Cassandra image. For details on the API Portal image, see the API Portal Installation and Upgrade Guide. These pre-built Docker images are recommended for development and test purposes in an standalone environment only, and are not designed for use in an HA production environment. For production environments, see Generate API Management Docker images on page 139. Prerequisites The following components are required on your system: Docker version 1.13.x Docker Compose version x API Gateway Docker images available from Axway Support API Gateway license file Axway API Gateway Installation Guide 137

138 Docker images require an API Gateway license that is not restricted to a specific host name. For more details, contact your Axway account manager. Run pre-built API Management images in a developement or test environment Perform the following steps: 1. Download the following file from Axway Support and extract to the current directory: APIGateway_7.5.3_DockerImage_Topology_linux-x86-64_BN<n>.tar.gz 2. Provide a license file in current directory (for example, my-apigateway-license.lic). 3. Load the Cassandra Docker image: docker load <./cassandra_centos-latest.tar.gz 4. Load the API Gateway Docker image: docker load <./gwlatest-1node-node1-centos-latest.tar.gz 5. Set the APIGW_LICENSE variable: export APIGW_LICENSE="$(cat./my-apigateway-license.lic gzip base64)" 6. Run the Docker images: docker-compose up Test the API Management system You can view and test the API Management sample system by accessing the following web consoles in a browser: API Gateway Manager API Manager For more details on using these tools, see the following: Axway API Gateway Installation Guide 138

139 API Gateway Administrator Guide API Manager User Guide Generate API Management Docker images This topic describes how to generate and configure custom API Management Docker images using scripts. This approach is recommended in a production environment for high availability. For details on how to download and run pre-built Docker images in a development or test environment, see Run pre-built API Management Docker images on page 137. Set up your local environment The following components are required on your system: Docker API Management supports the following: Docker version 1.13.x Docker Compose version x API Management The following components are required: API Gateway Linux installer available from Axway Support API Gateway Docker scripts available as a separate zip file from Axway Support API Gateway license file Docker images require an API Gateway license that is not restricted to a specific host name. For more details, contact your Axway account manager. Specify an API Gateway license file For details on how to specify a license file, see Step 1 Build your Docker images on page 141. You can also set the APIGW_LICENSE variable on the host machine that runs the Docker daemon. For example, this is useful when running a pre-built Docker image in a development environment. For details, see Run pre-built API Management Docker images on page 137. The following command shows an example of setting this variable: export APIGW_LICENSE="$(cat /path/to/license/my-apigateway-license.lic Axway API Gateway Installation Guide 139

140 gzip base64) If the APIGW_LICENSE environment variable is set, and a license file named lic.lic already exists in the container, the environment variable overrides the license file at runtime. If a license file does not exist, a new lic.lic file is created and populated with the value of this variable (in compressed and base-64 decoded format). If this variable is not set or invalid, and there is no license file in the container, the API Gateway fails to start up. Python Python version 2.7.x is required to create Docker data volumes. For more details, see Customize your API Management topology in Docker on page 144. Minimum disk space and memory The following are required for the 3-node sample architecture: At least 100 GB of disk space At least 16 GB of RAM Tip On Linux systems, the free -h command provides human-readable information about the amount of free and used memory in the system. You can also use other tools such as top and vm_stat to get this information. See also Troubleshooting on page 144. Create your API Management Docker infrastructure When you have set up your environment, the steps to create your API Management Docker infrastructure are as follows: These steps are described in the following sections: Axway API Gateway Installation Guide 140