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.179
1 files changed, 28 insertions, 51 deletions
diff --git a/doc/man/gnunet-zoneimport.1 b/doc/man/gnunet-zoneimport.1
index fcd3ee630..b549ffcf4 100644
--- a/doc/man/gnunet-zoneimport.1
+++ b/doc/man/gnunet-zoneimport.1
@@ -26,66 +26,45 @@
26gnunet\-zoneimport \- import DNS zone into GNS zone 26gnunet\-zoneimport \- import DNS zone into GNS zone
27.SH SYNOPSIS 27.SH SYNOPSIS
28.B gnunet\-zoneimport 28.B gnunet\-zoneimport
29.RI [-h]
30.RI [-c\ FILENAME\ |\ --config=FILENAME] 29.RI [-c\ FILENAME\ |\ --config=FILENAME]
30.RI [-h\ |\ --help]
31.RI [-m\ RELATIVETIME\ |\ --minimum-expiration=RELATIVETIME] 31.RI [-m\ RELATIVETIME\ |\ --minimum-expiration=RELATIVETIME]
32.RI [-s\ MAPSIZE\ |\ --size=MAPSIZE] 32.RI [-s\ MAPSIZE\ |\ --size=MAPSIZE]
33[IP]+ 33[IP]+
34.SH DESCRIPTION 34.SH DESCRIPTION
35\fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from 35\fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from stdin and issues DNS queries for each of the domain names given.
36stdin and issues DNS queries for each of the domain names given. It 36It then checks if a local ego with a name matching the domain exists.
37then checks if a local ego with a name matching the domain 37Specifically, 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").
38exists. Specifically, if the domain name is "example.fr", it will 38If 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).
39check if an ego "fr" exists, while for a domain "example.com.fr" it
40will look for an ego called "com.fr"). If so, it will convert the DNS
41records into GNS records (in particular converting NS records and glue
42records to GNS2DNS records) and add them to the namestore under the
43label ("example" in the examples above).
44.PP 39.PP
45The arguments given to gnunet\-zoneimport is a list of IP addresses of 40The arguments given to gnunet\-zoneimport is a list of IP addresses of DNS servers to query.
46DNS servers to query.
47.PP 41.PP
48gnunet\-zoneimport will usually never terminate: it will check when 42gnunet\-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.
49DNS records expire, and re-issue requests when the old DNS records
50have expired so that GNS always has the latest data.
51.PP 43.PP
52gnunet\-zoneimport will issue many DNS queries in parallel, but is 44gnunet\-zoneimport will issue many DNS queries in parallel, but is rate-limited in various ways, so most DNS servers should easily handle the load.
53rate-limited in various ways, so most DNS servers should easily handle 45gnunet\-zoneimport will perform a limited number of retries if queries fail.
54the load. gnunet\-zoneimport will perform a limited number of retries
55if queries fail.
56.PP 46.PP
57gnunet\-zoneimport operates incrementally. It will check if the 47gnunet\-zoneimport operates incrementally.
58namestore already has (non-expired) records stored for a given name in 48It 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.
59the respective zone and not issue those requests again. Thus, it is 49Thus, it is fine to restart gnunet\-zoneimport whenever the list of domain names changes.
60fine to restart gnunet\-zoneimport whenever the list of domain names
61changes.
62.PP 50.PP
63Finally, gnunet\-zoneimport keeps information for each domain name in 51Finally, gnunet\-zoneimport keeps information for each domain name in memory.
64memory. This consumes about 200 bytes per domain name, or 1 GB for 5 52This consumes about 200 bytes per domain name, or 1 GB for 5 million labels.
65million labels.
66.SH OPTIONS 53.SH OPTIONS
67.B 54.IP "\-c FILENAME\ | \-\-config=FILENAME"
68.IP "\-c FILENAME, \-\-config=FILENAME"
69Use the configuration file FILENAME. 55Use the configuration file FILENAME.
70.B 56.IP "\-h\ | \-\-help"
71.IP "\-h, \-\-help"
72Print short help on options. 57Print short help on options.
73.B 58.IP "\-m RELATIVETIME\ | \-\-minimum-expiration=RELATIVETIME"
74.IP "\-m RELATIVETIME, \-\-minimum-expiration=RELATIVETIME" 59Ensure that imported DNS records never have an expiration time that is less than RELATIVETIME into the future.
75.B 60RELATIVETIME is a time given like "1 week" or "1 h".
76Ensure that imported DNS records never have an expiration time that 61If 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).
77is less than RELATIVETIME into the future. RELATIVETIME is a time 62Default is zero.
78given like "1 week" or "1 h". If DNS returns records with a shorter 63.IP "\-s MAPSIZE\ | \-\-size=MAPSIZE"
79lifetime, gnunet\-zoneimport will simply bump the lifetime to the 64Specifies the size (in number of entries) to use for the main hash map.
80specified value (relative to the time of the import). Default is zero. 65The value provided should be at least twice the number of domain names that will be given to the tool.
81.IP "\-s MAPSIZE, \-\-size=MAPSIZE" 66This 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).
82Specifies the size (in number of entries) to use for the main hash 67Do not worry about this unless you are importing millions of domain names from a zone.
83map. The value provided should be at least twice the number of domain
84names that will be given to the tool. This option is required for very
85large zones where the number of records encountered is too large for
86the automatic growth mechanism to work (that one is limited to at most
8716 MB allocations for security reasons). Do not worry about this
88unless you are importing millions of domain names from a zone.
89.SH EXAMPLES 68.SH EXAMPLES
90.TP 69.TP
91Typical invocaton would be: 70Typical invocaton would be:
@@ -110,9 +89,7 @@ should give you access to the complete handbook,
110.PP 89.PP
111will give you access to a tutorial for developers. 90will give you access to a tutorial for developers.
112.PP 91.PP
113Depending on your installation, this information is also 92Depending on your installation, this information is also available in
114available in
115\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7). 93\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7).
116.SH BUGS 94.SH BUGS
117Report bugs by using Mantis <https://bugs.gnunet.org/> or by sending 95Report bugs by using Mantis <https://bugs.gnunet.org/> or by sending electronic mail to <gnunet\-developers@gnu.org>.
118electronic mail to <gnunet\-developers@gnu.org>