Bridgehub Install Guide

Anne Ramey

Installation

Note These installation instructions assume a Tomcat webserver. If not using a Tomcat server, use your webserver's method for deploying .war files.

  1. Ensure Tomcat is Running
  2. Copy the kinetic-bridgehub (.war file) to the /webapps directory
  3. Optionally configure the applications data directory to store configurations outside of the kinetic-bridgehub webapp (this will make future upgrades much easier).
  4. Navigate to the Bridgehub console (http://your-web-server/kinetic-bridgehub)
  5. The default admin username & password is admin/admin

Configuring the Console

Navigating to the Setup tab allows you to edit configuration details for the Bridgehub console.

The Configurator Username and Configurator Password allow you to modify the username/password combination that is needed to log into the Bridgehub Admin Console.

  • Log Level allows you to choose how verbose the bridge logging will be.

    • Info (Production) will log only necessary information
    • Debug (Development) will log events such as incoming requests
    • Trace (Troubleshooting) is the most verbose logging available
  • Log Size (MB) is the size that the Current Log is allowed to be in MB.

Creating a New Bridge

Click the Add Bridge button to start the process of creating a new Bridge.

From the Bridge Adapter dropdown, choose the type of Bridge Adapter that you want to create.

bridgehub-choose-bridge-adapter

After selecting a Bridge Adapter type, you will need to fill in the properties for your new Bridge.

bridgehub-setup

  • Name: The Display Name for the Bridge
  • Slug: Unique short name/id for the Bridge (no spaces)
  • Use Access Keys?: An extra security measure that can be used alongside IP Address restrictions to only allow access to requests that include a pre-generated access/secret key combination (similar to passing a username/password along with a request)
  • Servers Allows API Access: A comma separated list of IP Addresses (* to allow all IPs) - Defaults to ipv4 and ipv6 localhost addresses
  • Any remaining properties are specific to the selected Bridge Adapter Class. See the individual documentation for each adapter to get more specifics about those properties.

Adding a New Access Key

When a bridge configuration has Use Access Keys set to Yes, the access key management (on the right side of the edit screen) will be shown.

bridgehub-add-access-keys (1)

When adding access key the application will generate a secure and random access key and secret. It is also possible to edit these to values of your choosing when creating or editing access keys. It is also recommended to include a short description to denote who or what the key/secret will be used for.

Keep note of the access key and secret, which will be necessary for the user or integrating application to create signatures to authenticate the bridge request. All previously created access key/secret combinations will be available to view or edit on the bridge edit page.

bridgehub-added-access-key (1)

Configuring Bridgehub Clustering Support with Cassandra

Configuring Bridgehub clustering allows multiple Bridgehub instances to be running with the same exact configuration. Any time an update happens in one Bridgehub instance, the other Bridgehub instances that are running in that cluster will automatically update the configuration details that changed. This cluster support makes it easier to run a load balancer among multiple Bridgehub instances. This clustering is accomplished by storing the configuration information in a Cassandra database and then having each Bridgehub instance poll for changes that happen on other instances in the cluster.

Setting up Cassandra

To setup Cassandra it is recommended to either use cqlsh (a command line program) or DevCenter (a GUI program).

Create your keyspace

There are multiple way to create a keyspace in Cassandra, so no one example will universally work for all environments. The following are a couple examples labeled with what situation they are used in.

Example Development Keyspace

CREATE KEYSPACE IF NOT EXISTS kinetic_bridgehub_development WITH REPLICATION = { 'class': 'SimpleStrategy', 'replication_factor': 1 };

Example Production Keyspace

CREATE KEYSPACE IF NOT EXISTS kinetic_bridgehub_production WITH REPLICATION = { 'class': 'SimpleStrategy', 'replication_factor': 3};

Use the keyspace that was created USE kinetic_bridgehub_development;

Create the tables that are needed for clustering and storing created Bridge configurations

CREATE TABLE IF NOT EXISTS cluster_events (
    action text,
    bucket text,
    content text,
    id timeuuid,
    source_node_key text,
    PRIMARY KEY ((bucket), id)
)
WITH CLUSTERING ORDER BY (id ASC)
 AND COMPACTION={
    'sstable_size_in_mb': '256',
    'tombstone_threshold': '0.05',
    'unchecked_tombstone_compaction': 'true',
    'tombstone_compaction_interval': '3600',
    'class': 'LeveledCompactionStrategy'
};

CREATE TABLE IF NOT EXISTS cluster_configuration_items (
    bucket text,
    content text,
    key text,
    PRIMARY KEY ((bucket), key)
)
WITH CLUSTERING ORDER BY (key ASC)
 AND COMPACTION={
    'sstable_size_in_mb': '256',
    'tombstone_threshold': '0.05',
    'unchecked_tombstone_compaction': 'true',
    'tombstone_compaction_interval': '3600',
    'class': 'LeveledCompactionStrategy'
};

Setting up Tomact

Connection Details in Tomcat

Specify the following Cassandra connection details as Java System Properties for the Tomcat instance running Kinetic Bridgehub

Property Name Sample Value Description
com.kineticdata.bridgehub.clustering.contactpoints 127.0.0.1 Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology (Read a more detailed explanation of contact points in the DataStax Documention).
com.kineticdata.bridgehub.clustering.keyspace kineticbridgehubdevelopment The name of the keyspace that you previously created to store Bridgehub's data.
com.kineticdata.bridgehub.clustering.username a_user The username for the Cassandra instance.
com.kineticdata.bridgehub.clustering.password a_password The password for the Cassandra instance.
com.kineticdata.bridgehub.clustering.useSsl false true to use SSL, false if you are not.
com.kineticdata.bridgehub.clustering.ssl.keystore /path/to/client.keystore Fully qualified path to the keystore file.
com.kineticdata.bridgehub.clustering.ssl.keystore.password secret_password Password for the keystore (default blank)
com.kineticdata.bridgehub.clustering.ssl.truststore /path/to/client.truststore Fully qualified path to the truststore file.
com.kineticdata.bridgehub.clustering.ssl.truststore.password secret_password Password for the truststore (default blank)

Connection details in clustering.properties file

Cassandra clustering connection details can also be defined in place of or alongside the Java System Property configuration values in a clustering.properties property file. This file should be placed in the Bridgehub data directory and the properties correspond to the Java System Properties with the com.kineticdata.bridgehub.clustering remove from the front of the property. Below is what a sample property file might look like:

contactpoints=127.0.0.1
keyspace=kinetic_bridgehub_development
username=a_user
password=a_password
useSsl=false
ssl.keystore=/path/to/client.keystore
ssl.keystore.password=secret_password

Restart Tomcat

Restart any tomcat instance that java properties were added to - the changes won't take affect until restart.

Structured Logging

Kinetic Bridgehub v1.2.0 introduced Structured Logging into the application. Structured logging essentially is ensuring that a log file is a preset, consistent, and machine readable format. Structured logs are useful for enterprise log aggregation tools like Splunk, Graylog, or Elastic.