aboutsummaryrefslogtreecommitdiff
path: root/doc/man/gnunet-namestore.1
blob: 6915aed6e80270c2dbf56bc2d1e48774d95dfe86 (plain) (blame)
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
.\" This file is part of GNUnet.
.\" Copyright (C) 2001-2022 GNUnet e.V.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
.\" copy of the license is included in the file
.\" FDL-1.3.
.\"
.\" A copy of the license is also available from the Free Software
.\" Foundation Web site at http://www.gnu.org/licenses/fdl.html}.
.\"
.\" Alternately, this document is also available under the General
.\" Public License, version 3 or later, as published by the Free Software
.\" Foundation.  A copy of the license is included in the file
.\" GPL3.
.\"
.\" A copy of the license is also available from the Free Software
.\" Foundation Web site at http://www.gnu.org/licenses/gpl.html
.\"
.\" SPDX-License-Identifier: GPL3.0-or-later OR FDL1.3-or-later
.\"
.Dd April 15, 2014
.Dt GNUNET-NAMESTORE 1
.Os
.Sh NAME
.Nm gnunet-namestore
.Nd manipulate GNU Name System (GNS) zone data
.Sh SYNOPSIS
.Nm
.Op Fl a | -add
.Op Fl c Ar FILENAME | Fl -config= Ns Ar FILENAME
.Op Fl d | -delete
.Op Fl D | -display
.Op Fl e Ar TIME | Fl -expiration= Ns Ar TIME
.Op Fl h | -help
.Op Fl i Ar NICKNAME | Fl -nick= Ns Ar NICKNAME
.Op Fl L Ar LOGLEVEL | Fl -loglevel= Ns Ar LOGLEVEL
.Op Fl m | -monitor
.Op Fl n Ar NAME | Fl -name= Ns Ar NAME
.Op Fl O | -list-orphans
.Op Fl o | -omit-private
.Op Fl P | -purge-orphans
.Op Fl p | -public
.Op Fl s | -shadow
.Op Fl S | -from-stdin
.Op Fl T | -include-maintenance
.Op Fl t Ar TYPE | Fl -type= Ns Ar TYPE
.Op Fl u Ar URI | Fl -uri= Ns Ar URI
.Op Fl v | -version
.Op Fl V Ar VALUE | Fl -value= Ns Ar VALUE
.Op Fl X | -purge-zone-records
.Op Fl z Ar EGO | Fl -zone= Ns Ar EGO
.Op Fl Z Ar KEY | Fl -zone-to-name= Ns Ar KEY
.Sh DESCRIPTION
.Nm
can be used to manipulate records in a GNS zone.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl a | -add
Desired operation is adding a record.
.It Fl c Ar FILENAME | Fl -config= Ns Ar FILENAME
Use the configuration file FILENAME.
.It Fl d | -delete
Desired operation is deleting records under the given name that match
the specified type (-t) and value (-V).
If type or value are not specified, it means that all types (or
values) should be assumed to match (and possibly multiple or all
values under the given label will be deleted).
Specifying a label (-n) is mandatory.
Note that matching by expiration time or flags is (currently) not
supported.
.It Fl D | -display
Desired operation is listing of matching records.
.It Fl e Ar TIME | Fl -expiration= Ns Ar TIME
Specifies expiration time of record to add; format is relative time,
i.e "1 h" or "7 d 30 m".
Supported units are "ms", "s", "min" or "minutes", "h" (hours), "d"
(days) and "a" (years).
.It Fl h | -help
Print short help on options.
.It Fl i Ar NICKNAME | Fl -nick= Ns Ar NICKNAME
Set the desired NICKNAME for the zone.
The nickname will be included in all (public) records and used as the
suggested name for this zone.
.It Fl L Ar LOGLEVEL | Fl -loglevel= Ns Ar LOGLEVEL
Use LOGLEVEL for logging.
Valid values are DEBUG, INFO, WARNING and ERROR.
.It Fl m | -monitor
Monitor changes to the zone on an ongoing basis (in contrast to -D,
which merely displays the current records).
.It Fl n Ar NAME | Fl -name= Ns Ar NAME
Label or name of the record to add/delete/display.
.It Fl O | -list-orphans
List orphaned records.
.It Fl o | -omit-private
Filter private records. Use in combination with --display.
.It Fl P | -purge-orphans
Delete orphaned records from namestore.
.It Fl p | -public
Create a record that is public (shared with other users that know the
label).
.It Fl r | -recordline
Changes the output format of zones and records to recordline.
.It Fl s | -shadow
Create a record that is a shadow record.
Shadow records are only used once all other records of the same type
under the same label have expired.
.It Fl S | -from-stdin
Read recordlines from stdin until EOF is encountered.
The format uses
.B recordlines
:
A record in a recordline follows the format

