How To Install Graylog on Debian 13

Graylog stands as one of the most powerful open-source log management platforms available today, providing system administrators with comprehensive centralized logging capabilities, real-time log analysis, and robust security monitoring features. Organizations worldwide rely on Graylog to aggregate logs from multiple sources, analyze system behaviors, troubleshoot issues efficiently, and maintain security compliance across their infrastructure. This comprehensive guide walks through the complete installation process of Graylog on Debian 13, covering everything from initial system preparation to advanced configuration settings. Whether managing a small business network or enterprise-level infrastructure, this tutorial provides the technical knowledge needed to deploy a fully functional Graylog server.

Understanding Graylog Architecture

Before diving into installation, understanding Graylog’s architecture helps ensure proper deployment. Graylog operates on a three-tier architecture consisting of MongoDB, OpenSearch (or Elasticsearch), and the Graylog Server itself. MongoDB serves as the metadata storage engine, maintaining Graylog’s configuration data, user information, and system settings. OpenSearch functions as the primary data node, indexing and storing massive volumes of log data for lightning-fast search and retrieval.

The Graylog Server acts as the central processing unit, handling log ingestion, parsing, enrichment, and providing the web interface for visualization and analysis. When logs arrive at Graylog through various inputs, the server processes them according to configured pipelines and routes them to OpenSearch for indexing. This modular architecture allows for horizontal scaling, with options for both single-node deployments suitable for testing environments and multi-node clusters designed for production workloads.

System Requirements and Prerequisites

Hardware Requirements

Proper hardware allocation ensures optimal Graylog performance. A minimum of 4GB RAM is required, though 8GB or more is strongly recommended for production environments handling moderate log volumes. The system needs at least 4 CPU cores to handle concurrent log processing, searching, and web interface operations efficiently. Storage requirements vary significantly based on log retention policies and ingestion rates, but starting with 20GB minimum provides adequate space for the base installation and initial log data. For production deployments, using XFS file system offers better performance characteristics for large-scale log storage operations.

Software Prerequisites

The installation requires Debian 13 (also compatible with Debian 10, 11, or 12) with root or sudo privileges. Ensure the system has active internet connectivity for downloading necessary packages and dependencies. All system packages should be updated to their latest versions before beginning the installation process.

Network Requirements

Several network ports must be accessible for Graylog to function properly. Port 9000 serves the web interface, while port 12900 handles API communications. Input ports include 514 and 1514 for syslog traffic, and 12201 for GELF (Graylog Extended Log Format) messages. Configuring a proper DNS hostname, while optional, simplifies access management and certificate configuration for production environments.

Step 1: Update System and Install Dependencies

Begin by ensuring the system has the latest security patches and package updates. Open a terminal and execute:

sudo apt update && sudo apt upgrade -y

This command refreshes the package repository cache and upgrades all installed packages to their newest versions. Next, install the essential dependencies required for Graylog and its components:

sudo apt install apt-transport-https openjdk-17-jre-headless uuid-runtime pwgen dirmngr gnupg wget curl -y

Each dependency serves a specific purpose. The apt-transport-https package enables secure HTTPS connections for package downloads. OpenJDK 17 JRE provides the Java runtime environment required by both Graylog and OpenSearch. The uuid-runtime package generates unique identifiers, while pwgen creates secure random passwords. Both dirmngr and gnupg manage GPG keys for package verification, and wget downloads files from remote repositories.

Verify the Java installation succeeded by checking the version:

java -version

The output should display Java version 17 or higher. If kernel updates were installed, reboot the system to ensure all changes take effect:

sudo reboot

Step 2: Install and Configure MongoDB

MongoDB Installation

MongoDB stores Graylog’s configuration data, making it a critical component. First, import the MongoDB repository GPG key to verify package authenticity:

wget -qO- https://www.mongodb.org/static/pgp/server-7.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg

Add the MongoDB repository to your system’s sources list:

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

