Setting up Siren Investigate
This section includes information on how to set up Siren Investigate and get it running, including:
-
Supported platforms and version compatibility
-
Installing
-
Configuring
-
Upgrading
The instructions in this section are relevant for production deployments only. For a quick trial of Siren, download the Easy Start version and follow the instructions in the README file. |
Supported platforms
Packages of Siren Investigate are provided for and tested with Windows, Linux, and macOS operating systems.
Because Siren Investigate runs on Node.js, the required Node.js binaries for these platforms are included. Running Siren Investigate against a separately maintained version of Node.js is not supported. |
Siren Platform is supported on the following Web browsers:
-
Google Chrome
-
Mozilla Firefox
Siren Platform version compatibility
Each Siren Investigate version supports different Elasticsearch/Siren Federate versions in the following way:
-
Minimum supported version: Includes the set of features that are compatible with the Elasticsearch/Siren Federate version that is used.
-
Feature complete version: Includes all of the current Siren Investigate features.
-
Target version: Includes all of the current Siren Investigate features and, being the most up-to-date version, is recommended in most cases.
Version compatibility matrix
APIs are at risk of breaking if your Elasticsearch or Siren Federate back-end system is a more recent release than the Siren Investigate version. To reduce this risk, ensure that the difference is limited to only a minor release from the target version; that is, the second number in the sequence <major_release>.<minor_release>.<patch_release>. |
Siren Investigate | Siren Federate | Elasticsearch |
---|---|---|
11.1 |
Minimum: 6.8.0-10.3.0; Feature complete: 6.8.0-10.3.0; Target: 7.13.3-25.0 |
7.13.3; 7.10.2; 7.9.2; 7.9.1; 7.8.0; 7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0 |
11.0 |
Minimum: 6.8.0-10.3.0; Feature complete: 6.8.0-10.3.0; Target: 7.9.2-21.1 |
7.9.2; 7.9.1; 7.8.0; 7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0 |
10.5.4 |
Minimum: 6.8.0-10.3.0; Feature complete: 6.8.0-10.3.0; Target: 7.9.2-21.1 |
7.9.2; 7.9.1; 7.8.0; 7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0; 6.5.4 |
10.5.3 |
Minimum: 6.5.4-10.2.0; Feature complete: 6.8.0-10.3.0; Target: 7.6.2-20.0 |
7.9.1; 7.8.0; 7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0; 6.5.4 |
10.5.2 |
Minimum: 6.5.4-10.2.0; Feature complete: 6.8.0-10.3.0; Target: 7.6.2-20.0 |
7.8.1; 7.8.0; 7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0; 6.5.4 |
10.5.1 |
Minimum: 6.5.4-10.2.0; Feature complete: 6.8.0-10.3.0; Target: 7.3.2-19.1 |
7.8.0; 7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0; 6.5.4 |
10.5.0 |
Minimum: 6.5.4-10.2.0; Feature complete: 6.8.0-10.3.0; Target: 7.3.2-19.1 |
7.7.1; 7.6.2; 7.3.2; 6.8.12; 6.8.6; 6.8.2; 6.8.0; 6.5.4 |
10.4.1 |
6.8.6-10.3.5 |
6.8.6 |
10.4.0 |
6.8.6-10.3.4 |
6.8.6 |
Installing Siren Investigate
Siren Investigate is provided in the following package formats:
|
The |
|
Siren Investigate Docker images are available at https://hub.docker.com/u/sirensolutions/. |
Prerequisites
Ensure that you have obtained a license for Siren Platform on the Siren Support Portal.
On Windows, you must install a modern ZIP manager such as 7-zip to extract the platform archives: Windows' built-in ZIP support cannot process the large number of files in the package.
Installing Siren Investigate with the ZIP package
Siren Investigate is provided for Windows, Linux, and macOS as a .zip
package. These packages are the easiest formats to use when you are trying Siren Investigate for the first time.
The latest version of Siren Investigate can be found on the Siren Support Portal. Descriptions of the separate demonstration packages are also available.
Installing on Linux or macOS
You can download the Linux or macOS (Darwin) .zip
packages from the Siren Support Portal download page.
Save the compressed file and extract it to a local directory.
If you are running macOS Catalina or a later version, you must remove an extended file attribute (xattr) before you extract the downloaded ZIP file. Run the following command:
|
Running Siren Investigate from the Terminal
Start Siren Investigate by opening a Terminal window and running the following command:
./bin/investigate
By default, Siren Investigate runs in the foreground, prints its logs to
STDOUT
, and can be stopped by pressing Ctrl + C
. The installation is complete when you see the message “[plugin:graph_browser_vis] Status changed from yellow to green - Initialized” in the log window.
After the installation is complete, open a Web browser and navigate to http://localhost:5606.
Folder layout of the ZIP archive
The .zip
packages are entirely self-contained. This is very convenient because you do not have to create any directories to start using Siren Investigate, and uninstalling is as easy as removing the folder.
However, it is advisable to change the default locations of the configuration and data folders so that you do not remove important data later on.
Type | Description | Default Location | Setting |
---|---|---|---|
home |
Siren Investigate home folder or |
Folder
created by unpacking the archive; in demonstration distributions, the
folder is |
|
bin |
Binary scripts including |
|
|
config |
Configuration files including |
|
|
data |
The location of the data files written to disk by Siren Investigate and its plugins |
|
|
optimize |
Transpiled source code. Certain administrative actions, for
example |
|
|
plugins |
The location of the plugin files. Each plugin will be contained in a subfolder. |
|
Installing Siren Investigate on Windows
Download the Windows .zip
package from the Siren Support Portal download page.
Save the compressed file and extract it to a local directory.
Running Siren Investigate from the command prompt
Start Siren Investigate by opening a command prompt and running the following command:
.\bin\start.bat
You can also run the installation by simply double-clicking on the start.bat
file.
By default, Siren Investigate runs in the foreground, prints its logs to
STDOUT
, and can be stopped by pressing Ctrl + C
. The installation is complete when you see the message “[plugin:graph_browser_vis] Status changed from yellow to green - Initialized” in the log window.
After the installation is complete, open a Web browser and navigate to http://localhost:5606.
Folder layout of Windows ZIP archive
The .zip
package is entirely self-contained.
This is very convenient because you do not have to create any directories to start using Siren Investigate, and uninstalling Siren Investigate is as easy as removing the folder. However, it is advisable to change the default locations of the configuration and data folders so that you do not remove important data later on.
Type | Description | Default Location | Setting |
---|---|---|---|
home |
Siren Investigate home folder or |
Folder
created by unpacking the archive; in demonstration distributions, the
folder is |
|
bin |
Binary scripts including |
|
|
config |
Configuration files including |
|
|
data |
The location of the data files written to disk by Siren Investigate and its plugins |
|
|
optimize |
Transpiled source code. Certain administrative actions, for
example |
|
|
plugins |
The location of the plugin files. Each plugin will be contained in a subfolder. |
|
Running Siren Investigate on Docker
Docker images for Siren Investigate are available from the sirensolutions organization on Dockerhub.
Pulling the Image
Obtaining Siren Investigate for Docker is as simple as issuing a docker pull command.
Option 1: To retrieve the Docker image for the latest version of Siren Investigate, run the following command:
docker pull sirensolutions/siren-platform:latest
docker run -d -p 5606:5606 -p 9220:9220 sirensolutions/siren-platform:latest
Option 2: To retrieve a specific version of Siren Investigate, such as version 10.0.0, run the following command:
docker pull sirensolutions/siren-platform:10.0.0
docker run -d -p 5606:5606 -p 9220:9220 sirensolutions/siren-platform:10.0.0
Option 3: To retrieve an image that is pre-populated with demonstration data, run the following command:
docker pull sirensolutions/siren-platform-demo-data:latest
docker run -d -p 5606:5606 -p 9220:9220 sirensolutions/siren-platform-demo-data:latest
Environment variable configuration
Under Docker, Siren Investigate can be configured by using environment variables. When the container starts, a helper process checks the environment for variables that can be mapped to Siren Investigate command-line arguments.
For compatibility with container orchestration systems, these environment variables are written in all capitals, with underscores as word separators. The helper translates these names to valid Siren Investigate setting names.
Some example translations are provided as follows:
Environment Variable |
Siren Investigate Setting |
|
|
|
|
|
|
In general, any setting listed in Configuring Siren Investigate can be configured with this technique.
These variables can be set by using docker-compose as follows:
services:
investigate:
image: docker.elastic.co/kibana/kibana:10.0.0
environment:
SERVER_NAME: siren.example.org
ELASTICSEARCH_URL: http://elasticsearch.example.org
Because environment variables are translated to CLI arguments, they take
precedence over settings that are configured in the investigate.yml
file.
Upgrading Siren Investigate
To upgrade Siren Investigate, follow these steps:
-
Save a copy of the Siren Investigate configuration file:
config/investigate.yml
. -
Save a copy of any certificate or key that is referenced by
config/investigate.yml
; by convention, these files are stored in a directory namedpki
. -
Create a back-up of the saved objects index or mappings (for example,
.siren
) and the security index or mappings (for example,.sirenaccess
) by running the following command:bin/investigate backup --backup-dir=DIR
-
In the new version of Siren Investigate, overwrite the
investigate.yml
file in theconfig
folder with the one that you saved in step 1. -
Restore the files or directories that you saved in step 2 by copying them to the same relative locations in the new installation directory.
-
In the
/plugins
folder, install the compatible versions of any third-party Siren Investigate plug-ins that you need. -
Run the following upgrade command:
bin/investigate upgrade
Configuring Siren Investigate
The Siren Investigate server reads properties from the
investigate.yml
file on startup. The default settings configure
Siren Investigate to run on localhost:5606
. To change the host or
port number, or connect to Elasticsearch running on a different machine,
you must update your investigate.yml
file. You can also enable SSL
and set a variety of other options.
External datasource configuration is documented in the Working with JDBC datasources while access control configuration is documented in Search Guard integration and Siren Investigate access control.
Environment Variable Placeholders
It is possible to use environment variable placeholders in configuration
settings. The syntax of placeholders is ${ENV_VARIABLE_NAME}
.
For example, to set elasticsearch.url
to the value of the
environment variable ES_URL
, edit config/investigate.yml
as
follows:
elasticsearch.url: ${ES_URL}
Setting | Description |
---|---|
|
Default: |
|
Default: |
|
Enables you to specify a path to mount Siren
Investigate as if you are running behind a proxy. This only affects the
URLs generated by Siren Investigate, your proxy is expected to remove
the basePath value before forwarding requests to Siren Investigate. This
setting cannot end in a slash ( |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
The tilemap is the base layer the map visualizations. To increase max zoom level for mapping visualizations, copy the following object in the `investigate.yml`file, this will increase the zoom level to 19 from the default of 15.
|
|
The URL to the tile service that Siren Investigate uses to display map tiles in tilemap visualizations. By default, Siren Investigate reads this URL from an external metadata service, but users can still override this parameter to use their own Tile Map Service. |
|
Default: |
|
Default: |
|
Default:
|
|
An array of subdomains used by the
tile service. Specify the position of the subdomain in the URL with the
token |
|
Specifies additional vector layers for use in Region Map visualizations. Each layer object points to an external vector file that contains a GeoJSON FeatureCollection. The file must use the WGS84 coordinate reference system and only include polygons. If the file is hosted on a separate domain from Siren Investigate, the server needs to be CORS (Cross Origin Request Security) enabled so that Siren Investigate can download the file. The following example shows a valid regionmap configuration.
|
|
Mandatory. A description of the map being provided. |
|
Mandatory. The location of the GeoJSON file as provided by a web server. |
|
Optional. References the originating source of the GeoJSON file. |
|
Mandatory. Each layer can contain multiple fields to indicate what properties from the geojson features you want to expose. This example shows how to define multiple properties. |
|
Mandatory. This value is used to do
an inner-join between the document stored in Elasticsearch and the
GeoJSON file. For example, if the field in the GeoJSON is called
|
|
Mandatory. The human readable text that is shown under the Options tab when building the Region Map visualization. |
|
If your Elasticsearch is protected with basic authentication, these settings provide the username and password that the Siren Investigate server uses to perform maintenance on the Siren Investigate index at startup. Your Siren Investigate users still need to authenticate with Elasticsearch, which is proxied through the Siren Investigate server. |
|
Default: For example, a
|
|
Default: |
|
Paths to the PEM-format SSL certificate and SSL key files, respectively. |
|
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted. |
|
List of paths to PEM encoded certificate files that should be trusted. |
|
Default:
|
|
Default:
For more information on the format, and valid options, refer to the OpenSSL cipher list format documentation (https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT). |
|
Optional settings that provide the paths to the PEM-format SSL
certificate and key files. These files are used to verify the identity
of Siren Investigate to Elasticsearch and are required when
|
|
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted. |
|
Optional setting that enables you to specify a list of paths to the PEM file for the certificate authority for your Elasticsearch instance. |
|
Default: |
|
Default: the value of the
|
|
Default: |
|
Default:
|
|
Default: |
|
Default: |
|
Default: |
|
Specifies the path where Siren Investigate creates the process ID file. |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Default: |
|
Override for cgroup cpu path when
mounted in manner that is inconsistent with |
|
Override for cgroup cpuacct path
when mounted in manner that is inconsistent with |
|
Default: |
White-labelling constants and images in Siren
White-labelling is the process of changing some elements in a product to reflect the branding of a company or organization deploying that product. You can now label certain constants and modify images and icons in Siren Investigate to reflect the branding of your company or organization.
Changing company and product names
The company and product names default to ‘Siren’ and ‘Investigate’, respectively. To change them, on the server, go to Siren Investigate > config and edit the investigate.yml
file. Search for the term whiteLabel
and you should find the company and product name keys as shown below.
#The white labels.
whiteLabel:
companyName: Siren
productName: Investigate
If the keys are not in investigate.yml , you can add them, ensuring they are formatted exactly as shown.
|
Change the names as required and once done, restart the server and refresh Investigate to view the changes.
Hiding the copyright
The copyright text is normally visible on the user interface under Management. If you want to suppress the display of this text, go to Siren Investigate > config and in the investigate.yml
file change the value of the whiteLabel.hideCopyright
key to true
. If the key is not there, add it as shown below.
#The white labels.
whiteLabel:
companyName: Siren
productName: Investigate
hideCopyright: false
Add management information
If you wish to add more information on the user interface under Management, it can be done by adding keys under whiteLabel.management.info
. For example, doing
#The white labels
whiteLabel:
companyName: Siren
productName: Investigate
hideCopyright: false
management:
info:
App Version: 1.4.5
would add the "App Version" on the Management page as shown below
Multiple keys can also be added under whiteLabel.management.info
.
The key(s) can also be added by passing the additional information as an environment variable to Investigate’s docker image. To do it, prepend the actual key you wish to pass with the string "WHITELABEL_MANAGEMENT_INFO_". For example, to add the "App Version" and the "Company Motto", a parameter will be passed to the docker run
command as follows
docker run -e WHITELABEL_MANAGEMENT_INFO_App_Version=1.4.5 -e WHITELABEL_MANAGEMENT_INFO_Company_Motto=Search_away_anything_andEverything <imageId>
In order to add space(s) between the strings of the keys or the values, add a "underscore" between them. The underscores are post processed to be replaced by space before showing up on the user interface. Everything else (including the case of the keys and values) remain the same. For example, running the above docker command will show the key and value on the user interface as follows |
Changing images and favicons
Custom images and favicons can be configured through imagesDir
and faviconsDir
respectively.
#The white labels.
whiteLabel:
companyName: Siren
productName: Investigate
hideCopyright: false
management:
info:
App Version: 1.4.5
faviconsDir: /path/to/your/favicons/folder
imagesDir: /path/to/your/images/folder
To change the images and/or favicons, perform the following steps.
-
Update
imagesDir
and/orfaviconsDir
configurations with a non-empty and accessible directory -
Delete the Siren Investigate > optimize folder
-
Restart the server
The logo images that can be customized are as follows:
Logo Name | Dimensions | Default (Preview) |
---|---|---|
logo.png |
1026x1021 |
|
full_logo.png |
348x102 |
|
loading_logo.gif |
66x65 |
Favicons folder is expected to have the standard set of favicons files as follows:
Filename |
---|
android-chrome-192x192.png |
android-chrome-256x256.png |
android-chrome-512x512.png |
apple-touch-icon.png |
browserconfig.xml |
favicon-16x16.png |
favicon-32x32.png |
favicon.ico |
manifest.json |
mstile-150x150.png |
safari-pinned-tab.svg |
Ensure that the new image has exactly the same name as the image you are replacing it with. For example, if you change the loading graphic (normally an animated GIF file), ensure that the name of the new GIF file is loading_logo.gif. |
Adding icons
Siren provides the ability to import custom icons into the application. The details of how to do this are specified in Adding custom icon packs.
Accessing Siren Investigate
Siren Investigate is a web application that you access through port 5606. All you need to do is point your web browser at the machine where Siren Investigate is running and specify the port number. For example, http://localhost:5606 or http://example.com:5606http://YOURDOMAIN.com:5606.
When you access Siren Investigate, the
Discover
page loads by
default with the default index pattern selected. The time filter is set
to the last 15 minutes and the search query is set to match-all (*
).
If you do not see any documents, try setting the time filter to a wider time range. If you still do not see any results, it is possible that you do not have any documents.
Checking Siren Investigate status
You can reach the Siren Investigate server’s status page by navigating
to http://localhost:5606/status
. The status page displays information
about the server’s resource usage and lists the installed plugins.
Collecting Elasticsearch diagnostics
Click Elasticsearch diagnostics to generate a single file by collecting different metrics about your Elasticsearch cluster. All collected information are saved to a local file and never transferred over a network. You can see a full list of Elasticsearch API calls by clicking the more info (i) icon.
For JSON formatted server status details, use the API endpoint at
http://localhost:5601/api/status .
|
Connecting Siren Investigate to backend datasources
Siren can visualize data that is accessible by the Siren backend, which is an Elasticsearch cluster enhanced by the Federate plugin.
The following diagram represents this concept. On the frontend, a user looks at data, for example data in a dashboard or on the Graph Link Analysis system. This data comes from Siren "searches", which reflect queries that are sent to indices that are on the Elasticsearch backend.
It is useful to distinguish between two types of searches:
-
Index Pattern Searches: Root definitions that describe which Elasticsearch indices will be used. They can be as simple as the name of the index itself or can be “patterns” e.g. new*_ to indicate “all the indices that begin with news_”. For more information and examples, see Index Pattern Searches.
-
Other searches: These are defined by filtering an Index Pattern Search, for example starting from a “News” Index Pattern Search, one might create a “News that contain the word Brexit” search.
Inside the main Elasticsearch cluster (the one that the NodeJS Siren application is connected to), indices can be of two types:
-
Physical indices: These are regular Elasticsearch indices, typically created via external ETL (e.g. Logstash) or via the Siren reflection process (an ETL that keeps external tables in sync). For more information, see Importing data.
-
Virtual indices: These will simulate Elasticsearch indices but will not copy data; instead, they will send queries to the remote backends and will translate the query results.
Both physical and virtual indices can be used to create index patterns (although in Siren 10.3, you cannot create wildcard patterns (*) including virtual indices).
Before you can start using Siren Investigate, you need to tell it which Elasticsearch indices you want to explore. The first time you access Siren Investigate, you are prompted to define an index pattern search that matches the name of one or more of your indices. That is it. That is all you need to configure to start using Siren Investigate. You can create index pattern searches at any time from the Management tab.
By default, Siren Investigate connects to the Elasticsearch instance
running on localhost . To connect to a different Elasticsearch
instance, modify the Elasticsearch URL in the investigate.yml
configuration file and restart Siren Investigate. For information about
using Siren Investigate with your production nodes, see
Using Siren Investigate in a production environment
|
-
Point your browser at port 5606 to access the Siren Investigate user interface. For example, http://localhost:5606 or \http://example.com:5606.
-
Specify an index pattern search that matches the name of one or more of your Elasticsearch indices. You may have to access the index pattern search management in the Management tab. By default, Siren Investigate guesses that you are working with data being fed into Elasticsearch by Logstash. If that’s the case, you can use the default
logstash-*
as your index pattern search. The asterisk (*
) matches zero or more characters in an index’s name. If your Elasticsearch indices follow some other naming convention, enter an appropriate pattern. The "pattern" can also be the name of a single index. -
Select the index field that contains the timestamp that you want to use to perform time-based comparisons. Siren Investigate reads the index mapping to list all the fields that contain a timestamp. If your index does not have time-based data, switch off the Index contains time-based events option.
-
Click Create to add the index pattern search. This first pattern is automatically configured as the default. When you have more than one index pattern search, you can designate which one to use as the default by clicking on the star icon above the index pattern search title from the Data model app.
All done. Siren Investigate is now connected to your Elasticsearch data. Siren Investigate displays a read-only list of fields configured for the matching index.
Siren Investigate relies on dynamic mapping to use fields in
visualizations and manage the .siren index. If you have switched off
dynamic mapping, you need to manually provide mappings for the fields
that Siren Investigate uses to create visualizations. For more
information, see
Siren Investigate and Elasticsearch dynamic mapping
|
Start exploring your data
You are ready to dive in to your data:
-
Search and browse your data interactively from the Discover page.
-
Chart and map your data from the Visualizations page.
-
Create and view custom dashboards from the Dashboard page.
For a step-by-step introduction to these core Siren Investigate concepts, see the Getting Started tutorial.
Siren Investigate and Elasticsearch dynamic mapping
By default, Elasticsearch enables
dynamic
mapping for fields. Siren Investigate needs dynamic mapping to use
fields in visualizations correctly, as well as to manage the .siren
index where saved searches, visualizations, and dashboards are stored.
If your Elasticsearch use case requires you to switch off dynamic
mapping, you need to manually provide mappings for fields that Siren
Investigate uses to create visualizations. You also need to manually
enable dynamic mapping for the .siren
index.
The following procedure assumes that the .siren
index does not
already exist in Elasticsearch and that the index.mapper.dynamic
setting in elasticsearch.yml
is set to false
:
-
Start Elasticsearch.
-
Create the
.siren
index with dynamic mapping enabled just for that index:PUT .siren { "index.mapper.dynamic": true }
-
Start Siren Investigate and navigate to the web UI and verify that there are no error messages related to dynamic mapping.
Using Siren Investigate in a production environment
How you deploy Siren Investigate largely depends on your use case. If you are the only user, you can run it on your local machine and configure it to point to whatever Elasticsearch instance you want to interact with. Conversely, if you have a large number of heavy users, you may need to load balance across multiple instances that are all connected to the same Elasticsearch cluster.
While Siren Investigate is not terribly resource intensive, we still recommend running Siren Investigate separate from your Elasticsearch data or master nodes.
Make sure to set the configuration file as readable only to the user running the Siren Investigate process as it contains encryption keys to protect configuration settings stored in Elasticsearch; if you are connecting Siren Investigate to external datasources, we also recommend to use credentials with no write privileges as they are not required by the system.
Access control
Siren Investigate is compatible with Elastic Stack Security and Search Guard to enable index and document level access control.
For more information about access control features, see the Authentication and access control section.
Configuring a reverse proxy
To protect your system from protocol attacks, it is recommended that you run Siren Investigate behind a reverse proxy.
HTTP servers, such as Apache and NGINX, offer the reverse proxy functionality. See the Enabling HTTPS section for instructions.
Alternatively, you can use a proprietary solution, such as a web application firewall (WAF). Please consult the vendor documentation for instructions.
Load balancing across multiple Elasticsearch nodes
If you have multiple nodes in your Elasticsearch cluster, the easiest way to distribute Siren Investigate requests across the nodes is to run an Elasticsearch client node on the same machine as Siren Investigate. Elasticsearch client nodes are essentially smart load balancers that are part of the cluster. They process incoming HTTP requests, redirect operations to the other nodes in the cluster as needed, and gather and return the results. For more information, see Node in the Elasticsearch reference.
To use a local client node to load balance Siren Investigate requests:
-
Install Elasticsearch on the same machine as Siren Investigate.
-
Configure the node as a client node. In
elasticsearch.yml
, set bothnode.data
andnode.master
tofalse
:# You want this node to be neither master nor data node, but # to act as a "search load balancer" (fetching data from nodes, # aggregating results, and so on) # node.master: false node.data: false node.ingest: false
-
Configure the client node to join your Elasticsearch cluster. In
elasticsearch.yml
, set thecluster.name
to the name of your cluster.cluster.name: "my_cluster"
-
Make sure Siren Investigate is configured to point to your local client node. In
investigate.yml
, theelasticsearch.url
should be set tohttp://localhost:9220
.# The Elasticsearch instance to use for all your queries. elasticsearch.url: "http://localhost:9220"
Upgrading from Investigate 10.1.x or 10.2.x
You can migrate directly from Investigate 10.1.3 and higher to 11.1. If upgrading from an earlier version of Investigate, it is recommended that you first upgrade to 10.1.3 (which also supports Elasticsearch 5.x). You can then upgrade from 10.1.3 to 11.1.
When upgrading both Investigate and Elasticsearch, you should upgrade the Investigate objects first, and only then upgrade Elasticsearch. |
The recommended version of Elasticsearch is 6.8.0 (version 6.5.4 is also supported). See Search Guard Integration and Siren Investigate access control to configure Searchguard security settings correctly for Elasticsearch 6.8.0.
Before you upgrade Siren Investigate, you must take account of the security implications of the new features installed. Details of the necessary security procedures can be found in Security standardization. |
An existing Siren Investigate installation can be upgraded as follows:
-
Back up the 10.1.x
.siren
index. -
Back up the Siren Investigate configuration file (
config/investigate.yml
). -
Back up the
.sirenaccess
if ACL (Access Control Layer) is enabled -
If you are running Elasticsearch 6.3.2, you can optionally upgrade to version 6.8.0 (https://www.elastic.co/guide/en/elasticsearch/reference/6.5/setup-upgrade.html).
-
Before restarting each Elasticsearch node, ensure you install a compatible version of the Siren Federate plugin and access control plugins (Searchguard or Elastic Stack Security) if required.
-
Download and extract the new Siren Investigate version.
-
Copy the previous configuration file to the
config
folder of the new installation. -
Check for breaking changes to the configuration. See Search Guard Integration and Siren Investigate access control.
-
Install the compatible versions of third party Siren Investigate/Kibana plugins that you may need into the
/plugins
folder. -
Execute the
upgrade
command.
Elasticsearch requires a matching version of Search Guard. For example, Elasticsearch 6 requires Search Guard 6. For information on upgrading Search Guard, see https://docs.search-guard.com/latest/upgrading-560. |
Backing up and restoring the Siren Investigate indices
Before upgrading, you should have a backup of the .siren
index; the
recommended way to perform regular backups of Elasticsearch indexes is
through the
snapshot
and restore modules.
Siren Investigate ships with a command line interface for creating dumps
of the .siren
index and, in case the ACL
is enabled, the
.sirenaccess
index as well. An index dump is composed of two parts:
its mappings and its data.
Backup
The backup
command requires a running Elasticsearch instance and the
path to a folder where the dumps will be written to.
You can find out more about its options by executing the following:
$ ./bin/investigate backup --help
For example, the following line will dump in <MY_FOLDER>
the
.siren
index and the .sirenaccess
index if the option
investigate_access_control.acl.enabled
is true in
investigate.yml
:
$ ./bin/investigate backup --backup-dir <MY_FOLDER>
Restore
The restore command requires a running Elasticsearch instance and the path to a folder where the dumps were written to by the previous backup command.
You can find out more about its options by executing the following:
$ ./bin/investigate restore --help
For example, you can restore the previously saved indices by executing
the command and pointing to the dump folder, with .sirenaccess
as
well if the option investigate_access_control.acl.enabled
is true in
investigate.yml
:
$ ./bin/investigate restore --backup-dir <MY_FOLDER>
Upgrading the Siren index
To upgrade the objects in the .siren
index (dashboards,
visualizations, and so on), move to the folder in which Siren
Investigate is installed and execute the following command:
bin/investigate upgrade
The command will look for out of date objects and upgrade them, for example:
$ bin/investigate upgrade
log [17:58:33.494] [info][status][plugin:elasticsearch] Status changed from uninitialized to yellow - Waiting for Elasticsearch
log [17:58:36.127] [info][migrations] Executing migration "Upgrade scripts from version 1 to version 2"
log [17:58:36.141] [info][migrations] Executed migration "Upgrade scripts from version 1 to version 2"
log [17:58:36.142] [info][migrations] Executing migration "Upgrade graph browser visualization to version 2."
log [17:58:36.157] [info][migrations] Executed migration "Upgrade graph browser visualization to version 2."
log [17:58:36.158] [info][migrations] Executing migration "Upgrade saved queries from version 1 to version 2"
log [17:58:36.242] [info][migrations] Executed migration "Upgrade saved queries from version 1 to version 2"
log [17:58:36.242] [info][migrations] Executing migration "Upgrade saved templates from version 1 to version 2"
log [17:58:36.303] [info][migrations] Executed migration "Upgrade saved templates from version 1 to version 2"
log [17:58:36.303] [info][migrations] Executing migration "Upgrade saved queries definitions in external query terms aggregation, enhanced search results and query viewer."
log [17:58:36.400] [info][migrations] Executed migration "Upgrade saved queries definitions in external query terms aggregation, enhanced search results and query viewer."
Upgraded 20 objects.
It is possible to run the command multiple times, however running the command at the same time from multiple machines is not supported.
The upgrade
command runs an automatic backup of the siren indices
(.siren
, .sirenaccess
) and restores them (after deleting the
existing index) in the event of a problem in the upgrade
process -
ensuring the system is not left in an unusable state. In the event of a
successful upgrade, the backup is removed but if there is an issue, the
backed up indexes are stored in the backup folder (defaults to the
/data
folder).
You can specify various flags to control the backup/restore process.
-
--backup-dir <path>
: Custom backup folder path to store the index backup. -
--config <path>
: Path to the configuration file. -
--delete-backup
: Deletes the backup of the indexes after the upgrade process completes. -
--dont-backup
: Runs the upgrade process without creating a backup of the indexes. -
-y
: Accepts all of the options, for example, backup the indexes and remove the indexes before restoring.
Security standardization
The purpose of security standardization is to provide standard security configuration for all possible backends, and full support for Investigate 11.1.
This entails standardizing both action groups and role mappings.
Procedure
To standardize your security according to new action groups:
-
Download the applicable security bundle below.
-
Add any new client-specific roles or action groups you have added (if any) based on the action group and action name changes listed below.
-
Put the modified configuration files in the ./elasticsearch/config/sgconfig/ folder and upload the configuration to the cluster.
-
Ensure that you explicitly specify your ACL admin_role and Sentinl user_role in investigate.yml as defaults may have changed.
Standard sgconfig bundles
The following sgconfig bundles are available:
Action Group changes
Removed | Can be (loosely) replaced by |
---|---|
ALL |
INDICES_ALL |
CREATE_INDEX |
WRITE, MANAGE |
MANAGE_ALIASES |
VIEW_INDEX_METADATA |
MONITOR |
MANAGE |
INDICES_MONITOR |
VIEW_INDEX_METADATA |
DATA_ACCESS |
WRITE, READ, VIEW_INDEX_METADATA |
DELETE |
WRITE |
CRUD |
READ, WRITE |
SEARCH |
READ |
SUGGEST |
READ |
INDEX |
WRITE |
GET |
READ |
SIREN_READONLY |
READ, VIEW_INDEX_METADATA |
SIREN_READWRITE |
READ, WRITE, VIEW_INDEX_METADATA |
SIREN_CLUSTER |
CLUSTER_MANAGE, CLUSTER_MONITOR, CLUSTER_COMPOSITE_OPS_RO |
Elasticsearch Action Name Changes
ES 6.3.x onwards:
Index-level actions:
-
indices:data/write/bulk
to →indices:data/write/bulk[s]
or you may just useindices:data/write/bulk*
. -
indices:data/read/coordinate-msearch*
deprecated (not used by Siren).
Federate Action Name Changes
Federate 10.2.0 onwards:
Index-level actions:
-
indices:siren/plan*
to →indices:data/read/federate/planner/search*
-
indices:siren/mplan*
to →indices:data/read/federate/planner/msearch*
-
indices:data/siren/connector/mappings/get*
to →indices:admin/mappings/federate/connector/get*
-
indices:data/siren/connector/mappings/fields/get*
to →indices:admin/mappings/federate/connector/fields/get*
Cluster-level actions:
-
indices:siren/plan*
to →indices:data/read/federate/planner/search*
-
indices:siren/mplan*
to →indices:data/read/federate/planner/msearch*
-
cluster:siren/internal*
to →cluster:internal/federate/*
-
cluster:admin/plugin/siren/license/get
to →cluster:admin/federate/license/get
, or you may just usecluster:admin/federate/*
-
indices:data/siren/connector/*
to →indices:data/read/federate/*
,indices:admin/federate/*
andcluster:admin/federate/*