Debian Installation: Single Graylog Node

This installation guide covers installing Graylog on Debian Linux 10 (Buster), 11 (Bullseye), or 12 (Bookworm) on a Core cluster, which is composed of one Graylog and MongoDB node and one Data Node. If you are deploying a multiple Graylog-node cluster on Debian, see Debian Installation: Multiple Graylog Nodes.

This article will guide you through installing three services that comprise the Graylog stack: MongoDB, Graylog Data Node, and Graylog.

Warning: The following guide will walk you through installing Graylog for use with Data Node as your search backend. Do not install OpenSearch directly! For information on deploying Graylog with self-managed OpenSearch, see Installing Graylog.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

  • Verify that all required ports are open. We assume in the following steps that firewalls are disabled and traffic can flow across all necessary ports.

  • We strongly recommend the use of an XFS file system for storage.

  • Review the Core architecture diagram and our recommendations for resource allocation before you begin installation.

Warning: This guide does not cover security settings! The server administrator must make sure the Graylog server is not publicly exposed and is following security best practices.

Server Timezone

To set a specific time zone on a Graylog server, you can use the following command. (For more information on setting a time zone, we recommend this blog post.)

Copy
sudo timedatectl set-timezone UTC

Configuration and Service Files

Before you begin the process of installing Graylog and its required components, it is important to note that there are multiple configuration files and service files included in the Graylog and MongoDB operating system packages that should be adjusted during the initial deployment process to optimize your system performance. For your reference, the files mentioned in this installation guide for each service are as follows:

Install MongoDB

MongoDB is a NoSQL database designed to store and manage data in a flexible, scalable, and high-performance manner. As a part of the Graylog stack, MongoDB serves as the metadata database for the system.

The official MongoDB documentation provides a helpful tutorial on installation with Debian. For information on installing MongoDB for use with Graylog, we recommend you generally follow the process below.

Warning: This guide assumes you are installing MongoDB 7.0. Review the compatibility matrix for versions of MongoDB supported both by your chosen Graylog and operating system versions.

  1. Install gnupg and curl:

    Copy
    sudo apt-get install gnupg curl
  2. Import the MongoDB public key:

    Copy
    curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
       sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg \
       --dearmor
  3. Create a list file for MongoDB:

    Copy
    echo "deb [signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/7.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

    Hint: In the code snippet above, we assume you are using Debian 12. For a previous version of Debian, you will need to replace the titled operating system package debian bookworm with the following: 
    • Debian 10: debian buster

    • Debian 11: debian bullseye

  4. Reload the local package database:

    Copy
    sudo apt-get update
  5. Install the latest stable version of MongoDB:

    Copy
    sudo apt-get install -y mongodb-org
  6. Hold the currently installed version of the MongoDB package to prevent it from being automatically upgraded to a newer version when updates are installed:

    Copy
    sudo apt-mark hold mongodb-org
  7. Open the MongoDB configuration file:

    Copy
    sudo nano /etc/mongod.conf
  8. By default, MongoDB only listens locally.You must modify either the bindIp or bindIpAll setting in the MongoDB configuration file so that the port binds to an interface address or a host name or listens on all interfaces. See the example configurations below.

    To listen on all interfaces:

    Copy
    net:
      port: 27017
      bindIpAll: true

    To bind to a specific interface, like 192.168.50.71:

    Copy
    net:
      port: 27017
      bindIp: 192.168.50.71

    To bind to a host name, like graylog01:

    Copy
    net:
      port: 27017
      bindIp: graylog01
  9. Enable MongoDB and start the service:

    Copy
    sudo systemctl daemon-reload
    sudo systemctl enable mongod.service
    sudo systemctl start mongod.service

Install Data Node

Data Node is a component in Graylog's architecture designed to handle log ingestion, processing, and indexing, managing communication with OpenSearch for storing and querying logs efficiently. As noted in the Core architecture, the Data Node service should be maintained on its own node, separate from Graylog and MongoDB.

