netsukuku/src/man/ntk-resolv.8

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ntk-resolv 8"
.TH ntk-resolv 8 "2006-06-16" "perl v5.8.6" ""
.SH "NAME"
ntk\-resolv \- Andns Lookup Resolver
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
ntk-resolv [\-vnPtrspShbml] host
ntk-resolv \-H host
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Ntk-resolv is an interface to \s-1ANDNA\s0 daemon: it performs andns queries and displays
the answers to stdout. It is able to formule questions for objects in Internet 
and Netsukuku realms.
It uses the 'andns protocol' to encode his contents, as explained in Netsukuku
\&\s-1RFC\s0 006. 
.SH "USAGE"
.IX Header "USAGE"
The simplest example is:
.PP
.Vb 1
\&        ntk-resolv hname
.Ve
.PP
With this comand, it asks \s-1ANDNA\s0 which \s-1IP\s0 registered the hostname 'hname'.
The default behavior is to perform the query in the Netsukuku realm.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-v\fR	\fB\-\-version\fR" 4
.IX Item "-v	--version"
Print Version, then exit.
.IP "\fB\-n\fR	\fB\-\-nameserver=host\fR" 4
.IX Item "-n	--nameserver=host"
Specify the nameserver to use. The default is localhost.
.IP "\fB\-P\fR	\fB\-\-port=n\fR" 4
.IX Item "-P	--port=n"
Uses the port <n> of nameserver. Default is 53.
.IP "\fB\-t\fR	\fB\-\-query\-type=snsd \-\-query\-type=ptr \-\-qury\-type=global \-\-query\-type=mx\fR" 4
.IX Item "-t	--query-type=snsd --query-type=ptr --qury-type=global --query-type=mx"
Specify the query type . Default is snsd. See the section \fB\s-1QUERY\s0 \s-1TYPE\s0\fR.
.IP "\fB\-r\fR	\fB\-\-realm=inet \-\-realm=ntk\fR" 4
.IX Item "-r	--realm=inet --realm=ntk"
Specify the realm of the query: Internet or Netsukuku. Default is ntk.
.IP "\fB\-s\fR	\fB\-\-service=n[/proto]\fR" 4
.IX Item "-s	--service=n[/proto]"
Specify the \s-1SNSD\s0 service and the relative protocol to search. See
\&\fIservices\fR\|(5). The service can be specified in alfanumeric or numeric format.
The default service and protocol are 0 and tcp.
Example:
.Sp
.Vb 2
\&        ntk-resolv -s domain/udp host
\&        ntk-resolv -s 53/udp host
.Ve
.Sp
See the section \fB\s-1QUERY\s0 \s-1TYPE\s0, \s-1SERVICES\s0 \s-1AND\s0 \s-1PROTOCOL\s0\fR for a better explanation.
.IP "\fB\-S\fR	\fB\-\-silent\fR" 4
.IX Item "-S	--silent"
With this option, ntk-resolv will be very discrete.
.IP "\fB\-b\fR	\fB\-\-block\-recursion\fR" 4
.IX Item "-b	--block-recursion"
Set recursion \s-1OFF\s0. If recursion is \s-1ON\s0 (default), when a \s-1SNSD\s0 service is requested, 
and the service is specified with a hostname instead of an \s-1IP\s0, the \s-1IP\s0 of that 
hostname will be searched. In the case of a success research, the answer will 
contain the \s-1IP\s0 of the hostname, and \s-1NOT\s0 the hostname \s-1HASH\s0.
.IP "\fB\-m\fR	\fB\-\-md5\-hash\fR" 4
.IX Item "-m	--md5-hash"
If this option is set, the hostname specified is interpreted as a \s-1MD5\s0 hash.
This is useful when you want to know a hostname \s-1IP\s0, but you know only the hash
of his name.
.IP "\fB\-H\fR	\fB\-\-compute\-hash\fR" 4
.IX Item "-H	--compute-hash"
Compute the hash of specified hostname and print it to stdout.
Example:
.Sp
.Vb 1
\&        ntk-resolv -H hname
.Ve
.Sp
It will print the md5 hash of `hname'. This is useful to debug \s-1SNSD\s0
configurations. In fact, if a query is not recursive, the results are hash'ed
hostnames: so, it's possible to verify if the \s-1ANDNA\s0 cache is storing the
correct hash-value for your \s-1SNSD\s0 hostnames.
.IP "\fB\-l\fR	\fB\-\-parsable\-output\fR" 4
.IX Item "-l	--parsable-output"
Print answers in a synthetic way. The format of output is:
.Sp
.Vb 6
\&        ~ IP                               (SNSD s=0)
\&        - hname                            (Inverse)
\&        - hname prio weight                (SNSD s!=0)
\&        ~ ip prio weight                   (SNSD s!=0)  
\&        ~ ip service proto prio weight     (Global)
\&        - hname service proto prio weight  (Global)
.Ve
.Sp
Note that when an answer contains an \s-1IP\s0, the first character is `~'; if the
answer contains a hostname (hash'ed or not) the line begins with `\-'.
.IP "\fB\-h\fR	\fB\-\-help\fR" 4
.IX Item "-h	--help"
Prints to stdout a short explanation of ntk\-resolv.
.IP "\fBFinal note:\fR" 4
.IX Item "Final note:"
All options that take string arguments could be expressed in a shorter 
way, by specifing univoque abbreviation of argument. So, there is the equivalence:
.Sp
.Vb 1
\&        ntk-resolv -r i = ntk-resolv -r inet
.Ve
.Sp
with the exception of option \-s, wich requires a valid service.
.SH "QUERY TYPE"
.IX Header "QUERY TYPE"
You can formule different kind of queries.
.Sp
With a `ptr' query, you specify an \s-1IP\s0, and you will have, if exists, the hostname
that registered that \s-1IP\s0.
.Sp
With a `snsd' query, you specify a hostname, a service and a protocol. If service and
protocol are not specified, they are set to 0, and you will have the \s-1IP\s0 assigned
to the hostname at this moment.
If you specify a service and a protocol, the answer will contain the \s-1IP\s0 that gives
the specified service/protocl for the hostname.
See the section \fB\s-1SNSD\s0, \s-1SERVICES\s0 \s-1AND\s0 \s-1PROTOCOL\s0\fR to understand better the \s-1SNSD\s0 behavior.
.Sp
A global query will return the complete \s-1SNSD\s0 configuration for a hostname.
Ie, you will have an answer for each service that hostname registered.
.Sp
The `mx' query is equivalent to a snsd query with service 25 and proto \s-1TCP\s0. 
.SH "SNSD, SERVICES AND PROTOCOL"
.IX Header "SNSD, SERVICES AND PROTOCOL"
\&\s-1SNSD\s0 Query Type gives a hostname resolution.
With \s-1SNSD\s0 (Scattered Name Service Disgregation) \s-1ANDNA\s0 lets the user to
ask for a domain and a service.
If service is 0, the resolution will show which \s-1IP\s0 registered the hostname.
If service is non\-0, the resolution will show which \s-1IP\s0 gives specified service
for the hostname (considering the protocol too). See \fIservices\fR\|(5).
.Sp
You can specify a service as expressed in /etc/services. It can be
expressed  also in numeric form.
It is also possible to specify the protocol:
.Sp
.Vb 1
\&        "domain", "53", "53/udp", "domain/udp"
.Ve
.Sp
are valid service/proto strings.
.Sp
For example, the next commands will retrieve the \s-1IP\s0(s) that offers web-pages
for the hostname \*(L"host\*(R":
.Sp
.Vb 4
\&        ntk-resolv -s http/tcp host
\&        ntk-resolv -s 80/tcp   host
\&        ntk-resolv -s 80       host
\&        ntk-resolv -s http     host
.Ve
.Sp
To configure the \s-1SNSD\s0 delegations, see the \s-1SNSD\s0 HowTo.
.Sp
If the delegation for a service (say http) is not set, the \s-1IP\s0 returned is
the \s-1IP\s0 that registered the hostname. So, if you do not want to set \s-1SNSD\s0 delegations
for specific services, the main hostname \s-1IP\s0 will be used and you don't need to
do nothing.
.Sp
The hope is that every client will build different queries: browsers
will make queries with service=80 and proto=tcp, mail-clients will build
queries with service=25 and proto tcp and so on.
.Sp
The service is useless if the query realm is Internet.
.Sp
The default service is 0: ie, the query will return the \s-1IP\s0 that registered
the hostname. Default protocol is tcp. Protocol is ignored when service
requested is 0.
.Sp
Note: service and proto are also ignored when the query type is `ip\->host`
(ptr query type).
.SH "BUGS"
.IX Header "BUGS"
{ Don't panic! }
.Sp
If you encounter any bug, please report it.
Use the online bug track system: 
    <http://bugs.dyne.org/> 
.Sp
or the mailing list:
    <http://lists.dyne.org/netsukuku/>
.Sp
and explain what the problem is and if possible a way to reproduce it.
.SH "CONTACTS"
.IX Header "CONTACTS"
Subscribe to the netsukuku mailing to get help, be updated on the latest news
and discuss on its development.
.Sp
To subscribe to the list, send a message to:
    netsukuku\-subscribe@lists.dyne.org
.Sp
We live night and day in \s-1IRC\s0, come to see us in:
#netsukuku
on the FreeNode irc server (irc.freenode.org).
.SH "AUTHORS"
.IX Header "AUTHORS"
Main authors and maintainers:
.Sp
Federico Tomassini  <effetom@gmail.com> wrote ntk-resolv and network libraries.
.Sp
Andrea Lo Pumo aka AlpT <alpt@freaknet.org> wrote \s-1ANDNA\s0 and Netsukuku Core.
.Sp
Main contributors:
.Sp
Andrea Leofreddi <andrea.leofreddi@gmail.com>, Katolaz <katolaz@freaknet.org>,
.Sp
For a complete list read the \s-1AUTHORS\s0 file or visit:
    <http://netsukuku.freaknet.org/?p=Contacts>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIntkd\fR\|(8), \fIandna\fR\|(8), \fIservices\fR\|(5)