Nuff Manual Pages

Nuff Manual Pages

Nuff Manual Pages

This document contains the manual pages for the scripts and utilities shipped with the nuff distribution. Some of this information can also be read in formatted ascii from the command line by using the help command:

$ nuff help <utility>

Code Types

  1. General Utilities
  2. DNS Utilities
  3. Meta-Utilities

General Utilities

  1. trace
  2. probeip4
  3. ping


Parallel, generic traceroute tool

trace DOES require root privileges.

trace is a tool designed to demonstrate nuff's concurrency features and the power of pipelining network operations. It performs a similar function to Van Jacobson's classic traceroute program but performs operations in parallel to illustrate the power of pipelining. If you specify the option "-pipeline 1" trace will perform the operations sequentially, like the original traceroute (no pipelining). Try experimenting with different values for -pipeline to get a feel for network concurrency.

trace will print a status update consisting of 1 character per hop every -update seconds unless nothing has changed from the previous status update. The characters have the following meanings:

  • . : Trace probe has been sent, waiting for reply.

  • r : Trace probe reply received. Performing reverse DNS.

  • x : Trace probe timed out. Host unknown.

  • O : Host finished OK, reverse DNS successful.

  • N : Host finished OK, NXDOMAIN on reverse DNS.

  • S : Host finished OK, SERVFAIL on reverse DNS.

Here is an example, using the default pipeline depth of 10. Notice how the trace is completely finished after 3 seconds but, since the reverse DNS is misconfigured for hop 12, we have to wait around for it to timeout:

