Square Bubble Version 2 Installation Guide

Install Square Bubble

We recommend you read all the instructions before you start the install. We also assume all the commands need to be run as root (preferably via sudo) unless otherwise stated.

RPM Install

rpm
  1. Download the rpm using the link provided.
  2. Install the rpm using the command (assumes the rpm file is in the current directory):
    • RHEL 6 (or equivalent):
      [...] # sudo yum install sqrbbl-<version>.noarch.rpm
    • RHEL 7 (or equivalent):
      [...] # sudo dnf install sqrbbl-<version>.noarch.rpm

    As well as installing the software, this command will also create the user and group named sqrbbl. The application shall be run as this user which requires no special privileges. This is a security best practice.

  3. Download and install Java. The minimum version supported is Java Standard Edition (Java SE) Version 7. We recommend you use the latest version available as will have the latest security patches. Square Bubble has been tested with OpenJDk, Oracle and IBM JVMs. The JDK is required to enable the stop script. The IBM JDK does not work using the attach api during the stop operation, so the process will instead be killed.
  4. Configure JAVA_HOME & PATH environment variables by editing the file /etc/sqrbbl/sqrbbl-setup and setting up access to java. You can use any editor to do this (such as vi), but as an example, this is what the file should look like to use the Oracle java install:

    #!/bin/sh
    # run time config for Square Bubble Version 2
    # use this config script to set PATH to point to the correct version of java, example below

    JAVA_HOME=/usr/java/jdk1.8.0_161
    export PATH=${JAVA_HOME}/bin:${PATH}

    # set square bubble options (other than config & licensedir), such as
    #SQRBBL_OPTS="-props /etc/sqrbbl/sqrbbl-props"
    SQRBBL_OPTS="-startsec 0"

    # and set any additional java options required, as follows
    START_JAVA_OPTS="-server -Xmx256m"
    STOP_JAVA_OPTS=""

  5. Configure the IIB, MQ and DataPower instances you wish to monitor as well as the desired output (e.g. splunk). To do this you need to edit the /etc/sqrbbl/sqrbbl-config.xml and modify as directed by our Configuration guide.
  6. Copy the license file provided into the license directory, /etc/sqrbbl/license.d
  7. Validate the configuration as directed in the Operating Guide.
  8. Start the service as directed in the Operating Guide

    You should then see data appearing in the output destinations, such as Square Bubble splunk app, within a few minutes.


Tar Install

tar
  1. Download the tar file from the provided link
  2. Extract the tar file using the command:
    [...] $ cd <install target base>
    [...] $ tar xf <tarfile>

    This will create a directory called sqrbbl-<version>, which we will refer to as the install directory.
  3. cd into the install directory sqrbbl-<version> (all commands assume you are in the installation directory from here on, denoted by ./)
  4. remove the README file in the ./license.d/ directory
  5. copy the provided license file into the ./license.d/ directory
  6. Download and install Java. The minimum version supported is Java Standard Edition (Java SE) Version 7. We recommend you use the latest version available as will have the latest security patches. Square Bubble has been tested with OpenJDk, Oracle and IBM JVMs. The JDK is required to enable the stop script. The IBM JDK does not work using the attach api during the stop operation, so the process will instead be killed.
  7. Configure JAVA_HOME & PATH environment variables by editing the file ./sqrbbl-setup and setting up access to java. You can use any editor to do this (such as vi), but as an example, this is what the file should look like to use the Oracle java install:

    #!/bin/sh
    # run time config for Square Bubble Version 2
    # use this config script to set PATH to point to the correct version of java, example below

    JAVA_HOME=/usr/java/jdk1.8.0_161
    export PATH=${JAVA_HOME}/bin:${PATH}

    # set square bubble options (other than config & licensedir), such as
    #SQRBBL_OPTS="-props /etc/sqrbbl/sqrbbl-props"
    SQRBBL_OPTS="-startsec 0"

    # and set any additional java options required, as follows
    START_JAVA_OPTS="-server -Xmx256m"
    STOP_JAVA_OPTS=""

  8. configure Square Bubble by modifying the ./etc/sqrbbl-config.xml file (more details can be found in the configuration guide), you may notice that the config is setup to run against a local IIBV10 instance (without MQ) and provides output to a file. This is a good place to start to check you can connect and acquire data.
  9. The XML can be validated using xmllint. Using an XML editor is recommended.
  10. You can also validate by using the ./bin/validate script. This will test all connections can be made if the XML parses successfully and a valid license file is found.
  11. To start run ./bin/start-sqrbbl, this will put the running agent in the background, you can check the progress by tailing the file in ./log/sqrbbl.log. If Square Bubble fails to start, and therefore fails to create the log file, all other output will be in ./log/sqrbbl-stdouterr.log.

