// to display images directly on GitHub
ifdef::env-github[]
:encoding: UTF-8
:lang: en
:doctype: book
:toc: left
:imagesdir: ../images
endif::[]

////

    This file is part of the PacketFence project.

    See PacketFence_Installation_Guide.asciidoc
    for authors, copyright and license information.

////

//== Additional Integration

=== DHCP Remote Sensor

The DHCP remote sensor consists of a lightweight binary installed on the production DHCP server to replicate all DHCP traffic (1-to-1) to the PacketFence server. This solution is more reliable than DHCP relaying since PacketFence receives a copy of all the DHCP traffic including broadcast traffic. Supported DHCP servers include Microsoft DHCP server and CentOS 6 and 7.

These sensors capture low-level packets on the DHCP server and forwards them to the PacketFence management interface.

==== Microsoft Remote Sensor

The PacketFence-Forwarder is an optimized version of the udp-reflector, which installs easily and only forwards DHCPREQUESTS and DHCPACK packets from the source to the destination as well optionally mirroring DNS traffic for integration with the Fingerbank Collector

Download the http://inverse.ca/downloads/PacketFence/windows-packetfence-forwarder/PacketFence-Forwarder-Installer.exe[DHCP Forwarder installer].

This installs `nPCAP`, `nssm`, launches a configurator for the interface, IP and port, saves the configuration, and finally installs and launches the DHCP-Forwarder service.

When asked for a host IP and UDP port for DHCP mirroring provide the PacketFence management IP and 767 respectively.

Visit the https://github.com/inverse-inc/packetfence-dhcp-forwarder[PacketFence Forwarder project page].

==== Linux-based Sensor

First download the RPM on your DHCP server.

===== CentOS 6 and 7 servers

For CentOS 6 (x86_64):

[source,bash]
----
wget http://inverse.ca/downloads/PacketFence/CentOS6/extra/x86_64/RPMS/udp-reflector-1.0-6.1.x86_64.rpm
----

For CentOS 7 (x86_64):

[source,bash]
----
wget http://inverse.ca/downloads/PacketFence/CentOS7/extra/x86_64/RPMS/udp-reflector-1.0-6.1.x86_64.rpm
----

Install the sensor with [command]`rpm`:

[source,bash]
----
rpm -i udp-reflector-*.rpm
----

===== Compiling the sensor from source on a Linux system

First ensure the following packages are installed:
[options="compact"]
* libpcap
* libpcap-devel
* gcc-c++

Get the sensor source code:

[source,bash]
----
mkdir -p ~/udp-reflector && cd ~/udp-reflector
wget http://inverse.ca/downloads/PacketFence/udp-reflector/udp_reflector.cpp
g++ udp_reflector.cpp -o /usr/local/bin/udp_reflector -lpcap
----

===== Configure the Sensor

Place the following line in `/etc/rc.local`
[options="compact"]
* where `pcap0` is the pcap interface where the DHCP server listens on. (List them using `udp_reflector -l`)
* where `192.168.1.5` is the management IP of the PacketFence server

[source,bash]
----
/usr/local/bin/udp_reflector -s pcap0:67 -d 192.168.1.5:767 -b 25000 &
----

Start the sensor:

[source,bash]
----
/usr/local/bin/udp_reflector -s pcap0:67 -d 192.168.1.5:767 -b 25000 &
----

All DHCP traffic is now reflected to the PacketFence server.

=== Active Directory Integration

==== Deleted Account

Create the script `unreg_node_deleted_account.ps1` on the Windows Server with the following content:

----
#########################################################################################
#Powershell script to unregister deleted Active Directory account based on the UserName.#
#########################################################################################

Get-EventLog -LogName Security -InstanceId 4726 |
   Select ReplacementStrings,"Account name"|
   % {
    $url = "https://@IP_PACKETFENCE:9090/"
    $username = "admin" # Username for the webservices
    $password = "admin" # Password for the webservices
    [System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}
    $command = '{"jsonrpc": "2.0", "method": "unreg_node_for_pid", "params": ["pid", "'+$_.ReplacementStrings[0]+'"]}'

    $bytes = [System.Text.Encoding]::ASCII.GetBytes($command)
    $web = [System.Net.WebRequest]::Create($url)
    $web.Method = "POST"
    $web.ContentLength = $bytes.Length
    $web.ContentType = "application/json-rpc"
    $web.Credentials = new-object System.Net.NetworkCredential($username, $password)
    $stream = $web.GetRequestStream()
    $stream.Write($bytes,0,$bytes.Length)
    $stream.close()

    $reader = New-Object System.IO.Streamreader -ArgumentList $web.GetResponse().GetResponseStream()
    $reader.ReadToEnd()
    $reader.Close()
   }
----

NOTE: Change `@IP_PACKETFENCE` to the IP address of the PacketFence server and change the `$username` and `$password` so they match the credentials defined in the Web admin interface under _Configuration -> Integration -> Web Services_.

===== Create a scheduled task for an event ID

*Start -> Run -> Taskschd.msc*

*Task Scheduler -> Task Scheduler Library -> Event Viewer Task -> Create Task*

General

