@menu
-* Checking the Installation::
-* First steps - File-sharing::
+* Start and stop GNUnet::
* First steps - Using the GNU Name System::
* First steps - Using GNUnet Conversation::
* First steps - Using the GNUnet VPN::
* File-sharing::
* The GNU Name System::
* Using the Virtual Public Network::
-* The graphical configuration interface::
-* How to start and stop a GNUnet peer::
+* MOVE TO INSTALL The graphical configuration interface::
+* MOVE TO INSTALL Checking the Installation::
+* MOVE TO INSTALL Config Leftovers::
@end menu
-@node Checking the Installation
-@section Checking the Installation
-@c %**end of header
-
-This section describes a quick, casual way to check if your GNUnet
-installation works. However, if it does not, we do not cover
-steps for recovery --- for this, please study the instructions
-provided in the developer handbook as well as the system-specific
-instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}.
-
-
-@menu
-* gnunet-gtk::
-* Statistics::
-* Peer Information::
-@end menu
-
-@cindex GNUnet GTK
-@cindex GTK
-@cindex GTK user interface
-@node gnunet-gtk
-@subsection gnunet-gtk
-@c %**end of header
-
-The @command{gnunet-gtk} package contains several graphical
-user interfaces for the respective GNUnet applications.
-Currently these interfaces cover:
-
-@itemize @bullet
-@item Statistics
-@item Peer Information
-@item GNU Name System
-@item File Sharing
-@item Identity Management
-@item Conversation
-@end itemize
-
-@node Statistics
-@subsection Statistics
-@c %**end of header
+@node Start and stop GNUnet
+@section Start and stop GNUnet
-First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}.
-You can do this from the command-line by typing
+To start GNUnet:
@example
-gnunet-statistics-gtk
+$ gnunet-arm -s -l gnunet.log
@end example
-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''.}
-is running correctly, you should see a bunch of lines,
-all of which should be ``significantly'' above zero (at least if your
-peer has been running for more than a few seconds). The lines indicate
-how many other peers your peer is connected to (via different
-mechanisms) and how large the entire overlay network is currently
-estimated to be. The X-axis represents time (in seconds since the
-start of @command{gnunet-gtk}).
-
-You can click on "Traffic" to see information about the amount of
-bandwidth your peer has consumed, and on "Storage" to check the amount
-of storage available and used by your peer. Note that "Traffic" is
-plotted cumulatively, so you should see a strict upwards trend in the
-traffic.
-
-@node Peer Information
-@subsection Peer Information
-@c %**end of header
-
-First, you should launch the graphical user interface. You can do
-this from the command-line by typing
+To stop GNUnet:
@example
-$ gnunet-peerinfo-gtk
+$ gnunet-arm -e
@end example
-
-Once you have done this, you will see a list of known peers (by the
-first four characters of their public key), their friend status (all
-should be marked as not-friends initially), their connectivity (green
-is connected, red is disconnected), assigned bandwidth, country of
-origin (if determined) and address information. If hardly any peers
-are listed and/or if there are very few peers with a green light for
-connectivity, there is likely a problem with your network
-configuration.
-
-@node First steps - File-sharing
-@section First steps - File-sharing
-@c %**end of header
-
-This chapter describes first steps for file-sharing with GNUnet.
-To start, you should launch @command{gnunet-fs-gtk}.
-
-As we want to be sure that the network contains the data that we are
-looking for for testing, we need to begin by publishing a file.
-
-
-@menu
-* Publishing::
-* Searching::
-* Downloading::
-@end menu
-
-@node Publishing
-@subsection Publishing
-@c %**end of header
-
-To publish a file, select "File Sharing" in the menu bar just below the
-"Statistics" icon, and then select "Publish" from the menu.
-
-Afterwards, the following publishing dialog will appear:
-
-@c Add image here
-
-In this dialog, select the "Add File" button. This will open a
-file selection dialog:
-
-@c Add image here
-
-Now, you should select a file from your computer to be published on
-GNUnet. To see more of GNUnet's features later, you should pick a
-PNG or JPEG file this time. You can leave all of the other options
-in the dialog unchanged. Confirm your selection by pressing the "OK"
-button in the bottom right corner. Now, you will briefly see a
-"Messages..." dialog pop up, but most likely it will be too short for
-you to really read anything. That dialog is showing you progress
-information as GNUnet takes a first look at the selected file(s).
-For a normal image, this is virtually instant, but if you later
-import a larger directory you might be interested in the progress dialog
-and potential errors that might be encountered during processing.
-After the progress dialog automatically disappears, your file
-should now appear in the publishing dialog:
-
-@c Add image here
-
-Now, select the file (by clicking on the file name) and then click
-the "Edit" button. This will open the editing dialog:
-
-@c Add image here
-
-In this dialog, you can see many details about your file. In the
-top left area, you can see meta data extracted about the file,
-such as the original filename, the mimetype and the size of the image.
-In the top right, you should see a preview for the image
-(if GNU libextractor was installed correctly with the
-respective plugins). Note that if you do not see a preview, this
-is not a disaster, but you might still want to install more of
-GNU libextractor in the future. In the bottom left, the dialog contains
-a list of keywords. These are the keywords under which the file will be
-made available. The initial list will be based on the extracted meta data.
-Additional publishing options are in the right bottom corner. We will
-now add an additional keyword to the list of keywords. This is done by
-entering the keyword above the keyword list between the label "Keyword"
-and the "Add keyword" button. Enter "test" and select "Add keyword".
-Note that the keyword will appear at the bottom of the existing keyword
-list, so you might have to scroll down to see it. Afterwards, push the
-"OK" button at the bottom right of the dialog.
-
-You should now be back at the "Publish content on GNUnet" dialog. Select
-"Execute" in the bottom right to close the dialog and publish your file
-on GNUnet! Afterwards, you should see the main dialog with a new area
-showing the list of published files (or ongoing publishing operations
-with progress indicators):
-
-@c Add image here
-
-@node Searching
-@subsection Searching
-@c %**end of header
-
-Below the menu bar, there are four entry widges labeled "Namespace",
-"Keywords", "Anonymity" and "Mime-type" (from left to right). These
-widgets are used to control searching for files in GNUnet. Between the
-"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
-which is used to initiate the search. We will ignore the "Namespace",
-"Anonymity" and "Mime-type" options in this tutorial, please leave them
-empty. Instead, simply enter "test" under "Keywords" and press "Search".
-Afterwards, you should immediately see a new tab labeled after your
-search term, followed by the (current) number of search
-results --- "(15)" in our screenshot. Note that your results may
-vary depending on what other users may have shared and how your
-peer is connected.
-
-You can now select one of the search results. Once you do this,
-additional information about the result should be displayed on the
-right. If available, a preview image should appear on the top right.
-Meta data describing the file will be listed at the bottom right.
-
-Once a file is selected, at the bottom of the search result list
-a little area for downloading appears.
-
-@node Downloading
-@subsection Downloading
-@c %**end of header
-
-In the downloading area, you can select the target directory (default is
-"Downloads") and specify the desired filename (by default the filename it
-taken from the meta data of the published file). Additionally, you can
-specify if the download should be anonymous and (for directories) if
-the download should be recursive. In most cases, you can simply start
-the download with the "Download!" button.
-
-Once you selected download, the progress of the download will be
-displayed with the search result. You may need to resize the result
-list or scroll to the right. The "Status" column shows the current
-status of the download, and "Progress" how much has been completed.
-When you close the search tab (by clicking on the "X" button next to
-the "test" label), ongoing and completed downloads are not aborted
-but moved to a special "*" tab.
-
-You can remove completed downloads from the "*" tab by clicking the
-cleanup button next to the "*". You can also abort downloads by right
-clicking on the respective download and selecting "Abort download"
-from the menu.
-
-That's it, you now know the basics for file-sharing with GNUnet!
-
@node First steps - Using the GNU Name System
@section First steps - Using the GNU Name System
@c %**end of header
@subsection The GNS Tab
@c %**end of header
-Maintaining your zones is through the NAMESTORE service and is discussed
+Maintaing your zones is through the NAMESTORE service and is discussed
here. You can manage your zone using @command{gnunet-identity} and
@command{gnunet-namestore}, or most conveniently using
@command{gnunet-namestore-gtk}.
how they impact users that publish, search or download files.
-
@menu
-* File-sharing Concepts::
-* File-sharing Publishing::
-* File-sharing Searching::
-* File-sharing Downloading::
-* File-sharing Directories::
-* File-sharing Namespace Management::
+* fs-Searching::
+* fs-Downloading::
+* fs-Publishing::
+* fs-Concepts::
+* fs-Directories::
+* Namespace Management::
* File-Sharing URIs::
+* GTK User Interface::
@end menu
-@node File-sharing Concepts
-@subsection File-sharing Concepts
+@node fs-Searching
+@subsection Searching
@c %**end of header
-Sharing files in GNUnet is not quite as simple as in traditional
-file sharing systems. For example, it is not sufficient to just
-place files into a specific directory to share them. In addition
-to anonymous routing GNUnet attempts to give users a better experience
-in searching for content. GNUnet uses cryptography to safely break
-content into smaller pieces that can be obtained from different
-sources without allowing participants to corrupt files. GNUnet
-makes it difficult for an adversary to send back bogus search
-results. GNUnet enables content providers to group related content
-and to establish a reputation. Furthermore, GNUnet allows updates
-to certain content to be made available. This section is supposed
-to introduce users to the concepts that are used to achive these goals.
+The command @command{gnunet-search} can be used to search
+for content on GNUnet. The format is:
+@example
+$ gnunet-search [-t TIMEOUT] KEYWORD
+@end example
-@menu
-* Files::
-* Keywords::
-* Directories::
-* Pseudonyms::
-* Namespaces::
-* Advertisements::
-* Anonymity level::
-* Content Priority::
-* Replication::
-@end menu
+@noindent
+The -t option specifies that the query should timeout after
+approximately TIMEOUT seconds. A value of zero is interpreted
+as @emph{no timeout}, which is also the default. In this case,
+gnunet-search will never terminate (unless you press CTRL-C).
-@node Files
-@subsubsection Files
-@c %**end of header
+If multiple words are passed as keywords, they will all be
+considered optional. Prefix keywords with a "+" to make them mandatory.
-A file in GNUnet is just a sequence of bytes. Any file-format is allowed
-and the maximum file size is theoretically 264 bytes, except that it
-would take an impractical amount of time to share such a file.
-GNUnet itself never interprets the contents of shared files, except
-when using GNU libextractor to obtain keywords.
+Note that searching using
-@node Keywords
-@subsubsection Keywords
-@c %**end of header
+@example
+$ gnunet-search Das Kapital
+@end example
-Keywords are the most simple mechanism to find files on GNUnet.
-Keywords are @strong{case-sensitive} and the search string
-must always match @strong{exactly} the keyword used by the
-person providing the file. Keywords are never transmitted in
-plaintext. The only way for an adversary to determine the keyword
-that you used to search is to guess it (which then allows the
-adversary to produce the same search request). Since providing
-keywords by hand for each shared file is tedious, GNUnet uses
-GNU libextractor to help automate this process. Starting a
-keyword search on a slow machine can take a little while since
-the keyword search involves computing a fresh RSA key to formulate the
-request.
-
-@node Directories
-@subsubsection Directories
-@c %**end of header
-
-A directory in GNUnet is a list of file identifiers with meta data.
-The file identifiers provide sufficient information about the files
-to allow downloading the contents. Once a directory has been created,
-it cannot be changed since it is treated just like an ordinary file
-by the network. Small files (of a few kilobytes) can be inlined in
-the directory, so that a separate download becomes unnecessary.
+@noindent
+is not the same as searching for
-@node Pseudonyms
-@subsubsection Pseudonyms
-@c %**end of header
+@example
+$ gnunet-search "Das Kapital"
+@end example
-Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
-that allow a GNUnet user to maintain an identity (which may or may not
-be detached from their real-life identity). GNUnet's pseudonyms are not
-file-sharing specific --- and they will likely be used by many GNUnet
-applications where a user identity is required.
+@noindent
+as the first will match files shared under the keywords
+"Das" or "Kapital" whereas the second will match files
+shared under the keyword "Das Kapital".
-Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
-pseudonyms for a single user, and users could (theoretically) share the
-private pseudonym keys (currently only out-of-band by knowing which files
-to copy around).
+Search results are printed by gnunet-search like this:
-@node Namespaces
-@subsubsection Namespaces
-@c %**end of header
+@c it will be better the avoid the ellipsis altogether because I don't
+@c understand the explanation below that
+@example
+$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
+=> The GNU Public License <= (mimetype: text/plain)
+@end example
-A namespace is a set of files that were signed by the same pseudonym.
-Files (or directories) that have been signed and placed into a namespace
-can be updated. Updates are identified as authentic if the same secret
-key was used to sign the update. Namespaces are also useful to establish
-a reputation, since all of the content in the namespace comes from the
-same entity (which does not have to be the same person).
+@noindent
+The first line is the command you would have to enter to download
+the file. The argument passed to @code{-o} is the suggested
+filename (you may change it to whatever you like).
+@c except it's triple dash in the above example ---
+The @code{--} is followed by key for decrypting the file,
+the query for searching the file, a checksum (in hexadecimal)
+finally the size of the file in bytes.
+The second line contains the description of the file; here this is
+"The GNU Public License" and the mime-type (see the options for
+gnunet-publish on how to specify these).
-@node Advertisements
-@subsubsection Advertisements
+@node fs-Downloading
+@subsection Downloading
@c %**end of header
-Advertisements are used to notify other users about the existence of a
-namespace. Advertisements are propagated using the normal keyword search.
-When an advertisement is received (in response to a search), the namespace
-is added to the list of namespaces available in the namespace-search
-dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
-namespace is created, an appropriate advertisement can be generated.
-The default keyword for the advertising of namespaces is "namespace".
+In order to download a file, you need the three values returned by
+@command{gnunet-search}.
+You can then use the tool @command{gnunet-download} to obtain the file:
-Note that GNUnet differenciates between your pseudonyms (the identities
-that you control) and namespaces. If you create a pseudonym, you will
-not automatically see the respective namespace. You first have to create
-an advertisement for the namespace and find it using keyword
-search --- even for your own namespaces. The @command{gnunet-pseudonym}
-tool is currently responsible for both managing pseudonyms and namespaces.
-This will likely change in the future to reduce the potential for
-confusion.
+@example
+$ gnunet-download -o FILENAME --- GNUNETURL
+@end example
-@node Anonymity level
-@subsubsection Anonymity level
-@c %**end of header
+@noindent
+FILENAME specifies the name of the file where GNUnet is supposed
+to write the result. Existing files are overwritten. If the
+existing file contains blocks that are identical to the
+desired download, those blocks will not be downloaded again
+(automatic resume).
-The anonymity level determines how hard it should be for an adversary to
-determine the identity of the publisher or the searcher/downloader. An
-anonymity level of zero means that anonymity is not required. The default
-anonymity level of "1" means that anonymous routing is desired, but no
-particular amount of cover traffic is necessary. A powerful adversary
-might thus still be able to deduce the origin of the traffic using
-traffic analysis. Specifying higher anonymity levels increases the
-amount of cover traffic required. While this offers better privacy,
-it can also significantly hurt performance.
+If you want to download the GPL from the previous example,
+you do the following:
-@node Content Priority
-@subsubsection Content Priority
-@c %**end of header
+@example
+$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
+@end example
-Depending on the peer's configuration, GNUnet peers migrate content
-between peers. Content in this sense are individual blocks of a file,
-not necessarily entire files. When peers run out of space (due to
-local publishing operations or due to migration of content from other
-peers), blocks sometimes need to be discarded. GNUnet first always
-discards expired blocks (typically, blocks are published with an
-expiration of about two years in the future; this is another option).
-If there is still not enough space, GNUnet discards the blocks with the
-lowest priority. The priority of a block is decided by its popularity
-(in terms of requests from peers we trust) and, in case of blocks
-published locally, the base-priority that was specified by the user
-when the block was published initially.
+@noindent
+If you ever have to abort a download, you can continue it at any time by
+re-issuing @command{gnunet-download} with the same filename.
+In that case, GNUnet will @strong{not} download blocks again that are
+already present.
-@node Replication
-@subsubsection Replication
-@c %**end of header
+GNUnet's file-encoding mechanism will ensure file integrity, even if the
+existing file was not downloaded from GNUnet in the first place.
-When peers migrate content to other systems, the replication level
-of a block is used to decide which blocks need to be migrated most
-urgently. GNUnet will always push the block with the highest
-replication level into the network, and then decrement the replication
-level by one. If all blocks reach replication level zero, the
-selection is simply random.
+You may want to use the @command{-V} switch (must be added before
+@c Same as above it's triple dash
+the @command{--}) to turn on verbose reporting. In this case,
+@command{gnunet-download} will print the current number of
+bytes downloaded whenever new data was received.
-@node File-sharing Publishing
-@subsection File-sharing Publishing
+@node fs-Publishing
+@subsection Publishing
@c %**end of header
The command @command{gnunet-publish} can be used to add content
even if it is still (encrypted) on the drive and the adversary is
able to crack the encryption (e.g. by guessing the keyword.
-@node File-sharing Searching
-@subsection File-sharing Searching
+@node fs-Concepts
+@subsection Concepts
@c %**end of header
-The command @command{gnunet-search} can be used to search
-for content on GNUnet. The format is:
+Sharing files in GNUnet is not quite as simple as in traditional
+file sharing systems. For example, it is not sufficient to just
+place files into a specific directory to share them. In addition
+to anonymous routing GNUnet attempts to give users a better experience
+in searching for content. GNUnet uses cryptography to safely break
+content into smaller pieces that can be obtained from different
+sources without allowing participants to corrupt files. GNUnet
+makes it difficult for an adversary to send back bogus search
+results. GNUnet enables content providers to group related content
+and to establish a reputation. Furthermore, GNUnet allows updates
+to certain content to be made available. This section is supposed
+to introduce users to the concepts that are used to achive these goals.
-@example
-$ gnunet-search [-t TIMEOUT] KEYWORD
-@end example
-@noindent
-The -t option specifies that the query should timeout after
-approximately TIMEOUT seconds. A value of zero is interpreted
-as @emph{no timeout}, which is also the default. In this case,
-gnunet-search will never terminate (unless you press CTRL-C).
+@menu
+* Files::
+* Keywords::
+* Directories::
+* Pseudonyms::
+* Namespaces::
+* Advertisements::
+* Anonymity level::
+* Content Priority::
+* Replication::
+@end menu
-If multiple words are passed as keywords, they will all be
-considered optional. Prefix keywords with a "+" to make them mandatory.
+@node Files
+@subsubsection Files
+@c %**end of header
-Note that searching using
+A file in GNUnet is just a sequence of bytes. Any file-format is allowed
+and the maximum file size is theoretically 264 bytes, except that it
+would take an impractical amount of time to share such a file.
+GNUnet itself never interprets the contents of shared files, except
+when using GNU libextractor to obtain keywords.
-@example
-$ gnunet-search Das Kapital
-@end example
+@node Keywords
+@subsubsection Keywords
+@c %**end of header
-@noindent
-is not the same as searching for
+Keywords are the most simple mechanism to find files on GNUnet.
+Keywords are @strong{case-sensitive} and the search string
+must always match @strong{exactly} the keyword used by the
+person providing the file. Keywords are never transmitted in
+plaintext. The only way for an adversary to determine the keyword
+that you used to search is to guess it (which then allows the
+adversary to produce the same search request). Since providing
+keywords by hand for each shared file is tedious, GNUnet uses
+GNU libextractor to help automate this process. Starting a
+keyword search on a slow machine can take a little while since
+the keyword search involves computing a fresh RSA key to formulate the
+request.
-@example
-$ gnunet-search "Das Kapital"
-@end example
+@node Directories
+@subsubsection Directories
+@c %**end of header
-@noindent
-as the first will match files shared under the keywords
-"Das" or "Kapital" whereas the second will match files
-shared under the keyword "Das Kapital".
+A directory in GNUnet is a list of file identifiers with meta data.
+The file identifiers provide sufficient information about the files
+to allow downloading the contents. Once a directory has been created,
+it cannot be changed since it is treated just like an ordinary file
+by the network. Small files (of a few kilobytes) can be inlined in
+the directory, so that a separate download becomes unnecessary.
-Search results are printed by gnunet-search like this:
+@node Pseudonyms
+@subsubsection Pseudonyms
+@c %**end of header
-@c it will be better the avoid the ellipsis altogether because I don't
-@c understand the explanation below that
-@example
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
-=> The GNU Public License <= (mimetype: text/plain)
-@end example
+Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
+that allow a GNUnet user to maintain an identity (which may or may not
+be detached from their real-life identity). GNUnet's pseudonyms are not
+file-sharing specific --- and they will likely be used by many GNUnet
+applications where a user identity is required.
-@noindent
-The first line is the command you would have to enter to download
-the file. The argument passed to @code{-o} is the suggested
-filename (you may change it to whatever you like).
-@c except it's triple dash in the above example ---
-The @code{--} is followed by key for decrypting the file,
-the query for searching the file, a checksum (in hexadecimal)
-finally the size of the file in bytes.
-The second line contains the description of the file; here this is
-"The GNU Public License" and the mime-type (see the options for
-gnunet-publish on how to specify these).
+Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
+pseudonyms for a single user, and users could (theoretically) share the
+private pseudonym keys (currently only out-of-band by knowing which files
+to copy around).
-@node File-sharing Downloading
-@subsection File-sharing Downloading
+@node Namespaces
+@subsubsection Namespaces
@c %**end of header
-In order to download a file, you need the three values returned by
-@command{gnunet-search}.
-You can then use the tool @command{gnunet-download} to obtain the file:
+A namespace is a set of files that were signed by the same pseudonym.
+Files (or directories) that have been signed and placed into a namespace
+can be updated. Updates are identified as authentic if the same secret
+key was used to sign the update. Namespaces are also useful to establish
+a reputation, since all of the content in the namespace comes from the
+same entity (which does not have to be the same person).
-@example
-$ gnunet-download -o FILENAME --- GNUNETURL
-@end example
+@node Advertisements
+@subsubsection Advertisements
+@c %**end of header
+
+Advertisements are used to notify other users about the existence of a
+namespace. Advertisements are propagated using the normal keyword search.
+When an advertisement is received (in response to a search), the namespace
+is added to the list of namespaces available in the namespace-search
+dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
+namespace is created, an appropriate advertisement can be generated.
+The default keyword for the advertising of namespaces is "namespace".
+
+Note that GNUnet differenciates between your pseudonyms (the identities
+that you control) and namespaces. If you create a pseudonym, you will
+not automatically see the respective namespace. You first have to create
+an advertisement for the namespace and find it using keyword
+search --- even for your own namespaces. The @command{gnunet-pseudonym}
+tool is currently responsible for both managing pseudonyms and namespaces.
+This will likely change in the future to reduce the potential for
+confusion.
+
+@node Anonymity level
+@subsubsection Anonymity level
+@c %**end of header
-@noindent
-FILENAME specifies the name of the file where GNUnet is supposed
-to write the result. Existing files are overwritten. If the
-existing file contains blocks that are identical to the
-desired download, those blocks will not be downloaded again
-(automatic resume).
+The anonymity level determines how hard it should be for an adversary to
+determine the identity of the publisher or the searcher/downloader. An
+anonymity level of zero means that anonymity is not required. The default
+anonymity level of "1" means that anonymous routing is desired, but no
+particular amount of cover traffic is necessary. A powerful adversary
+might thus still be able to deduce the origin of the traffic using
+traffic analysis. Specifying higher anonymity levels increases the
+amount of cover traffic required. While this offers better privacy,
+it can also significantly hurt performance.
-If you want to download the GPL from the previous example,
-you do the following:
+@node Content Priority
+@subsubsection Content Priority
+@c %**end of header
-@example
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
-@end example
+Depending on the peer's configuration, GNUnet peers migrate content
+between peers. Content in this sense are individual blocks of a file,
+not necessarily entire files. When peers run out of space (due to
+local publishing operations or due to migration of content from other
+peers), blocks sometimes need to be discarded. GNUnet first always
+discards expired blocks (typically, blocks are published with an
+expiration of about two years in the future; this is another option).
+If there is still not enough space, GNUnet discards the blocks with the
+lowest priority. The priority of a block is decided by its popularity
+(in terms of requests from peers we trust) and, in case of blocks
+published locally, the base-priority that was specified by the user
+when the block was published initially.
-@noindent
-If you ever have to abort a download, you can continue it at any time by
-re-issuing @command{gnunet-download} with the same filename.
-In that case, GNUnet will @strong{not} download blocks again that are
-already present.
+@node Replication
+@subsubsection Replication
+@c %**end of header
-GNUnet's file-encoding mechanism will ensure file integrity, even if the
-existing file was not downloaded from GNUnet in the first place.
+When peers migrate content to other systems, the replication level
+of a block is used to decide which blocks need to be migrated most
+urgently. GNUnet will always push the block with the highest
+replication level into the network, and then decrement the replication
+level by one. If all blocks reach replication level zero, the
+selection is simply random.
-You may want to use the @command{-V} switch (must be added before
-@c Same as above it's triple dash
-the @command{--}) to turn on verbose reporting. In this case,
-@command{gnunet-download} will print the current number of
-bytes downloaded whenever new data was received.
-@node File-sharing Directories
-@subsection File-sharing Directories
+@node fs-Directories
+@subsection Directories
@c %**end of header
Directories are shared just like ordinary files. If you download a
other meta information, and possibly even the full original file
(if it was small).
-@node File-sharing Namespace Management
-@subsection File-sharing Namespace Management
+@node Namespace Management
+@subsection Namespace Management
@c %**end of header
@b{Please note that the text in this subsection is outdated and needs}
"root" which by convention refers to some kind of index or other
entry point into the namespace.
+@node GTK User Interface
+@subsection GTK User Interface
+This chapter describes first steps for file-sharing with GNUnet.
+To start, you should launch @command{gnunet-fs-gtk}.
+
+As we want to be sure that the network contains the data that we are
+looking for for testing, we need to begin by publishing a file.
+
+@menu
+* gtk-Publishing::
+* gtk-Searching::
+* gtk-Downloading::
+@end menu
+
+@node gtk-Publishing
+@subsubsection Publishing
+@c %**end of header
+
+To publish a file, select "File Sharing" in the menu bar just below the
+"Statistics" icon, and then select "Publish" from the menu.
+
+Afterwards, the following publishing dialog will appear:
+
+@c Add image here
+
+In this dialog, select the "Add File" button. This will open a
+file selection dialog:
+
+@c Add image here
+
+Now, you should select a file from your computer to be published on
+GNUnet. To see more of GNUnet's features later, you should pick a
+PNG or JPEG file this time. You can leave all of the other options
+in the dialog unchanged. Confirm your selection by pressing the "OK"
+button in the bottom right corner. Now, you will briefly see a
+"Messages..." dialog pop up, but most likely it will be too short for
+you to really read anything. That dialog is showing you progress
+information as GNUnet takes a first look at the selected file(s).
+For a normal image, this is virtually instant, but if you later
+import a larger directory you might be interested in the progress dialog
+and potential errors that might be encountered during processing.
+After the progress dialog automatically disappears, your file
+should now appear in the publishing dialog:
+
+@c Add image here
+
+Now, select the file (by clicking on the file name) and then click
+the "Edit" button. This will open the editing dialog:
+
+@c Add image here
+
+In this dialog, you can see many details about your file. In the
+top left area, you can see meta data extracted about the file,
+such as the original filename, the mimetype and the size of the image.
+In the top right, you should see a preview for the image
+(if GNU libextractor was installed correctly with the
+respective plugins). Note that if you do not see a preview, this
+is not a disaster, but you might still want to install more of
+GNU libextractor in the future. In the bottom left, the dialog contains
+a list of keywords. These are the keywords under which the file will be
+made available. The initial list will be based on the extracted meta data.
+Additional publishing options are in the right bottom corner. We will
+now add an additional keyword to the list of keywords. This is done by
+entering the keyword above the keyword list between the label "Keyword"
+and the "Add keyword" button. Enter "test" and select "Add keyword".
+Note that the keyword will appear at the bottom of the existing keyword
+list, so you might have to scroll down to see it. Afterwards, push the
+"OK" button at the bottom right of the dialog.
+
+You should now be back at the "Publish content on GNUnet" dialog. Select
+"Execute" in the bottom right to close the dialog and publish your file
+on GNUnet! Afterwards, you should see the main dialog with a new area
+showing the list of published files (or ongoing publishing operations
+with progress indicators):
+
+@c Add image here
+
+@node gtk-Searching
+@subsubsection Searching
+@c %**end of header
+
+Below the menu bar, there are four entry widges labeled "Namespace",
+"Keywords", "Anonymity" and "Mime-type" (from left to right). These
+widgets are used to control searching for files in GNUnet. Between the
+"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
+which is used to initiate the search. We will ignore the "Namespace",
+"Anonymity" and "Mime-type" options in this tutorial, please leave them
+empty. Instead, simply enter "test" under "Keywords" and press "Search".
+Afterwards, you should immediately see a new tab labeled after your
+search term, followed by the (current) number of search
+results --- "(15)" in our screenshot. Note that your results may
+vary depending on what other users may have shared and how your
+peer is connected.
+
+You can now select one of the search results. Once you do this,
+additional information about the result should be displayed on the
+right. If available, a preview image should appear on the top right.
+Meta data describing the file will be listed at the bottom right.
+
+Once a file is selected, at the bottom of the search result list
+a little area for downloading appears.
+
+@node gtk-Downloading
+@subsubsection Downloading
+@c %**end of header
+
+In the downloading area, you can select the target directory (default is
+"Downloads") and specify the desired filename (by default the filename it
+taken from the meta data of the published file). Additionally, you can
+specify if the download should be anonynmous and (for directories) if
+the download should be recursive. In most cases, you can simply start
+the download with the "Download!" button.
+
+Once you selected download, the progress of the download will be
+displayed with the search result. You may need to resize the result
+list or scroll to the right. The "Status" column shows the current
+status of the download, and "Progress" how much has been completed.
+When you close the search tab (by clicking on the "X" button next to
+the "test" label), ongoing and completed downloads are not aborted
+but moved to a special "*" tab.
+
+You can remove completed downloads from the "*" tab by clicking the
+cleanup button next to the "*". You can also abort downloads by right
+clicking on the respective download and selecting "Abort download"
+from the menu.
+
+That's it, you now know the basics for file-sharing with GNUnet!
+
+
@node The GNU Name System
@section The GNU Name System
@c %**end of header
@c NOTE: Inserted from Installation Handbook in original ``order'':
@c FIXME: Move this to User Handbook.
-@node The graphical configuration interface
-@section The graphical configuration interface
+@node MOVE TO INSTALL The graphical configuration interface
+@section MOVE TO INSTALL The graphical configuration interface
If you also would like to use @command{gnunet-gtk} and
@command{gnunet-setup} (highly recommended for beginners), do:
If you operate a peer permanently connected to GNUnet you can configure
your peer to act as a hostlist server, providing other peers the list of
-peers known to it.
+peers known to him.
Your server can act as a bootstrap server and peers needing to obtain a
list of peers can contact it to download this list.
@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
The HTTP plugin supports data transfer using reverse proxies. A reverse
-proxy forwards the HTTP request it receives with a certain URL to another
+proxy forwards the HTTP request he receives with a certain URL to another
webserver, here a GNUnet peer.
So if you have a running Apache or nginx webserver you can configure it to
and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
sequence.
-@node How to start and stop a GNUnet peer
-@section How to start and stop a GNUnet peer
+@node MOVE TO INSTALL Checking the Installation
+@section MOVE TO INSTALL Checking the Installation
+@c %**end of header
+
+This section describes a quick, casual way to check if your GNUnet
+installation works. However, if it does not, we do not cover
+steps for recovery --- for this, please study the instructions
+provided in the developer handbook as well as the system-specific
+instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}.
+
+
+@menu
+* gnunet-gtk::
+* Statistics::
+* Peer Information::
+@end menu
+
+@cindex GNUnet GTK
+@cindex GTK
+@cindex GTK user interface
+@node gnunet-gtk
+@subsection gnunet-gtk
+@c %**end of header
+
+The @command{gnunet-gtk} package contains several graphical
+user interfaces for the respective GNUnet applications.
+Currently these interfaces cover:
+
+@itemize @bullet
+@item Statistics
+@item Peer Information
+@item GNU Name System
+@item File Sharing
+@item Identity Management
+@item Conversation
+@end itemize
+
+@node Statistics
+@subsection Statistics
+@c %**end of header
+
+First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}.
+You can do this from the command-line by typing
+
+@example
+gnunet-statistics-gtk
+@end example
+
+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''.}
+is running correctly, you should see a bunch of lines,
+all of which should be ``significantly'' above zero (at least if your
+peer has been running for more than a few seconds). The lines indicate
+how many other peers your peer is connected to (via different
+mechanisms) and how large the entire overlay network is currently
+estimated to be. The X-axis represents time (in seconds since the
+start of @command{gnunet-gtk}).
+
+You can click on "Traffic" to see information about the amount of
+bandwidth your peer has consumed, and on "Storage" to check the amount
+of storage available and used by your peer. Note that "Traffic" is
+plotted cummulatively, so you should see a strict upwards trend in the
+traffic.
+
+@node Peer Information
+@subsection Peer Information
+@c %**end of header
+
+First, you should launch the graphical user interface. You can do
+this from the command-line by typing
+
+@example
+$ gnunet-peerinfo-gtk
+@end example
+
+Once you have done this, you will see a list of known peers (by the
+first four characters of their public key), their friend status (all
+should be marked as not-friends initially), their connectivity (green
+is connected, red is disconnected), assigned bandwidth, country of
+origin (if determined) and address information. If hardly any peers
+are listed and/or if there are very few peers with a green light for
+connectivity, there is likely a problem with your network
+configuration.
+
+@node MOVE TO INSTALL Config Leftovers
+@section MOVE TO INSTALL Config Leftovers
This section describes how to start a GNUnet peer. It assumes that you
have already compiled and installed GNUnet and its' dependencies.
be owned by group "gnunetdns" unless that group already exists (!).
An alternative name for the "gnunetdns" group can be specified using the
@code{--with-gnunetdns=GRPNAME} configure option.
+
projects / oweals / gnunet.git / commitdiff