# Additional information about imports
<!--- --------------------------------------------------------------------- --->

### Pi-hole DNS (v5 or v6) ###

To use this feature, Pi.Alert requires the password for Pi-hole. During this import, an active host is recognized by 
the fact that it has sent a DNS query to Pi-hole within the last 5 minutes. If the time of the last query was longer ago, 
the host is marked as inactive or added to the device list as an inactive new host. In isolated cases, 
Pi.Alert may repeatedly recognize a host despite it having been deleted, even though the host has long since ceased to exist. When using this importer, 
the problem may also lie with Pi-hole. The maximum number of clients to be imported can also be specified in the configuration. 
By default, this value is set to “100” and must be adjusted if necessary.

### Pi-hole DHCP. (v5 or v6) ###

To use this feature, Pi.Alert requires the password for Pi-hole. This list is primarily used for name resolution.

### Fritzbox ###

To use this feature, the Fritzbox must be configured to use a username and password. 
Since multiple users can be created on the Fritzbox, you can also create a separate account for Pi-Alert. The import queries all active hosts. 
These can be located in the guest Wi-Fi or in the standard Wi-Fi. IP-less devices such as the Fritz Powerline adapters are also detected here.

### Mikrotik ###

Pi.Alert requires a user name and password for this function. During import, the active hosts are collected from the DCHP server.

### UniFi ###

Pi.Alert requires a user name and password for this function. Active hosts are collected during import.

### OpenWRT ###

Pi.Alert requires a user name and password for this function. In addition, the “JSON-RPC” package ([link](https://github.com/openwrt/luci/wiki/JsonRpcHowTo)) must be installed on the OpenWRT device.
The active hosts are recorded during import.

### AsusWRT ###

Pi.Alert requires a user name and password for this function. Active hosts are collected during import.

### pfSense ###

Pi.Alert requires an API key for this function. This can be generated after installing the “pfSense REST API” ([link](https://pfrest.org/)) on the pfSense firewall.
To increase the speed at which inactive hosts are detected, I changed another setting within pfSense:

```
System → Advanced → System Tunables

Click on "Add"

Insert:
    Tunable: net.link.ether.inet.max_age
    Value: e.g. 600
```

The background here is how long an entry in the pfSense ARP table is valid, i.e., how long a host is flagged as “active” by pfSense. This also affects the marking of active hosts in the DHCP leases.
When importing from pfSense, all DHCP leases are imported and the active hosts are also marked as active by Pi.Alert. In addition, the hosts from the pfSense ARP table are also imported, which can include all interfaces,
even those that are not managed by a DHCP server. This means that hosts may also be detected on the “WAN” interface. For this reason, this interface is excluded by default in the Pi.Alert configuration.

### OPNsense ###

Pi.Alert requires an API key and API secret for this function. Create a dedicated,
non-administrator user in the OPNsense GUI under `System → Access → Users`, then
use the API key action for that user. Do not reuse an API key belonging to a
normal administrator account.

Pi.Alert reads the ARP table, the interface configuration and the interface name
mapping. The latter two requests are required to identify OPNsense's own
interfaces and to apply `OPNSENSE_EXCLUDE_INT` to interface names such as `WAN`,
`GUEST` or `IoT`. Depending on the configured DHCP service, Pi.Alert also tries
the ISC DHCPv4, Dnsmasq and Kea DHCPv4 lease endpoints.

The standard OPNsense privileges do not provide a dedicated permission for every
required interface endpoint. Granting `All pages` makes the integration work,
but also gives the API user access to unrelated and potentially write-capable
API endpoints. A dedicated custom ACL is therefore recommended.

#### Custom least-privilege ACL

OPNsense does not provide a GUI for importing custom ACL files. Log in to the
OPNsense firewall through SSH or its local console and create this file:

```text
/usr/local/opnsense/mvc/app/models/OPNsense/PiAlert/ACL/ACL.xml
```

Create the parent directories if they do not exist, then store the following
content in `ACL.xml`:

```xml
<acl>
    <page-pialert-network-inventory>
        <name>Pi.Alert: Network inventory</name>
        <description>Read-only network inventory access for Pi.Alert</description>
        <patterns>
            <!-- ARP and interface information -->
            <pattern>api/diagnostics/interface/search_arp*</pattern>
            <pattern>api/diagnostics/interface/get_interface_config*</pattern>
            <pattern>api/diagnostics/interface/get_interface_names*</pattern>

            <!-- ISC DHCPv4 -->
            <pattern>api/dhcpv4/leases/search_lease*</pattern>

            <!-- Dnsmasq DHCP -->
            <pattern>api/dnsmasq/leases/search*</pattern>

            <!-- Kea DHCPv4 -->
            <pattern>api/kea/leases4/search*</pattern>
        </patterns>
    </page-pialert-network-inventory>
</acl>
```

After installing the file, open `System → Access → Users`, edit the dedicated
Pi.Alert API user and add `Pi.Alert: Network inventory` under `Effective
Privileges`. The privilege can alternatively be assigned to a dedicated group
under `System → Access → Groups`. Remove `All pages` and all other permissions
which are not needed by that account. Log out and back in if an existing session
does not immediately reflect the new privilege.

The ACL contains the lease read endpoints for all three DHCP backends so Pi.Alert
can retain its automatic backend detection. It does not grant access to DHCP
configuration, service control, lease deletion or other write endpoints.

The custom ACL is not managed by the OPNsense package system. Keep a separate
backup and verify that the file is still present after OPNsense upgrades.

To increase the speed at which inactive hosts are detected, I changed another setting within OPNsense:

```
System → Settings → Tunables

Click on "Add"

Insert:
    Tunable: net.link.ether.inet.max_age
    Value: e.g. 600

(optional)

Insert:
    Tunable: net.link.ether.inet.prune_intvl
    Value: e.g. 600

```

The background here is how long an entry in the OPNsense ARP table is valid, i.e., how long a host is flagged as “active” by OPNsense.
When importing from OPNsense, all DHCP leases are imported and the active (in the ARP table) hosts are also marked as active by Pi.Alert. In addition, the hosts from the OPNsense ARP table are also imported, which can include all interfaces,
even those that are not managed by a DHCP server. This means that hosts may also be detected on the “WAN” interface. For this reason, this interface is excluded by default in the Pi.Alert configuration.


## Satellite Scan ## 

arp-scan, Pi-hole DNS, Pi-hole DHCP, Mikrotik, UniFi, OpenWRT, AsusWRT, pfSense



[Next (5) - Additional documents](./004.md)

[Back (3) - Settings](./002.md)

[Guide_005]:             https://raw.githubusercontent.com/leiweibau/Pi.Alert/assets/guide_005.png         "Guide_005"


