-------------------------------------------

DEMARC Network Security Monitor v. 1.05-RC2 

       ::Installation Document::

Website: http://demarc.org/
Updated: August 27, 2001  
Contributors:
 Demarc Team  (info@demarc.org)
 Patrick Prue (scream@cgocable.net)

-------------------------------------------


[Step 1: System Check List]
-------------------------------------------
Required:
Perl 5.005
MySQL 3.23 or higher with development libraries
Snort 1.8 or higher 
 Libpcap (Required by Snort)
 Libnet (Optional: Provides flex response capabilities for Snort)

-----------------------------------------

 
[Step 2a: Unpack DEMARC]
-----------------------------------------
Home: http://demarc.org/
Source: http://demarc.org/downloads/demarc-105/demarc-1.05RC2.tar.gz

 In your shell:
 ------------------
 tar fxvz demarc-1.05-RC2.tar.gz

##########################
# For new installations:
 mv demarc-1.05-RC2 /usr/local/demarc

NOTE: a new "tmp" directory is included under "/usr/local/demarc", it
is highly suggested that you make it readable/writable ONLY by the 
user the webserver runs as. For example, if it runs as "nobody", you
would perform the following:

 chown nobody /usr/local/demarc/tmp
 chmod 700 /usr/local/demarc/tmp

If you are unsure, or are not concerned with security on that box, it 
will work without any changes, but it aill be readable/writable by all.

Make sure that the first line of the following files
you just copied have the correct path to the perl interpreter on
your system. This usually does NOT need to be changed from the
default "#!/usr/bin/perl" though:

 /usr/local/demarc/bin/demarcd
 /usr/local/demarc/cgi/demarc
 /usr/local/demarc/install/dm_load_db.pl
 /usr/local/demarc/check_pms.pl


##########################
# Upgrading from DEMARC 1.04.XX:

 mv demarc-1.05-RC2 /usr/local/demarc

##########################
# Upgrading from DEMARC 1.05-RC2:

