1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<!-- $Id: mdnsproxy.html,v 1.4 2001/10/23 06:04:15 miyayama Exp $ -->
<html lang="ja">
<head>
<title>mdnsproxy specification</title>
<meta http-equiv="Content-Type" content="text/html; charset=Shift_JIS">
<link rev="made" href="mailto:idn-cmt@nic.ad.jp">
<link rel="stylesheet" type="text/css" href="spec.css">
</head>
<body>
<h1>mdnsproxy</h1>
<!-- =========================================================== -->
<hr>
<h2><a name="overview">Overview</a></h2>
<p>
mnsproxy receives DNS requests including local code-based multilingual domain names from the client and converts them to domain names that can be accepted by the multilingualized DNS. In reverse, it returns multilingual domain names included in responses from the DNS to a format that can be recognized by the client side.
</p>
<p>
Because of this, without modification, the client can use various multilingual domain names.
From the DNS server's point of view, because of client + mdnsproxy, the client operates as if it supports multilingual domain names.
</p>
<p>
However, in order for mdnsproxy to operate correctly, it is necessary for the resolver library of the client to transmit domain names in local encoding as is and does not cause an error. Regretably, many current UNIX resolver libraries are not 8-bit through and they cannot support multilingual domain names even when mdnsproxy is used. In such cases, it is necessary to use the following methods.
</p>
<p>
Use resolver library for which <a href="spec.html#eightbitthru-patch">8-bit through patch of BIND 8</a> is applied.
<!-- Instead of mdnsproxy, use runmdn or BIND-9 patch. -->
</p>
<p>
In addition, since mdnsproxy ignores <a href="resolvconfig.html#mdn_disable">the setting of the environment variable MDN_DISABLE</a> explicitly ,in spite of whether the environment variable MDN_DISABLE is set or not, the conversion of the domain names is performed.
</p>
<!-- =========================================================== -->
<hr>
<h2><a name="invoke">Invoke</a></h2>
<p>
The command line format used to start up mdnsproxy is as follows.
</p>
<blockquote>
<p>
<code>$ mdnsproxy</code> [<var>Option...</var>]
</p>
</blockquote>
<!-- =========================================================== -->
<hr>
<h2><a name="options">Options</a></h2>
<p>
mdnsproxy recognizes the following command line options.
</p>
<dl>
<dt><a name="opt-daemon"><code>-daemon</code></a>
<dd>Activates mdnsproxy as a daemon.
<dt><a name="opt-config"><code>-config</code> <var>config-file</var></a>
<dd>Indicates the configuration file. When the command line does is not used to indicate a configuration file, the default configuration file is used. The details of this are explained in the <a href="#config-file">Configuration file</a>.
<dt><a name="opt-logfile"><code>-logfile</code> <var>log-file</var></a>
<dd>Specifies the file name for mdnsproxy to output the execution log. Unless otherwise specified, the execution log is output to the log file specified by the configuration file or the default log file.
</dl>
<!-- =========================================================== -->
<hr>
<h2><a name="config-file">Configuration file</a></h2>
<p>
mdnsproxy configuration information is written in the configuration file. The configuration file can be specified using a command line upon activation of mdnsproxy.
</p>
<blockquote>
<pre>
<code>% mdnsproxy -config</code> <var><config-file></var>
</pre>
</blockquote>
<p>
When the configuration file is not specified by the command line, the default configuration file is used. The default configuration file is <code>/usr/local/etc/mdnsproxy.conf</code> if mDNkit were installed under <code>/usr/local</code>.
</p>
<p>
The configuration file is a plain text file and each line of the file (except comment lines that begin with # and blank line) consists of the following simple format.
</p>
<blockquote>
<pre>
Keyword value ...
</pre>
</blockquote>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="listen"><code>listen</code></a></h3>
<p>
Specifies the network address and port number used by mdnsproxy to receive requests from the client.
</p>
<blockquote>
<p>
<code>listen</code> <var><address></var>
</p>
</blockquote>
<p>
<var><address></var> is specified using one of the following formats.
</p>
<blockquote>
<table summary="<address> format">
<tr><td><var><IP address></var>:<var><port number></var></td></tr>
<tr><td><var>:<port number></var></td></tr>
<tr><td><var><IP address></var></td></tr>
</table>
</blockquote>
<p>
When <var><IP address></var> is omitted, <code>0.0.0.0</code>
(<code>INADDR_ANY</code>) is used and when <var><port number></var> is omitted, port number 53 is used.
When <code>listen</code> itself is omitted, <code>0.0.0.0:53</code> is used as <var><address></var>.
</p>
<p>
If the client uses a DNS server via mdnsproxy, set the address and port specified here as the DNS server. Many clients cannot change the port number, thus it is recommended that default port number 53 be used as is.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="forward"><code>forward</code></a></h3>
<p>
Specifies the original network address and port number of the DNS server used by mdnsproxy to transfer DNS requests and receive responses.
</p>
<blockquote>
<p>
<code>forward</code> <var><address></var> [ <code>bind4compat</code> ]
</p>
</blockquote>
<p>
The format of <var><address></var> is the same as the one for the above <a href="#listen"><code>listen</code></a>.
</p>
<p>
When <code>bind4compat</code> option is specified, the address and port specified by <code>listen</code> as the source address is used. This is a function of BIND 4 and it is assumed that UDP port is used under limited access. If this option is not specified, 1024 or greater source port is used.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="client-encoding"><code>client-encoding</code></a></h3>
<p>
Specifies the encoding of domain names at the client side.
</p>
<blockquote>
<p>
<code>client-encoding</code> <var><Encoding></var>
</p>
</blockquote>
<p>
The encoding of domain names in the DNS query sent by the client is converted to UTF-8 encoding that is used internally. Then normalization (described below) and conversion to server side encoding are performed after which the data is sent to the DNS server. The response from the DNS server is converted back to the original encoding and returned to the client.
</p>
<p>
The encoding names that can be used here depend on libmdn of mDNkit and iconv library to be used.
Since the encoding name used differs with the iconv library that is employed, check the library manual to confirm the encoding names that can be used. In addition to the encoding provided by iconv, libdmn supports the following encoding schemes recommended for multilingual DNS. <br>
The following encoding schemes are supported.
</p>
<blockquote>
<table summary="Encoding for multilingual DNS">
<tr><td>Punycode</td>
<td><a href="../../reference/draft/draft-ietf-idn-punycode-00.txt">draft-ietf-idn-punycode-00.txt</a></td>
</tr>
<tr><td>RACE</td>
<td><a href="../../reference/draft/draft-ietf-idn-race-03.txt">draft-ietf-idn-race-03.txt</a></td>
</tr>
<tr><td>DUDE</td>
<td><a href="../../reference/draft/draft-ietf-idn-dude-02.txt">draft-ietf-idn-dude-02.txt</a></td>
</tr>
</table>
</blockquote>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="mdn-conf-file"><code>mdn-conf-file</code></a></h3>
<p>
Specifies the configuration file names of libmdn attached to mDNkit.
</p>
<blockquote>
<p>
<code>mdn-conf-file</code> <var><path></var>
</p>
</blockquote>
<p>
mdnsproxy uses libmdn attched to mDNkit to perform multilingual domain-related processing. <code>mdn-conf-file</code> is used to specify the file name of the libmdn configuration file.
</p>
<p>
The file name can be specified by <code>-conf</code> command line option. When both are specifed, the command line operation specification takes precedence. If neither are not specified, the configuration file is loaded from <code>/usr/local/etc/mdn.conf</code>.
</p>
<p>
For information on how to describe the libmdn configuration file, refer to <a href="../guide/resolvconfig.html">Configuration of mDNkit</a>.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="log-file"><code>log-file</code></a></h3>
<p>
Specifies the file name for mdnsproxy to output the execution log.
</p>
<blockquote>
<p>
<code>log-file</code> <var><path></var>
</p>
</blockquote>
<p>
The log file name can also be specified with the <code>-logfile</code> command line option. When both are specified, the command line option specification takes precedence.When neither are specified, the execution log is output to <code>/usr/local/var/mdnsproxy/mdnsproxy.log</code>.
</p>
<p>
Note that the execution log is added to continuously and should be deleted from time to time. When a hangup signal (SIGHUP) is sent to mdnsproxy, it temporarily closes the log file and then reopens it. This is a convenient command when the log file is to be archived.
</p>
<p>
When <code>syslog</code> is specified as <var><path></var>, log is output for syslog. When <code>stderr</code> is specified, log is output for standard error output.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="log-level"><code>log-level</code></a></h3>
<p>
Sets the log level.
</p>
<blockquote>
<p>
<code>log-level</code> <var><level></var>
</p>
</blockquote>
<p>
The following log level values can be specified.
</p>
<blockquote>
<dl>
<dt><code>none</code>
<dd>No log is recorded. The absence of a log file makes it very difficult to identify the cause of a problem. If at all possible avoid using this level.
<dt><code>fatal</code>
<dd>Outputs a log only when a fatal error occurs.
<dt><code>warn</code>
<dd>Records warning messages in the log. This is the default used when no log level is specified.
<dt><code>trace</code>
<dd>Outputs execution trace messages in the log. This level provides a detailed record of dnsproxy operation, which is helpful in determining the cause of a problem. As it records a large amount of data, it is best not used during normal operation.
</dl>
</blockquote>
<p>
When syslog is used to output logs, a fatal error message is output in priority ERR of syslog. In the same way, a warning level error message is output in priority WARNING and a trace message is output in priority DEBUG.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="mdn-log-level"><code>mdn-log-level</code></a></h3>
<p>
Sets the log level of libmdn.
</p>
<blockquote>
<p>
<code>mdn-log-level</code> <var><level></var>
</p>
</blockquote>
<p>
mdnsproxy uses libmdn attched to mDNkit to perform multilingual domain-related processing. <code>mdn-conf-file</code> is used to specify the file name of the libmdn configuration file, <code>mdn-log-level</code> is used to set the log related to internal processing of libmdn, and <a href="#log-level"><code>log-level</code></a> is used to set processing parts other than the above.
</p>
<p>
The following five log levels are defined.
</p>
<blockquote>
<ul>
<li><code>fatal</code> (= 0)
<li><code>error</code> (= 1)
<li><code>warning</code> (= 2)
<li><code>info</code> (= 3)
<li><code>trace</code> (= 4)
<li><code>dump</code> (= 5)
</ul>
</blockquote>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="syslog-facility"><code>syslog-facility</code></a></h3>
<p>
Sets syslog facility.
</p>
<blockquote>
<p>
<code>syslog-facility</code> <var><facility></var>
</p>
</blockquote>
<p>
The facility used when the log is output using syslog. When the log is not output using syslog, it is ignored. (To output a log using syslog, it is necessary to specify with <a href="#log-file"><code>log-file</code></a> or <code>-logfile</code> command line option.) When it is omitted, a <code>daemon</code> is used.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="user-id"><code>user-id</code></a></h3>
<p>
Specifies process owner's user id of mdnsproxy.
</p>
<blockquote>
<p>
<code>user-id</code> <var><user></var>
</p>
</blockquote>
<p>
Normally, mdnsproxy must be started up with root permission to use a privileged port, but continued use of root permission is not recommended for security reasons. With this specification, mdnsproxy runs under the specified user's control with a created privileged port before start of service.
</p>
<p>
var><user></var> allows you to specify user name or user ID number.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="group-id"><code>group-id</code></a></h3>
<p>
Specifies process owner's user id of mdnsproxy.
</p>
<blockquote>
<p>
<code>group-id</code> <var><group></var>
</p>
</blockquote>
<p>
This resembles the <code>user-id</code> entry, but differs from it in that it specifies a group in place of the user.
</p>
<p>
<var><group></var> can be specified by a group name or group ID number.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="root-directory"><code>root-directory</code></a></h3>
<p>
Specifies the root directory used with mdnsproxy.
</p>
<blockquote>
<p>
<code>root-directory</code> <var><path></var>
</p>
</blockquote>
<p>
This, also, is a security measure. By specifying the root directory used with mdnsproxy access cannot be made outside of this directory. This specification causes mdnsproxy to use chroot() system calls to set the specified directory as the root directory before starting service.
</p>
<p>
<var><path></var> specifies the name of the directory to be used as the root.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="allow-access"><code>allow-access</code></a></h3>
<p>
Sets the access restriction based on the IP address of clients to limit which clients have access to mdnsproxy.
</p>
<blockquote>
<p>
<code>allow-acccess</code> <var><where></var> ...
</p>
</blockquote>
<p>
<var><where></var> is specified using one of the following formats.
</p>
<blockquote>
<table summary="<where> format">
<tr><td><var><IP address></var></td></tr>
<tr><td><var><IP address></var>/<var><prefix-length></var></td></tr>
</table>
</blockquote>
<p>
The first one permits access from a host with a specific IP address. The latter permits access from hosts that has an address prefix specified by <var><IP address></var> and <var><prefix-length></var>. For example, when the following is specified,
</p>
<blockquote>
<p>
<code>allow-access 192.168.0.0/16</code>
</p>
</blockquote>
<p>
access is permitted from hosts whose upper 16 bits of address (prefix) is 192.168.
</p>
<p>
More than one entry can be specified. When more than one entry is specified, access is permitted if one of them matches.
</p>
<p>
When this entry is not specified, access from all hosts is permitted.
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="log-on-denied"><code>log-on-denied</code></a></h3>
<p>
When a connection is rejected by the access restriction set in <a href="#allow-access"><code>allow-access</code></a>, whether it is recorded in the log is specified.
</p>
<blockquote>
<p>
<code>log-on-denied</code> <var><yes-or-no></var>
</p>
</blockquote>
<p>
<code>yes</code> or <code>no</code> can be specified. When yes is specified, the rejected connection is recorded in the log. If not, it is not recorded in the log.
</p>
<!-- =========================================================== -->
<hr>
<h2><a name="signal">Signal</a></h2>
<p>
When a hangup signal (SIGHUP) is sent to mdnsproxy, it temporarily closes the log file and then reopens it. This is to archive the log using the following steps.
<ol>
<li>Use the <code>mv</code> command to create a log file under a different name.
<li>Send SIGHUP to mdnsproxy to open the new log file.
</ol>
</body>
</html>
|
