1. Introduction

We've tried to make Sagan as simple and easy to use as possible. For the most part, compiling and installation is done your typical Unix way. That is, the old "./configure && make && make install". Currently, there is only one required dependency to get the basic functionality of Sagan up and running. However, this basic functionality is extremely limited.

This Sagan installation guide covers the most common and most requested functions of Sagan. These are:

  • The best log normalization possible.
  • Unified2 output.
  • Writing alerts to a SQL database with Barnyard2.
Sagan is capable of much, much more. However, this document will only cover the above. If you are interested in other Sagan capabilities, see the SaganPrerequisites.

2. Sagan Prerequisites (library requirements, etc).

For this document, we'll need to install three Sagan prerequisites. They are:

  • PCRE - libpcre is used for rules that have regular expressions
  • LibLogNorm - Used to extract useful information from logs.
  • libdnet - This is used for Unified2 output, which is used with Barnyard2 & writing to SQL databases.

2.1 Installing PCRE.

That is PCRE (http://www.pcre.org) (libpcre). With only the PCRE library dependency meant, this will get the Sagan engine up and running with the most basic fuctionality.

Operating System Commands to install PCRE
Gentoo emerge -av libpcre
Ubuntu apt-get install libpcre3-dev libpcre3
FreeBSD/OpenBSD cd /usr/ports/devel/pcre && make && make install
CentOS / Redhat yum install pcre-devel

2.2 Installing LibLogNorm.

LibLogNorm helps Sagan extract useful information for log messages. Sagan will operate without this library, but it may not always extract important information you may want. I the majority of cases, you probably want LibLogNorm installed.

Operating System Commands to install liblognorm
Gentoo emerge -av liblognorm
Ubuntu apt-get install liblognorm0 liblognorm-dev
FreeBSD/OpenBSD Install from source. See LibLogNorm
CentOS / Redhat Install from source. See LibLogNorm

Note: liblognorm version 1.0.0 is required for Sagan! Make sure your distribution is version 1.0.0 or higher! If it is not, consider building liblognorm from source!

If you distribution doesn't have LibLogNorm, consider building from source. See the LibLogNorm for more information about building from source.

2.3 Installing libdnet.

An optional, but typically desired dependency is the ability to write alerts to a SQL database. This is also required if you want to view Sagan events in consoles link Snorby, Squil, etc. This also lets Sagan correlate log events with your Snort or Suricata. In order to do this, you'll want Sagan to have the ability to write alerts in a Unified2 output format. In order to do this, Sagan requires libdnet (http://libdnet.sf.net).

Operating System Commands to install libdnet
Gentoo emerge -av libdnet
Ubuntu apt-get install libdumbnet1 libdumbnet-dev
FreeBSD/OpenBSD cd /usr/ports/net/libdnet && make && make install
CentOS/Redhat Manual install from source (http://libdnet.sourceforge.net)

If you require Sagan to other action on alerting (e-mailing, etc), check out the SaganPrerequisites page.

3. Compiling and installing Sagan.

We will need to download the Sagan source code. There are two locations of the Sagan source code. The development tree that is located on Github and the stable branch that is located on the main Sagan site (http://sagan.quardrantsec.com). For this document, we'll be building the development branch.

To the download the development source code, you can use the "git" command like this:

git clone https://github.com/beave/sagan

Note: if you don't have "git" installed, you can download the source with wget. Type "wget https://github.com/beave/sagan/archive/master.zip"

After the transfer is complete, go into the Sagan source directory.

cd sagan

At this point, you'll want to run "configure" command. This sets up Sagan to be compiled. For additional configuration options, type "./configure --help". Otherwise, type:


Note to FreeBSD/OpenBSD users. When using the Bash shell, you may need to do the following to get ./configure to detect system libraries properly: "LDFLAGS=-L/usr/local/lib CFLAGS=-I/usr/local/include ./configure"

Once this completes without errors, Sagan will be ready to compile. Type the following commands:

sudo make
sudo make install

Note: By default, the Sagan binary will be saved to the /usr/local/bin directory. The Sagan configuration file will be saved to the /usr/local/etc directory. To change this, look into the "--prefix" configure option.

At this point, Sagan should be installed. To test, you can execute sagan like this:

sagan --help

If Sagan is installed correctly, it should display a help screen along with the version of Sagan installed. If it does not, back track in the installation processes and look for errors.

There are still a few more things we need to do to the system before we are ready to continue. For one, we need to add a user to the system for Sagan to "run as". In most cases, Sagan is typically started by the "root" user. However, for security reasons, when Sagan is fully initialized, Sagan releases the "root" privileges and becomes a non-privileged user. By default, Sagan attempts to use the user name "sagan". With this in mind, we need to add a "sagan" user to the system. Depending on the operating system/distribution you are running, this command may or may not work. If this command fails, consult the documentation for your system on "how to add users".

sudo useradd sagan --shell /sbin/nologin --home /
After the non-privileged users has been created, we'll need to give ownership to a couple of directories for Sagan to write to. To do this, type:
sudo chown -R sagan:sagan /var/log/sagan
sudo chown -R sagan:sagan /var/run/sagan

We are now ready to move on to the Sagan configuration file!

4. The Sagan configuration file (sagan.conf).

The Sagan configuration file, which by default is located in the /usr/local/etc/sagan.conf, has quite a few options in it. Rather than going over all possible configuration options, we'll be going over the nessesary to accomplish our goal. That is to have Sagan up and running with signatures, writing a unified2 output file for alerts and having Barnyard2 store those alerts into a SQL database. After you have Sagan up and running, you may then want to go back and read about more advanced configuration option. Sagan can do some pretty interesting and nifty things with logs, let's get the basics up and running first.

Open the /usr/local/etc/sagan.conf with your favorite text editor (vim, nano, etc).

Find the following lines:

sagan_port 514

Replace the with the IP address of the system that will be running Sagan. Replace the 514 with the port you plan on recieving syslog messages on (514 is the default syslog port).

Note: Technically, this information is only used when log normalization fails. Sagan does not actually recieve syslog messages over then network. You syslog daemon will actually receive the syslog data and hand it to Sagan. If you don't use UDP to recieve logs, add the option "sagan_proto 6" (TCP).

Next we will want to enable unified2 output, which we will later use with Barnyard2. Find the following line and make sure it is enabled.

output unified2: filename sagan.u2, limit 128

The final step of the configuration processes is to enabled/disable Sagan rules. By default, the Sagan configuration file comes with all rules enabled. It is highly unlikely you want this, as it waste CPU and memory. You'll want to only enabled rules for software and/or equipment that you use within your network. For example, if you have Cisco ASA's in your network but you do not use Citrix gear, you'd want to enable the cisco-pixasa.rules and disable the citrix.rules.

The rules section of the "sagan.conf" is at the very bottom. Below is a short snip-it of that section:


include $RULE_PATH/apache.rules
include $RULE_PATH/apc-emu.rules
include $RULE_PATH/arp.rules
include $RULE_PATH/asterisk.rules


Note: Sagan rules are stored by default in the /usr/local/etc/sagan-rules directory. If you want to change this, alter the RULE_PATH option.

That's it!

Well, this will get the basic setup running. Once you have Sagan up and running, go back and review the other options in the Sagan configuration. There likely other options that you can benifit from. However, for the basic setup, this should get you up and running.

5. Downloading and using Sagan rules.

You'll not need rules to tell Sagan "what" to trigger on. There are two branches of rules. The stable branch and the development branch. For this document, we'll be using the development branch.

cd /usr/local/etc
sudo git clone https://github.com/beave/sagan-rules

Note: if you don't have "git" installed, you can download the source with wget. Type "wget https://github.com/beave/sagan-rules/archive/master.zip"

6. Configuring the syslog-ng/rsyslog daemon.

6.1 Basic Syslog-ng configuration.


source sagan_linux { udp(port(514)); };
destination sagan_fifo {
      template("$SOURCEIP|$FACILITY|$PRIORITY|$LEVEL|$TAG|$YEAR-$MONTH-$DAY|$HOUR:$MIN:$SEC|$PROGRAM| $MSG\n") template-escape(no));

log { source(src); destination(sagan_fifo); };
log { source(kernsrc); destination(sagan_fifo); };
log { source(sagan); destination(sagan_fifo); };

6.2 Basic "rsyslog" configuration.

# The standard "input" template Sagan uses.  Basically the message 'format' Sagan understands.  The template is _one_ line.
$template sagan,"%fromhost-ip%|%syslogfacility-text%|%syslogpriority-text%|%syslogseverity-text%|%syslogtag%|%timegenerated:1:10:date-rfc3339%|%timegenerated:12:19:date-rfc3339%|%programname%|%msg%\n"
# The FIFO/named pipe location.  This is what Sagan will read.
*.*     |/var/run/sagan.fifo;sagan

6.3 FIFO and testing

Once your syslog daemon has been configured, you'll need to create a FIFO for it to write to. To do this, issue the following commands as "root":

# mkfifo /var/run/sagan.fifo
# chown sagan:sagan /var/run/sagan.fifo    # Sagan needs to be able to read the FIFO!

Now restart your syslog daemon. Once it has been restarted, you can test it by type "cat /var/run/sagan.fifo". If you see events coming in, then your syslog daemon is correctly setup and you're ready to move on to the next step! If you don't receive any logs via the FIFO, then you'll need to correct this before moving on to the next step. The FIFO is used for Sagan to receive logs in real time. Without it, Sagan will not be able to receive logs!

7. Unified2 for database output.

If you want to log Sagan information to a SQL database, you'll need Barnyard2. Barnyard2 is a "dedicated spooler" unified2 binary output format. Sagan writes alerts to the unified2 file, just like Snort does. In order for these alerts to make there way into the SQL database, you'll need to use Barnyard2 to read in this file and write them to the database. The first step is to install Barnyard2:

Operating System Commands to install Barnyard2
Gentoo emerge -av barnyard2
Ubuntu Install from source (https://github.com/firnsy/barnyard2)
FreeBSD/OpenBSD cd /usr/ports/security/barnyard2 && make install
CentOS/Redhat Install from source (https://github.com/firnsy/barnyard2)

Once Barnyard2 is installed, you'll need to create a Barnyard2 configuration file. Below is a sample contents of the Barnyard2 configuration file is based off default file location when Sagan is built from source. You will need to modify it to fit your environment.

config reference_file: /usr/local/etc/sagan-rules/reference.config
config classification_file: /usr/local/etc/sagan-rules/classification.config
config gen_file: /usr/local/etc/sagan-rules/gen-msg.map
config sid_file: /usr/local/etc/sagan-rules/sagan-sid-msg.map
config hostname: sagan-unified2
config interface: syslog
config set_gid: sagan
config set_uid: sagan
config waldo_file: /var/log/barnyard2/barnyard2-sagan.waldo
input unified2
output database: log, mysql, user=sagan password=mypassword dbname=snort host=, detail full

Note: Make sure you change the password, username, hostname and dbname!

As the "root" user, test your configuration by running the following command. If all goes well, you should see a message "Waiting for new data". Then means that Barnyard2 is reading the data that Sagan is writing to the unified2 file.

/usr/bin/barnyard2 -c /etc/barnyard2/barnyard2-sagan.conf

To run "barnyard2" in the background, simply append the "-D" switch.

-- ChampClark - 2014-01-27

Edit | Attach | Watch | Print version | History: r16 | r14 < r13 < r12 < r11 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r12 - 2014-01-27 - ChampClark
  • Edit
  • Attach
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback