This is another release of connmapperl with the client to server connections now using SSL encryption now instead of plain plain data structs sent over the wire. The SQLite Query Interface results can now be replotted back onto the world map. It also has an icon. But mainly it's the SSL stuff that makes this update useful. I was starting to feel uneasy about streaming all my various computers' connection data in plain text over the internet.
You can either use the pre-generated server-cert.pem and server-key.pem, or better, delete them, then run the connmapperl-server.pl program again and it will autogenerate new ones by calling openssl. server-cert.pem has to be in the same directory as the connmapperl-client.pl on remote machines for it to connect! Just TLS things.
[comment on this post] Append "/@say/your message here" to the URL in the location bar and hit enter.
I've been puttering away at improving my connmapperl port(s) of connmap (c/X11) geoip map network visualizer in terms of both features and performance. ip2asn.pl for the fully-offline(local) asn and org-name and peering look-ups is ever so slightly faster. The sql database side for long term detailed connection history is about 10x faster and 100x less IO which shows how bad it was before stateful connection tracking. Fancy things like sql queries and a mapping of the points onto the ipv4 range on a space filling hilbert curve (like the xkcd comic) also exist. The client program is forwards and backwards compatible; it just handles sudden socket closings a bit better, re: reconnecting now.
The size is from the included geoip dbs and regional internet registry whois dumps. Leave the .pl files in the extracted folder and just run them there.
All this started with and was forked and ported from an inspiringly simple .c program for X11 called connmap. My versions just happens to be in another language and graphical toolkit and tacks on sql points history and a lot of not necessarily useful features and eye candy. I still don't understand the original connmap's math for the lat/lon gps to x/y pixel translation but luckily through open source licensing I can build with it.
connmap-(tk|gtk2|gtk3) and [connmapperl-server + connmapperl-client] are a set of geoip map visualization applications. They rapidly call 'ss' and 'lsof' for established tcp connections and shows geoip dots, program process name, ASN, and Org Name where the remote peer is. They also can right click on points to pop up a window with copyable-text and a form for doing offline whois look-ups. It does this only accessing database files stored on disk. No network calls or getting banned by whois servers. It was made with lots of gemini-2.5-pro LLM AI help.
The size is from the included geoip dbs and regional internet registry whois dumps. Leave the .pl files in the extracted folder and just run them there.
The above are my simple ports and expanded forks from C to Perl of the X11 program connmap.
I did this because my Ubuntu 10.04 computer with Xorg 1.7 was too
old to run the original connmap program. At least 1 of these 5 programs
will run on almost anything from 1998 to 2025.
But as I did it I was having lots of fun so I added new obvious features and eventually diverged quite far from the base connmap code. Except in terms of lat,long to x,y calculation and the core concept; the hard stuff. That is still the same wonderful connmap logic.
"connmap-tk", "connmap-gtk2", "connmap-gtk3", and "connmapperl-server" have some extra features but don't
have the ability to scale like connmap. "connmap-simple-gtk3" is a pure port with no extra features that
can't scale like connmap either. None support "connmaprc" and instead use "connmapperlrc"; a new format.
"connmap-gtk2", "connmapperl-server", and "connmap-gtk3" are the best versions (though sometimes -gtk3 lags behind in features). They all load local/peer port map/color rules from config files which can be toggled on/off in the program by clicking the square buttons next to their name in the color key. They save all geoip points history, toggle with 'h' key, and can overlay them as white transparent circles scaled proportional to the number of times they appeared. They can save 's' and load 'l' this history file from disk. They can turn off global ip->asn/org-name look-ups and display globally by pressing 't'. They can right click near points and get a detailed list of their info as well as a field for doing full off-line whois lookups.
"connmap-simple-gtk3" is a direct port of connmap. No extra features. "connmap-tk" is somewhere in between.
"connmapperl-server" and "connmapperl-client" are the same program as "connmap-gtk2" but split into a gtk2 server/GUI and lightweight cli daemon clients which connect over the network via tcp/ip. It's really neat seeing all my computers and my VPSs active internet connections on one map at the same time on my home desktop. Since the client is pure perl and core modules only it runs on anything that has linux's "ss" and "lsof" programs.
Feature comparisons and Non-core Perl Dependencies
--- client/server architecture ---
"connmapperl-server" is a windowless GUI program server that listens on a port for client data and displays.
listens on port 6789
visual updates a tiny bit slower (1s), but client->server data updates are still fast (0.1s).
uses Gtk2 (which rocks) which your modern OS probably doesn't have.
can be dragged around with the mouse left-click hold.
has right-click map to get list of points IPv4 info within circle near the mouse pointer.
- optional ip2asn non-network based fully offline whois lookups for right click menu
has 't' key toggle for doing the 'text' ASN/Org-Name look-ups and showing them.
has 'h' key toggle for 'history' which shows all points seen scaled by count.
has 's' and 'l' keys to 'save' and 'load' history points.
has 'Esc' key to close and also an invisible exit button in the top right.
loads ports/colors/names from config file "connmapperlrc"
- does search/shows text depending on local/peer and port in "connmapperlrc"
- can turn look-ups for rules on/off by clicking square next to their name in the key.
- has 'c' config key to reload connmapperlrc file settings while running.
Perl Dependencies: use Gtk2, use Cairo, use Glib, use Net::IP, use Text::CSV
"connmapperl-client" is a tiny perl core modules only script that will run on everything, even routers.
is headless and uses a tcp connection to connect to connmapperl-server
requires the presence of $ ss and $ lsof binaries.
connects to port 6789
Perl Dependencies: none
--- single program architecture ---
"connmap-gtk2" is windowless and can be dragged around with the mouse left-click hold.
has right-click map to get list of points IPv4 info within circle near the mouse pointer.
- optional ip2asn non-network based fully offline whois lookups for right click menu
has 't' key toggle for doing the 'text' ASN/Org-Name look-ups and showing them.
has 'h' key toggle for 'history' which shows all points seen scaled by count.
has 's' and 'l' keys to 'save' and 'load' history points.
has 'Esc' key to close and also an invisible exit button in the top right.
uses Gtk2 (which rocks) which your modern OS probably doesn't have.
loads ports/colors/names from config file "connmapperlrc"
- does search/shows text depending on local/peer and port in "connmapperlrc"
- can turn look-ups for rules on/off by clicking square next to their name in the key.
Perl Dependencies: use Gtk2, use Cairo, use Glib, use Net::IP, use Text::CSV
"connmap-tk" has a traditional window bar.
hard coded: shows process name : port, ASN, and Org Name text for most ports
is Tk. Tk never changes and is available on both old and new OSes.
is Tk and so a little slower.
Perl Dependencies: use Tk, use Net::IP, use Text::CSV
"connmap-simple-gtk3" is a *direct* 1-to-1 connmap X11 feature port.
is a simple port that just shows red dots.
is what will run on most modern OSes.
is windowless and can be dragged around with the mouse.
Perl Dependencies: use Gtk3, use Cairo, use Glib
"connmap-gtk3" is windowless and can be dragged around with the mouse left-click hold.
has right-click map to get list of points IPv4 info within circle near the mouse pointer.
- optional ip2asn non-network based fully offline whois lookups for right click menu
has 't' key toggle for doing the 'text' ASN/Org-Name look-ups and showing them.
has 'h' key toggle for 'history' which shows all points seen scaled by count.
has 's' and 'l' keys to 'save' and 'load' history points.
has 'Esc' key to close and also an invisible exit button in the top right.
uses Gtk3 which is what will run on most modern OSes.
loads ports/colors/names from config file "connmapperlrc"
- does search/shows text depending on local/peer and port in "connmapperlrc"
- can turn look-ups for rules on/off by clicking square next to their name in the key.
Perl Dependencies: use Gtk3, use Cairo, use Glib, use Net::IP, use Text::CSV
The local/peer ports, their names, and their colors from a config file located in the same directory as it: connmapperlrc. These rules can be toggled for IP->ASN/Org-Name resolution and display by setting the last field to 0=Off or 1=On, or done so while the program is running by clicking their corresponding colored square in the key.
# connmapperlrc - Configuration for ConnMapperl
# Format: KeyLabel,Type,Port,Red,Green,Blue,Alpha,ShowText
# ShowText: 1 = Display dot and text, 0 = Display dot only
"Webserver",local,80,0.2,0.5,1,0.8,1
"Webserver",local,443,0.2,0.5,1,0.8,1
"Web Surfing",peer,80,0.68,0.85,1.0,0.8,0
"Web Surfing",peer,443,0.68,0.85,1.0,0.8,0
"IRC",peer,6667,1,1,0.2,0.8,0
"IRC",peer,6669,1,1,0.2,0.8,0
"IRC",peer,6660,1,1,0.2,0.8,0
"IRC",peer,5555,1,1,0.2,0.8,0
"SSH Out",peer,22,0.6,0.2,0.8,0.8,0
"SSH In",local,22,0.7,0.2,0.6,0.8,0
"IMAP/S",peer,993,0.1,0.9,0.2,0.8,0
"IMAP/S",local,993,0.1,0.9,0.2,0.8,0
"smtpd",local,587,0.3,0.6,0.3,0.8,0
"Torrents",local,12000,1.0,0.4,0.7,0.8,0
"Torrents",peer,12000,1.0,0.4,0.7,0.8,0
"Shadowsocks",peer,31415,0.5,0.5,0.5,0.8,0
"Shadowsocks",local,31415,0.5,0.5,0.5,0.8,0
"Shadowsocks",peer,31416,0.5,0.5,0.5,0.8,0
"Shadowsocks",local,31416,0.5,0.5,0.5,0.8,0
"connmap",local,6789,0.5,0.5,0.1,0.8,0
"connmap",peer,6789,0.5,0.5,0.1,0.8,0
# By default only connections to the local webserver are shown with ASN+OrgName lookups
# because that process is somewhat cpu and io intensive. This applies to the 'h' history
# function too. Points matching local or peer ports with ShowText field 0 will not show
# up as dots in history's scaled dot display.
# Generally anything that's always going that you already know about set ShowText 0 to
# ignore and not blow out the history heatmap.
Right-click the map to get a selectable text pop-up of IPs near the click. The white circle which appears briefly shows the range. Local whois/peering look-ups available in the pop-up window detail list.
There a lots of comments at the top of the source re: configuration required if any.
Paths are set relative to the folder so as long as ./resources/ exists
and you have the perl modules required it should work.
An aside on the lack of libgtk2-perl on many distros
There are a few tricks to getting it to work but the most important one is at the very top of the ./libgtk2-perl/debian/rules file (on a new line before any other text), adding the following line:
Without this it's all "xs/Gtk2.c: loadable library and perl binaries are mismatched (got handshake key 0xce00080, needed 0xed00080)" errors when Gtk2 is actually attempted to be used.
Otherwise it was just a matter of changing some paths and versions in the ./DEBIAN/control file of the libgtk2-perl_1.24993-1_amd64.deb produced after, "$ DEB_BUILD_OPTIONS=nocheck debuild -us -uc -b" like changing DEBIAN/control so that perlapi-5.28.1 -> perlapi-5.32.1, and changing the folder name of ./usr/lib/x86_64-linux-gnu/perl5/5.28 to ./usr/lib/x86_64-linux-gnu/perl5/5.32 (for Debian 11, for other distros use the appropriate perl version/path).
I did this by unpacking the produced .deb,
dpkg-deb -R libgtk2-perl_1.24993-1_amd64.deb tmp/
Then doing the above changes manually, then repacking,
dpkg-deb -b tmp libgtk2-perl_1.24993-1_GOODPATHSWORKING_amd64.deb
Then there's the command line tools I made for offline whois.
If connmap-gtk2.pl detects ip2asn.pl in the directory it will offer the option to use it for all local (no network connectivity needed) look-ups of whois dumps from the regional internet registries.
"ip2asn" is a sort of janky fully-local "whois" for all 5 regional internet registries.
The other scripts are for processing the raw data to a form usable for ip2asn.pl
It started as a scratch pad for testing which were the best ways to go from IP to
organization name but eventually became a useful tool in it's own right to avoid
getting throttled by internet whois servers when doing many lookups in a row.
It uses 4 diferent methods to try to go from IP to ASN and org name.
The first 3 methods are relatively fast.
The 4th, awk'ing through big whois dumps, is not.
It is called like: $ ./ip2asn 94.74.97.164
--- Found IP Information for: 94.74.97.164 ---
Registry: apnic
Country Code: SG
Start IP: 94.74.64.0
Range Size: 16384
Status: allocated
Opaque ID: A917E678
--- Associated ASN Records ---
HUAWEI INTERNATIONAL PTE. LTD.
ASN: 131444, Count: 1, Status: allocated, Date: 20160715
ASN: 136907, Count: 1, Status: allocated, Date: 20170807
ASN: 141180, Count: 1, Status: allocated, Date: 20200914
ASN: 149167, Count: 1, Status: allocated, Date: 20211206
ASN: 151610, Count: 1, Status: allocated, Date: 20230712
HUAWEI INTERNATIONAL PTE. LTD.
22.2908 , 114.1501136907 - "HUAWEI CLOUDS"
aut-num: AS131444
as-name: HIPL-AS-AP
descr: Huawei IT Data Center in AP
country: HK
remarks: --------------------------------------------------------
remarks: To report network abuse, please contact mnt-irt
remarks: For troubleshooting, please contact tech-c and admin-c
remarks: Report invalid contact via www.apnic.net/invalidcontact
remarks: --------------------------------------------------------
org: ORG-HIPL2-AP
admin-c: HIPL7-AP
tech-c: HIPL7-AP
abuse-c: AH905-AP
mnt-lower: MAINT-HIPL-SG
mnt-routes: MAINT-HIPL-SG
mnt-by: APNIC-HM
mnt-irt: IRT-HIPL-SG
last-modified: 2020-06-17T13:05:46Z
source: APNIC
It doesn't always work that nicely though. And lacnic entries are pretty bare.
All this is done by including 600 MB of RIR ipv4 delegation files,
all five regional internet registry's whois and peering dumps,
various maxmind geolite ip->lat,long csv databases, and
caida.org/archive/as2org/ as-org2info.txt. See appendix for URLs
Appendix of various resources and notes
### the various resources/* files and where they come from to update them.
## RIR whois/peering db
# RIPE NCC https://ftp.ripe.net/ripe/dbase/split/ripe.db.aut-num.gz
# ARIN https://ftp.arin.net/pub/rr/arin.db.gz
# APNIC https://ftp.apnic.net/apnic/whois/apnic.db.aut-num.gz
# LACNIC https://ftp.lacnic.net/lacnic/dbase/lacnic.db.gz
# AFRINIC https://ftp.afrinic.net/dbase/afrinic.db.gz
## RIR Delegation files
# https://www-public.telecom-sudparis.eu/~maigron/rir-stats/
# https://ftp.afrinic.net/pub/stats/afrinic/delegated-afrinic-extended-latest
# https://ftp.apnic.net/stats/apnic/delegated-apnic-extended-latest
# https://ftp.arin.net/pub/stats/arin/delegated-arin-extended-latest
# https://ftp.lacnic.net/pub/stats/lacnic/delegated-lacnic-extended-latest
# https://ftp.ripe.net/pub/stats/ripencc/delegated-ripencc-extended-latest
early version of the gtk2 port, what the gtk3 port looks like
recent version during a distributed botnet attempting to mirror the entire website at once
connmap-tk with integrating time lapse mode enabled by commenting out the "connection_item" tag on the dots:
# 1. Draw the dot using Tk::Canvas->createOval
$canvas->createOval(
$x - $radius, $y - $radius, $x + $radius, $y + $radius,
-fill => $dot_color,
-outline => $dot_color, # Use same color for outline to make a solid dot
# -tags => 'connection_item',
);
It's easy to see there is some error in the geoip placement on the map gif background.
[comment on this post] Append "/@say/your message here" to the URL in the location bar and hit enter.
Old machine generated docs of the client/server versions that give a general idea
ConnMapperl is a client-server desktop application designed to provide a real-time, interactive visualization of network connections. A headless client program runs on one or more machines, gathers data about active TCP connections, and sends this data to a central GUI server. The server then performs a GeoIP lookup on the destination IP addresses and plots them as colored dots on a world map. The application is highly interactive, allowing the user to explore connection history, look up information about specific IPs, and customize the display.
How It Works: The Data Flow
Client-Side Data Collection: The headless client (connmap-client-headless) runs continuously in the background. In a loop, it executes system commands (ss and lsof) to get a list of all ESTABLISHED TCP connections. For each connection, it captures the local IP/port, the remote (peer) IP/port, and tries to identify the name of the program that initiated the connection.
Secure Transmission: The client serializes the list of connections into a binary format using Perl's Storable module. It then connects to the server, authenticates with a shared password (passwordhere by default), and transmits the data. The data is prefixed with its length to ensure the server reads the complete message. The client has a robust reconnection policy, automatically trying to reconnect to the server with an increasing backoff delay if the connection is lost.
Server-Side Reception & Processing: The GUI server (connmap-gtk2-server) listens for incoming client connections. It authenticates clients and then continuously receives connection data.
Geolocation: For each connection reported by a client, the server takes the remote IP address and looks up its geographical location. It does this by performing an efficient binary search against a local, pre-sorted CSV file (ipv4.csv), which maps IP address ranges to latitude and longitude. This makes the lookup very fast and independent of any online services.
Visualization: The server converts the latitude and longitude into X/Y coordinates on a 2D map using a Mercator projection. It then draws a colored dot at this location on the world map background.
Component Breakdown
The Client (connmap-client-headless)
Purpose: A lightweight, persistent agent for gathering and reporting network data.
Functionality:
Uses ss and lsof for efficient and detailed connection discovery.
Operates in a continuous loop, providing near real-time updates.
Authenticates with the server to ensure only authorized clients can send data.
Features an exponential backoff mechanism for automatically reconnecting to the server.
Can be configured via command-line arguments to specify the server's IP and password.
The Server (connmap-gtk2-server)
Purpose: The central hub that receives data, processes it, and provides the graphical user interface.
Functionality:
GUI: A borderless, draggable window displaying a world map. It uses the Gtk2 toolkit for the window and the Cairo graphics library for all custom drawing, resulting in a smooth, anti-aliased display.
Networking: Handles multiple clients simultaneously using a non-blocking I/O model.
Data Storage: Manages two types of history:
A simple, in-memory history (.connmap-history2.dat) that tracks the count of connections to each location for a quick visual overview.
A detailed, persistent history in an SQLite database (.connmap-history2.sqlite) that logs comprehensive details for every unique connection, including timestamps, IP/port pairs, program names, and map coordinates.
Drawing Engine: Responsible for rendering the map, current connection dots, historical connection markers, text labels, and all interactive UI elements.
The Configuration File (connmapperlrc)
Purpose: A simple CSV file that allows the user to define rules for how connections are displayed.
KeyLabel: The name for the rule (e.g., "Web Surfing").
Type: Can be local (matches the local port) or peer (matches the remote port).
Port: The port number to match.
Red,Green,Blue,Alpha: The color and transparency for the dot (values from 0.0 to 1.0).
ShowText: 1 to show the text label by default, 0 to hide it.
Key Features and Interactivity
This application is rich with features accessible via keyboard shortcuts and mouse clicks.
Visualization & Display
Real-time Plotting: New connections appear on the map almost instantly.
Configurable Colors: The connmapperlrc file gives you full control over the color-coding of different services.
History View (h key): Toggles the display of historical connections. These appear as semi-transparent white circles, with the size of the circle logarithmically scaled to the number of past connections to that location.
Global Text Toggle (t key): Instantly show or hide all text labels for a cleaner view.
Client Visibility Toggling: The on-screen client list allows you to selectively hide or show connections originating from specific clients.
Draggable Interface: The borderless window can be moved by clicking and dragging anywhere on the map.
Advanced Tools & Popups
Right-Click Info: Right-clicking on any point on the map brings up an information window listing all nearby connections from both the current session and the detailed SQLite history.
Connection Inspector: The info popup provides further tools for the selected IP:
net whois: Runs a whois command on the IP address.
Weblogs: Greps the nginx access log (/var/log/nginx/access.log) for entries from that IP.
Lookup: Can execute a custom ip2asn.pl script for more detailed lookups.
Color Key Interaction: The color key at the bottom-left is interactive.
Clicking a rule's colored box toggles the text label for that specific rule.
Clicking a rule's text label opens a new window listing all active connections matching that rule.
IPv4 Hilbert Curve View (z key): A unique and powerful feature. This opens a new window that visualizes the entire IPv4 address space using a Hilbert space-filling curve. This allows you to see connection patterns not based on geography, but on their proximity within the IP address space itself. Colors on the curve are based on the IP's first octet (e.g., 10.x.x.x IPs will be clustered in one color region).
History and Session Management
Save/Load Simple History (s/l keys): You can manually save the current in-memory history to disk and load it back in a later session.
History Pruning (p key): Opens a settings dialog to configure automatic pruning of the detailed SQLite history. You can set a time limit (e.g., 6 hours), and the application will periodically delete older records to manage disk space. You can also disable detailed history recording entirely from this menu.
Reset History (r key): Instantly clears both the simple and detailed history databases.
Configuration Reload (c key): Reloads the connmapperlrc file without needing to restart the application.
In summary, ConnMapperl is not just a visualizer but a comprehensive and interactive tool for monitoring and investigating network traffic in a geographical context, with advanced features for historical analysis and deep-dives into specific connections.
