Skip to content
Snippets Groups Projects
Name Last commit Last update
gitlab-ci
src
.gitignore
.gitlab-ci.yml
LICENSE
README.md

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.

Section Name Type Required Default Description
global - - - - -
" enabled boolean no 1 When set to 0, disables hostmngr. The daemon will however keep running, and can be re-enabled by setting to 1.
" history boolean no 1 When set to 0, disables history.
" history_reboot_persistent boolean no 1 When set to 0, history entries are not persisted across reboots.
" history_file string no '/etc/hosts_history.json' Specifies history file name. History records are stored in this file in JSON format.
" history_timeout integer no 604800 Specifies the duration in seconds a non-live history record will be kept in history.
interface - - - - -
" ifname string no br-lan Interface name over which hostmngr runs. Default is 'br-lan', which is the bridge interface facing the LAN side. This means hostmngr detects host devices in the LAN side.

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:

Dependency Link License
libeasy https://dev.iopsys.eu/hal/libeasy.git LGPL 2.1
libwifi https://dev.iopsys.eu/hal/libwifi.git LGPL 2.1
libuci https://git.openwrt.org/project/uci.git LGPL 2.1
libubox https://git.openwrt.org/project/libubox.git ISC
libblobmsg_json https://git.openwrt.org/project/libubox.git ISC
libubus https://git.openwrt.org/project/ubus.git LGPL 2.1
libjson-c https://s3.amazonaws.com/json-c_releases MIT
libnl-3 https://github.com/thom311/libnl.git LGPLv2.1
libnl-genl-3 https://github.com/thom311/libnl.git LGPLv2.1
libnl-route-3 https://github.com/thom311/libnl.git LGPLv2.1
libnetfilter_conntrack https://git.netfilter.org/libnetfilter_conntrack GPLv2+
libnfnetlink https://git.netfilter.org/libnfnetlink GPLv2+
libmnl https://git.netfilter.org/libmnl LGPLv2.1

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.