Please note this guide assumes you are installing Graylog Illuminate for the first time. This guide also does not cover Illuminate deployments in Graylog Cloud. Please refer to the Illuminate Upgrade Guide documentation for instructions to upgrade an existing Graylog Illuminate installation.
Prerequisites
The following is required prior to installing Graylog Illuminate:
-
A Graylog server running at least version 5.0.0.
-
A valid Operations or Security license.
-
Administrator access to the Graylog server.
-
The Graylog server backend must be able to communicate with
https://contenthub.graylog.cloudon port 443 in order to use in-app Illuminate download functionality. -
Illuminate 2.0.0 or greater installed and activated.
Install Illuminate
There are currently two methods of installation for Graylog Illuminate. The following section will describe installation directly via the Graylog interface, which is the preferred method as of Graylog 5.1; however, if your Graylog server cannot access the public internet, then you will need to complete a manual installation using a release file obtained from your sales representative.
Installing Illuminate In Graylog
1. Navigate to the Illuminate page by selecting Enterprise > Illuminate.
2. You will see a notification at the top right of the screen indicating that a new Illuminate bundle is ready to install. You may select Install from this menu, or you can navigate to the Install Another Bundle link located beneath the Illuminate Bundle Version drop-down menu.
3. On this menu select the Illuminate version you wish to install and click the Download & Install button. (You may also wish to preview the available versions by selecting them from the side navigation and reviewing the attached changelogs.)
4. Confirm your installation by selecting Confirm on the pop-up menu to begin the installation process.
5. Once complete you will receive a notification that Illuminate has been successfully installed.
Illuminate Pack Selection
After the Illuminate installation is complete, navigate back to Enterprise > Illuminate for a list of Illuminate packs that can be activated on your Graylog system. You can enable the following Illuminate packs from this menu:
Activating Illuminate Packs
1. Browse through the list of packs provided by Illuminate using the controls near the bottom of the page, selecting any packs you wish to activate.
2. When you have selected all of your chosen packs, click Enable Selected on the upper right of the Illuminate packs list window.
Illuminate Core Extension Packs
There are some Illuminate packs that are optional add-on extensions to the functionality of Illuminate core. The optional packs are:
About the Anomaly Detection Add-on Pack
Graylog Security includes an anomaly detection feature, and Graylog Illuminate provides an anomaly detection content pack containing pre-defined rules that work with Illuminate. This add-on provides:
-
An index set and stream definition for events generated by the anomaly detection functionality in Graylog Security.
-
Rules to enrich events required by Graylog anomaly detection rules pack to analyze events processed by Graylog Illuminate.
About the GIM Enforcement Pack
What is GIM?
GIM, short for Graylog Information Model, is how we ensure known types of messages that have been properly categorized will have the necessary fields required for processing.
Why Enable GIM Enforcement?
GIM Enforcement, when enabled, will ensure that all events that have been categorized and intended to be available for search and aggregation, even if the message has been parsed incorrectly. The GIM Enforcement rules will identify categorized messages that are missing required fields; mark those fields and assign default values for the missing fields. Missing fields can be due to log format changes between versions of a product or unexpected data in the message that the parsing logic did not account for.
When the GIM Enforcement rules identify a categorized message that is missing a required field, they will add a field named gim_error with a value that identifies the categorization assignment that failed, and then they will assign a placeholder value to the fields missing values. The placeholder values assigned depend upon the field type:
-
Text fields will be assigned the value
_undefined_. -
Numeric fields will be assigned the value
0. -
IP fields will be assigned the value
0.0.0.0.
For example, all logon events should have the field user_name. With GIM Enforcement enabled, any message that has been categorized but is missing one of these required fields will have a default value assigned, and the field gim_error will be added indicating that the message is incomplete. This will ensure that searches, which look for logon messages by user_name, will include these messages in related search results and aggregations.
Without GIM enforcement messages may not be included in search results or aggregations if they have been improperly parsed or if they are malformed in some way.
We recommend enabling GIM enforcement at least occasionally when troubleshooting field extraction issues or performing a test or review of data quality.
About the Geolocation and Autonomous System (AS) Packs
Two technology packs support geolocation and ASN enrichment: one supporting MaxMind city and AS databases and another supporting IPinfo city and AS databases.
Illuminate Geolocation and AS Deprecation Notice
The Graylog Illuminate Geolocation and AS enrichment processing packs are deprecated and will be removed from a future version of Graylog Illuminate. The functionality of these packs is replaced by the Geolocation Processor. Instead of using the Illuminate Geolocation Processor packs, please configure the Geolocation Processor, making sure the Enforce default Graylog schema option is selected.
Enabling MaxMind Geolocation and ASN Enrichment
The “Geolocation and AS Enrichment Add-on for MaxMind Databases Geolocation and ASN Enrichment” requires that two files be installed on every Graylog Operations node in your cluster:
-
The MaxMind City database in MMDB format with the file name
GeoLite2-City.mmdb. -
The MaxMind AS database in MMDB format with the file name
GeoLite2-ASN.mmdb.
These files must be placed in the directory /etc/graylog/server on all Graylog nodes in your cluster for the enrichment to function properly.
Enabling IPinfo Geolocation and ASN Enrichment
The “Geolocation and AS Enrichment Add-on for IPinfo Databases” requires that two files be installed on every Graylog Operations node in your cluster:
-
The IPinfo City database in MMDB format with the file name
standard_location.mmdb. -
The IPinfo ASN database in MMDB format with the file name
asn.mmdb.
These files must be placed in the directory /etc/graylog/server on all Graylog nodes in your cluster for the enrichment to function properly.
Illuminate Spotlights
The Illuminate "Spotlight" content packs are a component of Illuminate that contain Graylog web interface content such as dashboards and saved searches.
Most of the Spotlight content packs are product focused and are a companion to the Illuminate packs included in the Illuminate bundle, but there are additional content packs included that provide other content.
Installation of the Spotlight content packs is optional and does not affect the operation of the Illuminate processing packs.
Additional Spotlight Content
In addition to the product Spotlight content packs, there are some additional content packs included with Illuminate:
-
The Message Summaries content pack (for Graylog Security 5.0.0+): summarizes messages in the message view that have been categorized according to the GIM model, called "message summaries."
-
Event Definition content packs: contains pre-defined event definitions.
