Building & Installing proximmon

You will need a C++14 or better compiler; in 2020, these are ubiquitous: Clang 4¹ or later, gcc 5² or later.

Feature Dependencies

These are all optional, to obtain the corresponding feature:

• libdnet, for the optional ARP/MAC-based proximity detector
• [BlueZ], a Linux Bluetooth library
• MacOS 10.6 or later (for the IOBluetooth library)

Building

If you have all of the dependencies listed above, use:

./configure && make

If you’d like to use the unit test to verify it works:

make check

A sample configuration file is provided in src/proximmon-config.json. It’s straightforward; see proximmon-config(5) for more details.

You can run the software directly from the source directory:

./src/proximmon -c "src/proximmon-config.json"

To install it:

sudo make install

Use proximmon’s ‘-?’ or ‘-h’ help for a list of options; see proximmon(1) man page for details.

Manual Build Configuration

Configuring the build has some options:

--enable-debug (default is --disable-debug)

When enabled, turns on assertions (self-checks in the software), some additional logging and debug compile (-g). These enlarge and slow the code down slightly, but make debugging much, much easier.

--with-ping or --without-ping

Include presence detection of static IPv4 addresses via ICMP Echo (ping). Default is to include it if necessary headers are available.

--with-arp or --without-arp

Include presence detection by monitoring the ARP cache. This tracks dynamically-assigned IPv4 addresses, although it’s noiser on the network. It also works as a fallback for ping, which requires root privileges.

--with-bluetooth=package

Chooses a bluetooth package. Options are ‘no’, ‘check’ (use one if available), ‘yes’ (require one or fail to configure), ‘osx’ (use built-in libraries on macOS Snow Leopard or later), or ‘bluez’ (a library mostly available on Linux).

Reporting Bugs

Report bugs to perette@deviousfish.com. Include details of what causes the problem, how it exhibits. For crashes, if possible, include a stack dump using gdb, the GNU debugger::

For a hang, attach to an existing process:

ps x | grep pianod
50942   ??  S      8:50.40 /usr/local/bin/pianod
gdb -p 50942

For crashes, start proximmon from gdb:

gdb /usr/local/bin/proximmon _insert your options here_
run

When it crashes, gdb will report this and give you a command prompt. (Capture a hang this way by pressing control-C.)

Now, in the gdb console, do the following: (For more on gdb, see the GDB Cheat sheet.)

info args
info locals
info variables
info threads
info signals
thread apply all where full

Cut-and-paste from the gdb window to your bug report and mail it in.

Security Implications

THIS PROGRAM EXECUTES CODE FROM THE CONFIG FILE. On arrivals or departures, it executes commands you define; if not locked down, there is an avenue of exploitation. Wisely do not run proximmon near privileged information.

For best safety:

• If you’re going to run proximmon as root, wrap executed commands in ‘su - otheruser -c “command”’ so they aren’t running as root.
• Ensure there’s no write access by other users to your config file’s path.
• Ensure the config file is not writable by other users.