# ZMap Copyright 2013 Regents of the University of Michigan

# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at http://www.apache.org/licenses/LICENSE-2.0

# zmap option description to be processed by gengetopt

package "zmap"
version "2.1.0"
purpose "A fast Internet-wide scanner."

section "Basic arguments"

option "target-port"            p "port number to scan (for TCP and UDP scans)"
    typestr="port"
    optional int
option "output-file"            o "Output file"
    typestr="name"
    optional string
option "blacklist-file"         b "File of subnets to exclude, in CIDR notation, e.g. 192.168.0.0/16"
    typestr="path"
    optional string
option "whitelist-file"         w "File of subnets to constrain scan to, in CIDR notation, e.g. 192.168.0.0/16"
    typestr="path"
    optional string

section "Scan options"
option "rate"                   r "Set send rate in packets/sec"
    typestr="pps"
    optional int
option "bandwidth"              B "Set send rate in bits/second (supports suffixes G, M and K)"
    typestr="bps"
    optional string
option "max-targets"            n "Cap number of targets to probe (as a number or a percentage of the address space)"
    typestr="n"
    optional string
option "max-runtime"            t "Cap length of time for sending packets"
    typestr="ses"
    optional int
option "max-results"            N "Cap number of results to return"
    typestr="n"
    optional int
option "probes"                 P "Number of probes to send to each IP"
    typestr="n"
    default="1"
    optional int
option "cooldown-time"          c "How long to continue receiving after sending last probe"
    typestr="secs"
    default="8"
    optional int
option "seed"                   e "Seed used to select address permutation"
    typestr="n"
    optional longlong
option "retries"                - "Max number of times to try to send packet if send fails"
    typestr="n"
    default="10"
    optional int
option "dryrun"                 d "Don't actually send packets"
    optional
option "shards"                 - "Set the total number of shards"
    typestr="N"
    optional int
    default="1"
option "shard"                  - "Set which shard this scan is (0 indexed)"
    typestr="n"
    optional int
    default="0"

section "Network options"

option "source-port"            s "Source port(s) for scan packets"
    typestr="port|range"
    optional string
option "source-ip"              S "Source address(es) for scan packets"
    typestr="ip|range"
    optional string
option "gateway-mac"            G "Specify gateway MAC address"
    typestr="addr"
    optional string
option "source-mac"             - "Source MAC address"
    typestr="addr"
    optional string
option "interface"              i "Specify network interface to use"
    typestr="name"
    optional string
option "vpn"                    X "Sends IP packets instead of Ethernet (for VPNs)"
    optional

section "Probe Modules"
option "probe-module"           M "Select probe module"
    typestr="name"
    default="tcp_synscan"
    optional string

option "probe-args"             - "Arguments to pass to probe module"
    typestr="args"
    optional string

option "list-probe-modules"     - "List available probe modules"
        optional

section "Data Output"
option "output-fields"          f "Fields that should be output in result set"
    typestr="fields"
    optional string
option "output-module"          O "Select output module"
    typestr="name"
    default="default"
    optional string
option "output-args"            - "Arguments to pass to output module"
    typestr="args"
    optional string
option "output-filter"          - "Specify a filter over the response fields to limit what responses get sent to the output module"
    typestr="filter"
    optional string
option "list-output-modules"    - "List available output modules"
        optional
option "list-output-fields"     - "List all fields that can be output by selected probe module"
    optional

section "Logging and Metadata"
option "verbosity"              v "Level of log detail (0-5)"
    typestr="n"
    default="3"
    optional int
option "log-file"               l "Write log entries to file"
    typestr="name"
    optional string
option "log-directory"          L "Write log entries to a timestamped file in this directory"
    typestr="directory"
    optional string
option "metadata-file"          m "Output file for scan metadata (JSON)"
    typestr="name"
    optional string
option "status-updates-file"    u "Write scan progress updates to CSV file"
    typestr="name"
    optional string
option "quiet"                  q "Do not print status updates"
    optional
option "disable-syslog"         - "Disables logging messages to syslog"
    optional
option "notes"                  - "Inject user-specified notes into scan metadata"
    typestr="notes"
    optional string
option "user-metadata"          - "Inject user-specified JSON metadata into scan metadata"
    typestr="json"
    optional string

section "Additional options"
option "config"                 C "Read a configuration file, which can specify any of these options"
    typestr="filename"
    default="/etc/zmap/zmap.conf"
    optional string
option "sender-threads"         T "Threads used to send packets"
    typestr="n"
    default="1"
    optional int
option "cores"                 - "Comma-separated list of cores to pin to"
    optional string


option "ignore-invalid-hosts"   - "Ignore invalid hosts in whitelist/blacklist file"
    optional
option "help"                   h "Print help and exit"
    optional
option "version"                V "Print version and exit"
    optional

text "\nExamples:\n\
    zmap -p 80 (scan the Internet for hosts on tcp/80 and output to stdout)\n\
    zmap -N 5 -B 10M -p 80 (find 5 HTTP servers, scanning at 10 Mb/s)\n\
    zmap -p 80 10.0.0.0/8 192.168.0.0/16 -o (scan both subnets on tcp/80)\n\
    zmap -p 80 1.2.3.4 10.0.0.3 (scan 1.2.3.4, 10.0.0.3 on tcp/80)"
