doc: Set author for manpage
[resolv_wrapper.git] / doc / resolv_wrapper.1
1 '\" t
2 .\"     Title: resolv_wrapper
3 .\"    Author: The Samba Team
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\"      Date: 2020-01-31
6 .\"    Manual: \ \&
7 .\"    Source: \ \&
8 .\"  Language: English
9 .\"
10 .TH "RESOLV_WRAPPER" "1" "2020\-01\-31" "\ \&" "\ \&"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 resolv_wrapper \- A wrapper for dns name resolving or dns faking\&.
32 .SH "SYNOPSIS"
33 .sp
34 LD_PRELOAD=libresolv_wrapper\&.so RESOLV_WRAPPER_CONF="/path/to/resolv\&.conf" \fB\&./myapplication\fR
35 .SH "DESCRIPTION"
36 .sp
37 resolv_wrapper makes it possible on most UNIX platforms to contact your own DNS implementation in your test environment\&. It requires socket_wrapper to be able to contact it\&. If it doesn\(cqt work on a special platform the wrapper is able to fake DNS queries and return valid responses to your application\&.
38 .sp
39 .RS 4
40 .ie n \{\
41 \h'-04'\(bu\h'+03'\c
42 .\}
43 .el \{\
44 .sp -1
45 .IP \(bu 2.3
46 .\}
47 Redirects name queries to the nameservers specified in your resolv\&.conf
48 .RE
49 .sp
50 .RS 4
51 .ie n \{\
52 \h'-04'\(bu\h'+03'\c
53 .\}
54 .el \{\
55 .sp -1
56 .IP \(bu 2.3
57 .\}
58 Can fake DNS queries using a simple formatted DNS hosts file\&.
59 .RE
60 .SH "ENVIRONMENT VARIABLES"
61 .PP
62 \fBRESOLV_WRAPPER_CONF\fR
63 .RS 4
64 This is used to specify the resolv\&.conf to use\&. The format of the resolv\&.conf file is defined in the manpage
65 \fIresolv\&.conf(5)\fR\&. Currently only the
66 \fBnamserver\fR
67 directive is supported\&.
68 .RE
69 .PP
70 \fBRESOLV_WRAPPER_HOSTS\fR
71 .RS 4
72 This environment variable is used for faking DNS queries\&. It must point to a hosts\-like text file that specifies fake records for custom queries\&. The format of the file looks like this:
73 .sp
74 .if n \{\
75 .RS 4
76 .\}
77 .nf
78 TYPE    RECORD_NAME RECORD_VALUE
79 .fi
80 .if n \{\
81 .RE
82 .\}
83 .RE
84 .sp
85 For example:
86 .sp
87 .if n \{\
88 .RS 4
89 .\}
90 .nf
91 A       dc\&.cwrap\&.org 127\&.0\&.0\&.10
92 AAAA    dc\&.cwrap\&.org fd00::5357:5f0a
93 CNAME   kerberos\&.cwrap\&.org dc\&.cwrap\&.org
94 SRV     _kerberos\&._tcp\&.cwrap\&.org kerberos\&.cwrap\&.org 88
95 URI     _vpn\&.cwrap\&.org https://vpn\&.cwrap\&.org/VPN
96 TXT     cwrap\&.org v=spf1 mx
97 .fi
98 .if n \{\
99 .RE
100 .\}
101 .PP
102 \fBRESOLV_WRAPPER_DEBUGLEVEL\fR
103 .RS 4
104 If you need to see what is going on in resolv_wrapper itself or try to find a bug, you can enable logging support in resolv_wrapper if you built it with debug symbols\&.
105 .sp
106 .RS 4
107 .ie n \{\
108 \h'-04'\(bu\h'+03'\c
109 .\}
110 .el \{\
111 .sp -1
112 .IP \(bu 2.3
113 .\}
114 0 = ERROR
115 .RE
116 .sp
117 .RS 4
118 .ie n \{\
119 \h'-04'\(bu\h'+03'\c
120 .\}
121 .el \{\
122 .sp -1
123 .IP \(bu 2.3
124 .\}
125 1 = WARNING
126 .RE
127 .sp
128 .RS 4
129 .ie n \{\
130 \h'-04'\(bu\h'+03'\c
131 .\}
132 .el \{\
133 .sp -1
134 .IP \(bu 2.3
135 .\}
136 2 = DEBUG
137 .RE
138 .sp
139 .RS 4
140 .ie n \{\
141 \h'-04'\(bu\h'+03'\c
142 .\}
143 .el \{\
144 .sp -1
145 .IP \(bu 2.3
146 .\}
147 3 = TRACE
148 .RE
149 .RE
150 .PP
151 \fBRESOLV_WRAPPER_DISABLE_DEEPBIND\fR
152 .RS 4
153 This allows you to disable deep binding in resolv_wrapper\&. This is useful for running valgrind tools or sanitizers like (address, undefined, thread)\&.
154 .RE
155 .SH "EXAMPLE"
156 .sp
157 The following command would trick \fIkinit(1)\fR into using DNS servers from "\&./resolv\&.conf" for Kerberos service resolution:
158 .sp
159 .if n \{\
160 .RS 4
161 .\}
162 .nf
163 $ LD_PRELOAD=libresolv_wrapper\&.so RESOLV_WRAPPER_CONF="\&./resolv\&.conf" kinit user@EXAMPLE\&.COM
164 .fi
165 .if n \{\
166 .RE
167 .\}
168 .SH "AUTHOR"
169 .PP
170 \fBThe Samba Team\fR
171 .RS 4
172 Author.
173 .RE