----
Name: PacketFence-Unreg_node-for-deleted-account
Check: Run whether user is logged on or not
Check: Run with highest privileges
----

Triggers -> New

----
Begin on the task: On an event
Log: Security
Source: Microsoft Windows security auditing.
Event ID: 4726
----

Actions -> New

----
Action: Start a program
Program/script: powershell.exe
Add arguments (optional): C:\scripts\unreg_node_deleted_account.ps1
----

Settings:

----
At the bottom, select in the list "Run a new instance in parallel" in order to unregister multiple nodes at the same time.
----

Validate with Ok and provide the account that will run this task (usually _DOMAIN\Administrator_).

==== Disabled Account

Create the script `unreg_node_disabled_account.ps1` on the Windows Server with the following content:

----
##########################################################################################
#Powershell script to unregister disabled Active Directory account based on the UserName.#
##########################################################################################

Get-EventLog -LogName Security -InstanceId 4725 |
   Select ReplacementStrings,"Account name"|
   % {
    $url = "https://@IP_PACKETFENCE:9090/"
    $username = "admin" # Username for the webservices
    $password = "admin" # Password for the webservices
    [System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}
    $command = '{"jsonrpc": "2.0", "method": "unreg_node_for_pid", "params": ["pid", "'+$_.ReplacementStrings[0]+'"]}'

    $bytes = [System.Text.Encoding]::ASCII.GetBytes($command)
    $web = [System.Net.WebRequest]::Create($url)
    $web.Method = "POST"
    $web.ContentLength = $bytes.Length
    $web.ContentType = "application/json-rpc"
    $web.Credentials = new-object System.Net.NetworkCredential($username, $password)
    $stream = $web.GetRequestStream()
    $stream.Write($bytes,0,$bytes.Length)
    $stream.close()

    $reader = New-Object System.IO.Streamreader -ArgumentList $web.GetResponse().GetResponseStream()
    $reader.ReadToEnd()
    $reader.Close()

   }
----

NOTE: Change `@IP_PACKETFENCE` to the IP address of the PacketFence server and change the `$username` and `$password` so they match the credentials defined in the Web admin interface under _Configuration -> Integration -> Web Services_.

===== Create a scheduled task for an event ID

*Start -> Run -> Taskschd.msc*

*Task Scheduler -> Task Scheduler Library -> Event Viewer Task -> Create Task*

General

----
Name: PacketFence-Unreg_node-for-disabled-account
Check: Run whether user is logged on or not
Check: Run with highest privileges
----

Triggers -> New

----
Begin on the task: On an event
Log: Security
Source: Microsoft Windows security auditing.
Event ID: 4725
----

Actions -> New

----
Action: Start a program
Program/script: powershell.exe
Add arguments (optional): C:\scripts\unreg_node_disabled_account.ps1
----

Settings:

----
At the bottom, select in the list "Run a new instance in parallel"
----

Validate with Ok and provide the account that will run this task (usually _DOMAIN\Administrator_).

==== Locked Account

Create the script `unreg_node_locked_account.ps1` on the Windows Server with the following content:

----
#########################################################################################
#Powershell script to unregister locked Active Directory account based on the UserName.#
#########################################################################################

Get-EventLog -LogName Security -InstanceId 4740 |
   Select ReplacementStrings,"Account name"|
   % {
    $url = "https://@IP_PACKETFENCE:9090/"
    $username = "admin" # Username for the webservices
    $password = "admin" # Password for the webservices
    [System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}
    $command = '{"jsonrpc": "2.0", "method": "unreg_node_for_pid", "params": ["pid", "'+$_.ReplacementStrings[0]+'"]}'

    $bytes = [System.Text.Encoding]::ASCII.GetBytes($command)
    $web = [System.Net.WebRequest]::Create($url)
    $web.Method = "POST"
    $web.ContentLength = $bytes.Length
    $web.ContentType = "application/json-rpc"
    $web.Credentials = new-object System.Net.NetworkCredential($username, $password)
    $stream = $web.GetRequestStream()
    $stream.Write($bytes,0,$bytes.Length)
    $stream.close()

    $reader = New-Object System.IO.Streamreader -ArgumentList $web.GetResponse().GetResponseStream()
    $reader.ReadToEnd()
    $reader.Close()

   }
----

NOTE: Change `@IP_PACKETFENCE` to the IP address of the PacketFence server and change the `$username` and `$password` so they match the credentials defined in the Web admin interface under _Configuration -> Integration -> Web Services_.

===== Create the scheduled task based on an event ID

*Start -> Run -> Taskschd.msc*

*Task Scheduler -> Task Scheduler Library -> Event Viewer Task -> Create Task*

General

----
Name: PacketFence-Unreg_node-for-locked-account
Check: Run whether user is logged on or not
Check: Run with highest privileges
----

Triggers -> New

----
Begin on the task: On an event
Log: Security
Source: Microsoft Windows security auditing.
Event ID: 4740
----

Actions -> New

----
Action: Start a program
Program/script: powershell.exe
Add arguments (optional): C:\scripts\unreg_node_locked_account.ps1
----

Settings:

----
At the bottom, select in the list "Run a new instance in parallel"
----

