aboutsummaryrefslogtreecommitdiff
path: root/doc/man/gnunet-zoneimport.1
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/gnunet-zoneimport.1')
-rw-r--r--doc/man/gnunet-zoneimport.1184
1 files changed, 100 insertions, 84 deletions
diff --git a/doc/man/gnunet-zoneimport.1 b/doc/man/gnunet-zoneimport.1
index 2a67718f9..e99b235b8 100644
--- a/doc/man/gnunet-zoneimport.1
+++ b/doc/man/gnunet-zoneimport.1
@@ -1,90 +1,106 @@
1.TH GNUNET-ZONEIMPORT 1 "April 23, 2018" "GNUnet" 1.\" This file is part of GNUnet.
2.SH NAME 2.\" Copyright (C) 2018, 2019 GNUnet e.V.
3gnunet\-zoneimport \- import DNS zone into GNS zone 3.\"
4.SH SYNOPSIS 4.\" Permission is granted to copy, distribute and/or modify this document
5.B gnunet\-zoneimport [IP]+ 5.\" under the terms of the GNU Free Documentation License, Version 1.3 or
6.SH DESCRIPTION 6.\" any later version published by the Free Software Foundation; with no
7\fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from 7.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
8stdin and issues DNS queries for each of the domain names given. It 8.\" copy of the license is included in the file
9then checks if a local ego with a name matching the domain 9.\" ``FDL-1.3''.
10exists. Specifically, if the domain name is "example.fr", it will 10.\"
11check if an ego "fr" exists, while for a domain "example.com.fr" it 11.\" A copy of the license is also available from the Free Software
12will look for an ego called "com.fr"). If so, it will convert the DNS 12.\" Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.
13records into GNS records (in particular converting NS records and glue 13.\"
14records to GNS2DNS records) and add them to the namestore under the 14.\" Alternately, this document is also available under the General
15label ("example" in the examples above). 15.\" Public License, version 3 or later, as published by the Free Software
16.PP 16.\" Foundation. A copy of the license is included in the file
17The arguments given to gnunet\-zoneimport is a list of IP addresses of 17.\" ``GPL3''.
18DNS servers to query. 18.\"
19.PP 19.\" A copy of the license is also available from the Free Software
20gnunet\-zoneimport will usually never terminate: it will check when 20.\" Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}.
21DNS records expire, and re-issue requests when the old DNS records 21.\"
22have expired so that GNS always has the latest data. 22.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later
23.PP 23.\"
24gnunet\-zoneimport will issue many DNS queries in parallel, but is 24.Dd April 23, 2018
25rate-limited in various ways, so most DNS servers should easily handle 25.Dt GNUNET-ZONEIMPORT 1
26the load. gnunet\-zoneimport will perform a limited number of retries 26.Os
27if queries fail. 27.Sh NAME
28.PP 28.Nm gnunet-zoneimport
29gnunet\-zoneimport operates incrementally. It will check if the 29.Nd
30namestore already has (non-expired) records stored for a given name in 30import DNS zone into GNS zone
31the respective zone and not issue those requests again. Thus, it is 31.Sh SYNOPSIS
32fine to restart gnunet\-zoneimport whenever the list of domain names 32.Nm
33changes. 33.Op Fl c Ar FILENAME | \-config= Ns Ar FILENAME
34.PP 34.Op Fl h | \-help
35Finally, gnunet\-zoneimport keeps information for each domain name in 35.Op Fl m Ar RELATIVETIME | Fl \-minimum-expiration= Ns Ar RELATIVETIME
36memory. This consumes about 200 bytes per domain name, or 1 GB for 5 36.Op Fl s Ar MAPSIZE | Fl \-size= Ns Ar MAPSIZE
37million labels. 37.Op Ar \IP
38.SH OPTIONS 38.Sh DESCRIPTION
39.B 39.Nm
40.IP "\-c FILENAME, \-\-config=FILENAME" 40reads a list of domain names (FQDN) from stdin and issues DNS queries for each of the domain names given.
41It then checks if a local ego with a name matching the domain exists.
42Specifically, if the domain name is "example.fr", it will check if an ego "fr" exists, while for a domain "example.com.fr" it will look for an ego called "com.fr").
43If so, it will convert the DNS records into GNS records (in particular converting NS records and glue records to GNS2DNS records) and add them to the namestore under the label ("example" in the examples above).
44.Pp
45The arguments given to gnunet-zoneimport is a list of IP addresses of DNS servers to query.
46.Pp
47gnunet-zoneimport will usually never terminate: it will check when DNS records expire, and re-issue requests when the old DNS records have expired so that GNS always has the latest data.
48.Pp
49gnunet-zoneimport will issue many DNS queries in parallel, but is rate-limited in various ways, so most DNS servers should easily handle the load.
50gnunet-zoneimport will perform a limited number of retries if queries fail.
51.Pp
52gnunet-zoneimport operates incrementally.
53It will check if the namestore already has (non-expired) records stored for a given name in the respective zone and not issue those requests again.
54Thus, it is fine to restart gnunet-zoneimport whenever the list of domain names changes.
55.Pp
56Finally, gnunet-zoneimport keeps information for each domain name in memory.
57This consumes about 200 bytes per domain name, or 1 GB for 5 million labels.
58.Bl -tag -width Ds
59.It Fl c Ar FILENAME | \-config= Ns Ar FILENAME
41Use the configuration file FILENAME. 60Use the configuration file FILENAME.
42.B 61.It Fl h | \-help
43.IP "\-h, \-\-help"
44Print short help on options. 62Print short help on options.
45.B 63.It Fl m Ar RELATIVETIME | Fl \-minimum-expiration= Ns Ar RELATIVETIME
46.IP "\-m RELATIVETIME, \-\-minimum-expiration=RELATIVETIME" 64Ensure that imported DNS records never have an expiration time that is less than RELATIVETIME into the future.
47.B 65RELATIVETIME is a time given like "1 week" or "1 h".
48Ensure that imported DNS records never have an expiration time that 66If DNS returns records with a shorter lifetime, gnunet\-zoneimport will simply bump the lifetime to the specified value (relative to the time of the import).
49is less than RELATIVETIME into the future. RELATIVETIME is a time 67Default is zero.
50given like "1 week" or "1 h". If DNS returns records with a shorter 68.It Fl s Ar MAPSIZE | Fl \-size= Ns Ar MAPSIZE
51lifetime, gnunet\-zoneimport will simply bump the lifetime to the 69Specifies the size (in number of entries) to use for the main hash map.
52specified value (relative to the time of the import). Default is zero. 70The value provided should be at least twice the number of domain names that will be given to the tool.
53.IP "\-s MAPSIZE, \-\-size=MAPSIZE" 71This option is required for very large zones where the number of records encountered is too large for the automatic growth mechanism to work (that one is limited to at most 16 MB allocations for security reasons).
54Specifies the size (in number of entries) to use for the main hash 72Do not worry about this unless you are importing millions of domain names from a zone.
55map. The value provided should be at least twice the number of domain 73.It Ar \IP
56names that will be given to the tool. This option is required for very 74IP Is the list of IPs given.
57large zones where the number of records encountered is too large for 75.El
58the automatic growth mechanism to work (that one is limited to at most 76.Sh EXAMPLES
5916 MB allocations for security reasons). Do not worry about this
60unless you are importing millions of domain names from a zone.
61.SH NOTES
62.TP
63Typical invocaton would be: 77Typical invocaton would be:
64$ gnunet\-zoneimport 1.2.3.4 < names.txt 78.Pp
65.SH BUGS 79.Dl $ gnunet\-zoneimport 1.2.3.4 < names.txt
66Report bugs by using Mantis <https://bugs.gnunet.org/> or by sending 80.Sh SEE ALSO
67electronic mail to <gnunet\-developers@gnu.org> 81.Xr gnunet-gns 1 ,
68.SH SEE ALSO 82.Xr gnunet-namestore 1
69gnunet\-gns(1), gnunet\-namestore(1) 83.sp
70.PP 84The full documentation for gnunet is maintained as a Texinfo manual.
71The full documentation for
72.B gnunet
73is maintained as a Texinfo manual.
74If the 85If the
75.B info 86.Xr info 1
76and 87and gnunet programs are properly installed at your site, the command
77.B gnunet 88.Pp
78programs are properly installed at your site, the command 89.Dl info gnunet
79.IP 90.Pp
80.B info gnunet
81.PP
82should give you access to the complete handbook, 91should give you access to the complete handbook,
83.IP 92.Pp
84.B info gnunet-c-tutorial 93.Dl info gnunet-c-tutorial
85.PP 94.Pp
86will give you access to a tutorial for developers. 95will give you access to a tutorial for developers.
87.PP 96.sp
88Depending on your installation, this information is also 97Depending on your installation, this information is also available in
89available in 98.Xr gnunet 7 and
90\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). 99.Xr gnunet-c-tutorial 7 .
100.\".Sh HISTORY
101.\".Sh AUTHORS
102.Sh BUGS
103Report bugs by using
104.Lk https://bugs.gnunet.org
105or by sending electronic mail to
106.Aq Mt gnunet-developers@gnu.org .
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-18 18:40:43 +0000