[apple/network_cmds.git] / unbound / doc / unbound-host.1.in

.TH "unbound\-host" "1" "Dec  8, 2014" "NLnet Labs" "unbound 1.5.1"
.\"
.\" unbound-host.1 -- unbound DNS lookup utility
.\"
.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B unbound\-host
\- unbound DNS lookup utility
.SH "SYNOPSIS"
.B unbound\-host
.RB [ \-vdhr46D ]
.RB [ \-c 
.IR class ]
.RB [ \-t
.IR type ]
.I hostname
.RB [ \-y
.IR key ]
.RB [ \-f
.IR keyfile ]
.RB [ \-F
.IR namedkeyfile ]
.RB [ \-C
.IR configfile ]
.SH "DESCRIPTION"
.B Unbound\-host
uses the unbound validating resolver to query for the hostname and display
results. With the \fB\-v\fR option it displays validation 
status: secure, insecure, bogus (security failure).
.P
By default it reads no configuration file whatsoever.  It attempts to reach
the internet root servers.  With \fB\-C\fR an unbound config file and with
\fB\-r\fR resolv.conf can be read.
.P
The available options are:
.TP
.I hostname
This name is resolved (looked up in the DNS).
If a IPv4 or IPv6 address is given, a reverse lookup is performed.
.TP
.B \-h
Show the version and commandline option help.
.TP
.B \-v
Enable verbose output and it shows validation results, on every line.
Secure means that the NXDOMAIN (no such domain name), nodata (no such data)
or positive data response validated correctly with one of the keys.
Insecure means that that domain name has no security set up for it.
Bogus (security failure) means that the response failed one or more checks,
it is likely wrong, outdated, tampered with, or broken.
.TP
.B \-d
Enable debug output to stderr. One \-d shows what the resolver and validator
are doing and may tell you what is going on. More times, \-d \-d, gives a
lot of output, with every packet sent and received.
.TP
.B \-c \fIclass
Specify the class to lookup for, the default is IN the internet class.
.TP
.B \-t \fItype
Specify the type of data to lookup. The default looks for IPv4, IPv6 and
mail handler data, or domain name pointers for reverse queries.
.TP
.B \-y \fIkey
Specify a public key to use as trust anchor. This is the base for a chain
of trust that is built up from the trust anchor to the response, in order
to validate the response message. Can be given as a DS or DNSKEY record.
For example \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD".
.TP
.B \-D
Enables DNSSEC validation.  Reads the root anchor from the default configured
root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR. 
.TP
.B \-f \fIkeyfile
Reads keys from a file. Every line has a DS or DNSKEY record, in the format
as for \-y. The zone file format, the same as dig and drill produce.
.TP
.B \-F \fInamedkeyfile
Reads keys from a BIND\-style named.conf file. Only the trusted\-key {}; entries
are read.
.TP
.B \-C \fIconfigfile
Uses the specified unbound.conf to prime
.IR libunbound (3).
.TP
.B \-r
Read /etc/resolv.conf, and use the forward DNS servers from there (those could
have been set by DHCP).  More info in
.IR resolv.conf (5).
Breaks validation if those servers do not support DNSSEC.
.TP
.B \-4
Use solely the IPv4 network for sending packets.
.TP
.B \-6
Use solely the IPv6 network for sending packets.
.SH "EXAMPLES"
Some examples of use. The keys shown below are fakes, thus a security failure
is encountered.
.P
$ unbound\-host www.example.com
.P
$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com
.P
$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153
.SH "EXIT CODE"
The unbound\-host program exits with status code 1 on error, 
0 on no error. The data may not be available on exit code 0, exit code 1
means the lookup encountered a fatal error.
.SH "SEE ALSO"
\fIunbound.conf\fR(5), 
\fIunbound\fR(8).
Commit	Line	Data
89c4ed63 A	1	.TH "unbound\-host" "1" "Dec 8, 2014" "NLnet Labs" "unbound 1.5.1"
	2	.\"
	3	.\" unbound-host.1 -- unbound DNS lookup utility
	4	.\"
	5	.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
	6	.\"
	7	.\" See LICENSE for the license.
	8	.\"
	9	.\"
	10	.SH "NAME"
	11	.B unbound\-host
	12	\- unbound DNS lookup utility
	13	.SH "SYNOPSIS"
	14	.B unbound\-host
	15	.RB [ \-vdhr46D ]
	16	.RB [ \-c
	17	.IR class ]
	18	.RB [ \-t
	19	.IR type ]
	20	.I hostname
	21	.RB [ \-y
	22	.IR key ]
	23	.RB [ \-f
	24	.IR keyfile ]
	25	.RB [ \-F
	26	.IR namedkeyfile ]
	27	.RB [ \-C
	28	.IR configfile ]
	29	.SH "DESCRIPTION"
	30	.B Unbound\-host
	31	uses the unbound validating resolver to query for the hostname and display
	32	results. With the \fB\-v\fR option it displays validation
	33	status: secure, insecure, bogus (security failure).
	34	.P
	35	By default it reads no configuration file whatsoever. It attempts to reach
	36	the internet root servers. With \fB\-C\fR an unbound config file and with
	37	\fB\-r\fR resolv.conf can be read.
	38	.P
	39	The available options are:
	40	.TP
	41	.I hostname
	42	This name is resolved (looked up in the DNS).
	43	If a IPv4 or IPv6 address is given, a reverse lookup is performed.
	44	.TP
	45	.B \-h
	46	Show the version and commandline option help.
	47	.TP
	48	.B \-v
	49	Enable verbose output and it shows validation results, on every line.
	50	Secure means that the NXDOMAIN (no such domain name), nodata (no such data)
	51	or positive data response validated correctly with one of the keys.
	52	Insecure means that that domain name has no security set up for it.
	53	Bogus (security failure) means that the response failed one or more checks,
	54	it is likely wrong, outdated, tampered with, or broken.
	55	.TP
	56	.B \-d
	57	Enable debug output to stderr. One \-d shows what the resolver and validator
	58	are doing and may tell you what is going on. More times, \-d \-d, gives a
	59	lot of output, with every packet sent and received.
	60	.TP
	61	.B \-c \fIclass
	62	Specify the class to lookup for, the default is IN the internet class.
	63	.TP
	64	.B \-t \fItype
