// 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.

////

//== Advanced Network Topics

=== Floating Network Devices

PacketFence supports floating network devices. A Floating network device is a device for which PacketFence has a different behavior compared to a non-floating (regular) network device. This functionality was originally added to support mobile Access Points.

CAUTION: Currently only Cisco and Nortel switches configured with port-security are supported.

A regular device is placed in the VLAN corresponding to its status (Registration, Isolation or Production VLAN) and is authorized on the port (port-security). This is not managed the same way as a floating network device.

When a floating network device is connected, PacketFence will let/allow all the MAC addresses are connected to this device or appear on the port. If necessary the port is configured as multi-vlan (trunk) the PVID is set and VLANs are tagged on the port.

When a floating network device is disconnected, PacketFence will reconfigure the port to what it was before the device connected.

==== How it works

Configuration:

[options="compact"]
* floating network devices have to be identified using their MAC address.
* linkup/linkdown traps are not enabled on the switches, only port-security traps are enabled.

.When a port-security trap is received for a floating network device, the port configuration is changed with:

[options="compact"]
* disable port-security
* set the PVID
* eventually set the port as multi-vlan (trunk) and set the tagged VLANs
* enable linkdown traps

.When a linkdown trap is received on a port in which a floating network device was connected, the port configuration is changed with:

[options="compact"]
* enable port-security
* disable linkdown traps

==== Identification

Each floating network device has to be identified. There are two ways to do this:

[options="compact"]
* by editing [filename]`/usr/local/pf/conf/floating_network_device.conf`
* through the Web GUI, in _Configuration -> Network Configuration -> Floating Device_

Available settings:

MAC Address::
  MAC address of the floating device.
IP Address::
  IP address of the floating device (not required, informational only).
trunkPort::
  Should the port be configured as a multi-vlan port (yes/no)?
pvid::
  Port VLAN.
taggedVlan::
  Comma separated list of VLANs. If the port is a multi-vlan, these are the VLANs that are tagged on the port.

=== Production DHCP access

MAC addresses need to be mapped to IP addresses in order to perform access control.

To have the ability to isolate a node or to have IP information about a node within a network or VLAN, *one* of the following techniques must be used.

NOTE: This is not required for the Registration or Isolation VLANs and inline interfaces since PacketFence acts as the DHCP server within these networks.

==== IP Helpers

If IP-helpers for your production DHCP in your production VLANs are already being used then this approach is the simplest to setup and works the best.

Add PacketFence's management IP address as the last `ip helper-address` in your network equipment. PacketFence will receive a copy of all DHCP requests for that VLAN and will record the IP addresses that were leased to each device using the `pfdhcplistener` daemon.

No DHCP Server should be listening on the interface where these requests are being sent, otherwise PacketFence would pointlessly reply to all DHCP requests.

==== Copy of the DHCP traffic

To copy all the DHCP Traffic from a dedicated physical interface of the PacketFence server run `pfdhcplistener` on the desired interface. This will properly configure the switch in order to perform port mirroring (network span) and sets the proper interface parameters to the operating system and in [filename]`/usr/local/pf/conf/pf.conf`.

`/etc/sysconfig/network-scripts/ifcfg-eth2`:

  DEVICE=eth2
  ONBOOT=yes
  BOOTPROTO=none

Add to [filename]`/usr/local/pf/conf/pf.conf`:

  [interface eth2]
  mask=255.255.255.0
  type=dhcp-listener
  gateway=192.168.1.5
  ip=192.168.1.1

NOTE: The IP address is not important and is only used to start PacketFence.

Restart PacketFence to apply the changes.

==== Interface in every VLAN

Because DHCP traffic is broadcast traffic, an alternative for small networks with few local VLANs is to put a VLAN interface for every VLAN on the PacketFence server and have a `pfdhcplistener` listen on that VLAN interface.

On the network side ensure that the VLAN reaches from your client to the DHCP infrastructure to the PacketFence server.

First configure an operating system VLAN interface in PacketFence like the example below [filename]`/etc/sysconfig/network-scripts/ifcfg-eth0.1010`:

  # Engineering VLAN
  DEVICE=eth0.1010
  ONBOOT=yes
  BOOTPROTO=static
  IPADDR=10.0.101.4
  NETMASK=255.255.255.0
  VLAN=yes

Then specify `type=dhcp-listener` in `/usr/local/pf/conf/pf.conf` within the VLANs using DHCP:

  [interface eth0.1010]
  mask=255.255.255.0
  type=dhcp-listener
  gateway=10.0.101.1
  ip=10.0.101.4

Repeat the above steps for all production VLANs then restart PacketFence to apply the changes.

=== Routed Networks

