Nuff Manual Pages

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 hcsw.org
Resolving hcsw.org
Tracing to IP 65.98.116.106
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
2.92  s : NNOOOOOOOOOrNO
Trace to hcsw.org finished after 5.52 seconds.
1: 192.168.123.1 (nxdomain)
2: 24.71.219.1 (nxdomain)
3: 64.59.170.2 (rd2ht-ge2-3-1.ok.shawcable.net)
4: 66.163.77.138 (rc1so-ge4-1-0.cg.shawcable.net)
5: 66.163.77.158 (rc2nr-pos11-0-0.wp.shawcable.net)
6: 66.163.73.170 (rc1sc-ge12-0-0.wp.shawcable.net)
7: 66.163.76.73 (rc1sh-pos13-0.mt.shawcable.net)
8: 66.163.77.154 (rc1hu-pos5-0-0.ny.shawcable.net)
9: 198.32.160.53 (nyiix.tengig1-2.ar1.nyc3.us.nlayer.net)
10: 69.31.95.130 (po1.ar1.nyc3.us.nlayer.net)
11: 69.31.95.26 (fortressitx.g4-26.ar1.nyc3.us.nlayer.net)
12: 208.116.63.244 (servfail)
13: 65.98.99.210 (nxdomain)
14: 65.98.116.106 (hcsw.org)

Required Arguments

Name	Description	Verifier
dest	"Destination Host"	(valid-host? x)

Optional Arguments

Switch	Description	Default	Verifier
-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.

Examples:

$ nuff probeip4 -ttl 5 target.com

$ nuff probeip4 -payload '(udp -dp 53 -data (dns -rd -question (list "google.com" DNS-TYPE-A)))' 1.2.3.4

Required Arguments

Name	Description	Verifier
dest	"Destination Host"	(valid-host? x)

Optional Arguments

Switch	Description	Default	Verifier
-ipid	"IPID"	65534	(<= 0 x 65535)
-ttl	"Time To Live"	64	(<= 0 x 255)
-src	"Source IP Address"	"0.0.0.0"	(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

Name	Description	Verifier
target	"The victim"	(valid-host? x)

Optional Arguments

Switch	Description	Default	Verifier
-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)"

Simple, secure, smart DNS server/forwarder

dnsd DOES require root privileges.

Optional Arguments

Switch	Description	Default	Verifier
-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 ("a.com" ("b.com" ("c.com"))))

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

(seq ("a.com") ("b.com") ("c.com"))

Required Arguments

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

Optional Arguments

Switch	Description	Default	Verifier
-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.

Examples:

$ nuff resolve -- hcsw.org slashdot.org

$ nuff resolve -type PTR -- 1.2.3.4

$ printf 'a.com\nb.com\n' | nuff resolve -stdin

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

Optional Arguments

Switch	Description	Default	Verifier
-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))

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

Name	Description	Verifier
docname	"Document name"	(string? x)

Optional Arguments

Switch	Description	Default	Verifier
-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

Name	Description	Verifier
form	"Form to execute"	(pair? (read-from-string x))

Optional Arguments

Switch	Description	Default	Verifier
-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 "127.0.0.1" -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

Name	Description	Verifier
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

Name	Description	Verifier
command	"Command to get help with"	(string? x)