Update the package cache and install MongoDB:

sudo apt update
sudo apt install mongodb-org -y

MongoDB Configuration

Enable MongoDB to start automatically at system boot and start the service immediately:

sudo systemctl enable mongod
sudo systemctl start mongod

Verify MongoDB is running correctly:

sudo systemctl status mongod

A status of “active (running)” indicates successful installation. The MongoDB configuration file resides at /etc/mongod.conf, where advanced settings can be adjusted if needed. Test the MongoDB connection locally to ensure it accepts connections:

mongosh --eval 'db.runCommand({ connectionStatus: 1 })'

This command should return connection status information, confirming MongoDB operates correctly.

Step 3: Install and Configure OpenSearch

OpenSearch Installation

OpenSearch serves as Graylog’s search and analytics engine. Download and import the OpenSearch GPG key:

wget -qO- https://artifacts.opensearch.org/publickeys/opensearch.pgp | sudo gpg --dearmor -o /usr/share/keyrings/opensearch-keyring.gpg

Add the OpenSearch repository:

echo "deb [signed-by=/usr/share/keyrings/opensearch-keyring.gpg] https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-2.x.list

Update package lists and install OpenSearch:

sudo apt update
sudo apt install opensearch -y

OpenSearch Configuration

Edit the OpenSearch configuration file to optimize it for Graylog:

sudo nano /etc/opensearch/opensearch.yml

Configure the following essential parameters. Set the cluster name to identify your deployment:

cluster.name: graylog
node.name: ${HOSTNAME}
network.host: 0.0.0.0
discovery.type: single-node
action.auto_create_index: false
plugins.security.disabled: true

These settings configure OpenSearch for single-node operation, disable the security plugin for simplified initial setup, and prevent automatic index creation to maintain Graylog’s control over index management.

JVM Heap Configuration

Proper heap allocation significantly impacts OpenSearch performance. Edit the JVM options file:

sudo nano /etc/opensearch/jvm.options

Set heap sizes to approximately half of available system RAM. For an 8GB system, use:

-Xms4g
-Xmx4g

Never allocate more than 32GB to the heap, as this defeats Java’s compressed object pointers optimization.

System Settings

OpenSearch requires specific kernel parameters for optimal operation. Set virtual memory map count:

sudo sysctl -w vm.max_map_count=262144

Make this setting persistent across reboots:

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

Disable swap to prevent performance degradation:

sudo swapoff -a

Service Management

Enable and start OpenSearch:

sudo systemctl enable opensearch
sudo systemctl start opensearch

Verify OpenSearch is running and responding to requests:

curl -X GET http://localhost:9200

The response should display cluster information, confirming successful installation.

Step 4: Install Graylog Server

Repository Setup

Download the Graylog repository configuration package:

wget https://packages.graylog2.org/repo/packages/graylog-6.0-repository_latest.deb

Install the repository package:

sudo dpkg -i graylog-6.0-repository_latest.deb

Update the package cache to include Graylog packages:

sudo apt update

Package Installation

Install the Graylog server and integration plugins:

sudo apt install graylog-server graylog-integrations-plugins -y

The installation process places configuration files in /etc/graylog/server/ and creates the necessary service configurations. Current stable versions maintain compatibility with MongoDB 7.0 and OpenSearch 2.x, ensuring smooth operation across the entire stack.

Step 5: Configure Graylog Server

Generating Security Credentials

Graylog requires two critical security values. Generate a 96-character password secret used for encryption:

pwgen -N 1 -s 96

Copy the output for use in the configuration file. This password_secret encrypts sensitive data stored in MongoDB and must never be changed after initial configuration.

Create a SHA-256 hash of your desired admin password:

echo -n "YourStrongPassword" | sha256sum | cut -d" " -f1

Replace “YourStrongPassword” with your chosen administrator password. Copy the resulting hash.

Editing Server Configuration

Open the Graylog server configuration file:

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