Install with Splunk

To use with Splunk:

  1. Optionally download, install and run Splunk enterprise or Splunk Light. The latest version is recommended. Refer to the Splunk Installation Manual for more details. Alternatively if you wish to use Splunk cloud, you will need to request splunk to install the application for you and skip the next step.
  2. Install the Square Bubble Version 2 splunk app on the running splunk instance. The file can be found in /opt/syntegrityinnovations/sqrbbl/splunk/SquareBubble-splunk.tar.gz for rpm installs or <install directory>/splunk/SquareBubble-splunk.tar.gz for tar installs
    • For Splunk Enterprise
      • For a standalone (or a combined indexer/search head) select 'Manage Apps' followed by 'Install app from file' and select the file (sqrbblinstall|localdir)/splunk/SquareBubble-splunk.tar.gz.
      • For a distributed deployment (with discrete search heads and indexers), the Square Bubble Splunk app needs to be repackaged using the Splunk Packaging Toolkit to partition the app accordingly. This will generate packages specific to the search head and indexers. The packages should then be deployed as required. Use of the deployment server should be considered here also.
    • For Splunk Light:
      • from the cmd line, install the square bubble splunk app (this will create the indexes and the dashboards, the latter will not be available initially) using the splunk cli as the splunk user. You will need to either access the local sqrbbl install or copy the tar.gz file from a sqrbbl install. Use the command (example from a linux machine):
        splunk@...:${splunkinstall}$ bin/splunk install app (sqrbblinstall|localdir)/SquareBubble-splunk.tar.gz
      • from the cmd line or file system explorer/navigator copy the contents of ${splunkinstall}/etc/apps/sqrbbl/default/data/ui/views/*.xml to ${splunkinstall}/etc/apps/search/local/data/ui/views (example below is a cmd line on linux with current directory being the splunk install directory such as /opt/splunk):
        splunk@...:/opt/splunk$ cp ./etc/apps/sqrbbl/default/data/ui/views/*.xml ./etc/apps/search/local/data/ui/views/
      • Restart Splunk Light
  3. For all cases involving splunk, consider creating a non-admin user for the users to view the dashboards. This will prevent updates to be made.

Install with Elastic

To use with the Elastic Stack:

  1. Download, install and run Elasticsearch V5.x, available from the download page .
  2. Download, install and run Kibana V5.x, available from the download page.
  3. Import the kibana artifacts. To do this you need to
    • cd to the elastic dir that was installed with Square Bubble. For the rpm this is in /opt/syntegrityinnovations/sqrbbl/elastic and for the tar install it is in <install dir>/elastic
    • Import the artifacts using the provided load script (./loadv5.sh) with the following options:
      • -h | -help - Print the help menu.
      • -l | -url - Elasticsearch URL. By default is http://localhost:9200.
      • -u | -user - Username and password for authenticating to Elasticsearch using Basic Authentication. The username and password should be separated by a colon (i.e. "admin:secret"). By default no username and password are used.
      • -i | -index - Kibana index pattern where to save the dashboards, visualizations, index patterns. By default is ".kibana".

      for example:
      [.../elastic] $ ./loadv5.sh
      Will load the dashboards etc into the .kibana index on the local machine running Elasticsearch.

The landing page can be found in the Dashboard called ".Square Bubble Version 2 landing page". From here you can load any of the provided Dashboards


Upgrade

This section is only applicable to installs using the rpm

We recommend you read all the instructions before you start the install. We also assume all the commands need to be run as root (preferably via sudo) unless otherwise stated.

  1. Download the rpm using the link provided.
  2. Stop the service as directed in the Operating Guide.
  3. Refer to the appropriate release notes to determine if any other operations are required, such as data backups or configuration updates
  4. Upgrade the rpm using the command (assumes the rpm file is in the current directory):

    [...] # yum update sqrbbl-<version>.noarch.rpm

  5. Optionally update the Square Bubble Version 2 splunk app on the running splunk instance. The file can be found in /opt/syntegrityinnovations/sqrbbl/bin/SquareBubble-splunk.tar.gz
  6. Optionally, you may need to amend your configuration as directed by our Configuration guide.
  7. Validate the configuration as directed in the Operating Guide.
  8. Start the service as directed in the Operating Guide.

    You should then see data appearing in the output destinations, such as Square Bubble for IBM Integration Bus & MQ splunk app, within a few minutes.


Uninstall

All the commands need to be run as root (preferably via sudo) unless otherwise stated.

  1. Stop the service as directed in the Operating Guide.
  2. Remove the rpm using the command:

    [...] # yum remove sqrbbl

You may see some files still in the /etc/sqrbbl directory. You can remove these manually if no longer needed