Graylog Illuminate is available for use with Graylog Operations and Graylog Security. Contact sales to learn more about obtaining Graylog Illuminate.

Prerequisites

Hint: The following instructions are valid only when upgrading from Illuminate 1.7.0. Any Illuminate versions prior to 1.7.0 must first be upgraded to Illuminate 1.7.0 prior to a final upgrade to Illuminate 2.0.0

If you are not currently running any previous Illuminate versions, see Installing Illuminate 2.0.

Warning: If you are upgrading to Illuminate 2.0.1 or later from Illuminate 1.x you must first upgrade to Illuminate 2.0.0 as instructed in this article. Then, proceed to the Illuminate 2.0.1 section.

Prior to upgrading, the following conditions must be met:

• The environment must be running Graylog Operations 4.2.0 or later.
• The Graylog cluster must have a current and valid Operations license.
• Verify that the content pack “Default Grok Patterns” is installed.

Changes In This Release

A new installation method is now available so that Illuminate 2.0 can be installed entirely from the Graylog web interface.

Hint: This installer does not include the addition of Geolocation and Autonomous System Number (ASN) lookup mmdb files, which can be installed manually if the Geolocation and ASN lookup files were configured to work with previous versions of Illuminate.

Additionally, Illuminate metadata fields that previously used the field name prefix gl2_ have now been renamed to the prefix gim_. This will improve support for using these fields in different parts of Graylog. Field aliases will allow searches that use the updated field names to access data previously indexed with the old field names.

Field aliases will also be used to allow content organized by the old field names to search newly indexed data; however, the one exception to this rule is the field gim_event_subcategory.

Upgrading from Illuminate 1.7.0

Follow the preceding steps in order to update your Illuminate instance to the latest version.

Review the Processor Order Configuration

Temporarily configuring the Illuminate processor to run prior to the Message Filter Chain and Pipeline Processor will ensure the upgrade of Illuminate is a more straightforward process.

1. Log in to your Graylog application.
2. Navigate to System > Configurations.
3. Review and make a note of the current order of the Message Processors Configuration. You will need this information to restore the listed order later!
4. Verify that the Illuminate Processor is ordered to run before the Pipeline Processor and Message Filter Chain. If this is not the case, select “Update” and move the Illuminate Processor as required.

Record Currently Enabled Content Packs

Next, you will want to record the current content packs enabled on your Graylog instance.

1. In Graylog, navigate to System > Content Packs.
2. Locate the filter entry text box; enter the word Illuminate and click on Filter.
3. Record a separate list of all Illuminate content packs that are listed as installed, but do not uninstall or delete these content packs.

Extract the Graylog Illuminate Release Archive File

Graylog Illuminate is distributed as a zip format archive file. Contact your sales representative for information on obtaining the Graylog Illuminate 2.0 release file.

1. Once you receive the file, download and extract it in a convenient location.
2. The archive will expand into a directory starting with the name “graylog_illuminate.” The Illuminate bundle zip file and the file “spotlights” will be located in this subdirectory, which contains all of the included Illuminate Spotlight content packs.

Upload the Illuminate Bundle

Now, you will upload and enable your new Illuminate bundle.

1. In the Graylog interface, navigate to Operations > Illuminate.
2. Drag and drop or click to select the Illuminate 2.0.0 bundle zip archive file that was extracted in the previous step.

3. In the following menu select all of the packs that correspond with your previously recorded list of installed content packs.
4. If your previous instance of Illuminate was configured to perform Geolocation and Autonomous System Number (ASN) lookups, and those files are installed on the Graylog server(s), then be sure to also select the pack, “Illuminate 2.0.0:Geolocation and AS Enrichment.”

Hint: You may also enable GIM Enforcement from this menu, if you choose; for more information please review the GIM Enforcement guide.

6. Click Enable Selected, and the selected packs will be updated to indicate which packs have been enabled. (This process may take a few moments.)

Uninstall Previous Illuminate Content

After the Illuminate technology packs have been installed and activated, the previous Illuminate content packs should be removed, with the sole exception of the “Events” Spotlight content pack.

1. Navigate again to System > Content Packs.
2. Filter through the packs using the word Illuminate as in the previous steps.
3. Now, uninstall all the listed Illuminate Spotlight content except for the “Illuminate:Events” Spotlight. Do not alter this content pack.
4. To remove the listed content packs, click on the Spotlight pack to uninstall. All available and installed revisions will be listed in the top left of the page.

5. Click on Uninstall.
6. Repeat this process until all of the Spotlight packs (except for the Events spotlight pack) have been removed.

Install the Illuminate Spotlight Content

Now, you can download your desired content packs for Illuminate.

Hint: The Illuminate installer does not currently support installing dashboards, saved searches, or event definitions; however, the Illuminate archive file has Spotlight content packs that contain these.