PacketFence will need to be configured if the Isolation and Registration networks are not reachable locally (at layer 2) on the network, but instead routed to the PacketFence server. PacketFence is able to provide DHCP and DNS in these routed networks.

image::diagram-routed-net.png[scaledwidth="100%",alt="Routed network example diagram"]

For dhcpd, ensure the clients DHCP requests are being forwarded correctly (IP Helpers in the remote routers) to the PacketFence server.

Considering the network architecture illustrated above, [filename]`/usr/local/pf/conf/pf.conf` will include the local Registration and Isolation interfaces only.

   [interface eth0.2]
   enforcement=vlan
   ip=192.168.2.1
   type=internal
   mask=255.255.255.0

   [interface eth0.3]
   enforcement=vlan
   ip=192.168.3.1
   type=internal
   mask=255.255.255.0

NOTE: PacketFence will not start unless at least one 'internal' interface is detected, thus local Registration and Isolation VLANs will need to be created even if they are not needed. The [command]`dhcpd` daemon only listens on the 'internal' interfaces, therefore the remote Registration and Isolation subnets need to point their DHCP helper-address to those particular IP addresses.

Provide the routed networks to PacketFence through the GUI in _Configuration -> Network Configuration -> Networks_ or manually in [filename]`/usr/local/pf/conf/networks.conf`.

Example `/usr/local/pf/conf/networks.conf`:

   [192.168.2.0]
   netmask=255.255.255.0
   gateway=192.168.2.1
   next_hop=
   domain-name=registration.example.com
   dns=192.168.2.1
   dhcp_start=192.168.2.10
   dhcp_end=192.168.2.200
   dhcp_default_lease_time=300
   dhcp_max_lease_time=600
   type=vlan-registration
   named=enabled
   dhcpd=enabled

   [192.168.3.0]
   netmask=255.255.255.0
   gateway=192.168.3.1
   next_hop=
   domain-name=isolation.example.com
   dns=192.168.3.1
   dhcp_start=192.168.3.10
   dhcp_end=192.168.3.200
   dhcp_default_lease_time=300
   dhcp_max_lease_time=600
   type=vlan-isolation
   named=enabled
   dhcpd=enabled

   [192.168.20.0]
   netmask=255.255.255.0
   gateway=192.168.20.254
   next_hop=192.168.2.254
   domain-name=registration.example.com
   dns=192.168.2.1
   dhcp_start=192.168.20.10
   dhcp_end=192.168.20.200
   dhcp_default_lease_time=300
   dhcp_max_lease_time=600
   type=vlan-registration
   named=enabled
   dhcpd=enabled

   [192.168.30.0]
   netmask=255.255.255.0
   gateway=192.168.30.254
   next_hop=192.168.3.254
   domain-name=isolation.example.com
   dns=192.168.3.1
   dhcp_start=192.168.30.10
   dhcp_end=192.168.30.200
   dhcp_default_lease_time=300
   dhcp_max_lease_time=600
   type=vlan-isolation
   named=enabled
   dhcpd=enabled


Restart `packetfence-keepalived` to apply the changes:
[source,bash]
----
/usr/local/pf/bin/pfcmd service keepalived restart
----

DHCP clients on the Registration and Isolation networks receive the PacketFence server IP as their DNS server in their lease, then DNS responses are spoofed to force clients via the portal. However, clients could manually configure their DNS settings to escape the portal. To prevent this, apply an ACL on the access router nearest to the clients, permitting access only to the PacketFence server and local DHCP broadcast traffic.

Example for VLAN 20 remote Registration network:

   ip access-list extended PF_REGISTRATION
    permit ip any host 192.168.2.1
    permit udp any any eq 67
    deny ip any any log
   interface vlan 20
    ip address 192.168.20.254 255.255.255.0
    ip helper-address 192.168.2.1
    ip access-group PF_REGISTRATION in

If the edge switches support 'vlan-isolation' the ACL can also be applied there.
This has the advantage of preventing machines in Isolation from attacking each other.

=== Network Devices Definition

Used only for VLAN enforcement. Inline enforcement can skip this section.

PacketFence needs to know which switches, access points or controllers it manages, their type and configuration. You can modify this configuration directly in [filename]`/usr/local/pf/conf/switches.conf` or from the Web Administration GUI in _Configuration -> Policies and Access Control -> Switches_ (recommended).

.The [filename]`/usr/local/pf/conf/switches.conf` configuration file contains a default section including:

[options="compact"]
* Default SNMP read/write communities for the switches
* Default working mode (see the note below about possible working modes)

.A switch section for each switch (managed by PacketFence) including:

[options="compact"]
* Switch IP/MAC/Range
* Switch vendor/type
* Switch uplink ports (trunks and non-managed IfIndex)
* per-switch re-definition of the VLANs (if required)

