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
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.graylog-server
- Set only one
-
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
nodes, make sure you use the samegraylog-server
password_secret
for all of them!
- 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
-
root_password_sha2
- A SHA2 hash of a password you will use for your initial login. Set this to a SHA2 hash generated with
and you will be able to log in to the web interface with username admin and password yourpassword.echo -n "Enter Password: " && head -1 </dev/stdin | tr -d '\n' | sha256sum | cut -d" " -f1
- A SHA2 hash of a password you will use for your initial login. Set this to a SHA2 hash generated with
-
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
parameter:-jar
-Dlog4j.configurationFile=file:///path/to/log4j2.xml
Substitute the actual path to the file for the
in the example./path/to/log4j2.xml
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
configuration is shown below:log4j2.xml
<?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
script:graylogctl
-h
,--help
: Show help message-f CONFIGFILE
,--configfile CONFIGFILE
: Use configuration fileCONFIGFILE
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 toPIDFILE
; 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
flag in your java.net.preferIPv4Stack
script or from wherever you are calling the graylogctl
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
on port 127.0.0.1
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.