1. Navigate again to System > Content Packs. Here, you can upload the content packs you wish to integrate into your Graylog instance.
2. Click Upload.

3. Then, click on Browse and navigate to the directory where the Graylog Illuminate archive was extracted in the previous steps.
4. Locate the “graylog_illuminate.v2_0_0” directory and select it.
5. Then, navigate to the “spotlights” subdirectory.
6. Here, select the Spotlight you wish to upload and click Open.
7. Repeat this process until all desired Spotlight packs have been uploaded.
8. Now, you need to install the content packs. These Spotlight packs will be listed on the "Content Packs" page in Graylog.
9. Click on an Illuminate Spotlight content pack to install.
10. On the left hand side, there will be a listing of versions; select the Actions button to the right of the most recent revision and click Install from the drop-down menu.

11. Repeat this process for all desired Spotlight packs to be installed.

Update the Event Definitions

Illuminate 2.0 includes some changes to field definitions that require updates to existing event definitions. The Illuminate 2.0 Event Definitions Spotlight includes updated event definitions for all existing rules.

Review currently enabled Illuminate event definitions.

1. Navigate to the “Alerts” dashboard in the Graylog web interface.
2. Click on the “Event Definitions” button on the upper right of the page.
3. Record a separate list of all enabled Illuminate events. You will need to refer to this list in future steps.

1. If the Illuminate 2.0.0 Event Definitions spotlight has not already been uploaded, then complete the following steps.

   1. Navigate to the System > Content Packs page in the Graylog web interface.
   2. Select Upload and then Browse, as in previous steps.
   3. Navigate to the directory where the Illuminate Spotlight archive was extracted.
   4. Click on the “Illuminate_events” subfolder and upload the content pack file.

2. Apply any customizations to the corresponding updated event, such as notification settings. (Illuminate event definitions are provided without any notification settings. If notification settings have been added, or if any of the threshold settings have been updated, then these must be applied to the updated event definitions included with Illuminate 2.0.0.)

   1. Navigate back to the “Event Definitions” page in the Graylog web interface.
   2. Click on the Edit button on the event definition to be updated.
   3. Record any changes to the threshold settings and notifications for the event definition and keep this record. (The updated event definitions will have similar titles as the previous definitions but will begin with “Illuminate:Events:4;”.)
   4. Locate and edit the updated event definition.
   5. Apply the recorded customizations.

3. Now, enable the new event.

   1. Click on the More button corresponding with the updated event definition.
   2. Then click Enable.

4. Then, disable the old event.

   1. Click on the More button corresponding with the previous event definition.
   2. Click Disable.

5. Repeat this entire process for all of the event definitions that were previously in use.

Remove Previous Event Definition Settings

After all event definition settings have been updated, the previous revisions of the event definitions should be removed. It is important to note that once the older content pack revisions have been uninstalled, all settings on the event definitions associated with the older event definitions will be removed and cannot be recovered.

To remove the previous event definitions:

1. Click on the content pack entry “Graylog Illuminate:Event Definitions;2021-10-16”.
2. The available and installed revisions of the content pack will be listed on the left side of the page.
3. Click on Uninstall for revisions 1, 2, and 3 only.

Restore the Processing Order

Once the installation is complete, it is necessary to revert to the previous processing order.

1. Navigate to System > Configurations in the Graylog web interface.
2. Consult your recorded notes on the previous processing order and restore the processing order exactly as recorded.

Illuminate 2.0.1

For upgrading to Illuminate 2.0.1, you must first install Illuminate 2.0.0 as described above. Then, proceed with the following installation and upgrade actions as you did with 2.0.0:

1. Download and extract the Graylog Illuminate 2.0.1 release archive file.
2. Upload the Illuminate 2.01 bundle.
   1. For this step, there are some additional confirmation actions that will need to occur. See the preceding section, "Upload the Illuminate 2.0.1 Bundle," for more details.
3. Uninstall the previous Illuminate content.
4. Upload and Install the Illuminate 2.0.1 Spotlight packs.

Upload the Illuminate 2.0.1 Bundle

Now, you will upload and enable your new Illuminate bundle as before in the "Upload the Illuminate Bundle" section above. This process is generally the same as before when installing Illuminate 2.0.0; however, after the bundle is updated, there will be a message indicating that the bundle was uploaded but that the previous version was active.

1. From here, click on the button Continue to Packs Manager to enable the new version of Illuminate.
2. Click on the Illuminate version selection drop-down menu located on the upper right corner of the Illuminate installer page.

            

3. Select the illuminate version to activate and click on the Activate button.
   
   

4. A confirmation message will appear.
   

5. Click Confirm to activate the new version of Illuminate.

6. Confirm that the previous technology packs that were activated are still active.