This document describes the hostmngr utility daemon that can detect and show host devices in the network.

The term 'host devices' here refer to devices that must contain atleast one network interface capable of being configured with IPv4/IPv6 address either via DHCP or Static method.

Examples of host devices - desktop/laptop, router/AP, IP-camera, smart-TV etc.

Build and build config

Run 'make' from within the "src" directory to build the 'hostmngr' utility daemon. See Dependencies section for the prerequisites.

For install, run 'make install'. This will install 'hostmngr' to the default install path at '/usr/sbin'.

Following config options may be passed during build to enable/disable certain features or change the values from their default -

Enable and maintain history of host devices:

CONFIG_HOSTMNGR_HOSTS_HISTORY=y

Configure hostmngr to use libwifi APIs when target device has WiFi:

HOSTMNGR_PLATFORM_HAS_WIFI=y

Configuration

The default configuration file is '/etc/config/hosts', which keeps the run-time configuration for hostmngr.

Sample '/etc/config/hosts' file -

config global 'global'
	option enabled '1'
	option history '1'
	option history_reboot_persistent '1'
	option history_file '/etc/hosts_history.json'
	option history_timeout '604800'

config interface
	list ifname 'br-lan'

The format of the config file is UCI compliant.

CLI (through UBUS)

The hostmngr daemon provides UBUS methods through which user or any service can interact with for fetching status and stats of the host devices in the network.

root@iopsys:~# ubus -v list hosts
'hosts' @1000ffff
	"show":{}
	"history":{}
	"debug":{}

Sample output of the 'ubus call hosts show' invocation -

root@eagle-44d43771baa0:~# ubus call hosts show
{
        "hosts": [
                {
                        "macaddr": "00:02:02:aa:bb:cc",
                        "hostname": "acx-laptop",
                        "active": true,
                        "active_last_change": "2023-05-30T21:31:57",
                        "ipaddr": "192.168.1.160",
                        "address_source": "DHCP",
                        "lease_time_remaining": 3369,
                        "interface_type": "Ethernet",
                        "is1905": false,
                        "link_macaddr": "",
                        "ndm_state": "reachable",
                        "num_tcp": 0,
                        "num_udp": 10,
                        "active_connections": 10,
                        "device": "eth3",
                        "network": "lan",
                        "ipv4_address": [
                                "ip": "192.168.1.160"
                        ],
                        "ipv6_address": [

                        ],
                        "stats": {
                                "tx_packets": 70,
                                "tx_bytes": 7323,
                                "rx_packets": 61,
                                "rx_bytes": 5860
                        }
                }
        ]
}

Sample output of the 'ubus call hosts history' -

root@eagle-44d43771baa0:~# ubus call hosts history
{
        "history": [
                {
                        "idx": 4,
                        "macaddr": "00:02:02:aa:bb:cc",
                        "hostname": "acx-laptop",
                        "first_seen": "2023-05-30T21:30:38",
                        "last_seen": "2023-05-30T21:31:57",
                        "alive": true,
                        "iswifi": false,
                        "stats": {
                                "tx_packets": 0,
                                "tx_bytes": 0,
                                "rx_packets": 0,
                                "rx_bytes": 0
                        }
                }
        ]
}

The value of 'alive' changes to false when the host device is no longer present in the network. A non-live host device is one that is not present in the network at that time.

Dependencies

'hostmngr' requires the following components for build and runtime dependencies:

Code structure

The source code is within the src directory.

Files within the src directory -

topology.h - defines hosts and network topology related data structures.

hostmngr.c - implements the hostmngr daemon.

config.c,h - for configuration related structures and functions.

neigh.c,h - for managing the connected host devices.

netlink.c - implements rtnetlink events handling.

stats.c - for IPv4/IPv6 connection statistics of the host devices.

history.c - includes functions for storing and loading history to/from history file.

ubus.c - implements UBUS objects and methods provided by hostmngr.

wifi_api.c,h - implements WiFi functions for target having HAS_WIFI=y.

main.c - includes the main() entry point for hostmngr daemon.

debug.c,h - contain functions used for debugging and logging.

util.c,h timer.c,h timer_impl.h lookup3_hash.c,h - these files implement utility and helper functions.