# nuff trace
Tracing to IP
0.04  s : ..........
0.15  s : r.........
0.26  s : r.......r.
0.42  s : r....r..rr
0.69  s : N..r.r.rrr.
0.98  s : N.rr.r.rOr..
1.16  s : N.rrrO.rOr...
1.44  s : N.rrrOrrOO....
1.63  s : NrrOrOrrOO...O
1.91  s : NrrOrOrOOOr..O
2.25  s : NrOOrOrOOOrr.O
2.4   s : NrOOOOrOOOrrrO
2.67  s : NNOOOOOOOOrrrO
Trace to finished after 5.52 seconds.
1: (nxdomain)
2: (nxdomain)
3: (
4: (
5: (
6: (
7: (
8: (
9: (
10: (
11: (
12: (servfail)
13: (nxdomain)
14: (

Required Arguments
dest"Destination Host"(valid-host? x)

Optional Arguments
-mode"Protocol to use""udp"(member x (quote ("udp" "tcp" "icmp")))
-base"Base port"33434(<= 0 x 65535)
-update"Update interval in seconds"0.1(< 0 x)
-pipeline"Number of queries to do in parallel"10(and (integer? x) (>= x 1))
-max-dist"Maximum distance to probe (in hops)"32(and (integer? x) (>= x 1))
-n"No reverse DNS (numeric output)"
-timeout"Maximum number of seconds to wait for a response"2(and (number? x) (> x 0))
-retries"Maximum number of retries for a response"2(and (integer? x) (>= x 0))


Convenient IP4 Prober

probeip4 DOES require root privileges.

This is a simple command that injects IP4 packets into the system's libdnet-ip interface. Several IP-level parameters can be set and a raw nuff layer macro can be given as the payload.


$ nuff probeip4 -ttl 5
$ nuff probeip4 -payload '(udp -dp 53 -data (dns -rd -question (list "" DNS-TYPE-A)))'

Required Arguments
dest"Destination Host"(valid-host? x)

Optional Arguments
-ipid"IPID"65534(<= 0 x 65535)
-ttl"Time To Live"64(<= 0 x 255)
-src"Source IP Address"""(inet-aton x)
-payload"Nuff Layer Form Payload""(icmp4 -type ICMP-TYPE-ECHO-REQUEST -data (icmp4/echo))"(pair? (read-from-string x))


Simple ping(8) clone

ping DOES require root privileges.

Sends ICMP ECHOs at a user-specified delay and waits for responses.

This is a ping program designed to test nuff's cooperative multi-tasking system.

Required Arguments
target"The victim"(valid-host? x)

Optional Arguments
-i"Wait x seconds between sending each packet"1(<= 0 x)
-s"Extra bytes of ICMP padding"8(<= 0 x)
-n"Numeric output (no reverse DNS)"

DNS Utilities

  1. dnsd
  2. dnssequence
  3. resolve


Simple, secure, smart DNS server/forwarder

dnsd DOES require root privileges.

Optional Arguments
-forward"Forward DNS Queries"
-zone"Zone file"()(or (null? x) (and (string? x) (file-readable? x)))
-predict"Use DNS prediction"
-port"Port to listen on"53(<= 1 x 65535)
-daemon"Run in "daemon mode" (silently, in the background)"
-nameservers"Nameservers to use for forwarding"()(or (null? x) (true-for-all (lambda (i) (and (pair? i) (= (length i) 2) (string? (car i)) (integer? (cadr i)) (<= 1 (cadr i) 65535))) (read-from-string x)))
-delay"Artificial resolve delay (in seconds)"0(<= 0 x 60)
-predict-window"Prediction look-ahead window (seconds)"3(<= 0 x)


Tree-based DNS Sequence Resolver

dnssequence DOES NOT require root privileges.

This program is designed to time how long it takes to issue a particular series of DNS queries. They can have multiple dependency orderings so that certain DNS requests can't be issued until the results have been received from previous ones. The way we model this sequence of dependencies is a tree.

We use a popular lisp recursive representation for a tree: A tree is either null or a list where the car is an element and the cdr is a list of sub-trees. Additionally, the root of our dependency tree is always the symbol seq.

The following is an ordered dependency sequence. A must be looked up before B which must be looked up before C:

(seq ("" ("" (""))))

The following is a sequence where all resolutions can be done in parallel (since none of them depend on each other):

(seq ("") ("") (""))

Required Arguments
tree"Tree of DNS Names"(let ((l (read-from-string x))) (and (pair? l) (eq? (car l) (quote seq))))

Optional Arguments
-nameservers"Nameservers to use for forwarding"()(or (null? x) (true-for-all (lambda (i) (and (pair? i) (= (length i) 2) (string? (car i)) (integer? (cadr i)) (<= 1 (cadr i) 65535))) (read-from-string x)))
-type"DNS Query Type""A"(defined? (symbolmash "DNS-TYPE-" x))
-graphviz"Display tree for graphviz output"
-timeonly"Only display elapsed time (in seconds)"


Parallel DNS Resolver

resolve DOES NOT require root privileges.

This is a nuff code interface to the nuff resolve function.

Supply the hosts in the extra arg (after the --) list unless you want -stdin. You can press enter during resolution to see the progress so far unless you specified -stdin.


$ nuff resolve --
$ nuff resolve -type PTR --
$ printf '\\n' | nuff resolve -stdin
$ nuff resolve -type PTR -- `perl -e 'for($i=100; $i<150; $i++) { print "65.98.116.$i\n"; }'`

Optional Arguments
-stdin"Read domain names from standard input instead of extra-args"
-sexpr"S-Expression output"
-type"DNS Query Type""A"(defined? (symbolmash "DNS-TYPE-" x))


  1. doc
  2. eval
  3. describe
  4. graphviz
  5. help


Displays nuff documentation in various output styles

doc DOES NOT require root privileges.

The nuffdoc format is a simple S-expression based format that provides most of nuff's documentation.

The nuffdoc files are stored in NUFFDIR/docs/*.nuffdoc

It outputs in ASCII text format by default but can also do HTML.

Required Arguments
docname"Document name"(string? x)

Optional Arguments
-style"Desired output style""text"(or (equal? x "text") (equal? x "html"))
-file"Treat document parameter as a filename, not a system nuffdoc"
-cols"Output columns (only for text mode)"80(and (integer? x) (<= 40 x))


Evaluate a scheme form

eval DOES require root privileges.

eval will (eval)uate the given form, (write) the result, then (quit).

form is evaluated without root privileges unless you specify the -priv option.

Required Arguments
form"Form to execute"(pair? (read-from-string x))

Optional Arguments
-priv"Execute with root privileges (if available)"


Describes various components of the nuff system

describe DOES NOT require root privileges.

describe provides a command-line interface to nuff's describe function.

At present you can ask describe for info on:

  • Layers

    $ nuff describe ip4
  • Interfaces

    $ nuff describe pcap
  • layer compilation forms

    $ nuff describe '(ip4 -src "" -data (udp -dp my-port))'
  • parsepaq compilation forms

    $ nuff describe '(parsepaq mypaq some-data ((eth ip4) (format #t "Got IP4 packet from ~a~%" mypaq-ip4-src)))

Required Arguments
form"Form/Symbol to describe"(string? x)


Visualise nuff's layers in dot format

graphviz DOES NOT require root privileges.

graphviz outputs nuff's layer transitions as a directed graph in the standard graphviz dot format.

Example use:

$ nuff graphviz | dot -Tpng > nuff-layers.png


Displays information on different nuff commands

help DOES NOT require root privileges.

help gives you a human-readable display of all the options provided by a nuff command.

It uses the information in the module information at the top of the specified nuff command to construct the information. Since this is also a part of the code nuff uses, it is guaranteed to be up-to-date and accurate (except for bugs).

Required Arguments
command"Command to get help with"(string? x)

All material is © Doug Hoyte and/or HCSW Labs unless otherwise noted or implied.