diff options
Diffstat (limited to 'doc/documentation/chapters')
-rw-r--r-- | doc/documentation/chapters/user.texi | 824 |
1 files changed, 419 insertions, 405 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 | |||
39 | This section describes a quick, casual way to check if your GNUnet | ||
40 | installation works. However, if it does not, we do not cover | ||
41 | steps for recovery --- for this, please study the instructions | ||
42 | provided in the developer handbook as well as the system-specific | ||
43 | instruction 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 | |||
59 | The @command{gnunet-gtk} package contains several graphical | ||
60 | user interfaces for the respective GNUnet applications. | ||
61 | Currently these interfaces cover: | ||
62 | 37 | ||
63 | @itemize @bullet | 38 | To 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 | |||
76 | First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. | ||
77 | You can do this from the command-line by typing | ||
78 | 39 | ||
79 | @example | 40 | @example |
80 | gnunet-statistics-gtk | 41 | $ gnunet-arm -s -l gnunet.log |
81 | @end example | 42 | @end example |
82 | 43 | ||
83 | If 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''.} | 44 | To stop GNUnet: |
84 | is running correctly, you should see a bunch of lines, | ||
85 | all of which should be ``significantly'' above zero (at least if your | ||
86 | peer has been running for more than a few seconds). The lines indicate | ||
87 | how many other peers your peer is connected to (via different | ||
88 | mechanisms) and how large the entire overlay network is currently | ||
89 | estimated to be. The X-axis represents time (in seconds since the | ||
90 | start of @command{gnunet-gtk}). | ||
91 | |||
92 | You can click on "Traffic" to see information about the amount of | ||
93 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
94 | of storage available and used by your peer. Note that "Traffic" is | ||
95 | plotted cumulatively, so you should see a strict upwards trend in the | ||
96 | traffic. | ||
97 | |||
98 | @node Peer Information | ||
99 | @subsection Peer Information | ||
100 | @c %**end of header | ||
101 | |||
102 | First, you should launch the graphical user interface. You can do | ||
103 | this 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 | |||
109 | Once you have done this, you will see a list of known peers (by the | ||
110 | first four characters of their public key), their friend status (all | ||
111 | should be marked as not-friends initially), their connectivity (green | ||
112 | is connected, red is disconnected), assigned bandwidth, country of | ||
113 | origin (if determined) and address information. If hardly any peers | ||
114 | are listed and/or if there are very few peers with a green light for | ||
115 | connectivity, there is likely a problem with your network | ||
116 | configuration. | ||
117 | |||
118 | @node First steps - File-sharing | ||
119 | @section First steps - File-sharing | ||
120 | @c %**end of header | ||
121 | |||
122 | This chapter describes first steps for file-sharing with GNUnet. | ||
123 | To start, you should launch @command{gnunet-fs-gtk}. | ||
124 | |||
125 | As we want to be sure that the network contains the data that we are | ||
126 | looking 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 | |||
139 | To publish a file, select "File Sharing" in the menu bar just below the | ||
140 | "Statistics" icon, and then select "Publish" from the menu. | ||
141 | |||
142 | Afterwards, the following publishing dialog will appear: | ||
143 | |||
144 | @c Add image here | ||
145 | |||
146 | In this dialog, select the "Add File" button. This will open a | ||
147 | file selection dialog: | ||
148 | |||
149 | @c Add image here | ||
150 | |||
151 | Now, you should select a file from your computer to be published on | ||
152 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
153 | PNG or JPEG file this time. You can leave all of the other options | ||
154 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
155 | button 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 | ||
157 | you to really read anything. That dialog is showing you progress | ||
158 | information as GNUnet takes a first look at the selected file(s). | ||
159 | For a normal image, this is virtually instant, but if you later | ||
160 | import a larger directory you might be interested in the progress dialog | ||
161 | and potential errors that might be encountered during processing. | ||
162 | After the progress dialog automatically disappears, your file | ||
163 | should now appear in the publishing dialog: | ||
164 | |||
165 | @c Add image here | ||
166 | |||
167 | Now, select the file (by clicking on the file name) and then click | ||
168 | the "Edit" button. This will open the editing dialog: | ||
169 | |||
170 | @c Add image here | ||
171 | |||
172 | In this dialog, you can see many details about your file. In the | ||
173 | top left area, you can see meta data extracted about the file, | ||
174 | such as the original filename, the mimetype and the size of the image. | ||
175 | In the top right, you should see a preview for the image | ||
176 | (if GNU libextractor was installed correctly with the | ||
177 | respective plugins). Note that if you do not see a preview, this | ||
178 | is not a disaster, but you might still want to install more of | ||
179 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
180 | a list of keywords. These are the keywords under which the file will be | ||
181 | made available. The initial list will be based on the extracted meta data. | ||
182 | Additional publishing options are in the right bottom corner. We will | ||
183 | now add an additional keyword to the list of keywords. This is done by | ||
184 | entering the keyword above the keyword list between the label "Keyword" | ||
185 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
186 | Note that the keyword will appear at the bottom of the existing keyword | ||
187 | list, so you might have to scroll down to see it. Afterwards, push the | ||
188 | "OK" button at the bottom right of the dialog. | ||
189 | |||
190 | You 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 | ||
192 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
193 | showing the list of published files (or ongoing publishing operations | ||
194 | with progress indicators): | ||
195 | |||
196 | @c Add image here | ||
197 | |||
198 | @node Searching | ||
199 | @subsection Searching | ||
200 | @c %**end of header | ||
201 | |||
202 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
203 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
204 | widgets are used to control searching for files in GNUnet. Between the | ||
205 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
206 | which is used to initiate the search. We will ignore the "Namespace", | ||
207 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
208 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
209 | Afterwards, you should immediately see a new tab labeled after your | ||
210 | search term, followed by the (current) number of search | ||
211 | results --- "(15)" in our screenshot. Note that your results may | ||
212 | vary depending on what other users may have shared and how your | ||
213 | peer is connected. | ||
214 | |||
215 | You can now select one of the search results. Once you do this, | ||
216 | additional information about the result should be displayed on the | ||
217 | right. If available, a preview image should appear on the top right. | ||
218 | Meta data describing the file will be listed at the bottom right. | ||
219 | |||
220 | Once a file is selected, at the bottom of the search result list | ||
221 | a little area for downloading appears. | ||
222 | |||
223 | @node Downloading | ||
224 | @subsection Downloading | ||
225 | @c %**end of header | ||
226 | |||
227 | In the downloading area, you can select the target directory (default is | ||
228 | "Downloads") and specify the desired filename (by default the filename it | ||
229 | taken from the meta data of the published file). Additionally, you can | ||
230 | specify if the download should be anonymous and (for directories) if | ||
231 | the download should be recursive. In most cases, you can simply start | ||
232 | the download with the "Download!" button. | ||
233 | |||
234 | Once you selected download, the progress of the download will be | ||
235 | displayed with the search result. You may need to resize the result | ||
236 | list or scroll to the right. The "Status" column shows the current | ||
237 | status of the download, and "Progress" how much has been completed. | ||
238 | When you close the search tab (by clicking on the "X" button next to | ||
239 | the "test" label), ongoing and completed downloads are not aborted | ||
240 | but moved to a special "*" tab. | ||
241 | |||
242 | You can remove completed downloads from the "*" tab by clicking the | ||
243 | cleanup button next to the "*". You can also abort downloads by right | ||
244 | clicking on the respective download and selecting "Abort download" | ||
245 | from the menu. | ||
246 | |||
247 | That'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 | ||
312 | Maintaining your zones is through the NAMESTORE service and is discussed | 112 | Maintaing your zones is through the NAMESTORE service and is discussed |
313 | here. You can manage your zone using @command{gnunet-identity} and | 113 | here. 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 | |||
904 | how they impact users that publish, search or download files. | 704 | how 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 | |||
722 | The command @command{gnunet-search} can be used to search | ||
723 | for content on GNUnet. The format is: | ||
724 | |||
725 | @example | ||
726 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
727 | @end example | ||
728 | |||
729 | @noindent | ||
730 | The -t option specifies that the query should timeout after | ||
731 | approximately TIMEOUT seconds. A value of zero is interpreted | ||
732 | as @emph{no timeout}, which is also the default. In this case, | ||
733 | gnunet-search will never terminate (unless you press CTRL-C). | ||
734 | |||
735 | If multiple words are passed as keywords, they will all be | ||
736 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
737 | |||
738 | Note that searching using | ||
739 | |||
740 | @example | ||
741 | $ gnunet-search Das Kapital | ||
742 | @end example | ||
743 | |||
744 | @noindent | ||
745 | is not the same as searching for | ||
746 | |||
747 | @example | ||
748 | $ gnunet-search "Das Kapital" | ||
749 | @end example | ||
750 | |||
751 | @noindent | ||
752 | as the first will match files shared under the keywords | ||
753 | "Das" or "Kapital" whereas the second will match files | ||
754 | shared under the keyword "Das Kapital". | ||
755 | |||
756 | Search 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 | ||
766 | The first line is the command you would have to enter to download | ||
767 | the file. The argument passed to @code{-o} is the suggested | ||
768 | filename (you may change it to whatever you like). | ||
769 | @c except it's triple dash in the above example --- | ||
770 | The @code{--} is followed by key for decrypting the file, | ||
771 | the query for searching the file, a checksum (in hexadecimal) | ||
772 | finally the size of the file in bytes. | ||
773 | The second line contains the description of the file; here this is | ||
774 | "The GNU Public License" and the mime-type (see the options for | ||
775 | gnunet-publish on how to specify these). | ||
776 | |||
777 | @node fs-Downloading | ||
778 | @subsection Downloading | ||
779 | @c %**end of header | ||
780 | |||
781 | In order to download a file, you need the three values returned by | ||
782 | @command{gnunet-search}. | ||
783 | You 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 | ||
790 | FILENAME specifies the name of the file where GNUnet is supposed | ||
791 | to write the result. Existing files are overwritten. If the | ||
792 | existing file contains blocks that are identical to the | ||
793 | desired download, those blocks will not be downloaded again | ||
794 | (automatic resume). | ||
795 | |||
796 | If you want to download the GPL from the previous example, | ||
797 | you do the following: | ||
798 | |||
799 | @example | ||
800 | $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992 | ||
801 | @end example | ||
802 | |||
803 | @noindent | ||
804 | If you ever have to abort a download, you can continue it at any time by | ||
805 | re-issuing @command{gnunet-download} with the same filename. | ||
806 | In that case, GNUnet will @strong{not} download blocks again that are | ||
807 | already present. | ||
808 | |||
809 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
810 | existing file was not downloaded from GNUnet in the first place. | ||
811 | |||
812 | You may want to use the @command{-V} switch (must be added before | ||
813 | @c Same as above it's triple dash | ||
814 | the @command{--}) to turn on verbose reporting. In this case, | ||
815 | @command{gnunet-download} will print the current number of | ||
816 | bytes downloaded whenever new data was received. | ||
817 | |||
818 | @node fs-Publishing | ||
819 | @subsection Publishing | ||
820 | @c %**end of header | ||
821 | |||
822 | The command @command{gnunet-publish} can be used to add content | ||
823 | to 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 | |||
839 | The option @code{-k} is used to specify keywords for the file that | ||
840 | should be inserted. You can supply any number of keywords, | ||
841 | and each of the keywords will be sufficient to locate and | ||
842 | retrieve the file. Please note that you must use the @code{-k} option | ||
843 | more than once -- one for each expression you use as a keyword for | ||
844 | the filename. | ||
845 | |||
846 | The -m option is used to specify meta-data, such as descriptions. | ||
847 | You can use -m multiple times. The TYPE passed must be from the | ||
848 | list of meta-data types known to libextractor. You can obtain this | ||
849 | list by running @command{extract -L}. Use quotes around the entire | ||
850 | meta-data argument if the value contains spaces. The meta-data | ||
851 | is displayed to other users when they select which files to | ||
852 | download. The meta-data and the keywords are optional and | ||
853 | maybe inferred using @code{GNU libextractor}. | ||
854 | |||
855 | gnunet-publish has a few additional options to handle namespaces and | ||
856 | directories. See the man-page for details. | ||
857 | |||
858 | @node Indexing vs. Inserting | ||
859 | @subsubsection Indexing vs Inserting | ||
860 | @c %**end of header | ||
861 | |||
862 | By default, GNUnet indexes a file instead of making a full copy. | ||
863 | This is much more efficient, but requries the file to stay unaltered | ||
864 | at the location where it was when it was indexed. If you intend to move, | ||
865 | delete or alter a file, consider using the option @code{-n} which will | ||
866 | force GNUnet to make a copy of the file in the database. | ||
867 | |||
868 | Since it is much less efficient, this is strongly discouraged for large | ||
869 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
870 | create an additional encrypted copy of the file but just computes a | ||
871 | summary (or index) of the file. That summary is approximately two percent | ||
872 | of the size of the original file and is stored in GNUnet's database. | ||
873 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
874 | this part is encrypted on-demand and send out. This way, there is no | ||
875 | need for an additional encrypted copy of the file to stay anywhere | ||
876 | on the drive. This is different from other systems, such as Freenet, | ||
877 | where each file that is put online must be in Freenet's database in | ||
878 | encrypted format, doubling the space requirements if the user wants | ||
879 | to preseve a directly accessible copy in plaintext. | ||
880 | |||
881 | Thus indexing should be used for all files where the user will keep | ||
882 | using this file (at the location given to gnunet-publish) and does | ||
883 | not want to retrieve it back from GNUnet each time. If you want to | ||
884 | remove a file that you have indexed from the local peer, use the tool | ||
885 | @command{gnunet-unindex} to un-index the file. | ||
886 | |||
887 | The option @code{-n} may be used if the user fears that the file might | ||
888 | be found on their drive (assuming the computer comes under the control | ||
889 | of an adversary). When used with the @code{-n} flag, the user has a | ||
890 | much better chance of denying knowledge of the existence of the file, | ||
891 | even if it is still (encrypted) on the drive and the adversary is | ||
892 | able 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 | ||
922 | Sharing files in GNUnet is not quite as simple as in traditional | 898 | Sharing 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 | |||
1072 | level by one. If all blocks reach replication level zero, the | 1048 | level by one. If all blocks reach replication level zero, the |
1073 | selection is simply random. | 1049 | selection is simply random. |
1074 | 1050 | ||
1075 | @node File-sharing Publishing | ||
1076 | @subsection File-sharing Publishing | ||
1077 | @c %**end of header | ||
1078 | |||
1079 | The command @command{gnunet-publish} can be used to add content | ||
1080 | to 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 | |||
1096 | The option @code{-k} is used to specify keywords for the file that | ||
1097 | should be inserted. You can supply any number of keywords, | ||
1098 | and each of the keywords will be sufficient to locate and | ||
1099 | retrieve the file. Please note that you must use the @code{-k} option | ||
1100 | more than once -- one for each expression you use as a keyword for | ||
1101 | the filename. | ||
1102 | |||
1103 | The -m option is used to specify meta-data, such as descriptions. | ||
1104 | You can use -m multiple times. The TYPE passed must be from the | ||
1105 | list of meta-data types known to libextractor. You can obtain this | ||
1106 | list by running @command{extract -L}. Use quotes around the entire | ||
1107 | meta-data argument if the value contains spaces. The meta-data | ||
1108 | is displayed to other users when they select which files to | ||
1109 | download. The meta-data and the keywords are optional and | ||
1110 | maybe inferred using @code{GNU libextractor}. | ||
1111 | |||
1112 | gnunet-publish has a few additional options to handle namespaces and | ||
1113 | directories. See the man-page for details. | ||
1114 | |||
1115 | @node Indexing vs. Inserting | ||
1116 | @subsubsection Indexing vs Inserting | ||
1117 | @c %**end of header | ||
1118 | |||
1119 | By default, GNUnet indexes a file instead of making a full copy. | ||
1120 | This is much more efficient, but requries the file to stay unaltered | ||
1121 | at the location where it was when it was indexed. If you intend to move, | ||
1122 | delete or alter a file, consider using the option @code{-n} which will | ||
1123 | force GNUnet to make a copy of the file in the database. | ||
1124 | |||
1125 | Since it is much less efficient, this is strongly discouraged for large | ||
1126 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
1127 | create an additional encrypted copy of the file but just computes a | ||
1128 | summary (or index) of the file. That summary is approximately two percent | ||
1129 | of the size of the original file and is stored in GNUnet's database. | ||
1130 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
1131 | this part is encrypted on-demand and send out. This way, there is no | ||
1132 | need for an additional encrypted copy of the file to stay anywhere | ||
1133 | on the drive. This is different from other systems, such as Freenet, | ||
1134 | where each file that is put online must be in Freenet's database in | ||
1135 | encrypted format, doubling the space requirements if the user wants | ||
1136 | to preseve a directly accessible copy in plaintext. | ||
1137 | |||
1138 | Thus indexing should be used for all files where the user will keep | ||
1139 | using this file (at the location given to gnunet-publish) and does | ||
1140 | not want to retrieve it back from GNUnet each time. If you want to | ||
1141 | remove a file that you have indexed from the local peer, use the tool | ||
1142 | @command{gnunet-unindex} to un-index the file. | ||
1143 | |||
1144 | The option @code{-n} may be used if the user fears that the file might | ||
1145 | be found on their drive (assuming the computer comes under the control | ||
1146 | of an adversary). When used with the @code{-n} flag, the user has a | ||
1147 | much better chance of denying knowledge of the existence of the file, | ||
1148 | even if it is still (encrypted) on the drive and the adversary is | ||
1149 | able 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 | |||
1155 | The command @command{gnunet-search} can be used to search | ||
1156 | for content on GNUnet. The format is: | ||
1157 | |||
1158 | @example | ||
1159 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
1160 | @end example | ||
1161 | |||
1162 | @noindent | ||
1163 | The -t option specifies that the query should timeout after | ||
1164 | approximately TIMEOUT seconds. A value of zero is interpreted | ||
1165 | as @emph{no timeout}, which is also the default. In this case, | ||
1166 | gnunet-search will never terminate (unless you press CTRL-C). | ||
1167 | |||
1168 | If multiple words are passed as keywords, they will all be | ||
1169 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
1170 | |||
1171 | Note that searching using | ||
1172 | |||
1173 | @example | ||
1174 | $ gnunet-search Das Kapital | ||
1175 | @end example | ||
1176 | |||
1177 | @noindent | ||
1178 | is not the same as searching for | ||
1179 | |||
1180 | @example | ||
1181 | $ gnunet-search "Das Kapital" | ||
1182 | @end example | ||
1183 | |||
1184 | @noindent | ||
1185 | as the first will match files shared under the keywords | ||
1186 | "Das" or "Kapital" whereas the second will match files | ||
1187 | shared under the keyword "Das Kapital". | ||
1188 | |||
1189 | Search 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 | ||
1199 | The first line is the command you would have to enter to download | ||
1200 | the file. The argument passed to @code{-o} is the suggested | ||
1201 | filename (you may change it to whatever you like). | ||
1202 | @c except it's triple dash in the above example --- | ||
1203 | The @code{--} is followed by key for decrypting the file, | ||
1204 | the query for searching the file, a checksum (in hexadecimal) | ||
1205 | finally the size of the file in bytes. | ||
1206 | The second line contains the description of the file; here this is | ||
1207 | "The GNU Public License" and the mime-type (see the options for | ||
1208 | gnunet-publish on how to specify these). | ||
1209 | |||
1210 | @node File-sharing Downloading | ||
1211 | @subsection File-sharing Downloading | ||
1212 | @c %**end of header | ||
1213 | |||
1214 | In order to download a file, you need the three values returned by | ||
1215 | @command{gnunet-search}. | ||
1216 | You 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 | ||
1223 | FILENAME specifies the name of the file where GNUnet is supposed | ||
1224 | to write the result. Existing files are overwritten. If the | ||
1225 | existing file contains blocks that are identical to the | ||
1226 | desired download, those blocks will not be downloaded again | ||
1227 | (automatic resume). | ||
1228 | |||
1229 | If you want to download the GPL from the previous example, | ||
1230 | you do the following: | ||
1231 | |||
1232 | @example | ||
1233 | $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992 | ||
1234 | @end example | ||
1235 | |||
1236 | @noindent | ||
1237 | If you ever have to abort a download, you can continue it at any time by | ||
1238 | re-issuing @command{gnunet-download} with the same filename. | ||
1239 | In that case, GNUnet will @strong{not} download blocks again that are | ||
1240 | already present. | ||
1241 | |||
1242 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
1243 | existing file was not downloaded from GNUnet in the first place. | ||
1244 | |||
1245 | You may want to use the @command{-V} switch (must be added before | ||
1246 | @c Same as above it's triple dash | ||
1247 | the @command{--}) to turn on verbose reporting. In this case, | ||
1248 | @command{gnunet-download} will print the current number of | ||
1249 | bytes 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 | ||
1255 | Directories are shared just like ordinary files. If you download a | 1056 | Directories are shared just like ordinary files. If you download a |
@@ -1264,8 +1065,8 @@ typically includes the mime-type, description, a filename and | |||
1264 | other meta information, and possibly even the full original file | 1065 | other 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 |
1437 | entry point into the namespace. | 1238 | entry point into the namespace. |
1438 | 1239 | ||
1240 | @node GTK User Interface | ||
1241 | @subsection GTK User Interface | ||
1242 | This chapter describes first steps for file-sharing with GNUnet. | ||
1243 | To start, you should launch @command{gnunet-fs-gtk}. | ||
1244 | |||
1245 | As we want to be sure that the network contains the data that we are | ||
1246 | looking 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 | |||
1258 | To publish a file, select "File Sharing" in the menu bar just below the | ||
1259 | "Statistics" icon, and then select "Publish" from the menu. | ||
1260 | |||
1261 | Afterwards, the following publishing dialog will appear: | ||
1262 | |||
1263 | @c Add image here | ||
1264 | |||
1265 | In this dialog, select the "Add File" button. This will open a | ||
1266 | file selection dialog: | ||
1267 | |||
1268 | @c Add image here | ||
1269 | |||
1270 | Now, you should select a file from your computer to be published on | ||
1271 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
1272 | PNG or JPEG file this time. You can leave all of the other options | ||
1273 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
1274 | button 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 | ||
1276 | you to really read anything. That dialog is showing you progress | ||
1277 | information as GNUnet takes a first look at the selected file(s). | ||
1278 | For a normal image, this is virtually instant, but if you later | ||
1279 | import a larger directory you might be interested in the progress dialog | ||
1280 | and potential errors that might be encountered during processing. | ||
1281 | After the progress dialog automatically disappears, your file | ||
1282 | should now appear in the publishing dialog: | ||
1283 | |||
1284 | @c Add image here | ||
1285 | |||
1286 | Now, select the file (by clicking on the file name) and then click | ||
1287 | the "Edit" button. This will open the editing dialog: | ||
1288 | |||
1289 | @c Add image here | ||
1290 | |||
1291 | In this dialog, you can see many details about your file. In the | ||
1292 | top left area, you can see meta data extracted about the file, | ||
1293 | such as the original filename, the mimetype and the size of the image. | ||
1294 | In the top right, you should see a preview for the image | ||
1295 | (if GNU libextractor was installed correctly with the | ||
1296 | respective plugins). Note that if you do not see a preview, this | ||
1297 | is not a disaster, but you might still want to install more of | ||
1298 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
1299 | a list of keywords. These are the keywords under which the file will be | ||
1300 | made available. The initial list will be based on the extracted meta data. | ||
1301 | Additional publishing options are in the right bottom corner. We will | ||
1302 | now add an additional keyword to the list of keywords. This is done by | ||
1303 | entering the keyword above the keyword list between the label "Keyword" | ||
1304 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
1305 | Note that the keyword will appear at the bottom of the existing keyword | ||
1306 | list, so you might have to scroll down to see it. Afterwards, push the | ||
1307 | "OK" button at the bottom right of the dialog. | ||
1308 | |||
1309 | You 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 | ||
1311 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
1312 | showing the list of published files (or ongoing publishing operations | ||
1313 | with progress indicators): | ||
1314 | |||
1315 | @c Add image here | ||
1316 | |||
1317 | @node gtk-Searching | ||
1318 | @subsubsection Searching | ||
1319 | @c %**end of header | ||
1320 | |||
1321 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
1322 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
1323 | widgets are used to control searching for files in GNUnet. Between the | ||
1324 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
1325 | which is used to initiate the search. We will ignore the "Namespace", | ||
1326 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
1327 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
1328 | Afterwards, you should immediately see a new tab labeled after your | ||
1329 | search term, followed by the (current) number of search | ||
1330 | results --- "(15)" in our screenshot. Note that your results may | ||
1331 | vary depending on what other users may have shared and how your | ||
1332 | peer is connected. | ||
1333 | |||
1334 | You can now select one of the search results. Once you do this, | ||
1335 | additional information about the result should be displayed on the | ||
1336 | right. If available, a preview image should appear on the top right. | ||
1337 | Meta data describing the file will be listed at the bottom right. | ||
1338 | |||
1339 | Once a file is selected, at the bottom of the search result list | ||
1340 | a little area for downloading appears. | ||
1341 | |||
1342 | @node gtk-Downloading | ||
1343 | @subsubsection Downloading | ||
1344 | @c %**end of header | ||
1345 | |||
1346 | In the downloading area, you can select the target directory (default is | ||
1347 | "Downloads") and specify the desired filename (by default the filename it | ||
1348 | taken from the meta data of the published file). Additionally, you can | ||
1349 | specify if the download should be anonynmous and (for directories) if | ||
1350 | the download should be recursive. In most cases, you can simply start | ||
1351 | the download with the "Download!" button. | ||
1352 | |||
1353 | Once you selected download, the progress of the download will be | ||
1354 | displayed with the search result. You may need to resize the result | ||
1355 | list or scroll to the right. The "Status" column shows the current | ||
1356 | status of the download, and "Progress" how much has been completed. | ||
1357 | When you close the search tab (by clicking on the "X" button next to | ||
1358 | the "test" label), ongoing and completed downloads are not aborted | ||
1359 | but moved to a special "*" tab. | ||
1360 | |||
1361 | You can remove completed downloads from the "*" tab by clicking the | ||
1362 | cleanup button next to the "*". You can also abort downloads by right | ||
1363 | clicking on the respective download and selecting "Abort download" | ||
1364 | from the menu. | ||
1365 | |||
1366 | That'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 | ||
2038 | If you also would like to use @command{gnunet-gtk} and | 1968 | If 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 | ||
2265 | If you operate a peer permanently connected to GNUnet you can configure | 2195 | If you operate a peer permanently connected to GNUnet you can configure |
2266 | your peer to act as a hostlist server, providing other peers the list of | 2196 | your peer to act as a hostlist server, providing other peers the list of |
2267 | peers known to it. | 2197 | peers known to him. |
2268 | 2198 | ||
2269 | Your server can act as a bootstrap server and peers needing to obtain a | 2199 | Your server can act as a bootstrap server and peers needing to obtain a |
2270 | list of peers can contact it to download this list. | 2200 | list 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 | ||
2885 | The HTTP plugin supports data transfer using reverse proxies. A reverse | 2815 | The HTTP plugin supports data transfer using reverse proxies. A reverse |
2886 | proxy forwards the HTTP request it receives with a certain URL to another | 2816 | proxy forwards the HTTP request he receives with a certain URL to another |
2887 | webserver, here a GNUnet peer. | 2817 | webserver, here a GNUnet peer. |
2888 | 2818 | ||
2889 | So if you have a running Apache or nginx webserver you can configure it to | 2819 | So 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 | |||
3619 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | 3549 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in |
3620 | sequence. | 3550 | sequence. |
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 | |||
3556 | This section describes a quick, casual way to check if your GNUnet | ||
3557 | installation works. However, if it does not, we do not cover | ||
3558 | steps for recovery --- for this, please study the instructions | ||
3559 | provided in the developer handbook as well as the system-specific | ||
3560 | instruction 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 | |||
3576 | The @command{gnunet-gtk} package contains several graphical | ||
3577 | user interfaces for the respective GNUnet applications. | ||
3578 | Currently 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 | |||
3593 | First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. | ||
3594 | You can do this from the command-line by typing | ||
3595 | |||
3596 | @example | ||
3597 | gnunet-statistics-gtk | ||
3598 | @end example | ||
3599 | |||
3600 | If 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''.} | ||
3601 | is running correctly, you should see a bunch of lines, | ||
3602 | all of which should be ``significantly'' above zero (at least if your | ||
3603 | peer has been running for more than a few seconds). The lines indicate | ||
3604 | how many other peers your peer is connected to (via different | ||
3605 | mechanisms) and how large the entire overlay network is currently | ||
3606 | estimated to be. The X-axis represents time (in seconds since the | ||
3607 | start of @command{gnunet-gtk}). | ||
3608 | |||
3609 | You can click on "Traffic" to see information about the amount of | ||
3610 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
3611 | of storage available and used by your peer. Note that "Traffic" is | ||
3612 | plotted cummulatively, so you should see a strict upwards trend in the | ||
3613 | traffic. | ||
3614 | |||
3615 | @node Peer Information | ||
3616 | @subsection Peer Information | ||
3617 | @c %**end of header | ||
3618 | |||
3619 | First, you should launch the graphical user interface. You can do | ||
3620 | this from the command-line by typing | ||
3621 | |||
3622 | @example | ||
3623 | $ gnunet-peerinfo-gtk | ||
3624 | @end example | ||
3625 | |||
3626 | Once you have done this, you will see a list of known peers (by the | ||
3627 | first four characters of their public key), their friend status (all | ||
3628 | should be marked as not-friends initially), their connectivity (green | ||
3629 | is connected, red is disconnected), assigned bandwidth, country of | ||
3630 | origin (if determined) and address information. If hardly any peers | ||
3631 | are listed and/or if there are very few peers with a green light for | ||
3632 | connectivity, there is likely a problem with your network | ||
3633 | configuration. | ||
3634 | |||
3635 | @node MOVE TO INSTALL Config Leftovers | ||
3636 | @section MOVE TO INSTALL Config Leftovers | ||
3624 | 3637 | ||
3625 | This section describes how to start a GNUnet peer. It assumes that you | 3638 | This section describes how to start a GNUnet peer. It assumes that you |
3626 | have already compiled and installed GNUnet and its' dependencies. | 3639 | have already compiled and installed GNUnet and its' dependencies. |
@@ -3949,3 +3962,4 @@ Furthermore, 'make install' will silently fail to set the DNS binaries to | |||
3949 | be owned by group "gnunetdns" unless that group already exists (!). | 3962 | be owned by group "gnunetdns" unless that group already exists (!). |
3950 | An alternative name for the "gnunetdns" group can be specified using the | 3963 | An 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 | |||