Locate and configure the following parameters. Add the password secret generated earlier:

password_secret = [your-96-character-secret]

Add the SHA-256 password hash:

root_password_sha2 = [your-password-hash]

Network Configuration

Configure network binding to determine which interfaces Graylog listens on. For direct access without a reverse proxy, bind to all interfaces:

http_bind_address = 0.0.0.0:9000

Alternatively, when using a reverse proxy, bind only to localhost:

http_bind_address = 127.0.0.1:9000

Set the external URI that users will use to access Graylog:

http_external_uri = http://your-server-ip:9000/

Replace “your-server-ip” with your actual server IP address or fully qualified domain name.

Database Connection Configuration

Configure the MongoDB connection URI:

mongodb_uri = mongodb://localhost:27017/graylog

Configure OpenSearch hosts:

elasticsearch_hosts = http://localhost:9200

Save the configuration file and exit the editor.

Step 6: Start and Enable Graylog Service

Reload the systemd daemon to recognize configuration changes:

sudo systemctl daemon-reload

Enable Graylog to start automatically at boot:

sudo systemctl enable graylog-server

Start the Graylog service:

sudo systemctl start graylog-server

Check the service status:

sudo systemctl status graylog-server

Graylog takes 30 to 60 seconds to fully initialize. Monitor the startup process by tailing the log file:

sudo tail -f /var/log/graylog-server/server.log

Look for the message “Graylog server up and running” indicating successful startup. If errors appear, they typically relate to configuration issues or connection problems with MongoDB or OpenSearch.

Step 7: Configure Firewall Rules

Proper firewall configuration balances security with functionality. Install UFW if not already present:

sudo apt install ufw -y

Allow SSH to prevent locking yourself out:

sudo ufw allow 22/tcp

Open the Graylog web interface port:

sudo ufw allow 9000/tcp

Allow API access:

sudo ufw allow 12900/tcp

Configure syslog input ports:

sudo ufw allow 514/tcp
sudo ufw allow 514/udp
sudo ufw allow 1514/tcp

Allow GELF input:

sudo ufw allow 12201/udp

Enable the firewall:

sudo ufw enable

For production environments, restrict access to specific IP addresses or subnets instead of allowing all connections. For example:

sudo ufw allow from 192.168.1.0/24 to any port 9000 proto tcp

Step 8: Access Graylog Web Interface

Open a web browser and navigate to your Graylog instance:

http://your-server-ip:9000

The Graylog login page should appear. Use the default credentials:

• Username: admin
• Password: The password you hashed in Step 5

After successful authentication, Graylog presents the main dashboard displaying system overview information. The interface includes several key sections: the Search page for querying logs, Streams for organizing log data, Inputs for configuring log sources, and System for administrative functions.

Immediately change the default password through the user profile settings to enhance security. Navigate to System > Users, select the admin user, and update the password.

If the interface fails to load or displays a blank page, verify the http_external_uri configuration matches the URL used to access Graylog. Check the browser console for JavaScript errors that might indicate configuration issues.

Step 9: Configure Graylog Inputs

Understanding Inputs

Inputs define how Graylog receives log data from various sources. Graylog supports numerous input types including Syslog, GELF, Beats, Raw/Plaintext, and many others. Each input type uses specific protocols and formats optimized for different use cases.

Creating a Syslog UDP Input

Syslog remains the most common logging protocol for Unix-like systems. Navigate to System > Inputs in the Graylog web interface. From the dropdown menu, select “Syslog UDP” and click “Launch new input”.

Configure the input parameters in the dialog that appears:

• Title: Give the input a descriptive name like “Syslog UDP 514”
• Bind address: Use 0.0.0.0 to listen on all interfaces
• Port: Enter 514 for standard syslog (requires root) or 1514 for unprivileged operation
• Store full message: Enable to preserve original messages

Click “Save” to create the input. The new input appears in the inputs list with a green “RUNNING” status indicator.

