aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/documentation/chapters/user.texi824
-rw-r--r--doc/documentation/gnunet.texi8
2 files changed, 423 insertions, 409 deletions
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
index 9c9bd8df8..7bb277421 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -20,232 +20,32 @@ always welcome.
20 20
21 21
22@menu 22@menu
23* Checking the Installation:: 23* Start and stop GNUnet::
24* First steps - File-sharing::
25* First steps - Using the GNU Name System:: 24* First steps - Using the GNU Name System::
26* First steps - Using GNUnet Conversation:: 25* First steps - Using GNUnet Conversation::
27* First steps - Using the GNUnet VPN:: 26* First steps - Using the GNUnet VPN::
28* File-sharing:: 27* File-sharing::
29* The GNU Name System:: 28* The GNU Name System::
30* Using the Virtual Public Network:: 29* Using the Virtual Public Network::
31* The graphical configuration interface:: 30* MOVE TO INSTALL The graphical configuration interface::
32* How to start and stop a GNUnet peer:: 31* MOVE TO INSTALL Checking the Installation::
32* MOVE TO INSTALL Config Leftovers::
33@end menu 33@end menu
34 34
35@node Checking the Installation 35@node Start and stop GNUnet
36@section Checking the Installation 36@section Start and stop GNUnet
37@c %**end of header
38
39This section describes a quick, casual way to check if your GNUnet
40installation works. However, if it does not, we do not cover
41steps for recovery --- for this, please study the instructions
42provided in the developer handbook as well as the system-specific
43instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}.
44
45
46@menu
47* gnunet-gtk::
48* Statistics::
49* Peer Information::
50@end menu
51
52@cindex GNUnet GTK
53@cindex GTK
54@cindex GTK user interface
55@node gnunet-gtk
56@subsection gnunet-gtk
57@c %**end of header
58
59The @command{gnunet-gtk} package contains several graphical
60user interfaces for the respective GNUnet applications.
61Currently these interfaces cover:
62 37
63@itemize @bullet 38To start GNUnet:
64@item Statistics
65@item Peer Information
66@item GNU Name System
67@item File Sharing
68@item Identity Management
69@item Conversation
70@end itemize
71
72@node Statistics
73@subsection Statistics
74@c %**end of header
75
76First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}.
77You can do this from the command-line by typing
78 39
79@example 40@example
80gnunet-statistics-gtk 41$ gnunet-arm -s -l gnunet.log
81@end example 42@end example
82 43
83If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.} 44To stop GNUnet:
84is running correctly, you should see a bunch of lines,
85all of which should be ``significantly'' above zero (at least if your
86peer has been running for more than a few seconds). The lines indicate
87how many other peers your peer is connected to (via different
88mechanisms) and how large the entire overlay network is currently
89estimated to be. The X-axis represents time (in seconds since the
90start of @command{gnunet-gtk}).
91
92You can click on "Traffic" to see information about the amount of
93bandwidth your peer has consumed, and on "Storage" to check the amount
94of storage available and used by your peer. Note that "Traffic" is
95plotted cumulatively, so you should see a strict upwards trend in the
96traffic.
97
98@node Peer Information
99@subsection Peer Information
100@c %**end of header
101
102First, you should launch the graphical user interface. You can do
103this from the command-line by typing
104 45
105@example 46@example
106$ gnunet-peerinfo-gtk 47$ gnunet-arm -e
107@end example 48@end example
108
109Once you have done this, you will see a list of known peers (by the
110first four characters of their public key), their friend status (all
111should be marked as not-friends initially), their connectivity (green
112is connected, red is disconnected), assigned bandwidth, country of
113origin (if determined) and address information. If hardly any peers
114are listed and/or if there are very few peers with a green light for
115connectivity, there is likely a problem with your network
116configuration.
117
118@node First steps - File-sharing
119@section First steps - File-sharing
120@c %**end of header
121
122This chapter describes first steps for file-sharing with GNUnet.
123To start, you should launch @command{gnunet-fs-gtk}.
124
125As we want to be sure that the network contains the data that we are
126looking for for testing, we need to begin by publishing a file.
127
128
129@menu
130* Publishing::
131* Searching::
132* Downloading::
133@end menu
134
135@node Publishing
136@subsection Publishing
137@c %**end of header
138
139To publish a file, select "File Sharing" in the menu bar just below the
140"Statistics" icon, and then select "Publish" from the menu.
141
142Afterwards, the following publishing dialog will appear:
143
144@c Add image here
145
146In this dialog, select the "Add File" button. This will open a
147file selection dialog:
148
149@c Add image here
150
151Now, you should select a file from your computer to be published on
152GNUnet. To see more of GNUnet's features later, you should pick a
153PNG or JPEG file this time. You can leave all of the other options
154in the dialog unchanged. Confirm your selection by pressing the "OK"
155button in the bottom right corner. Now, you will briefly see a
156"Messages..." dialog pop up, but most likely it will be too short for
157you to really read anything. That dialog is showing you progress
158information as GNUnet takes a first look at the selected file(s).
159For a normal image, this is virtually instant, but if you later
160import a larger directory you might be interested in the progress dialog
161and potential errors that might be encountered during processing.
162After the progress dialog automatically disappears, your file
163should now appear in the publishing dialog:
164
165@c Add image here
166
167Now, select the file (by clicking on the file name) and then click
168the "Edit" button. This will open the editing dialog:
169
170@c Add image here
171
172In this dialog, you can see many details about your file. In the
173top left area, you can see meta data extracted about the file,
174such as the original filename, the mimetype and the size of the image.
175In the top right, you should see a preview for the image
176(if GNU libextractor was installed correctly with the
177respective plugins). Note that if you do not see a preview, this
178is not a disaster, but you might still want to install more of
179GNU libextractor in the future. In the bottom left, the dialog contains
180a list of keywords. These are the keywords under which the file will be
181made available. The initial list will be based on the extracted meta data.
182Additional publishing options are in the right bottom corner. We will
183now add an additional keyword to the list of keywords. This is done by
184entering the keyword above the keyword list between the label "Keyword"
185and the "Add keyword" button. Enter "test" and select "Add keyword".
186Note that the keyword will appear at the bottom of the existing keyword
187list, so you might have to scroll down to see it. Afterwards, push the
188"OK" button at the bottom right of the dialog.
189
190You should now be back at the "Publish content on GNUnet" dialog. Select
191"Execute" in the bottom right to close the dialog and publish your file
192on GNUnet! Afterwards, you should see the main dialog with a new area
193showing the list of published files (or ongoing publishing operations
194with progress indicators):
195
196@c Add image here
197
198@node Searching
199@subsection Searching
200@c %**end of header
201
202Below the menu bar, there are four entry widges labeled "Namespace",
203"Keywords", "Anonymity" and "Mime-type" (from left to right). These
204widgets are used to control searching for files in GNUnet. Between the
205"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
206which is used to initiate the search. We will ignore the "Namespace",
207"Anonymity" and "Mime-type" options in this tutorial, please leave them
208empty. Instead, simply enter "test" under "Keywords" and press "Search".
209Afterwards, you should immediately see a new tab labeled after your
210search term, followed by the (current) number of search
211results --- "(15)" in our screenshot. Note that your results may
212vary depending on what other users may have shared and how your
213peer is connected.
214
215You can now select one of the search results. Once you do this,
216additional information about the result should be displayed on the
217right. If available, a preview image should appear on the top right.
218Meta data describing the file will be listed at the bottom right.
219
220Once a file is selected, at the bottom of the search result list
221a little area for downloading appears.
222
223@node Downloading
224@subsection Downloading
225@c %**end of header
226
227In the downloading area, you can select the target directory (default is
228"Downloads") and specify the desired filename (by default the filename it
229taken from the meta data of the published file). Additionally, you can
230specify if the download should be anonymous and (for directories) if
231the download should be recursive. In most cases, you can simply start
232the download with the "Download!" button.
233
234Once you selected download, the progress of the download will be
235displayed with the search result. You may need to resize the result
236list or scroll to the right. The "Status" column shows the current
237status of the download, and "Progress" how much has been completed.
238When you close the search tab (by clicking on the "X" button next to
239the "test" label), ongoing and completed downloads are not aborted
240but moved to a special "*" tab.
241
242You can remove completed downloads from the "*" tab by clicking the
243cleanup button next to the "*". You can also abort downloads by right
244clicking on the respective download and selecting "Abort download"
245from the menu.
246
247That's it, you now know the basics for file-sharing with GNUnet!
248
249@node First steps - Using the GNU Name System 49@node First steps - Using the GNU Name System
250@section First steps - Using the GNU Name System 50@section First steps - Using the GNU Name System
251@c %**end of header 51@c %**end of header
@@ -309,7 +109,7 @@ rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
309@subsection The GNS Tab 109@subsection The GNS Tab
310@c %**end of header 110@c %**end of header
311 111
312Maintaining your zones is through the NAMESTORE service and is discussed 112Maintaing your zones is through the NAMESTORE service and is discussed
313here. You can manage your zone using @command{gnunet-identity} and 113here. You can manage your zone using @command{gnunet-identity} and
314@command{gnunet-namestore}, or most conveniently using 114@command{gnunet-namestore}, or most conveniently using
315@command{gnunet-namestore-gtk}. 115@command{gnunet-namestore-gtk}.
@@ -904,19 +704,195 @@ file-sharing implementation. Then, we will discuss specifics as to
904how they impact users that publish, search or download files. 704how they impact users that publish, search or download files.
905 705
906 706
907
908@menu 707@menu
909* File-sharing Concepts:: 708* fs-Searching::
910* File-sharing Publishing:: 709* fs-Downloading::
911* File-sharing Searching:: 710* fs-Publishing::
912* File-sharing Downloading:: 711* fs-Concepts::
913* File-sharing Directories:: 712* fs-Directories::
914* File-sharing Namespace Management:: 713* Namespace Management::
915* File-Sharing URIs:: 714* File-Sharing URIs::
715* GTK User Interface::
716@end menu
717
718@node fs-Searching
719@subsection Searching
720@c %**end of header
721
722The command @command{gnunet-search} can be used to search
723for content on GNUnet. The format is:
724
725@example
726$ gnunet-search [-t TIMEOUT] KEYWORD
727@end example
728
729@noindent
730The -t option specifies that the query should timeout after
731approximately TIMEOUT seconds. A value of zero is interpreted
732as @emph{no timeout}, which is also the default. In this case,
733gnunet-search will never terminate (unless you press CTRL-C).
734
735If multiple words are passed as keywords, they will all be
736considered optional. Prefix keywords with a "+" to make them mandatory.
737
738Note that searching using
739
740@example
741$ gnunet-search Das Kapital
742@end example
743
744@noindent
745is not the same as searching for
746
747@example
748$ gnunet-search "Das Kapital"
749@end example
750
751@noindent
752as the first will match files shared under the keywords
753"Das" or "Kapital" whereas the second will match files
754shared under the keyword "Das Kapital".
755
756Search results are printed by gnunet-search like this:
757
758@c it will be better the avoid the ellipsis altogether because I don't
759@c understand the explanation below that
760@example
761$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
762=> The GNU Public License <= (mimetype: text/plain)
763@end example
764
765@noindent
766The first line is the command you would have to enter to download
767the file. The argument passed to @code{-o} is the suggested
768filename (you may change it to whatever you like).
769@c except it's triple dash in the above example ---
770The @code{--} is followed by key for decrypting the file,
771the query for searching the file, a checksum (in hexadecimal)
772finally the size of the file in bytes.
773The second line contains the description of the file; here this is
774"The GNU Public License" and the mime-type (see the options for
775gnunet-publish on how to specify these).
776
777@node fs-Downloading
778@subsection Downloading
779@c %**end of header
780
781In order to download a file, you need the three values returned by
782@command{gnunet-search}.
783You can then use the tool @command{gnunet-download} to obtain the file:
784
785@example
786$ gnunet-download -o FILENAME --- GNUNETURL
787@end example
788
789@noindent
790FILENAME specifies the name of the file where GNUnet is supposed
791to write the result. Existing files are overwritten. If the
792existing file contains blocks that are identical to the
793desired download, those blocks will not be downloaded again
794(automatic resume).
795
796If you want to download the GPL from the previous example,
797you do the following:
798
799@example
800$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
801@end example
802
803@noindent
804If you ever have to abort a download, you can continue it at any time by
805re-issuing @command{gnunet-download} with the same filename.
806In that case, GNUnet will @strong{not} download blocks again that are
807already present.
808
809GNUnet's file-encoding mechanism will ensure file integrity, even if the
810existing file was not downloaded from GNUnet in the first place.
811
812You may want to use the @command{-V} switch (must be added before
813@c Same as above it's triple dash
814the @command{--}) to turn on verbose reporting. In this case,
815@command{gnunet-download} will print the current number of
816bytes downloaded whenever new data was received.
817
818@node fs-Publishing
819@subsection Publishing
820@c %**end of header
821
822The command @command{gnunet-publish} can be used to add content
823to the network. The basic format of the command is
824
825@example
826$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
827@end example
828
829
830@menu
831* Important command-line options::
832* Indexing vs. Inserting::
916@end menu 833@end menu
917 834
918@node File-sharing Concepts 835@node Important command-line options
919@subsection File-sharing Concepts 836@subsubsection Important command-line options
837@c %**end of header
838
839The option @code{-k} is used to specify keywords for the file that
840should be inserted. You can supply any number of keywords,
841and each of the keywords will be sufficient to locate and
842retrieve the file. Please note that you must use the @code{-k} option
843more than once -- one for each expression you use as a keyword for
844the filename.
845
846The -m option is used to specify meta-data, such as descriptions.
847You can use -m multiple times. The TYPE passed must be from the
848list of meta-data types known to libextractor. You can obtain this
849list by running @command{extract -L}. Use quotes around the entire
850meta-data argument if the value contains spaces. The meta-data
851is displayed to other users when they select which files to
852download. The meta-data and the keywords are optional and
853maybe inferred using @code{GNU libextractor}.
854
855gnunet-publish has a few additional options to handle namespaces and
856directories. See the man-page for details.
857
858@node Indexing vs. Inserting
859@subsubsection Indexing vs Inserting
860@c %**end of header
861
862By default, GNUnet indexes a file instead of making a full copy.
863This is much more efficient, but requries the file to stay unaltered
864at the location where it was when it was indexed. If you intend to move,
865delete or alter a file, consider using the option @code{-n} which will
866force GNUnet to make a copy of the file in the database.
867
868Since it is much less efficient, this is strongly discouraged for large
869files. When GNUnet indexes a file (default), GNUnet does @strong{not}
870create an additional encrypted copy of the file but just computes a
871summary (or index) of the file. That summary is approximately two percent
872of the size of the original file and is stored in GNUnet's database.
873Whenever a request for a part of an indexed file reaches GNUnet,
874this part is encrypted on-demand and send out. This way, there is no
875need for an additional encrypted copy of the file to stay anywhere
876on the drive. This is different from other systems, such as Freenet,
877where each file that is put online must be in Freenet's database in
878encrypted format, doubling the space requirements if the user wants
879to preseve a directly accessible copy in plaintext.
880
881Thus indexing should be used for all files where the user will keep
882using this file (at the location given to gnunet-publish) and does
883not want to retrieve it back from GNUnet each time. If you want to
884remove a file that you have indexed from the local peer, use the tool
885@command{gnunet-unindex} to un-index the file.
886
887The option @code{-n} may be used if the user fears that the file might
888be found on their drive (assuming the computer comes under the control
889of an adversary). When used with the @code{-n} flag, the user has a
890much better chance of denying knowledge of the existence of the file,
891even if it is still (encrypted) on the drive and the adversary is
892able to crack the encryption (e.g. by guessing the keyword.
893
894@node fs-Concepts
895@subsection Concepts
920@c %**end of header 896@c %**end of header
921 897
922Sharing files in GNUnet is not quite as simple as in traditional 898Sharing files in GNUnet is not quite as simple as in traditional
@@ -1072,184 +1048,9 @@ replication level into the network, and then decrement the replication
1072level by one. If all blocks reach replication level zero, the 1048level by one. If all blocks reach replication level zero, the
1073selection is simply random. 1049selection is simply random.
1074 1050
1075@node File-sharing Publishing
1076@subsection File-sharing Publishing
1077@c %**end of header
1078
1079The command @command{gnunet-publish} can be used to add content
1080to the network. The basic format of the command is
1081
1082@example
1083$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
1084@end example
1085
1086
1087@menu
1088* Important command-line options::
1089* Indexing vs. Inserting::
1090@end menu
1091
1092@node Important command-line options
1093@subsubsection Important command-line options
1094@c %**end of header
1095
1096The option @code{-k} is used to specify keywords for the file that
1097should be inserted. You can supply any number of keywords,
1098and each of the keywords will be sufficient to locate and
1099retrieve the file. Please note that you must use the @code{-k} option
1100more than once -- one for each expression you use as a keyword for
1101the filename.
1102
1103The -m option is used to specify meta-data, such as descriptions.
1104You can use -m multiple times. The TYPE passed must be from the
1105list of meta-data types known to libextractor. You can obtain this
1106list by running @command{extract -L}. Use quotes around the entire
1107meta-data argument if the value contains spaces. The meta-data
1108is displayed to other users when they select which files to
1109download. The meta-data and the keywords are optional and
1110maybe inferred using @code{GNU libextractor}.
1111
1112gnunet-publish has a few additional options to handle namespaces and
1113directories. See the man-page for details.
1114
1115@node Indexing vs. Inserting
1116@subsubsection Indexing vs Inserting
1117@c %**end of header
1118
1119By default, GNUnet indexes a file instead of making a full copy.
1120This is much more efficient, but requries the file to stay unaltered
1121at the location where it was when it was indexed. If you intend to move,
1122delete or alter a file, consider using the option @code{-n} which will
1123force GNUnet to make a copy of the file in the database.
1124
1125Since it is much less efficient, this is strongly discouraged for large
1126files. When GNUnet indexes a file (default), GNUnet does @strong{not}
1127create an additional encrypted copy of the file but just computes a
1128summary (or index) of the file. That summary is approximately two percent
1129of the size of the original file and is stored in GNUnet's database.
1130Whenever a request for a part of an indexed file reaches GNUnet,
1131this part is encrypted on-demand and send out. This way, there is no
1132need for an additional encrypted copy of the file to stay anywhere
1133on the drive. This is different from other systems, such as Freenet,
1134where each file that is put online must be in Freenet's database in
1135encrypted format, doubling the space requirements if the user wants
1136to preseve a directly accessible copy in plaintext.
1137
1138Thus indexing should be used for all files where the user will keep
1139using this file (at the location given to gnunet-publish) and does
1140not want to retrieve it back from GNUnet each time. If you want to
1141remove a file that you have indexed from the local peer, use the tool
1142@command{gnunet-unindex} to un-index the file.
1143
1144The option @code{-n} may be used if the user fears that the file might
1145be found on their drive (assuming the computer comes under the control
1146of an adversary). When used with the @code{-n} flag, the user has a
1147much better chance of denying knowledge of the existence of the file,
1148even if it is still (encrypted) on the drive and the adversary is
1149able to crack the encryption (e.g. by guessing the keyword.
1150
1151@node File-sharing Searching
1152@subsection File-sharing Searching
1153@c %**end of header
1154
1155The command @command{gnunet-search} can be used to search
1156for content on GNUnet. The format is:
1157
1158@example
1159$ gnunet-search [-t TIMEOUT] KEYWORD
1160@end example
1161
1162@noindent
1163The -t option specifies that the query should timeout after
1164approximately TIMEOUT seconds. A value of zero is interpreted
1165as @emph{no timeout}, which is also the default. In this case,
1166gnunet-search will never terminate (unless you press CTRL-C).
1167
1168If multiple words are passed as keywords, they will all be
1169considered optional. Prefix keywords with a "+" to make them mandatory.
1170
1171Note that searching using
1172
1173@example
1174$ gnunet-search Das Kapital
1175@end example
1176
1177@noindent
1178is not the same as searching for
1179
1180@example
1181$ gnunet-search "Das Kapital"
1182@end example
1183
1184@noindent
1185as the first will match files shared under the keywords
1186"Das" or "Kapital" whereas the second will match files
1187shared under the keyword "Das Kapital".
1188
1189Search results are printed by gnunet-search like this:
1190
1191@c it will be better the avoid the ellipsis altogether because I don't
1192@c understand the explanation below that
1193@example
1194$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
1195=> The GNU Public License <= (mimetype: text/plain)
1196@end example
1197
1198@noindent
1199The first line is the command you would have to enter to download
1200the file. The argument passed to @code{-o} is the suggested
1201filename (you may change it to whatever you like).
1202@c except it's triple dash in the above example ---
1203The @code{--} is followed by key for decrypting the file,
1204the query for searching the file, a checksum (in hexadecimal)
1205finally the size of the file in bytes.
1206The second line contains the description of the file; here this is
1207"The GNU Public License" and the mime-type (see the options for
1208gnunet-publish on how to specify these).
1209
1210@node File-sharing Downloading
1211@subsection File-sharing Downloading
1212@c %**end of header
1213
1214In order to download a file, you need the three values returned by
1215@command{gnunet-search}.
1216You can then use the tool @command{gnunet-download} to obtain the file:
1217
1218@example
1219$ gnunet-download -o FILENAME --- GNUNETURL
1220@end example
1221
1222@noindent
1223FILENAME specifies the name of the file where GNUnet is supposed
1224to write the result. Existing files are overwritten. If the
1225existing file contains blocks that are identical to the
1226desired download, those blocks will not be downloaded again
1227(automatic resume).
1228
1229If you want to download the GPL from the previous example,
1230you do the following:
1231
1232@example
1233$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
1234@end example
1235
1236@noindent
1237If you ever have to abort a download, you can continue it at any time by
1238re-issuing @command{gnunet-download} with the same filename.
1239In that case, GNUnet will @strong{not} download blocks again that are
1240already present.
1241
1242GNUnet's file-encoding mechanism will ensure file integrity, even if the
1243existing file was not downloaded from GNUnet in the first place.
1244
1245You may want to use the @command{-V} switch (must be added before
1246@c Same as above it's triple dash
1247the @command{--}) to turn on verbose reporting. In this case,
1248@command{gnunet-download} will print the current number of
1249bytes downloaded whenever new data was received.
1250 1051
1251@node File-sharing Directories 1052@node fs-Directories
1252@subsection File-sharing Directories 1053@subsection Directories
1253@c %**end of header 1054@c %**end of header
1254 1055
1255Directories are shared just like ordinary files. If you download a 1056Directories are shared just like ordinary files. If you download a
@@ -1264,8 +1065,8 @@ typically includes the mime-type, description, a filename and
1264other meta information, and possibly even the full original file 1065other meta information, and possibly even the full original file
1265(if it was small). 1066(if it was small).
1266 1067
1267@node File-sharing Namespace Management 1068@node Namespace Management
1268@subsection File-sharing Namespace Management 1069@subsection Namespace Management
1269@c %**end of header 1070@c %**end of header
1270 1071
1271@b{Please note that the text in this subsection is outdated and needs} 1072@b{Please note that the text in this subsection is outdated and needs}
@@ -1436,6 +1237,135 @@ chosen keyword (or password!). A commonly used identifier is
1436"root" which by convention refers to some kind of index or other 1237"root" which by convention refers to some kind of index or other
1437entry point into the namespace. 1238entry point into the namespace.
1438 1239
1240@node GTK User Interface
1241@subsection GTK User Interface
1242This chapter describes first steps for file-sharing with GNUnet.
1243To start, you should launch @command{gnunet-fs-gtk}.
1244
1245As we want to be sure that the network contains the data that we are
1246looking for for testing, we need to begin by publishing a file.
1247
1248@menu
1249* gtk-Publishing::
1250* gtk-Searching::
1251* gtk-Downloading::
1252@end menu
1253
1254@node gtk-Publishing
1255@subsubsection Publishing
1256@c %**end of header
1257
1258To publish a file, select "File Sharing" in the menu bar just below the
1259"Statistics" icon, and then select "Publish" from the menu.
1260
1261Afterwards, the following publishing dialog will appear:
1262
1263@c Add image here
1264
1265In this dialog, select the "Add File" button. This will open a
1266file selection dialog:
1267
1268@c Add image here
1269
1270Now, you should select a file from your computer to be published on
1271GNUnet. To see more of GNUnet's features later, you should pick a
1272PNG or JPEG file this time. You can leave all of the other options
1273in the dialog unchanged. Confirm your selection by pressing the "OK"
1274button in the bottom right corner. Now, you will briefly see a
1275"Messages..." dialog pop up, but most likely it will be too short for
1276you to really read anything. That dialog is showing you progress
1277information as GNUnet takes a first look at the selected file(s).
1278For a normal image, this is virtually instant, but if you later
1279import a larger directory you might be interested in the progress dialog
1280and potential errors that might be encountered during processing.
1281After the progress dialog automatically disappears, your file
1282should now appear in the publishing dialog:
1283
1284@c Add image here
1285
1286Now, select the file (by clicking on the file name) and then click
1287the "Edit" button. This will open the editing dialog:
1288
1289@c Add image here
1290
1291In this dialog, you can see many details about your file. In the
1292top left area, you can see meta data extracted about the file,
1293such as the original filename, the mimetype and the size of the image.
1294In the top right, you should see a preview for the image
1295(if GNU libextractor was installed correctly with the
1296respective plugins). Note that if you do not see a preview, this
1297is not a disaster, but you might still want to install more of
1298GNU libextractor in the future. In the bottom left, the dialog contains
1299a list of keywords. These are the keywords under which the file will be
1300made available. The initial list will be based on the extracted meta data.
1301Additional publishing options are in the right bottom corner. We will
1302now add an additional keyword to the list of keywords. This is done by
1303entering the keyword above the keyword list between the label "Keyword"
1304and the "Add keyword" button. Enter "test" and select "Add keyword".
1305Note that the keyword will appear at the bottom of the existing keyword
1306list, so you might have to scroll down to see it. Afterwards, push the
1307"OK" button at the bottom right of the dialog.
1308
1309You should now be back at the "Publish content on GNUnet" dialog. Select
1310"Execute" in the bottom right to close the dialog and publish your file
1311on GNUnet! Afterwards, you should see the main dialog with a new area
1312showing the list of published files (or ongoing publishing operations
1313with progress indicators):
1314
1315@c Add image here
1316
1317@node gtk-Searching
1318@subsubsection Searching
1319@c %**end of header
1320
1321Below the menu bar, there are four entry widges labeled "Namespace",
1322"Keywords", "Anonymity" and "Mime-type" (from left to right). These
1323widgets are used to control searching for files in GNUnet. Between the
1324"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
1325which is used to initiate the search. We will ignore the "Namespace",
1326"Anonymity" and "Mime-type" options in this tutorial, please leave them
1327empty. Instead, simply enter "test" under "Keywords" and press "Search".
1328Afterwards, you should immediately see a new tab labeled after your
1329search term, followed by the (current) number of search
1330results --- "(15)" in our screenshot. Note that your results may
1331vary depending on what other users may have shared and how your
1332peer is connected.
1333
1334You can now select one of the search results. Once you do this,
1335additional information about the result should be displayed on the
1336right. If available, a preview image should appear on the top right.
1337Meta data describing the file will be listed at the bottom right.
1338
1339Once a file is selected, at the bottom of the search result list
1340a little area for downloading appears.
1341
1342@node gtk-Downloading
1343@subsubsection Downloading
1344@c %**end of header
1345
1346In the downloading area, you can select the target directory (default is
1347"Downloads") and specify the desired filename (by default the filename it
1348taken from the meta data of the published file). Additionally, you can
1349specify if the download should be anonynmous and (for directories) if
1350the download should be recursive. In most cases, you can simply start
1351the download with the "Download!" button.
1352
1353Once you selected download, the progress of the download will be
1354displayed with the search result. You may need to resize the result
1355list or scroll to the right. The "Status" column shows the current
1356status of the download, and "Progress" how much has been completed.
1357When you close the search tab (by clicking on the "X" button next to
1358the "test" label), ongoing and completed downloads are not aborted
1359but moved to a special "*" tab.
1360
1361You can remove completed downloads from the "*" tab by clicking the
1362cleanup button next to the "*". You can also abort downloads by right
1363clicking on the respective download and selecting "Abort download"
1364from the menu.
1365
1366That's it, you now know the basics for file-sharing with GNUnet!
1367
1368
1439@node The GNU Name System 1369@node The GNU Name System
1440@section The GNU Name System 1370@section The GNU Name System
1441@c %**end of header 1371@c %**end of header
@@ -2032,8 +1962,8 @@ that will terminate at the respective peer's service.
2032 1962
2033@c NOTE: Inserted from Installation Handbook in original ``order'': 1963@c NOTE: Inserted from Installation Handbook in original ``order'':
2034@c FIXME: Move this to User Handbook. 1964@c FIXME: Move this to User Handbook.
2035@node The graphical configuration interface 1965@node MOVE TO INSTALL The graphical configuration interface
2036@section The graphical configuration interface 1966@section MOVE TO INSTALL The graphical configuration interface
2037 1967
2038If you also would like to use @command{gnunet-gtk} and 1968If you also would like to use @command{gnunet-gtk} and
2039@command{gnunet-setup} (highly recommended for beginners), do: 1969@command{gnunet-setup} (highly recommended for beginners), do:
@@ -2264,7 +2194,7 @@ the configuration:
2264 2194
2265If you operate a peer permanently connected to GNUnet you can configure 2195If you operate a peer permanently connected to GNUnet you can configure
2266your peer to act as a hostlist server, providing other peers the list of 2196your peer to act as a hostlist server, providing other peers the list of
2267peers known to it. 2197peers known to him.
2268 2198
2269Your server can act as a bootstrap server and peers needing to obtain a 2199Your server can act as a bootstrap server and peers needing to obtain a
2270list of peers can contact it to download this list. 2200list of peers can contact it to download this list.
@@ -2883,7 +2813,7 @@ iwconfig wlan0 channel 1
2883@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx 2813@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
2884 2814
2885The HTTP plugin supports data transfer using reverse proxies. A reverse 2815The HTTP plugin supports data transfer using reverse proxies. A reverse
2886proxy forwards the HTTP request it receives with a certain URL to another 2816proxy forwards the HTTP request he receives with a certain URL to another
2887webserver, here a GNUnet peer. 2817webserver, here a GNUnet peer.
2888 2818
2889So if you have a running Apache or nginx webserver you can configure it to 2819So if you have a running Apache or nginx webserver you can configure it to
@@ -3619,8 +3549,91 @@ desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
3619and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in 3549and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
3620sequence. 3550sequence.
3621 3551
3622@node How to start and stop a GNUnet peer 3552@node MOVE TO INSTALL Checking the Installation
3623@section How to start and stop a GNUnet peer 3553@section MOVE TO INSTALL Checking the Installation
3554@c %**end of header
3555
3556This section describes a quick, casual way to check if your GNUnet
3557installation works. However, if it does not, we do not cover
3558steps for recovery --- for this, please study the instructions
3559provided in the developer handbook as well as the system-specific
3560instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}.
3561
3562
3563@menu
3564* gnunet-gtk::
3565* Statistics::
3566* Peer Information::
3567@end menu
3568
3569@cindex GNUnet GTK
3570@cindex GTK
3571@cindex GTK user interface
3572@node gnunet-gtk
3573@subsection gnunet-gtk
3574@c %**end of header
3575
3576The @command{gnunet-gtk} package contains several graphical
3577user interfaces for the respective GNUnet applications.
3578Currently these interfaces cover:
3579
3580@itemize @bullet
3581@item Statistics
3582@item Peer Information
3583@item GNU Name System
3584@item File Sharing
3585@item Identity Management
3586@item Conversation
3587@end itemize
3588
3589@node Statistics
3590@subsection Statistics
3591@c %**end of header
3592
3593First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}.
3594You can do this from the command-line by typing
3595
3596@example
3597gnunet-statistics-gtk
3598@end example
3599
3600If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.}
3601is running correctly, you should see a bunch of lines,
3602all of which should be ``significantly'' above zero (at least if your
3603peer has been running for more than a few seconds). The lines indicate
3604how many other peers your peer is connected to (via different
3605mechanisms) and how large the entire overlay network is currently
3606estimated to be. The X-axis represents time (in seconds since the
3607start of @command{gnunet-gtk}).
3608
3609You can click on "Traffic" to see information about the amount of
3610bandwidth your peer has consumed, and on "Storage" to check the amount
3611of storage available and used by your peer. Note that "Traffic" is
3612plotted cummulatively, so you should see a strict upwards trend in the
3613traffic.
3614
3615@node Peer Information
3616@subsection Peer Information
3617@c %**end of header
3618
3619First, you should launch the graphical user interface. You can do
3620this from the command-line by typing
3621
3622@example
3623$ gnunet-peerinfo-gtk
3624@end example
3625
3626Once you have done this, you will see a list of known peers (by the
3627first four characters of their public key), their friend status (all
3628should be marked as not-friends initially), their connectivity (green
3629is connected, red is disconnected), assigned bandwidth, country of
3630origin (if determined) and address information. If hardly any peers
3631are listed and/or if there are very few peers with a green light for
3632connectivity, there is likely a problem with your network
3633configuration.
3634
3635@node MOVE TO INSTALL Config Leftovers
3636@section MOVE TO INSTALL Config Leftovers
3624 3637
3625This section describes how to start a GNUnet peer. It assumes that you 3638This section describes how to start a GNUnet peer. It assumes that you
3626have already compiled and installed GNUnet and its' dependencies. 3639have already compiled and installed GNUnet and its' dependencies.
@@ -3949,3 +3962,4 @@ Furthermore, 'make install' will silently fail to set the DNS binaries to
3949be owned by group "gnunetdns" unless that group already exists (!). 3962be owned by group "gnunetdns" unless that group already exists (!).
3950An alternative name for the "gnunetdns" group can be specified using the 3963An alternative name for the "gnunetdns" group can be specified using the
3951@code{--with-gnunetdns=GRPNAME} configure option. 3964@code{--with-gnunetdns=GRPNAME} configure option.
3965
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi
index cd2f04399..8528cf80a 100644
--- a/doc/documentation/gnunet.texi
+++ b/doc/documentation/gnunet.texi
@@ -122,16 +122,16 @@ Philosophy
122 122
123Using GNUnet 123Using GNUnet
124 124
125* Checking the Installation:: 125* Start and stop GNUnet::
126* First steps - File-sharing::
127* First steps - Using the GNU Name System:: 126* First steps - Using the GNU Name System::
128* First steps - Using GNUnet Conversation:: 127* First steps - Using GNUnet Conversation::
129* First steps - Using the GNUnet VPN:: 128* First steps - Using the GNUnet VPN::
130* File-sharing:: 129* File-sharing::
131* The GNU Name System:: 130* The GNU Name System::
132* Using the Virtual Public Network:: 131* Using the Virtual Public Network::
133* The graphical configuration interface:: 132* MOVE TO INSTALL The graphical configuration interface::
134* How to start and stop a GNUnet peer:: 133* MOVE TO INSTALL Checking the Installation::
134* MOVE TO INSTALL Config Leftovers::
135 135
136GNUnet Contributors Handbook 136GNUnet Contributors Handbook
137 137