Reload the configuration to apply the changes:
[source,bash]
----
/usr/local/pf/bin/pfcmd configreload
----

NOTE: Any ports declared as uplinks are ignored and not managed by PacketFence. This parameter is defined in the [default] section of [filename]`/usr/local/pf/conf/switches.conf`. A different uplink list for each switch can be defined.

==== Working modes

Switches utilize three different working modes:

Testing::
pfsetvlan writes in the log files what it would normally do, but no VLAN changes are performed.
Registration::
pfsetvlan automatically registers all MAC addresses seen on the switch ports, but no VLAN changes are performed.
Production::
pfsetvlan sends the SNMP writes to change the VLAN on the switch ports.

==== RADIUS

To set the RADIUS secret, set it from the Web Administrative GUI when adding a switch. Alternatively, edit the switch configuration file [filename]`/usr/local/pf/conf/switches.conf` and set the following parameters

  radiusSecret = secretPassPhrase

NOTE: The RADIUS secret is required to support the RADIUS Dynamic Authentication (CoA or Disconnect) as defined in RFC3576.

==== SNMP v1, v2c and v3

SNMP is used to communicate with most switches. PacketFence also supports SNMPv3 which is used for bi-directional communication, from the switch to PacketFence and from PacketFence to the switch. SNMP usage is discouraged, as RADIUS should now be used. However, even if RADIUS is being used, some switches may also require SNMP configuration to work properly.

===== From PacketFence to a switch

Set the following parameters in the switch configuration file [filename]`/usr/local/pf/conf/switches.conf`:

  SNMPVersion = 3
  SNMPEngineID = AA5ED139B81D4A328D18ACD1
  SNMPUserNameRead = readUser
  SNMPAuthProtocolRead = MD5
  SNMPAuthPasswordRead = authpwdread
  SNMPPrivProtocolRead = AES
  SNMPPrivPasswordRead = privpwdread
  SNMPUserNameWrite = writeUser
  SNMPAuthProtocolWrite = MD5
  SNMPAuthPasswordWrite = authpwdwrite
  SNMPPrivProtocolWrite = AES
  SNMPPrivPasswordWrite = privpwdwrite

===== From a switch to PacketFence

Set the following parameters in the switch configuration file [filename]`/usr/local/pf/conf/switches.conf`:

  SNMPVersionTrap = 3
  SNMPUserNameTrap = readUser
  SNMPAuthProtocolTrap = MD5
  SNMPAuthPasswordTrap = authpwdread
  SNMPPrivProtocolTrap = AES
  SNMPPrivPasswordTrap = privpwdread

===== Switch Configuration

Set the following switch configuration in order to enable SNMPv3 in both directions on a Cisco Switch.

  snmp-server engineID local AA5ED139B81D4A328D18ACD1
  snmp-server group readGroup v3 priv
  snmp-server group writeGroup v3 priv read v1default write v1default
  snmp-server user readUser readGroup v3 auth md5 authpwdread priv aes 128 privpwdread
  snmp-server user writeUser writeGroup v3 auth md5 authpwdwrite priv aes 128 privpwdwrite
  snmp-server enable traps port-security
  snmp-server enable traps port-security trap-rate 1
  snmp-server host 192.168.0.50 version 3 priv readUser  port-security

Obtain the SNMPv3 engine identifier (SNMPEngineID) with `show snmp engineid`.

===== Test from a PacketFence server

The [command]`net-snmp` package can test SNMPv3 communication with a switch:

[source,bash]
----
snmpget -v3 -l authPriv -u readUser -a MD5 -A "authpwdread" \
  -x AES -X "privpwdread" IP_OF_YOUR_SWITCH sysName.0
----

NOTE: Passwords should be at least 8 characters in length.

==== Command-Line Interface: Telnet and SSH

