ZMAP(1)

📦
version 4.4.0 · 4 versions
, in arch rolling, epel 10, fedora 43, fedora 44, nixpkgs unstable

💖 zmap 💖

okay bestie, welcome to the manual page for zmap(1) — yes, that's the fast internet scanner and yes it's iconic. buckle up, this is a long one and we're doing it together. 🫶

✨ NAME ✨

zmap — The Fast Internet Scanner 👑

🌸 SYNOPSIS 🌸

zmap [ -p <port(s)> ] [ -o <outfile> ] [ OPTIONS... ] [ ip/hostname/range ]

🦋 DESCRIPTION 🦋

ZMap is a network tool for scanning the entire IPv4 address space (or large samples). bestie, it is fast fast. ZMap can scan the whole entire Internet in around 45 minutes on a gigabit network connection, hitting ~98% theoretical line speed. that's not a vibe, that's a flex. 💅

💅 OPTIONS 💅

🎀 BASIC OPTIONS 🎀

  • ip/hostname/range — the IP addresses or DNS hostnames you wanna scan, bestie. it accepts IP ranges in CIDR block notation. defaults to 0.0.0/8. (yes, that's the default, no cap.)
  • -p, --target-ports=port(s) — a list of TCP/UDP ports and/or port ranges to scan, like 80,443,100-105. use * to scan all ports, port 0 included. slay.
  • -o, --output-file=name — when you're using an output module that uses a file, write the results here. use - for stdout. 🍓
  • -b, --blocklist-file=path — a file of subnets to exclude, in CIDR notation, one per line. highly recommend you use this to exclude RFC 1918 addresses, multicast, IANA reserved space, and other IANA special-purpose addresses. there's an example blocklist file blocklist.conf for exactly this purpose. 💜
  • -w, --allowlist-file=path — a file of subnets to scan, in CIDR notation, one per line. specifying an allowlist file is equivalent to specifying ranges directly on the command line interface, but it lets you specify a large number of subnets. note: if you're specifying a large number of individual IP addresses (more than 10 million), you should instead use --list-of-ips-file.
  • -I, --list-of-ips-file=path — a file of individual IP addresses to scan, one per line. this feature lets you scan a large number of unrelated addresses. if you have a small number of IPs, it's faster to specify them on the command line or by using --allowlist-file. this should only be used when scanning more than 10 million addresses. when used in with --allowlist-path, only hosts in the intersection of both sets will be scanned. hosts specified here but included in the blocklist will be excluded. periodt. ✨

🔥 SCAN OPTIONS 🔥

  • -r, --rate=pps — set the send rate in packets/sec. note: when combined with --probes, this is total packets per second, not IPs per second. setting the rate to 0 will scan at full line rate. default: 10000 pps. 😌
  • -B, --bandwidth=bps — set the send rate in bits/second (supports the suffixes G, M, and K, e.g. -B 10M for 10 mbps). this overrides the --rate flag. highkey powerful.
  • -n, --max-targets=n — cap the number of targets to probe. this can either be a number (e.g. -n 1000) or a percentage (e.g. -n 0.1%) of the scannable address space (after excluding the blocklist). a target is an IP/port pair if you're scanning multiple ports, and an IP otherwise. in the case of percents and multiple ports, the percent is of the total number of IP/port pair combinations. 🧚
  • -N, --max-results=n — exit after receiving this many results.
  • -t, --max-runtime=secs — cap the length of time for sending packets.
  • -c, --cooldown-time=secs — how long to keep receiving after sending has completed (default=8). let it cook. 🍳
  • -e, --seed=n — the seed used to select the address permutation. use this if you want to scan addresses in the same order across multiple ZMap runs.
  • -P, --probes=n — number of probes to send to each IP/Port pair (default=1). probes are sent sequentially for a given IP/Port, so if --probes=4, we'll send 4 probe packets sequentially to that target rather than iterating across the target space 4 times. since ZMap composes Ethernet frames directly, probes can be lost en-route to destination. increasing --probes increases the chance that an online host will receive a probe on an unreliable network. this is contrasted with --retries, which just gives the number of attempts to send a single probe on the source NIC. 💀 (not the same thing, bestie!)
  • --retries=n — number of times to try resending a packet if the sendto call fails (default=10).
  • --batch=n — number of packets to batch before calling the appropriate syscall to send. used to take advantage of Linux's sendmmsg syscall to send the entire batch at once. only available on Linux, other OS's will send each packet individually. (default=64)

🌈 SCAN SHARDING 🌈

  • --shards=N — split the scan up into N shards/partitions among different instances of zmap (default=1). when sharding, --seed is required. don't forget it, bestie.
  • --shard=n — set which shard to scan (default=0). shards are 0-indexed in the range [0, N), where N is the total number of shards. when sharding, --seed is required.

👑 NETWORK OPTIONS 👑

  • -s, --source-port=port|range — source port(s) to send packets from.
  • --validate-source-port=enable|disable — used as an override to enable/disable source port validation. source port validation checks that a received probe response's src port matches the dst port of the probe sent to that IP/port pair. this ensures that multiple ZMap scans to the same hosts but to different ports will not interfere with each other. this overrides each module's default behavior on whether or not to validate source ports with probe responses.
  • -S, --source-ip=ip|range — source address(es) to send packets from. either a single IP or a range (e.g. 10.0.0.1-10.0.0.9).
  • -G, --gateway-mac=addr — gateway MAC address to send packets to (in case auto-detection fails). 🙈
  • --source-mac=addr — source MAC address to send packets from (in case auto-detection fails).
  • -i, --interface=name — the network interface to use.
  • -X, --iplayer — send IP layer packets instead of ethernet packets (for non-Ethernet interfaces).
  • --netmap-wait-ping=ip — (Netmap only) wait for ip to respond to an ICMP Echo request before commencing the scan. useful if you're connected to a switch with STP enabled, where the PHY reset that's needed for entering and leaving Netmap mode will cause the switch to mute the port until the spanning tree protocol has determined that the link should be set into forward state. iykyk. 🌸

🧚 PROBE OPTIONS 🧚

ZMap lets users specify and write their own probe modules, bestie. probe modules are responsible for generating the probe packets to send, and processing responses from hosts. main character energy, honestly.

  • --list-probe-modules — list available probe modules (e.g. tcp_synscan).
  • -M, --probe-module=name — select the probe module (default=tcp_synscan).
  • --probe-args=args — arguments to pass to the probe module.
  • --probe-ttl=hops — set the TTL value for probe IP packets.
  • --list-output-fields — list the fields the selected probe module can send to the output module. 👑

💜 OUTPUT OPTIONS 💜

ZMap lets users specify and write their own output modules for use with ZMap. output modules are responsible for processing the fieldsets returned by the probe module, and outputting them to the user. users can specify output fields, and write filters over the output fields. so much freedom fr fr.

  • --list-output-modules — list available output modules (e.g. csv).
  • -O, --output-module=name — select the output module (default=csv).
  • --output-args=args — arguments to pass to the output module.
  • -f, --output-fields=fields — comma-separated list of fields to output.
  • --output-filter — specify an output filter over the fields defined by the probe module. see the output filter section for more details. 👀
  • --no-header-row — excludes any header rows (e.g., CSV header fields) from ZMap output. this is useful if you're piping results into another application that expects only data. very "just give me the data" of it. 💅

🎀 RESPONSE DEDUPLICATION 🎀

hosts will oftentimes send multiple responses to a probe (either because the scanner doesn't send back a RST packet or because the host has a misimplemented TCP stack). to address this, ZMap will attempt to deduplicate responsive (ip,port) targets. so thoughtful of it. 😭

  • --dedup-method — specifies the method ZMap will use to deduplicate responses. options are: full, window, and none. full deduplication uses a 32-bit bitmap and guarantees that no duplicates will be emitted. however, full-deduplication requires around 500MB of memory for a single port. we do not support full deduplication for multiple ports. window uses a sliding window of the last (user-defined) number of responses as set by --dedup-window-size. none will prevent any deduplication. 🫶
  • --dedup-window-size=targets — specifies the size of the sliding window as the last n target responses to be used for deduplication. only applicable if using window deduplication.

🌟 LOGGING AND METADATA OPTIONS 🌟

  • -q, --quiet — do not print status updates once per second. (shhh 🤫)
  • -v, --verbosity=n — level of log detail (0-5, default=3).
  • -l, --log-file=filename — output file for log messages. by default, stderr.
  • -m, --metadata-file=filename — output file for scan metadata (JSON).
  • -L, --log-directory — write log entries to a timestamped file in this directory.
  • -u, --status-updates-file — write scan progress updates to CSV file.
  • --disable-syslog — disables logging messages to syslog.
  • --notes — inject user-specified notes into scan metadata.
  • --user-metadata — inject user-specified JSON metadata into scan metadata.

⭐ ADDITIONAL OPTIONS ⭐

  • -T, --sender-threads=n — threads used to send packets. ZMap will attempt to detect the optimal number of send threads based on the number of processor cores. defaults to min(4, number of processor cores on host - 1).
  • -C, --config=filename — read a configuration file, which can specify any other options.
  • -d, --dryrun — print out each packet to stdout instead of sending it (useful for debugging). look ma, no packets! 🌈
  • --fast-dryrun — don't actually send packets, print out a binary representation of probe dst IP and dst Port. used for faster integration tests, not for general use.
  • --max-sendto-failures — maximum NIC sendto failures before the scan is aborted.
  • --min-hitrate — minimum hitrate that the scan can hit before the scan is aborted.
  • --cores — comma-separated list of cores to pin to. 📌
  • --ignore-blocklist-errors — bestie, if your allowlist/blocklist file has entries that are invalid, malformed, or just plain unresolvable (like, they ghosted DNS entirely 💀), this makes ZMap shrug and move on instead of throwing a fit. Heads up though: this is the glow-up replacement for the old pre-v3.x --ignore-invalid-hosts option. same energy, new name.
  • -h, --help — prints the help text and dips out. classic. ✨
  • -V, --version — prints the version and exits. that's it, that's the whole job 💅

🌈 OUTPUT FILTERS 🌈

Okay so here's the tea: whatever your probe module spits out can get filtered before it ever reaches the output module. No messy data in your results file, we're gatekeeping. 🚪✨

Filters are defined over the output fields of a probe module, and they're written in a simple filtering language that's giving very SQL, very structured, very demure. You hand them to ZMap with the --output-filter option. People use these constantly to yeet duplicate results, or to let only the successful responses through to the output module. success only, no crumbs.

Filter expressions look like this:

<fieldname> <operation> <value>

The type of <value> has to be either a string or an unsigned integer literal, and it has to match the type of <fieldname>. Like, type-matching is the vibe check here. mismatch = rejected, sorry babe 🙈

The valid operations for integer comparisons are =, !=, <, >, <=, >=.

The operations for string comparisons are =, !=.

And if you wanna know what fields and types are even available for the probe module you picked? Run the --list-output-fields flag. It prints all of that and then exits. king behavior honestly. 👑

Wanna get fancy? You can build compound filter expressions by combining filter expressions with parenthesis to specify order of operations, plus the && (logical AND) and || (logical OR) operators. yes, it's giving boolean algebra and it's serving. 🧮

For example, a filter for only successful, non-duplicate responses would be written as:

--output-filter="success = 1 && repeat = 0"

look at that. beautiful. no duplicates, all success, main character results only. 💖

🦋 UDP PROBE MODULE OPTIONS 🦋

These arguments are all passed using the --probe-args=args option. And listen — only one argument may be passed at a time. one. singular. don't get greedy bestie. 🙅‍♀️

  • file:/path/to/file — path to the payload file that gets sent to each host over UDP. 📁
  • template:/path/to/template — path to a template file. For each destination host, the template file gets populated, set as the UDP payload, and sent. it's customizable, it's personal, it's iconic. ✨
  • text:<text> — ASCII text to send to each destination host. straightforward. we love a simple queen. 💅
  • hex:<hex> — hex-encoded binary to send to each destination host. for when your payload is too cool for ASCII. 🔥
  • template-fields — prints info about all the allowed template fields and exits. very "let me show you the menu" of it. 🎀

⭐ MID-SCAN CHANGES ⭐

You can change the rate at which ZMap is scanning mid-scan. like, live. on the fly. no restart, no drama. 🦋

How? Send signals to ZMap:

  • SIGUSR1 → increase the scan rate 📈
  • SIGUSR2 → decrease the scan rate 📉

And these will result in the scan rate increasing or decreasing by 5%. small steps, steady progress, we love a controlled glow-up. 💜

ngl this is the part where you go forth and scan responsibly. ZMap said what it said. periodt. 💅

that's a wrap on the page bestie — ZMap, November 2025, ZMAP(1) — version and date and everything, so you know exactly which era of this manual you're reading. 🫶🌸

📦 where this page comes from