Prerequisites

Graylog depends on MongoDB and Elasticsearch or OpenSearch to operate. Please refer to the system requirements for details.

Downloading and Extracting the Server

Download the tar archive from the download pages and extract it on your system:

tar xvfz graylog-VERSION.tgz
cd graylog-VERSION

Configuration

Now copy the example configuration file:

# cp graylog.conf.example /etc/graylog/server/server.conf 

You can leave most variables as they are for now. They all should be well documented.

Configure at least the following variables in /etc/graylog/server/server.conf:

• is_leader = true

  • Set only one graylog-server node as the leader. This node will perform periodical and maintenance actions that follower nodes won’t. Every follower node will accept messages just as the leader nodes. Nodes will fall back to follower mode if there already is a leader in the cluster.

• password_secret

  • You must set a secret that is used for password encryption and salting here. The server will refuse to start if it’s not set. Generate a secret with pwgen -N 1 -s 96 for example. If you run multiple graylog-server nodes, make sure you use the same password_secret for all of them!

• root_password_sha2

  • A SHA2 hash of a password you will use for your initial login. Set this to a SHA2 hash generated with echo -n "Enter Password: " && head -1 </dev/stdin | tr -d '\n' | sha256sum | cut -d" " -f1 and you will be able to log in to the web interface with username admin and password yourpassword.

• elasticsearch_hosts

  • List of Elasticsearch hosts Graylog should connect to.

• mongodb_uri

  • Enter your MongoDB connection and authentication information here.

Starting the Server

You need to have Java installed. Running the OpenJDK is fine and should be available on all platforms. For example on Debian it is:

apt-get install openjdk-17-jre

Start the server:

cd bin/$ ./graylogctl start

The server will try to write a node_id to the graylog-server-node-id file. It won’t start if it can’t write there because of missing permissions for example.

See the startup parameters description below to learn more about available startup parameters. Note that you might have to be bound to the popular port 514 for syslog inputs.

You should see a line like this in the debug output of Graylog successfully connected to your Elasticsearch cluster:

2013-10-01 12:13:22,382 DEBUG: org.elasticsearch.transport.netty - [graylog-server] connected to node [[Unuscione, Angelo][thN_gIBkQDm2ab7k-2Zaaw][inet[/10.37.160.227:9300]]]

You can find Graylog logs in the directory logs/.

Supplying External Logging Configuration

Graylog uses Apache Log4j 2 for its internal logging and ships with a default log configuration file which is embedded within the shipped JAR.

In case you need to modify Graylog’s logging configuration, you can supply a Java system property specifying the path to the configuration file in your start script (e.g. graylogctl).

Append this before the -jar parameter:

-Dlog4j.configurationFile=file:///path/to/log4j2.xml

Substitute the actual path to the file for the /path/to/log4j2.xml in the example.

In case you do not have a log rotation system already in place, you can also configure Graylog to rotate logs based on their size to prevent the log files growing without bounds by using the RollingFileAppender.

One such example log4j2.xml configuration is shown below:

<?xml version="1.0" encoding="UTF-8"?>
 <Configuration packages="org.graylog2.log4j" shutdownHook="disable">
  <Appenders>
      <RollingFile name="rolling-file" fileName="/var/log/graylog-server/server.log" filePattern="/var/log/graylog-server/server.log.%i.gz">
          <PatternLayout pattern="%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} %-5p [%c{1}] %m%n"/>
          <Policies>
              <SizeBasedTriggeringPolicy size="50MB"/>
          </Policies>
          <DefaultRolloverStrategy max="10" fileIndex="min"/>
      </RollingFile>

      <!-- Internal Graylog log appender. Please do not disable. This makes internal log messages available via REST calls. -->
      <Memory name="graylog-internal-logs" bufferSize="500"/>
  </Appenders>
  <Loggers>
      <!-- Application Loggers -->
      <Logger name="org.graylog2" level="info"/>
      <Logger name="com.github.joschi.jadconfig" level="warn"/>
      <!-- This emits a harmless warning for ActiveDirectory every time which we can't work around :( -->
      <Logger name="org.apache.directory.api.ldap.model.message.BindRequestImpl" level="error"/>
      <!-- Prevent DEBUG message about Lucene Expressions not found. -->
      <Logger name="org.elasticsearch.script" level="warn"/>
      <!-- Disable messages from the version check -->
      <Logger name="org.graylog2.periodical.VersionCheckThread" level="off"/>
      <!-- Silence chatty natty -->
      <Logger name="com.joestelmach.natty.Parser" level="warn"/>
      <!-- Silence Kafka log chatter -->
      <Logger name="kafka.log.Log" level="warn"/>
      <Logger name="kafka.log.OffsetIndex" level="warn"/>
      <!-- Silence useless session validation messages -->
      <Logger name="org.apache.shiro.session.mgt.AbstractValidatingSessionManager" level="warn"/>
      <Root level="warn">
          <AppenderRef ref="rolling-file"/>
          <AppenderRef ref="graylog-internal-logs"/>
      </Root>
  </Loggers>
</Configuration>

Command Line (CLI) Parameters

There are a number of CLI parameters you can pass to the call in your graylogctl script:

• -h, --help: Show help message
• -f CONFIGFILE, --configfile CONFIGFILE: Use configuration file CONFIGFILE for Graylog; default: /etc/graylog/server/server.conf
• -d, --debug: Run in debug mode
• -l, --local: Run in local mode. Automatically invoked if in debug mode. Will not send system statistics, even if enabled and allowed. Only interesting for development and testing purposes.
• -p PIDFILE, --pidfile PIDFILE: Set the file containing the PID of Graylog to PIDFILE; default: /tmp/graylog.pid.
• -np, --no-pid-file: Do not write PID file (overrides -p/--pidfile).
• --version: Show version of Graylog and exit.

Problems with IPv6 vs. IPv4?

If your Graylog node refuses to listen on IPv4 addresses and let's say it always chooses a http_bind_address like :::9000 you can tell the JVM to prefer the IPv4 stack.

Add the java.net.preferIPv4Stack flag in your graylogctl script or from wherever you are calling the graylog.jar:

sudo -u graylog java -Djava.net.preferIPv4Stack=true -jar graylog.jar

Create a Message Input and Send an Initial Message

Log in to the web interface on port 9000 (e.g. https://127.0.0.1:9000) and navigate to System > Inputs.

Launch a new Raw/Plaintext UDP input, listening on 127.0.0.1 on port 9099. There’s no need to configure anything else for now.

The list of running inputs on that node should show your new input right away.

Let’s send a message in:

echo "Hello Graylog, let's be friends." | nc - w 1 - u 127.0 . 0.1 9099

This will send a short string to the raw UDP input you just opened. Now search for friends using the search bar at the top and you should see the message you just sent in. Click on it in the table and see it in detail:

You have just sent your first message to Graylog! Why not spawn a syslog input and point some of your servers to it? You could also create some user accounts for your colleagues.