You can keep the same conf files that you modified for 1.05-RC2,
but you will need to copy over the newest versions of the following files:

 cp demarc-1.05-RC2/bin/demarcd /usr/local/demarc/bin/
 cp demarc-1.05-RC2/cgi/demarc /usr/local/demarc/cgi/
 cp demarc-1.05-RC2/cgi/stub_traffic_file /usr/local/demarc/cgi/
 cp demarc-1.05-RC2/cgi/templates/* /usr/local/demarc/cgi/templates/
 cp demarc-1.05-RC2/images/* /usr/local/demarc/images/

Make sure that the first line of the "demarc" and "demarcd" files
you just copied have the correct path to the perl interpreter on
your system. This usually does NOT need to be changed from the
default "#!/usr/bin/perl" though.

You will also need a new "tmp" directory under "/usr/local/demarc"
and it will need to be readable/writable by the owner of webserver.
Assuming the user is "nobody", you can do this as follows:
 
 mkdir /usr/local/demarc/tmp
 chown nobody /usr/local/demarc/tmp
 chmod 700 /usr/local/demarc/tmp

*If you don't know who the webserver runs as, you can get by by doing the
following, but it IS insecure and we recomend against it!:

 mkdir /usr/local/demarc/tmp
 chmod 777 /usr/local/demarc/tmp
  

-----------------------------------------
 

[Section 2b: Building the Binaries - MySQL]
-------------------------------------------
You will need a MySQL database in order to use Demarc. Only one host needs to
have a MySQL server installed.

Home: http://www.mysql.com/
Source: http://prdownloads.sourceforge.net/mysql/mysql-3.23.41.tar.gz
Linux RPM: (Download all of the following for standard i386 architecture)
      http://www.mysql.com/Downloads/mysql-3.23/mysql-shared-3.23.41-1.i386.rpm
      http://www.mysql.com/Downloads/mysql-3.23/mysql-devel-3.23.37-1.i386.rpm
      http://www.mysql.com/Downloads/mysql-3.23/mysql-client-3.23.37-1.i386.rpm
      http://www.mysql.com/Downloads/mysql-3.23/mysql-shared-3.23.37-1.i386.rpm

 In your shell:
 ------------------

 tar -fxvz mysql-3.23.41-1.tar.gz
 cd mysql-3.23.41-1

 ./configure --prefix=/usr/local/mysql \
 --enable-assembler \

 make
 make install
 /usr/local/mysql/bin/mysql_install_db
 

   Linux Systems:
  ------------------

  echo /usr/local/mysql/lib/mysql >> /etc/ld.so.conf
  ldconfig 

  To start the MySQL server on bootup:
  copy /usr/local/mysql/share/mysql/mysql.server to /etc/init.d/

  
   BSD Systems:
  ------------------
 
  To start the MySQL server on bootup:
  Add "/usr/local/mysql/bin/mysqld" to the /etc/rc.init file.

  
  
   AIX Systems:
  ------------------

  To start the MySQL server on bootup:
  Add "/usr/local/mysql/bin/mysqld" to the /etc/inittab or /etc/rc.tcpip
  file.

  
 

Recommendations:
------------------

 For added security create a specific MySQL user account on your system i.e. 
 "mysql". 
 
 In your shell type:
 chown -R mysql /usr/local/mysql
 
 Then edit /usr/local/mysql/bin/safe_mysqld and change the line "user=root"
 to "user=mysql" in the file.
 
 -----
 
 To resolve "Host ... is blocked" issues if you use Demarc to monitor MySQL 
 services, start the MySQL server with:
 "/usr/local/mysql/bin/mysqld -O max_connection_errors=999999999" 

------------------




[Step 2c: Building the Binaries - Perl]
-----------------------------------------
While you may already have Perl installed on your hosts, you may wish to
upgrade to version 5.6 or higher.

Home: http://www.perl.com/
Source: http://www.perl.com/CPAN/src/stable.tar.gz

 To check what version of perl you are currently using, type "perl -v" at in a 
 shell and find the line that looks like:

  "Summary of my perl5 (revision 5.0 version 6 subversion 1) configuration:"
 
  The line above would mean you're running Perl 5.6.1 and there's no need to 
  upgrade.
 
  "This is perl, version 5.005_03 built for i386-freebsd"
  The line above means that it is optional, but recommended that you upgrade.


 You will need the following Perl modules:
  DBI
  CGI
  CGI::Cookie
  DBD::MySQL

 To try and automate the process of checking and installing these modules,
 simply run the ./check_pms.pl script that is in /usr/local/demarc/install

 NOTE: In order for the DBD::MySQL module to build correctly, you MUST
 have the MySQL header files. You can usually determine if you have this
 by typing "locate MySQL.h", if you get a response back, such as
 "/usr/local/include/MySQL/MySQL.h", then you should be fine. If not, you'll
 need to get them. 
 
 Source:  http://www.cpan.org/authors/id/JWIED/DBD-mysql-2.0902.tar.gz
 Linux RPM:  http://www.rpmfind.net/linux/rpm2html/search.php?query=mysql-devel
 
 In your shell:
 ------------------

  tar fxvz DBD-mysql-2.0902.tar.gz
  cd DBD-mysql-2.0902
  perl Makefile.PL
  make && make install

 
   FreeBSD Systems:
  ------------------

  On FreeBSD they are installed automatically with the MySQL-client port. Type:
  cd /usr/ports/databases/mysql323-client/
  make && make install
 
 
Recommendations:
------------------

 Even if mysql.h is installed, the automatic "make test" that CPAN runs has 
 a tendency to timeout. If this happens, simply install this module manually 
 without the "make test" command.

----------------------------------------



[Step 2d: Building the Binaries - Snort]
----------------------------------------
 Snort should be installed on any hosts you would like to retrieve intrusion 
 detection information from. Although not required by Demarc clients, it
 is recommended.
 
 Home: http://snort.sourcefire.com/
 Source: http://snort.sourcefire.com/releases/snort-1.8.1-RELEASE.tar.gz
 Linux RPM: http://rpmfind.net/linux/rpm2html/search.php?query=Snort
 
 Demarc requires Snort version 1.8 or higher due to the database structure.

 Libpcap Source Code
 --------------------
 Before attempting to build Snort you should ensure you have a working
 libpcap installation. Libpcap is the packet capture header file required by 
 Snort. You can check for this by typing "locate pcap.h" in your shell.

 Base: http://www.tcpdump.org/release/
 Source: http://www.tcpdump.org/release/libpcap-0.6.2.tar.gz
 Linux RPM: http://www.rpmfind.net/linux/rpm2html/search.php?query=libpcap

 If installing from source please insure to make the include files with the
 command "make install-incl" after doing your make && make install

 NOTE: If you are using Redhat Check your version of libpcap. If you have a 
 versions lower than 0.6, you should update in order to avoid potential
 issues.
 ---------------------
 
 However you get Snort, you MUST make sure that your version of Snort is
 compiled with MySQL support. If you are building from source, build Snort
 using the following commands:

 ./configure --with-mysql=/usr/local/mysql --prefix=/usr/local/snort/ 
 make && make install

 You should now have a working Snort binary in /usr/local/Snort/
 Verify this by typing "which Snort" which should return 
 "/usr/local/snort/bin/snort".

 If you do not already have a directory "/var/log/snort", please create it
 by typing "mkdir /var/log/snort/"

-----------------------------------------
 

[Step 2e: Building the Binaries - Apache]
-----------------------------------------

 OpenSSL
 ---------------
 Home: http://www.openssl.org/
 Source: http://www.openssl.org/source/

  In your shell:
  --------------- 
  cd /usr/local
  tar -fxvz openssl-0.9.6a.tar.gz
  cd openssl-0.9.6a

  ./config
  make && make test && make install
  ---------------
 

 mm (Shared memory-lib)
 ---------------
 Source: http://www.engelschall.com/sw/mm/mm-1.1.3.tar.gz

  In your shell:
  --------------- 
  cd /usr/local
  tar -fxvz mm-1.1.3.tar.gz
  cd mm-1.1.3
  ./configure --prefix=/usr/local/lib/mm
  make && make test && make install
  ldconfig (Linux only)
  --------------- 


 ModSSL
 ---------------
 Home: http://www.modssl.org/
 Source: http://www.modssl.org/source/mod_ssl-2.8.2-1.3.19.tar.gz

  In your shell:
  --------------- 
  cd /usr/local/
  tar -fxvz mod_ssl-2.8.2-1.3.19.tar.gz
  cd mod_ssl-2.8.2-1.3.19/
  ./configure \
  --with-apache=/usr/local/apache_1.3.19 \
  --with-ssl=/usr/local/ssl \
  --enable-shared=ssl \
  --with-mm=/usr/local/lib/mm
  ----------------

 Mod_Perl (optional)
 ---------------
 Home: http://perl.apache.org/
 Source: http://perl.apache.org/dist/mod_perl-1.25.tar.gz

  In your shell:
  --------------- 
  cd /usr/local
  tar -fxvz mod_perl-1.25.tar.gz
  cd mod_perl-1.25
  perl Makefile.PL \
  EVERYTHING=1 \
  APACHE_SRC=../apache_1.3.19/src \
  USE_APACI=1 \
  PREP_HTTPD=1 \
  DO_HTTPD=1
  make && make install
  ---------------
  

 Make Apache
 ---------------
 Home: http://www.apache.org/
 Source: http://www.apache.org/dist/

  In your shell:
  --------------- 
  cd /usr/local/
  tar -fxvz apache_1.3.19.tar.gz
  cd /usr/local/apache_1.3.19/
  EAPI_MM="/usr/local/lib/mm" SSL_BASE="/usr/local/ssl" 
  ./configure \
  --enable-shared=ssl \
  --enable-module=ssl \
  --activate-module=src/modules/perl/libperl.a \
  --enable-module=perl
  make && make install

  cd /usr/local/ssl/bin
  ./openssl req -new > new.cert.csr
  ./openssl rsa -in privkey.pem -out new.cert.key
  ./openssl x509 -in new.cert.csr -out new.cert.cert -req -signkey \
  new.cert.key -days 999

  cp new.cert.key /usr/local/apache/conf/ssl.key/server.key
  cp new.cert.cert /usr/local/apache/conf/ssl.crt/server.crt

-----------------------------------------


[Step 3: Preparing the MySQL Database]
-----------------------------------------

 Start the MySQL client by typing "mysql". If you have restrictions, 
 follow the format "mysql -u your_username -p" and it will then prompt 
 you for your password.

 Set a password for access by typing the following commands:

 shell> mysql -u root mysql
 mysql> UPDATE user SET Password=PASSWORD('new_password')
           WHERE user='root';
 mysql> FLUSH PRIVILEGES;


 While still at the "mysql>" prompt, type in the following commands 
 sequentially. Change the your_password to your chosen MySQL password, this 
 sequence will allow this user to connect to your MySQL server from any host 
 except the localhost.

CREATE DATABASE snort;
 
grant UPDATE,DELETE,INSERT,SELECT on snort.* to snort identified by 'your_password';

# for more security, you should lock it down to a specific site by executing
# the following variation (with the IP address of the client that will be
# connecting to the DB substituted for the fake IP address) INSTEAD of the commands above:

grant UPDATE,DELETE,INSERT,SELECT on snort.* to snort@192.168.0.11 identified by 'your_password';

FLUSH PRIVILEGES;


Many times mysql databases come with default anonymous access users.  This can cause problems and
not allow access to the snort user.  In order to delete these anonymous accounts perform the following
commands at the mysql prompt:
(NOTE: make sure there are no other programs that need this access and that you are actually
experiencing trouble after performing the previous commands before performing the following)

use mysql;
DELETE FROM user WHERE User = '';
FLUSH PRIVILEGES;
exit;
 
 -----------------------

 
 Upgrading from DEMARC 1.04.XX
 -----------------------
 From /usr/local/demarc/install run "./patch_db.pl"

 It will prompt you for DB host, username, password, and db name, etc.  
 Please make sure the DB user specified  has enough privileges to alter
 the database schema (the default snort user does not).

 Select "1" when asked:
 >Which previous version of DEMARC are you upgrading FROM? 
 >   
 >1) 1.04.XX
 >2) 1.05-RC1

 It will then run the queries against your current DB schema.
 
 
 Upgrading from DEMARC 1.05-RC1
 -----------------------
 From /usr/local/demarc/install run "./patch_db.pl"

 It will prompt you for DB host, username, password, and db name, etc.  
 Please make sure the DB user specified  has enough privileges to alter
 the database schema (the default snort user does not).

 Select "2" when asked:
 >Which previous version of DEMARC are you upgrading FROM? 
 >   
 >1) 1.04.XX
 >2) 1.05-RC1

 It will then run the queries against your current DB schema.
 


  
 New Installation
 -----------------------
 If you've followed the previous steps your database is ready to accept the schema.
 From your /usr/local/demarc/install directory, run "./dm_load_db.pl", if you get any 
 perl errors here, it's most likely due to uninstalled perl modules.

 It will prompt you as follows:
 > DB USER? >snort
 > DB PASSWORD? >your_password
 > DB HOST? >localhost
 > DB NAME? >snort

 NOTE: Please make sure the DB user specified  has enough privileges to alter
       the database schema (the default snort user does not).

 and return:
  
 > User: snort
 > Password: your_password
 > Host: localhost
 > Name: snort
 >
 > Is this correct?[Y/n] >

 Type "y" and then press enter it should run through a series of queries 
 without any errors.


Recommendations
-------------------

 To be more secure, you should have a different account for 
 each sensor, and lock those accounts down to each host they are connecting 
 from.

-----------------------------------------



[Step 4: Apache Preparation]
-------------------------------------------

 Apache is the only supported webserver at this time, however that does not
 mean it won't work on other web servers. In fact, there's no real reason for
 it not to run on any server that runs perl scripts, however we've only
 tested it on Apache. If you test it on another webserver, please send us an
 email with the details.

 DEMARC will run much faster when using mod_perl, and is optimized for use with 
 mod_perl, however it will run perfectly with regular Perl as well, just a 
 little slower. If you are using Virtual Hosts place the following between your 
 <VirtualHost ...></VirtualHost> tags, otherwise place at the bottom of your 
 httpd.conf file. Replace your_domain with your actual domain name.

  In your httpd.conf:
  -------------------
  Redirect /demarc https://your_domain.com/dm/demarc
  Alias /dm_images "/usr/local/demarc/images"
  <Directory "/usr/local/demarc/cgi">
    AllowOverride all
    DirectoryIndex demarc
  </Directory>
  --------------------
  
  For regular Perl add:
  --------------------  
  ScriptAlias /dm "/usr/local/demarc/cgi"
  ---------------------

  For Mod_Perl add:
  --------------------  
  PerlModule Apache::Registry
  KeepAlive Off
  Alias /dm /usr/local/demarc/cgi
   <Location /dm>
      SetHandler perl-script
      PerlHandler Apache::Registry
      Options ExecCGI
      allow from all
      PerlSendHeader On
      DirectoryIndex demarc
   </Location>
  --------------------  

 Finally you will need to restart Apache.
 
 In your shell:
 --------------------  
 /usr/local/apache/bin/apachectl stop
 /usr/local/apache/bin/apachectl startssl
 ---------------------
 
 Demarc can therefore be accessed in either setup option via:

 https://yourhost.com/demarc 
  
-------------------------------------------


[Step 5: Installing Demarc Console]
-------------------------------------------

 Make sure the demarc script in the new directory is executable 
 by the user the webserver runs as...  and the perl modules are
 readable by the same user, if in doubt, just issue: 

 chmod 644 /usr/local/demarc/cgi/DEMARC_config.pm
 chmod 644 /usr/local/demarc/cgi/StaticServices.pm
 chmod 755 /usr/local/demarc/cgi/demarc
 chmod -R 644 /usr/local/demarc/cgi/templates
 chmod  755 /usr/local/demarc/cgi/templates
 

 Edit your "/usr/local/demarc/cgi/DEMARC_config.pm" file and insert your database information 
 in place of the defaults it ships with, also change the value for "monitor_sid" to the snort
 SID that the monitor is being run from.  If in doubt, leave it as the default and you shouldn't
 have any problems.

 There are also paths to system binaries and other configuration options in there.
 For now, you could probably ignore everything else, and only return to it if you 
 experience problems during install.

 If you followed the directions from above you'll be fine putting those credentials here, however 
 if you are using an existing DB user, make sure the user has INSERT, SELECT, DELETE, and UPDATE.


---------

 You can run Demarc over HTTP, however it is a high security risk and not 
 recommended. Demarc will alert you if it's not running over HTTPS 
 you can bypass it by setting the following flag in the Demarc script:

 $conf{'bypass_admin_lockout_on_no_ssl'}  = 1;

 You can enable "anonymous" access which will allow anyone to log 
 in to monitor the system, but carries with it no admin privileges, by 
 setting the flag in the Demarc script:

 $conf{'allow_anonymous_access'}          = 1;

 If for some reason the default login (below) doesn't work for you, you can 
 enable anonymous access as show above. Then *temporarily* make the anonymous 
 user an admin by setting the flag in the Demarc Script:

 $conf{'anonymous_user_is_admin'}         = 1;
 
 This is a heavy security risk. Only use this to reset the admin password and
 then changed back. 

 At this point you should be able to log in:
 https://your_domain.com/demarc
  default username: admin
  default password: my_DEMARC
 NOTE: Change these as soon as you login! (under "Configure")

-------------------------------------------


[Step 6: Installing Demarc Client]
-------------------------------------------

 You'll need to untar/gz the demarc-1.05-RC2.tar.gz file on each host 
 you wish to place a sensor. You've already done it for the first sensor.
 
 The following directories can optionally be removed:
  /usr/local/demarc/cgi
  /usr/local/demarc/images
  /usr/local/demarc/install

 Softlink demarcd over to make it easier to access from any directory. 
 You should then view all of the available options in demarcd.

  In your shell:
  ---------------
  ln -s /usr/local/demarc/bin/demarcd /usr/local/bin/
  demarcd -h 
  ---------------

  Next you'll want to bring your sensor online.
  
  In your shell:
  ---------------
  demarcd -I
  ---------------

 You will be prompted for some information about the database and about the 
 sensor you're about to bring online.  If you have lynx and tar working on
 your system, you will be able to download and install the latest snort rules 
 from the http://snort.sourcefire.com/ website. 

  In your shell:
  ---------------
  killall snort
  ---------------
 
 You'll then have to take the SID # that was given to you by the last script, 
 along  with your database information and sensor name and insert those
 into the demarcd.conf file located in /usr/local/demarc/conf/demarcd.conf

 Next start demarcd for the first time:

  In your shell:
  ---------------
  demarcd
  ---------------

 You can type "demarcd" again to make sure that it is running. If all went well
 it will let you know that it is already running.

 If you should need to stop the client simply type "demarcd -k" in your shell.

-------------------------------------------


[Final Notes]
-------------------------------------------

 First place to check for errors with the client is by typing "demarcd -D" to put it 
 into debug mode.  This will stay in the foreground and all debugging info
 will be piped to STDOUT.
 
 If you're getting an "internal server error", check the httpd error log first. If 
 you still can't figure it out, submit the question to the General Users mailing list 
 at http://lists.demarc.org/ and include any applicable errors from the error log.


 This doc should have got you up and running. More refined documentation, as well 
 as feature descriptions/instructions are on the way and will be accessible via the 
 website: http://www.demarc.org/

 Your comments and suggestions help, please send them to suggest@demarc.org

-------------------------------------------
 
