TORLOOKUP(1)

✨ TORLOOKUP(1) — the tor exit node lookup page, but make it cute ✨

okay so first things first: this is the manual page for torlookup, from the General Commands Manual. Debian gang, $Mdocdate$ era, we're vibing. 💅

---

🌸 NAME 🌸

torlookup — literally the tool for looking up whether an IP address was a tor exit node. no cap, that's the whole job. 🕵️‍♀️

---

🎀 SYNOPSIS 🎀

ok so here's how you call her:

torlookup [-H torDBfile] [-h] iplist
torlookup -d directory -w torDBfile

like, two whole modes. lookup mode and build mode. pick your fighter. ✨

---

🦋 DESCRIPTION 🦋

so torlookup is this iconic little tool that checks whether an IP address was a tor exit node during specific time intervals. but bestie, listen — before you use torlookup, you gotta create the nfdump-specific lookup database first. it's giving "prerequisite." 🫶

torlookup is ALSO the girl who creates the nfdump formatted lookup database file from a bunch of tor archive files. and the best part? you do not need an account to download or build the nfdump tor database. no login, no signup, no "create a password with one uppercase and a symbol" nonsense. building instructions are in the section below, iykyk. 👑

torlookup accepts a list of IP addresses either on the command line (separated by spaces) or on stdin, line by line. and here's the cute part — the IP address on each line can be embedded in a string separated by spaces on the left and right, so it can literally read the piped output from other tools. she's flexible like that. 💖

the options are as follows, bestie:

⭐ OPTIONS ⭐

• -d directory — use the tor archive files in directory to build the binary lookup database file. with this argument, torlookup creates a new binary lookup database file. new file, who dis. 🔥
• -w torDBfile — name of the new lookup database file. name her something cute. 🎀
• -H torDBfile — use the binary torDBfile as the lookup database for the tor exit node lookups. like, "hey, use THIS one." 💅
• -h — print help and exit. the classic. the icon. 🙈

so when you wanna specify the tor lookup database, torlookup searches at these places, in this order:

• if the default nfdump(1) configuration file exists, it reads the tag tordb.path
• if the environment variable NFTORDB is set, use this setting as lookup database
• the command line argument -H

and if multiple locations are specified? -H takes precedence over the NFTORDB environment variable, which in turn overrides the nfdump configuration file. so it's giving hierarchy. -H is the main character, NFTORDB is the supporting role, and the config file is the extra in the background. periodt. 👑

---

💜 ENVIRONMENT 💜

torlookup reads the environment variable NFTORDB. that's the one. that's the whole section. she's lowkey mysterious. 🌙

---

🌈 EXIT STATUS 🌈

torlookup returns 0 on success and 255 otherwise. so if you see 255, something went wrong and she's not happy about it. 😭

---

🍓 EXAMPLES 🍓

the easiest way for creating or updating the binary lookup database is to use the script updateTorDB.sh, provided with all other nfdump files. she's included, bestie, you don't gotta hunt for her. 🧚

the script updateTorDB.sh accepts one argument: the number of months of Tor exit node data to include in the database. so like, "how many months of data, queen?" and you tell her. this means you need to update the torDB on a regular basis to have up-to-date information — no letting it get crusty. and do not forget to move the lookup database to the final location. seriously. don't forget. 🙈

lookup an IP with torlookup:

% ./torlookup -H tordb_full.nf 178.218.144.18
Node: 178.218.144.18, last published: 2024-07-31 11:53:12,
intervals: 7
0 first: 2022-10-25 20:16:03, last: 2022-11-21 20:55:32
1 first: 2022-12-19 23:16:38, last: 2022-12-28 18:17:01
2 first: 2023-01-08 02:04:07, last: 2023-03-25 07:13:15
3 first: 2023-03-29 05:08:45, last: 2023-09-12 17:05:01
4 first: 2023-09-18 13:11:30, last: 2023-12-05 21:19:41
5 first: 2024-01-05 03:05:32, last: 2024-03-22 21:08:22
6 first: 2024-04-24 04:47:28, last: 2024-08-01 04:09:14

torlookup returns the number of intervals the IP was registered as an exit node, limited by first/last timestamps. so you get the receipts. 🧾✨

and you can pipe the output of an nfdump statistic to torlookup for tor exit node verification:

% nfdump -r nfcapd.202408011200 -s ip | torlookup -H tordb_full.nf

pipe it, queen. 🫶

---

🔥 NOTES 🔥

if you use the tordb with nfdump to list flows and mark them as tor exit nodes, the IP address as well as the flow start or flow end timestamp must fall into the appropriate tor exit node interval. both. not just one. both. 💀

in the pipe example above, torlookup does not care about timestamps. she's just there for the vibe, not the timing. 😌

use nfdump with the tordb:

% nfdump -H tordb.nf -r nfcapd.2024081200 -o tor

that's the move. that's the whole move. 💅

---

🌟 SEE ALSO 🌟

nfdump(1) includes built-in options to annotate output with Tor exit node information. see also the nfdump tags %stor and %dtor. absolute icons. 👑

and of course, nfdump(1). the parent. the legend. 🌈

---

k bye bestie, go look up some tor exit nodes 💖✨🎀🦋🌸💅🫶

— Debian, $Mdocdate$, TORLOOKUP(1). that's the sign-off, mwah. 😘