Input Setup Wizard

Graylog’s setup wizard streamlines initial configuration. The wizard guides through data routing, stream creation, and index set configuration. For basic setups, accepting default settings works well. Advanced deployments benefit from creating dedicated streams to organize logs by source type, facility, or priority.

Testing Input Connectivity

Verify the input receives data by sending a test message from the Graylog server itself:

logger -n localhost -P 1514 "Test message from Graylog server"

Navigate to the Search page and look for the test message in recent logs. If messages don’t appear, check firewall rules, verify the input shows “RUNNING” status, and review server logs for errors.

Step 10: Set Up Nginx Reverse Proxy (Optional)

Why Use a Reverse Proxy

Implementing Nginx as a reverse proxy provides several advantages. It simplifies SSL/TLS certificate management, centralizes authentication, enables advanced load balancing across multiple Graylog nodes, and adds an extra security layer.

Installing Nginx

Install Nginx from Debian repositories:

sudo apt install nginx -y

Enable and start the Nginx service:

sudo systemctl enable nginx
sudo systemctl start nginx

Configuring Nginx for Graylog

Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/graylog

Add the following configuration:

server {
    listen 80;
    server_name graylog.yourdomain.com;

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Graylog-Server-URL http://$server_name/;
        proxy_pass http://127.0.0.1:9000;
    }
}

Enable the configuration by creating a symbolic link:

sudo ln -s /etc/nginx/sites-available/graylog /etc/nginx/sites-enabled/

Test the configuration for syntax errors:

sudo nginx -t

Reload Nginx to apply changes:

sudo systemctl reload nginx

Enabling HTTPS/SSL

For production environments, always use HTTPS. Install Certbot for Let’s Encrypt certificates:

sudo apt install certbot python3-certbot-nginx -y

Obtain and configure SSL certificates automatically:

sudo certbot --nginx -d graylog.yourdomain.com

Certbot modifies the Nginx configuration to enable HTTPS and configures automatic HTTP to HTTPS redirection.

Updating Graylog Configuration

Modify Graylog’s server.conf to work behind the proxy:

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

Update these settings:

http_bind_address = 127.0.0.1:9000
http_external_uri = https://graylog.yourdomain.com/

Restart Graylog to apply changes:

sudo systemctl restart graylog-server

Access Graylog through the Nginx proxy at https://graylog.yourdomain.com. If encountering blank pages, verify all proxy headers are correctly configured and http_external_uri matches the external URL.

Step 11: Configure Log Sources

Configuring Rsyslog

Most Debian systems use rsyslog for local logging. Configure rsyslog to forward logs to Graylog. Create a new configuration file:

sudo nano /etc/rsyslog.d/90-graylog.conf

Add the following content to forward all logs:

*.* @localhost:1514;RSYSLOG_SyslogProtocol23Format

This configuration forwards all facilities and priorities to Graylog using RFC 5424 format. For UDP transmission, use @. For TCP (more reliable), use @@.

Restart rsyslog to activate the configuration:

sudo systemctl restart rsyslog

Configuring Remote Servers

To send logs from remote servers, replace localhost with the Graylog server’s IP address:

*.* @graylog-server-ip:1514;RSYSLOG_SyslogProtocol23Format

Ensure firewall rules on both the client and Graylog server allow the configured port.

Testing Log Transmission

Generate test log entries:

logger "Test message from remote server"

Check Graylog’s search interface for the test message. If logs don’t appear, verify network connectivity, check firewall rules, and ensure the Graylog input is running and listening on the correct port. Review rsyslog’s status for error messages:

sudo systemctl status rsyslog

Security Best Practices

Implementing robust security measures protects log data and system integrity. Change default passwords immediately after installation, using strong, unique passwords for all accounts. Configure role-based access control (RBAC) to limit user permissions according to their responsibilities.