NAME.EGO:
 TYPE EXPIRATION [FLAGS] VALUE
 ...
Multiple records may be provided for a name.

EXPIRATION is given in microseconds without a unit (e.g. 3600000000 for 3600 seconds).

FLAGS is a concatenation of record flags.
Possible values for flags and their meaning are:
.Pp
  p: Public
  s: Shadow
  S: Supplemental
  C: Critical
  r: Relative expiration

TYPE and VALUE are used in the same way as for the "-t" and "-V" options.
Example formats for recordlines can be output using the "-D" flag combined
with "--recordline".
An example record set in recordline format can be found in the examples.
It is possible to specify multiple record sets.
Can only be used in combination with "-a" to add the parsed record sets.
Existing record sets under names will be replaced.
.It Fl T | -include-maintenance
Show maintenance records such as TOMBSTONEs. Use in combination with --display.
.It Fl t Ar TYPE | Fl -type= Ns Ar TYPE
Type of the record to add/delete/display ("A"; "AAAA"; "NS"; "PKEY"; "MX"; etc.).
.It Fl u Ar URI | Fl -uri= Ns Ar URI
Add PKEY record from gnunet://gns/-URI to our zone; the record type is
always PKEY, if no expiration is given FOREVER is used
.It Fl v | -version
Print GNUnet version number.
.It Fl V Ar VALUE | Fl -value= Ns Ar VALUE
Value to store or remove from the GNS zone.
Specific format depends on the record type.
A records expect a dotted decimal IPv4 address, AAAA records an IPv6
address, PKEY a public key in GNUnet's printable format, and CNAME and
NS records should be a domain name.
.It Fl X | -purge-zone-records
Delete all records in a zone.
.It Fl z Ar EGO | Fl -zone= Ns Ar EGO
Specifies the name of the ego controlling the private key for the
zone. If not provided, we will attempt to use the default identity set
for the "namestore". Alternatively, a private key may be passed in
Base32-encoding using the GNUNET_NAMESTORE_EGO_PRIVATE_KEY environment
variable. The latter is useful to improve performance of tools like
Ascension as it allows the command to skip IPC with the identity
management subsystem.
.It Fl Z Ar KEY | Fl -zone-to-name= Ns Ar KEY
Determine our GNS name for the given public key (reverse lookup of the
KEY) in the given zone.
.El
.Sh EXAMPLES
.Tp
.Nm
-z example -a -n www -t A -V "1.2.3.4" -e 1d -p
.Tp
.Pp
.Dl Add a public record for ego "example" with name "www" containing an IP address.
.sp
.Tp
.Nm
-z example -D
.Tp
.Pp
.Dl Show all records for ego "example".
.sp
.Tp
.Nm
-z example -D -r
.Tp
.Pp
.Dl Show all records for ego "example" in recordline format.
.sp
.Tp
.Nm
--add --from-stdin <<EOF
 www.alice:
  A 3600000000 [pr] 1.2.3.4
  TXT 3600000001 [pr] Hello World

 www.bob:
  A 12345679000000 [pr] 4.3.2.1
 EOF
.Tp
.Pp
.Dl Read record sets in recordline format from stdin.
.\".Sh FILES
.Sh SEE ALSO
.Xr gnunet-gns 1 ,
.Xr gnunet-namestore-gtk 1
.sp
The full documentation for GNUnet is maintained as a Texinfo manual.
If the
.Xr info 1
and gnunet programs are properly installed at your site, the command
.Pp
.Dl info gnunet
.Pp
should give you access to the complete handbook,
.Pp
.Dl info gnunet-c-tutorial
.Pp
will give you access to a tutorial for developers.
.sp
Depending on your installation, this information is also available in
.Xr gnunet 7 and
.Xr gnunet-c-tutorial 7 .
.\".Sh HISTORY
.\".Sh AUTHORS
.Sh BUGS
Report bugs by using
.Lk https://bugs.gnunet.org
or by sending electronic mail to
.Aq Mt gnunet-developers@gnu.org .