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 documentation for instructions on how to upgrade an existing Graylog Illuminate installation.
Prerequisites
The following is required prior to installing Graylog Illuminate:
-
A Graylog server running Graylog 5.0+.
-
A valid Enterprise or Security license.
-
Administrator access to the Graylog server.
-
The Graylog server backend must be able to communicate with https://contenthub.graylog.cloud and https://glc-illuminate-hub.s3.amazonaws.com/ on port 443 in order to use in-app Illuminate download functionality.
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 you have initiated the installation, you will be presented with a page that breaks down each individual step in the installation process and its status. As processes are executed successfully, a green check mark will appear, and the next process will run. If an error occurs during installation, an error message will appear so that you may investigate the cause. Please note that the installation process may take several minutes depending on your environment.
6. When the installation process is 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.
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.