Implement advanced authentication methods such as LDAP, Active Directory, or SAML for centralized user management in enterprise environments. Enable TLS/SSL for all connections, including web interface access and log transmission, to prevent data interception.

Restrict input sources to specific IP addresses or networks to prevent unauthorized log injection and potential denial-of-service attacks. Harden firewall configurations by allowing only necessary ports and implementing IP whitelisting for administrative access.

Maintain regular security updates by monitoring Graylog, MongoDB, and OpenSearch releases for security patches . Configure alerts for suspicious activities, including failed login attempts, unusual query patterns, or unexpected system behavior. Secure database connections by enabling authentication for MongoDB and OpenSearch in production environments.

Troubleshooting Common Issues

Graylog Service Won’t Start

When Graylog fails to start, examine the service logs for detailed error messages:

sudo journalctl -u graylog-server -n 100

Common causes include configuration syntax errors, incorrect password_secret or root_password_sha2 values, inability to connect to MongoDB or OpenSearch, and insufficient memory or system resources. Verify all services are running:

sudo systemctl status mongod opensearch graylog-server

Check that MongoDB and OpenSearch respond to health checks before troubleshooting Graylog further.

Messages Not Appearing in Search

When logs fail to appear in search results, several factors might be responsible. Timestamp issues rank among the most common culprits—messages with timestamps far in the future or past won’t appear in default search ranges. Adjust the time range selector in the search interface to cover wider periods.

Index problems can prevent message storage or retrieval. Navigate to System > Indices to verify indices show “green” health status. Failed indices require intervention to restore functionality. Time range selection must encompass the message timestamps for them to appear in results.

Web Interface Issues

Blank pages when accessing through a reverse proxy typically indicate incorrect header configuration or http_external_uri mismatch. Verify all X-Forwarded-* headers are properly set in the proxy configuration. Connection timeout errors suggest network connectivity issues or firewall blockages.

SSL/TLS handshake errors occur when certificate configurations are incomplete or incorrect. Verify certificate validity, ensure proper certificate chain installation, and confirm Graylog’s http_external_uri uses the correct protocol (http vs https).

OpenSearch/Elasticsearch Problems

Heap size misconfiguration causes frequent crashes or out-of-memory errors. Review and adjust JVM heap settings in /etc/opensearch/jvm.options. Monitor cluster health status:

curl -X GET http://localhost:9200/_cluster/health?pretty

Yellow or red status indicates problems requiring attention. Index optimization and maintenance become necessary as data volumes grow, requiring regular attention to prevent performance degradation.

Performance Issues

Thread limit problems manifest as “Unable to create new native thread” errors. Increase system thread limits in /etc/security/limits.conf. Storage I/O bottlenecks significantly impact performance—using SSD storage dramatically improves log ingestion and search speeds.

Query optimization becomes crucial as data volumes increase. Use specific field searches instead of full-text searches when possible, and implement index retention policies to manage data volume.

Performance Optimization Tips

Tuning JVM heap sizes appropriately maximizes performance without wasting resources. Allocate 50% of system RAM to OpenSearch heap, never exceeding 32GB. Configure proper index retention policies to automatically close and delete old indices, preventing unlimited storage growth.

SSD storage provides substantially better I/O performance compared to traditional spinning disks, particularly for OpenSearch data directories. Optimize OpenSearch cluster settings including shard allocation, refresh intervals, and merge policies based on workload characteristics.

Manage disk space proactively by configuring watermark settings that prevent disk space exhaustion. Organize streams and index sets logically to improve search performance and simplify data management. Optimize processing pipelines by placing simple rules before complex ones and avoiding unnecessary processing steps.

Regular maintenance tasks including index optimization, curator jobs, and cleanup routines keep the system running efficiently. Monitor system resources continuously to identify bottlenecks and plan capacity upgrades before problems occur.

Congratulations! You have successfully installed Graylog. Thanks for using this tutorial for installing Graylog log management and security analytics on your Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Graylog website.