Validate with Ok and provide the account that will run this task (usually _DOMAIN\Administrator_).

=== Switch Login Access

PacketFence is able to provide an authentication and authorization service on port 1815 for granting command-line interface (CLI) access to switches.
PacketFence currently supports Cisco switches which must be configured using the following guide: http://www.cisco.com/c/en/us/support/docs/security-vpn/remote-authentication-dial-user-service-radius/116291-configure-freeradius-00.html. From the PacketFence web admin interface, configure an Admin Access role (_Configuration -> System Configuration -> Admin Access_) that contains the action 'Switches CLI - Read' or 'Switches CLI - Write' and assign this role to an internal user or with an Administration rule in an internal source.

Then enable `_CLI Access Enabled_` setting on the switch(s) to manage in _Configuration -> Network devices -> Switches_.

NOTE: The `ALL` administrative role allows the user to login into the switches. Change this role to `ALL_PF_ONLY` to allow the user all the necessary administrative roles except for switch login.


=== Syslog forwarding

Syslog forwarding forwards PacketFence logs (all or specific log files) to a remote Syslog server using the Syslog protocol.

Configure this feature in _Configuration -> Integration -> Syslog Forwarding_

After adding a new Syslog server, perform the following commands:

[source,bash]
----
systemctl restart rsyslog
----

Logs are retained on the PacketFence server **and** a copy is sent to the remote Syslog server(s).

=== Monit

`monit` manages and monitors processes, files, directories and filesystems on a Unix system. Monit conducts automatic maintenance and repair, and can execute meaningful causal-actions in error situations. E.g. Monit can start a process if it stops running, restart a process if it does not respond and stop a process if it uses too much resources.

For further reference the monit documentation is available at: https://mmonit.com/monit/documentation/monit.html

The monit configuration path is different between EL and Debian systems:

EL based systems:

* [filename]`MONIT_PATH=/etc/monit.d`

Debian based systems:

* [filename]`MONIT_PATH=/etc/monit/conf.d`

To simplify further documentation, `$MONIT_PATH` will be used as a reference to these paths herein.

Starting from PacketFence 11.1, the Monit configuration is directly managed by PacketFence.

To enable Monit, configure the following settings in _Configuration -> System Configuration -> Main Configuration -> Monit_:
[options="compact"]
* Status: enabled
* Alert Email To: The email address(es) to send the alerts. If left empty, the default email addresses defined in _Configuration -> System Configuration -> Main Configuration -> Alerting_ will be used.
* Configuration: Enter the configurations for monit to use. If left empty, the defaults should be fine unless port-security enforcement or active/passive cluster is used.
* Mailserver: Specify the mailserver to use. This can only be used for unauthenticated relaying. If using localhost, ensure postfix is installed and properly configured. If left empty, the SMTP server settings in _Configuration -> System Configuration -> Main Configuration -> Alerting_ are used. Note that monit doesn't support StartTLS so 'none' or 'ssl' must be configured for SMTP encryption in the alerting configuration. If StartTLS is required, configure postfix for relaying and use 'localhost' as the Mailserver in the monit configuration.

Restart the monit service:

[source,bash]
----
systemctl restart monit
----

==== Monitoring scripts

Digitally signed scripts are included in the monit configuration which are fetched from http://inverse.ca/downloads/PacketFence/monitoring-scripts/v1/. These scripts will be updated and run at regular intervals to ensure the environment follows the best practices defined by Inverse and to email alerts of any important changes that may need to be performed.

Run manually to help with troubleshooting:

[source,bash]
----
/usr/local/pf/addons/monit/monitoring-scripts/update.sh
/usr/local/pf/addons/monit/monitoring-scripts/run-all.sh
----

===== Ignoring some checks

To ignore one of the checks that are being performed, add its script name in [filename]`$MONIT_PATH/packetfence/local-ignores`.

For example, to ignore the script that generated the following output add [filename]`/usr/local/pf/var/monitoring-scripts/.check-epel.sh` to [filename]`$MONIT_PATH/packetfence/local-ignores`:
----
------------------------------------------
/usr/local/pf/var/monitoring-scripts/.check-epel.sh failed
Result of /usr/local/pf/var/monitoring-scripts/.check-epel.sh
The EPEL repository is enabled. This can cause disastrous issues by having the wrong versions of certain packages installed. It is recommended to disable it using the following command: sed -i 's/enabled\s*=\s*1/enabled = 0/g' /etc/yum.repos.d/epel.repo
------------------------------------------
----


===== Run some checks as root

Some scripts need to run as root but are disabled by default. To run these checks add the following in [filename]`$MONIT_PATH/packetfence/local-vars`:

[source,bash]
----
export RUN_ROOT_SCRIPTS=1
----

==== Monit Summary

View the monit summary and ensure all services show status `Running`, `Accessible`, or `Status ok`. Any services that display a failed status will need to be investigated. Monit will process and display the services in the same order that they are listed. If the summary appears stuck, troubleshoot the next service in the list.

[source,bash]
----
monit summary
----

TIP: More information on the monit command line arguments is available at https://mmonit.com/monit/documentation/monit.html


