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:

MongoDB: The MongoDB configuration file. For extensive information on the configuration properties included in this file, we recommend you review the MongoDB documentation. We offer some additional guidance on the use and maintenance of this file in Additional Configuration.
Data Node: The Graylog Data Node has a configuration file that should be adjusted during deployment. A full reference for the Data Node configuration file can be found in Data Node Configuration Settings Reference.
Graylog: Graylog also has both a configuration file and a service file that should be adjusted during deployment. We recommend you review Initial Configuration Settings first. A full reference for the Graylog server configuration file can also be found in Graylog Server Configuration Settings Reference. Also, the Graylog service file must be adjusted for heap settings; additional information on this file may be found in Additional Configuration.

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.

Install gnupg and curl:
Copy
```
sudo apt-get install gnupg curl
```

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

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
Reload the local package database:
Copy
```
sudo apt-get update
```
Install the latest stable version of MongoDB:
Copy
```
sudo apt-get install -y mongodb-org
```
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
```
Open the MongoDB configuration file:
Copy
```
sudo nano /etc/mongod.conf
```
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
```

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:

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

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

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.

Open the Data Node configuration file:

Copy

sudo nano /etc/graylog/datanode/datanode.conf

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.
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.
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
```

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:

On your Graylog/MongoDB node, install the Graylog package.
For Graylog Open ▼
Copy
sudo apt-get install graylog-server
For Graylog Enterprise ▼
Copy
sudo apt-get install graylog-enterprise
For Graylog Security ▼
Copy
sudo apt-get install graylog-enterprise
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.
Open the Graylog server configuration file:
Copy
```
sudo nano /etc/graylog/server/server.conf
```
Enter the value you created for the root_password_sha2 in the previous step into the Graylog configuration file.
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.
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
```
Hint: More information about these settings can be found in The Web Interface.
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
```
Open the graylog-server file found by default at /etc/default/:
Copy
```
sudo nano /etc/default/graylog-server
```
In the graylog-server 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"
```

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