To install Data Node, we recommend you follow the process below: 

  1. Install the Data Node package:

    Copy
    wget https://packages.graylog2.org/repo/packages/graylog-6.2-repository_latest.deb
    sudo dpkg -i graylog-6.2-repository_latest.deb
    sudo apt-get update
    sudo apt-get install graylog-datanode
  2. Ensure that the Linux setting vm.max_map_count is set to at least 262144. To check the current value:

    Copy
    cat /proc/sys/vm/max_map_count

    To increase the value:

    Copy
    echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.d/99-graylog-datanode.conf
    sudo sysctl --system
    cat /proc/sys/vm/max_map_count
  3. Create your password_secret. This is a secure, randomly generated string used to encrypt sensitive data within the system:

    Copy
    openssl rand -hex 32

    Hint: This command uses OpenSSL, a toolkit for TLS/SSL protocols and cryptography, to generate a secure random password. See the OpenSSL documentation for more information.

  4. Open the Data Node configuration file:

    Copy
    sudo nano /etc/graylog/datanode/datanode.conf
  5. Add the password_secret value to the Data Node configuration file. Note that you must add this same value to the Graylog server configuration file in a later step since it is crucial that this value be the same for the Graylog node.

  6. Ensure the heap settings are set to half your system memory, up to a max of 31 GB. To do so, you will need to add the following configuration property to your Data Node configuration file. For example, if you have 16 GB of RAM, you would set it to 8 GB, like in the example below:

    Copy
    opensearch_heap = 8g

    Warning: This configuration property is not included in the datanode.conf by default! It must be added to the file manually.

  7. Configure the MongoDB connection string in the Data Node configuration file. In the following example command, graylog01 represents the host name of the MongoDB node:

    Copy
    mongodb_uri = mongodb://graylog01:27017/graylog
  8. Enable Data Node and start the service:

    Copy
    sudo systemctl daemon-reload
    sudo systemctl enable graylog-datanode.service
    sudo systemctl start graylog-datanode

Install Graylog

After Data Node installation is complete, you must install the core Graylog service. The Core architecture model is designed so that Graylog and MongoDB are installed on the same node.

To install Graylog, we recommend you follow the process below: 

1. Install the Graylog package.

2. Use the following command to create your root_password_sha2. This is the password for the root administrator account for the Graylog interface. Make sure you record this password as you will need it to log into the Graylog interface after preflight configuration: 

Copy
echo -n "Enter Password: " && head -1 </dev/stdin | tr -d '\n' | sha256sum | cut -d" " -f1

Warning: Do NOT attempt to log into Graylog for the first time using the password you generated in the steps above! You must complete the preflight login with the credentials found in the log file after first starting the Graylog service. You will be able to login to Graylog with your generated password after the preflight is complete. See The Web Interface for more information.

3. Open the Graylog server configuration file:

Copy
sudo nano /etc/graylog/server/server.conf

4. Enter the value you created for the root_password_sha2 in the previous step into the Graylog configuration file.

5. Retrieve the password secret from the Data Node configuration file as indicated in steps 3-5 of Install Data Node and add it to the password_secret property in the Graylog configuration file.

6. Set the http_bind_address value in the Graylog configuration file to the public host name or a public IP address on which the Graylog web and API server will listen for incoming HTTP requests. (This property is commented out by default and listed beneath the # HTTP settings section of the configuration file): 

Copy
http_bind_address = 0.0.0.0:9000

More information about these settings can be found in The Web Interface.

7. Adjust your journal settings. We recommend you configure your journal settings' max age to 72 hours and the size to your expected total log volume over a 72-hour period. So, if your expected daily log volume is 30 GB, your max size should be adjusted to 90 GB, as in the following example:

Copy
message_journal_max_age = 72h
message_journal_max_size = 90gb

8. Now, open the graylog-server file found by default at /etc/default/:

Copy
sudo nano /etc/default/graylog-server

9. In this file, adjust your heap settings to half the system memory up to a max of 16 GB for the Graylog service, as recommended in Additional Configuration. It is recommended that you set the minimum and maximum values to be the same, so if you are setting your minimum to 2 GB, like shown in -Xms2g, and your maximum to 2 GB, like shown in -Xmx2g, the setting may look like: 

Copy
GRAYLOG_SERVER_JAVA_OPTS="-Xms2g -Xmx2g -server -XX:+UseG1GC -XX:-OmitStackTraceInFastThrow"

10. Enable Graylog and start the service:

Copy
sudo systemctl daemon-reload
sudo systemctl enable graylog-server.service
sudo systemctl start graylog-server.service

Once installation is complete, proceed to the following section on the preflight login to access the Graylog web interface! 

Preflight Login

After installation is complete, immediately proceed to The Web Interface for information on completing the preflight process and logging into Graylog for the first time. This preflight login will require the initial login credentials found in the log file after first starting the Graylog service!

Troubleshooting and Common Issues

The following section outlines troubleshooting steps for common issues to assist you in resolving potential challenges you may encounter.

Issue: Network Connectivity Issue During MongoDB Installation

It is possible you may receive a network connectivity issue while you are initiating the replica set for MongoDB. This may be related to your DNS and/or your TCP port or network configuration.

Solution: Modify Firewall and/or DNS Settings

If you encounter this issue, we recommend you test whether the required port TCP/27017 is open. You can use telnet or nc (Netcat) to test:

Copy
nc -vz <node_ip> 27017