WARNING: Privilege detection is disabled in the current PacketFence version due to some issues (see https://packetfence.org/bugs/view.php?id=1370[#1370]). Ensure that the `cliUser` and `cliPwd` provided grants privileged mode (except for Trapeze hardware).

PacketFence can occasionally establish an interactive command-line session with a switch. This can be done using either Telnet or SSH. Edit the switch configuration file [filename]`/usr/local/pf/conf/switches.conf` and set the following parameters or :

  cliTransport = SSH (or Telnet)
  cliUser = admin
  cliPwd = admin_pwd
  cliEnablePwd =

This can also be configured with the Web Administration GUI in _Configuration -> Policies and Access Control -> Switches_.

==== Web Services Interface

PacketFence can occasionally establish a Web Services dialog with a switch. Edit the switch config file [filename]`/usr/local/pf/conf/switches.conf` and set the following parameters:

  wsTransport = http (or https)
  wsUser = admin
  wsPwd = admin_pwd

This can also be configured with the Web Administration GUI in _Configuration -> Policies and Access Control -> Switches_.

==== Role-based Enforcement

Some network devices support the assignment of a specific set of rules (firewall or ACLs) to a user. These rules are more accurate in controlling what a user can or cannot do compared to VLAN, which has a larger overhead with network management. PacketFence can assign roles on devices with switches and WiFi controllers that support role-based assignment.

NOTE: The current role assignment strategy is to assign the role along with the VLAN (this may change in the future).

A special internal-role to external-role assignment must be configured in the switch configuration file [filename]`/usr/local/pf/conf/switches.conf` using the format `<role_name>Role=<controller_role>`. Provide the internal-role to external-role assignments on either the switch, or the parent switch group.

Example that returns the `full-access` role to the nodes categorized as admin or engineering and the role `little-access` to nodes categorized as sales:

  adminRole=full-access
  engineeringRole=full-access
  salesRole=little-access

This can also be configured with the Web Administration GUI in _Configuration -> Policies and Access Control -> Switches_.

CAUTION: Ensure the roles are defined in the network devices prior to configuring role-based assignment.

==== VoIP Integration with CDP, LLDP and LLDP-MED

Cisco Discovery Protocol (CDP) is device-discovery protocol supported on all Cisco-manufactured equipment including routers, access servers, bridges, and switches. Using CDP, a device can advertise its existence to other devices and receive information about other devices on the same LAN or on the remote side of a WAN. CDP can determine if the connecting device is an IP Phone, and instruct the IP Phone to tag ethernet frames using the configured voice VLAN on the switchport.

Many other vendors support LLDP or LLDP-MED. Link Layer Discovery Protocol (LLDP) is a vendor-neutral Link Layer protocol in the Internet Protocol Suite used by network devices for advertising their identity, capabilities, and neighbors. Same as CDP, LLDP can instruct an IP Phone which VLAN ID is the voice VLAN.

==== VoIP and VLAN assignment

VLAN assignment techniques such as port-security, MAC authentication and 802.1X are supported.

===== Port-security

Using port-security, the VoIP device relies on CDP/LLDP to tag the ethernet frames using the configured voice VLAN on the switch port. Afterwards a security trap is sent from the voice VLAN so PacketFence can authorize the MAC address on the port. When the device connects another security trap is sent from the data VLAN. That way, 1 MAC address is authorized on the voice VLAN, and 1 on the access VLAN.

NOTE: Not all vendors support VoIP on port-security, please refer to the _Network Configuration Guide_.

===== MAC Authentication and 802.1X

Cisco switches support a multi-domain configuration using Vendor-Specific Attributes (VSA), which allows one device on the VOICE domain and one device on the DATA domain. When the phone connects to the switch port, PacketFence will only respond with the proper VSA, no RADIUS tunneled attributes. CDP then instructs the phone to tag ethernet frames using the configured voice VLAN on the switch port. When a PC connects, the RADIUS server returns the tunneled attributes, and the switch will place the port in the provided access VLAN.

On other vendor hardware VoIP works using RADIUS VSAs. When an IP phone connects to a switch port, the proper VSA is returned to instruct the switch to allow tagged frames from this device. When a PC connects, PacketFence will return the standard RADIUS tunnel attributes to the switch, for the untagged VLAN.

NOTE: Refer to the _Network Configuration Guide_ for switch hardware VoIP support.

==== What if CDP/LLDP feature is missing

If an IP phone does not support CDP or LLDP, DHCP can be used to provision the device with a voice VLAN. Some models require a specific DHCP option in order for the DHCP server to lease the device a voice VLAN ID. After rebooting the ethernet frames are tagged using the provided VLAN tag.

For this scenario to work, the Registration and Production DHCP servers must be configured to provide the DHCP option, there is a voice VLAN configured on the port, and IP Phones are auto-registered (On the first connection, the phone is assigned on the registration VLAN).

=== DHCP Option 82

PacketFence is able to locate a device on the network even if the switch port is not managed by PacketFence.

All switches must be added and _SNMP read_ (switch and PacketFence side) enabled in _Configuration -> Policies and Access Control -> Network Devices -> Switches_.

Enable _DHCP option 82_ in _Configuration -> Network Configuration -> Networks -> Network_. Once enabled, restart the [command]`pfdhcplistener` and [command]`pfmon` (or [command]`pfcron`, if Packetfence version is >= 10.2) services. `pfmon` (or `pfcron`) queries all the switches via SNMP to maintain a map (MAC address -> switch). `pfdhcplistener` parses DHCP Option 82 and uses the map to resolve the MAC to the switch while updating the locationlog of the device.