65	Specify the type of data to lookup. The default looks for IPv4, IPv6 and
66	mail handler data, or domain name pointers for reverse queries.
67	.TP
68	.B \-y \fIkey
69	Specify a public key to use as trust anchor. This is the base for a chain
70	of trust that is built up from the trust anchor to the response, in order
71	to validate the response message. Can be given as a DS or DNSKEY record.
72	For example \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD".
73	.TP
74	.B \-D
75	Enables DNSSEC validation. Reads the root anchor from the default configured
76	root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR.
77	.TP
78	.B \-f \fIkeyfile
79	Reads keys from a file. Every line has a DS or DNSKEY record, in the format
80	as for \-y. The zone file format, the same as dig and drill produce.
81	.TP
82	.B \-F \fInamedkeyfile
83	Reads keys from a BIND\-style named.conf file. Only the trusted\-key {}; entries
84	are read.
85	.TP
86	.B \-C \fIconfigfile
87	Uses the specified unbound.conf to prime
88	.IR libunbound (3).
89	.TP
90	.B \-r
91	Read /etc/resolv.conf, and use the forward DNS servers from there (those could
92	have been set by DHCP). More info in
93	.IR resolv.conf (5).
94	Breaks validation if those servers do not support DNSSEC.
95	.TP
96	.B \-4
97	Use solely the IPv4 network for sending packets.
98	.TP
99	.B \-6
100	Use solely the IPv6 network for sending packets.
101	.SH "EXAMPLES"
102	Some examples of use. The keys shown below are fakes, thus a security failure
103	is encountered.
104	.P
105	$ unbound\-host www.example.com
106	.P
107	$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com
108	.P
109	$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153
110	.SH "EXIT CODE"
111	The unbound\-host program exits with status code 1 on error,
112	0 on no error. The data may not be available on exit code 0, exit code 1
113	means the lookup encountered a fatal error.
114	.SH "SEE ALSO"
115	\fIunbound.conf\fR(5),
116	\fIunbound\fR(8).