diff options
author | ng0 <ng0@infotropique.org> | 2017-10-18 15:29:02 +0000 |
---|---|---|
committer | ng0 <ng0@infotropique.org> | 2017-10-18 15:29:02 +0000 |
commit | 4f99b2f88095dd632f72a7c76b5b0a213e0c6679 (patch) | |
tree | d775754ad02aaee748bd4596091aabdd4cab294a | |
parent | 7d624c472ac3f0c2c4df16efef25f3f25aabcc45 (diff) | |
download | gnunet-4f99b2f88095dd632f72a7c76b5b0a213e0c6679.tar.gz gnunet-4f99b2f88095dd632f72a7c76b5b0a213e0c6679.zip |
mostly gnunet-c-tutorial changes.
-rw-r--r-- | doc/Makefile.am | 22 | ||||
-rw-r--r-- | doc/gnunet-c-tutorial.texi | 569 | ||||
-rw-r--r-- | doc/tutorial-examples/003.c | 10 |
3 files changed, 399 insertions, 202 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index d9a68d533..feb0f0715 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am | |||
@@ -155,21 +155,29 @@ version.texi: | |||
155 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ | 155 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ |
156 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ | 156 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ |
157 | echo "@set EDITION $(PACKAGE_VERSION)" >> $@ | 157 | echo "@set EDITION $(PACKAGE_VERSION)" >> $@ |
158 | echo "@set VERSION $(PACKAGE_VERSION)" >> $@ | 158 | echo "@set VERSION $(PACKAGE_VERSION)" >> $@ |
159 | |||
160 | # Workaround for makeinfo error. Whcih in turn introduces more | ||
161 | # date-related 'warnings'. Well. | ||
162 | version2.texi: | ||
163 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ | ||
164 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ | ||
165 | echo "@set EDITION $(PACKAGE_VERSION)" >> $@ | ||
166 | echo "@set VERSION $(PACKAGE_VERSION)" >> $@ | ||
159 | 167 | ||
160 | doc-pdf: version.texi | 168 | doc-pdf: version.texi |
161 | @makeinfo --pdf --quiet gnunet.texi | 169 | @makeinfo --pdf --quiet gnunet.texi |
162 | doc-pdf-tutorial: version.texi | 170 | doc-pdf-tutorial: version.texi version2.texi |
163 | @makeinfo --pdf --quiet gnunet-c-tutorial.texi | 171 | @makeinfo --pdf --quiet gnunet-c-tutorial.texi |
164 | 172 | ||
165 | doc-html: version.texi | 173 | doc-html: version.texi |
166 | @makeinfo --html gnunet.texi | 174 | @makeinfo --html gnunet.texi |
167 | doc-html-tutorial: version.texi | 175 | doc-html-tutorial: version.texi version2.texi |
168 | @makeinfo --html gnunet-c-tutorial.texi | 176 | @makeinfo --html gnunet-c-tutorial.texi |
169 | 177 | ||
170 | doc-info: version.texi | 178 | doc-info: version.texi |
171 | @makeinfo --no-split gnunet.texi | 179 | @makeinfo --no-split gnunet.texi |
172 | doc-info-tutorial: version.texi | 180 | doc-info-tutorial: version.texi version2.texi |
173 | @makeinfo --no-split gnunet-c-tutorial.texi | 181 | @makeinfo --no-split gnunet-c-tutorial.texi |
174 | 182 | ||
175 | # FIXME: rm *.html and *.pdf | 183 | # FIXME: rm *.html and *.pdf |
@@ -180,17 +188,17 @@ doc-all: doc-pdf doc-html doc-info doc-pdf-tutorial doc-html-tutorial doc-info-t | |||
180 | 188 | ||
181 | doc-pdf-noise: version.texi | 189 | doc-pdf-noise: version.texi |
182 | @makeinfo --pdf gnunet.texi | 190 | @makeinfo --pdf gnunet.texi |
183 | doc-pdf-tutorial-noise: version.texi | 191 | doc-pdf-tutorial-noise: version.texi version2.texi |
184 | @makeinfo --pdf gnunet-c-tutorial.texi | 192 | @makeinfo --pdf gnunet-c-tutorial.texi |
185 | 193 | ||
186 | doc-html-noise: version.texi | 194 | doc-html-noise: version.texi |
187 | @makeinfo --html gnunet.texi | 195 | @makeinfo --html gnunet.texi |
188 | doc-html-tutorial-noise: version.texi | 196 | doc-html-tutorial-noise: version.texi version2.texi |
189 | @makeinfo --html gnunet-c-tutorial.texi | 197 | @makeinfo --html gnunet-c-tutorial.texi |
190 | 198 | ||
191 | doc-info-noise: version.texi | 199 | doc-info-noise: version.texi |
192 | @makeinfo --no-split gnunet.texi | 200 | @makeinfo --no-split gnunet.texi |
193 | doc-info-tutorial-noise: version.texi | 201 | doc-info-tutorial-noise: version.texi version2.texi |
194 | @makeinfo --no-split gnunet-c-tutorial.texi | 202 | @makeinfo --no-split gnunet-c-tutorial.texi |
195 | 203 | ||
196 | doc-all-give-me-the-noise: doc-pdf-noise doc-html-noise doc-info-noise doc-pdf-tutorial-noise doc-html-tutorial-noise doc-info-tutorial-noise | 204 | doc-all-give-me-the-noise: doc-pdf-noise doc-html-noise doc-info-noise doc-pdf-tutorial-noise doc-html-tutorial-noise doc-info-tutorial-noise |
diff --git a/doc/gnunet-c-tutorial.texi b/doc/gnunet-c-tutorial.texi index 3a4200d7c..2e3069638 100644 --- a/doc/gnunet-c-tutorial.texi +++ b/doc/gnunet-c-tutorial.texi | |||
@@ -5,6 +5,9 @@ | |||
5 | @settitle GNUnet C Tutorial | 5 | @settitle GNUnet C Tutorial |
6 | @c %**end of header | 6 | @c %**end of header |
7 | 7 | ||
8 | @c including 'version.texi' makes makeinfo throw errors. | ||
9 | @include version2.texi | ||
10 | |||
8 | @copying | 11 | @copying |
9 | Copyright @copyright{} 2001-2017 GNUnet e.V. | 12 | Copyright @copyright{} 2001-2017 GNUnet e.V. |
10 | 13 | ||
@@ -29,7 +32,7 @@ Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. | |||
29 | 32 | ||
30 | @titlepage | 33 | @titlepage |
31 | @title GNUnet C Tutorial | 34 | @title GNUnet C Tutorial |
32 | @subtitle A Tutorial for GNUnet 0.10.x (C version) | 35 | @subtitle A Tutorial for GNUnet @value{VERSION} (C version) |
33 | @author The GNUnet Developers | 36 | @author The GNUnet Developers |
34 | 37 | ||
35 | @page | 38 | @page |
@@ -48,10 +51,14 @@ Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. | |||
48 | @node Top | 51 | @node Top |
49 | @top Introduction | 52 | @top Introduction |
50 | 53 | ||
51 | This tutorials explains how to install GNUnet on a GNU/Linux system and gives an introduction on how | 54 | This tutorials explains how to install GNUnet on a |
52 | GNUnet can be used to develop a Peer-to-Peer application. Detailed installation instructions for | 55 | GNU/Linux system and gives an introduction on how |
53 | various operating systems and a detailed list of all dependencies can be found on our website at | 56 | GNUnet can be used to develop a Peer-to-Peer application. |
54 | @uref{https://gnunet.org/installation}. | 57 | Detailed installation instructions for |
58 | various operating systems and a detailed list of all | ||
59 | dependencies can be found on our website at | ||
60 | @uref{https://gnunet.org/installation} and in our | ||
61 | Reference Documentation (GNUnet Handbook). | ||
55 | 62 | ||
56 | Please read this tutorial carefully since every single step is | 63 | Please read this tutorial carefully since every single step is |
57 | important and do not hesitate to contact the GNUnet team if you have | 64 | important and do not hesitate to contact the GNUnet team if you have |
@@ -60,6 +67,7 @@ team: @uref{https://gnunet.org/contact_information} | |||
60 | 67 | ||
61 | @menu | 68 | @menu |
62 | 69 | ||
70 | * Vocabulary:: Vocabulary used throughout this document | ||
63 | * Installing GNUnet:: Installing GNUnet | 71 | * Installing GNUnet:: Installing GNUnet |
64 | * Introduction to GNUnet Architecture:: Introduction to GNUnet Architecture | 72 | * Introduction to GNUnet Architecture:: Introduction to GNUnet Architecture |
65 | * First Steps with GNUnet:: First Steps with GNUnet | 73 | * First Steps with GNUnet:: First Steps with GNUnet |
@@ -68,6 +76,8 @@ team: @uref{https://gnunet.org/contact_information} | |||
68 | @detailmenu | 76 | @detailmenu |
69 | --- The Detailed Node Listing --- | 77 | --- The Detailed Node Listing --- |
70 | 78 | ||
79 | Vocabulary | ||
80 | |||
71 | Installing GNUnet | 81 | Installing GNUnet |
72 | 82 | ||
73 | * Obtaining a stable version:: | 83 | * Obtaining a stable version:: |
@@ -100,6 +110,55 @@ Developing Applications | |||
100 | @end detailmenu | 110 | @end detailmenu |
101 | @end menu | 111 | @end menu |
102 | 112 | ||
113 | @node Vocabulary | ||
114 | @chapter Vocabulary | ||
115 | |||
116 | @menu | ||
117 | * Words and characters:: | ||
118 | * Technical Assumptions:: | ||
119 | @end menu | ||
120 | |||
121 | @node Words and characters | ||
122 | @section Words and characters | ||
123 | |||
124 | Throughout this document we use certain words and characters. | ||
125 | |||
126 | @enumerate | ||
127 | @item | ||
128 | @c ``@command{#}'' in example code blocks describes commands you execute as root. | ||
129 | ``@command{#}'' in example code blocks describes commands, ie comments. | ||
130 | |||
131 | @example | ||
132 | # Do the foobar thing: | ||
133 | $ make foobar | ||
134 | @end example | ||
135 | |||
136 | @item | ||
137 | Dollarsign ``@command{$}'' in example code blocks describes commands you execute as | ||
138 | unprivileged users. | ||
139 | |||
140 | @example | ||
141 | $ cd foo; ./configure --example-switch | ||
142 | @end example | ||
143 | |||
144 | @item | ||
145 | Backslash ``@command{\}'' describes linebreaks. | ||
146 | |||
147 | @example | ||
148 | ./configure --foo --bar --baz \ | ||
149 | --short-loop | ||
150 | @end example | ||
151 | |||
152 | ...expands to @code{./configure --foo --bar --baz --short-loop} | ||
153 | |||
154 | @end enumerate | ||
155 | |||
156 | @node Technical Assumptions | ||
157 | @section Technical Assumptions | ||
158 | |||
159 | @c Is it really assuming Bash (ie Bash extensions of POSIX being used)? | ||
160 | The shell on GNU systems is assumed to be Bash. | ||
161 | |||
103 | @node Installing GNUnet | 162 | @node Installing GNUnet |
104 | @chapter Installing GNUnet | 163 | @chapter Installing GNUnet |
105 | 164 | ||
@@ -123,67 +182,88 @@ certain feature or a certain issue has been fixed since the last release. | |||
123 | @node Obtaining a stable version | 182 | @node Obtaining a stable version |
124 | @section Obtaining a stable version | 183 | @section Obtaining a stable version |
125 | 184 | ||
126 | You can download the latest stable version of GNUnet from GNU FTP mirrors: | 185 | Download the tarball from |
127 | @uref{https://ftp.gnu.org/gnu/gnunet/gnunet-0.10.x.tar.gz} | 186 | @indicateurl{https://ftp.gnu.org/gnu/gnunet/gnunet-@value{VERSION}.tar.gz}. |
128 | You should also download the signature file and verify the integrity of the tarball. | 187 | |
129 | @uref{https://ftp.gnu.org/gnu/gnunet/gnunet-0.10.x.tar.gz.sig} | 188 | Make sure to download the associated @file{.sig} file and to verify the |
130 | To verify the signature you should first import the GPG key used to sign the tarball | 189 | authenticity of the tarball against it, like this: |
190 | |||
131 | @example | 191 | @example |
132 | $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E | 192 | $ wget https://ftp.gnu.org/gnu/gnunet/gnunet-@value{VERSION}.tar.gz.sig |
193 | $ gpg --verify-files gnunet-@value{VERSION}.tar.gz.sig | ||
133 | @end example | 194 | @end example |
134 | And use this key to verify the tarball's signature | 195 | |
196 | If this command fails because you do not have the required public key, | ||
197 | then you need to run this command to import it: | ||
198 | |||
135 | @example | 199 | @example |
136 | $ gpg --verify gnunet-0.10.x.tar.gz.sig gnunet-0.10.x.tar.gz | 200 | $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E |
137 | @end example | 201 | @end example |
138 | After successfully verifying the integrity you can extract the tarball using | 202 | |
203 | @noindent | ||
204 | and rerun the @code{gpg --verify-files} command. | ||
205 | |||
206 | Now you can extract the tarball and rename the resulting | ||
207 | directory to @i{gnunet} which we will be using in the | ||
208 | remainder of this document. | ||
209 | |||
139 | @example | 210 | @example |
140 | $ tar xvzf gnunet-0.10.x.tar.gz | 211 | $ tar xvzf gnunet-@value{VERSION}.tar.gz |
141 | ## we will use the directory "gnunet" in the remainder of this document | 212 | $ mv gnunet-@value{VERSION} gnunet |
142 | $ mv gnunet-0.10.x gnunet | ||
143 | $ cd gnunet | 213 | $ cd gnunet |
144 | @end example | 214 | @end example |
145 | 215 | ||
146 | However, please note that stable versions can be very outdated, as a developer | 216 | @noindent |
147 | you are strongly encouraged to use the version from @uref{https://gnunet.org/git/}. | 217 | However, please note that stable versions can be very outdated. |
218 | As a developer you are @b{strongly} encouraged to use the version | ||
219 | from @uref{https://gnunet.org/git/, git}. | ||
148 | 220 | ||
149 | @node Installing Build Tool Chain and Dependencies | 221 | @node Installing Build Tool Chain and Dependencies |
150 | @section Installing Build Tool Chain and Dependencies | 222 | @section Installing Build Tool Chain and Dependencies |
151 | 223 | ||
152 | To successfully compile GNUnet you need the tools to build GNUnet and the required dependencies. | 224 | To successfully compile GNUnet you need the tools to build GNUnet and |
153 | Please have a look at @uref{https://gnunet.org/dependencies} for a list of required dependencies | 225 | the required dependencies. Please have a look at |
154 | and @uref{https://gnunet.org/generic_installation} for specific instructions for your operating system. | 226 | @uref{https://gnunet.org/dependencies} for a list of required dependencies |
155 | 227 | and @uref{https://gnunet.org/generic_installation} for specific | |
156 | Please check the notes at the end of the configure process about required dependencies. | 228 | instructions for your operating system. Please check the notes at |
229 | the end of the configure process about required dependencies. | ||
157 | 230 | ||
158 | For GNUnet bootstrapping support and the http(s) plugin you should install libgnurl. | 231 | For GNUnet bootstrapping support and the http(s) plugin you should |
159 | For the filesharing service you should install at least one of the datastore backends mysql, | 232 | install @uref{https://gnunet.org/gnurl, libgnurl}. |
160 | sqlite or postgresql. | 233 | For the filesharing service you should install at least one of the |
234 | datastore backends. MySQL, SQlite and PostgreSQL are supported. | ||
161 | 235 | ||
162 | @node Obtaining the latest version from Git | 236 | @node Obtaining the latest version from Git |
163 | @section Obtaining the latest version from Git | 237 | @section Obtaining the latest version from Git |
164 | 238 | ||
165 | The latest development version can obtained from our Git repository. To obtain | 239 | The latest development version can obtained from our Git repository. |
166 | the code you need Git installed and checkout the repository using: | 240 | To obtain the code you need Git installed and checkout the repository |
241 | using: | ||
242 | |||
167 | @example | 243 | @example |
168 | $ git clone https://gnunet.org/git/gnunet | 244 | $ git clone https://gnunet.org/git/gnunet |
169 | @end example | 245 | @end example |
170 | After cloning the repository you have to execute | 246 | |
247 | @noindent | ||
248 | After cloning the repository you have to execute the @file{bootstrap} | ||
249 | script in the directory: | ||
250 | |||
171 | @example | 251 | @example |
172 | $ cd gnunet | 252 | $ cd gnunet ; ./bootstrap |
173 | $ ./bootstrap | ||
174 | @end example | 253 | @end example |
175 | 254 | ||
176 | The remainder of this tutorial assumes that you have Git branch ``master'' checked out. | 255 | @noindent |
256 | The remainder of this tutorial assumes that you have the Git branch | ||
257 | ``master'' checked out. | ||
177 | 258 | ||
178 | @node Compiling and Installing GNUnet | 259 | @node Compiling and Installing GNUnet |
179 | @section Compiling and Installing GNUnet | 260 | @section Compiling and Installing GNUnet |
180 | 261 | ||
181 | First, you need to install at least libgnupgerror version 1.27 | 262 | First, you need to install at least libgnupgerror 1.27 and libgcrypt 1.7.6. |
182 | @uref{https://www.gnupg.org/ftp/gcrypt/libgpg-error/libgpg-error-1.27.tar.bz2} | ||
183 | and libgcrypt version 1.7.6 @uref{https://www.gnupg.org/ftp/gcrypt/libgcrypt/libgcrypt-1.7.6.tar.bz2}. | ||
184 | 263 | ||
185 | @example | 264 | @example |
186 | $ wget https://www.gnupg.org/ftp/gcrypt/libgpg-error/libgpg-error-1.27.tar.bz2 | 265 | $ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt" |
266 | $ wget $GNUPGFTP/libgpg-error/libgpg-error-1.27.tar.bz2 | ||
187 | $ tar xf libgpg-error-1.27.tar.bz2 | 267 | $ tar xf libgpg-error-1.27.tar.bz2 |
188 | $ cd libgpg-error-1.27 | 268 | $ cd libgpg-error-1.27 |
189 | $ ./configure | 269 | $ ./configure |
@@ -192,7 +272,8 @@ $ cd .. | |||
192 | @end example | 272 | @end example |
193 | 273 | ||
194 | @example | 274 | @example |
195 | $ wget https://www.gnupg.org/ftp/gcrypt/libgcrypt/libgcrypt-1.7.6.tar.bz2 | 275 | $ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt" |
276 | $ wget $GNUPGFTP/libgcrypt/libgcrypt-1.7.6.tar.bz2 | ||
196 | $ tar xf libgcrypt-1.7.6.tar.bz2 | 277 | $ tar xf libgcrypt-1.7.6.tar.bz2 |
197 | $ cd libgcrypt-1.7.6 | 278 | $ cd libgcrypt-1.7.6 |
198 | $ ./configure | 279 | $ ./configure |
@@ -220,10 +301,12 @@ $ make | |||
220 | $ make install | 301 | $ make install |
221 | @end example | 302 | @end example |
222 | 303 | ||
223 | After installing GNUnet you have to add your GNUnet installation to your path | 304 | @noindent |
224 | environmental variable. In addition you have to create the @file{.config} | 305 | After installing GNUnet you have to add your GNUnet installation |
225 | directory in your home directory (unless it already exists) where GNUnet stores | 306 | to your path environmental variable. In addition you have to |
226 | its data and an empty GNUnet configuration file: | 307 | create the @file{.config} directory in your home directory |
308 | (unless it already exists) where GNUnet stores its data and an | ||
309 | empty GNUnet configuration file: | ||
227 | 310 | ||
228 | @example | 311 | @example |
229 | $ export PATH=$PATH:$PREFIX/bin | 312 | $ export PATH=$PATH:$PREFIX/bin |
@@ -238,23 +321,34 @@ $ touch ~/.config/gnunet.conf | |||
238 | You should check your installation to ensure that installing GNUnet | 321 | You should check your installation to ensure that installing GNUnet |
239 | was successful up to this point. You should be able to access GNUnet's | 322 | was successful up to this point. You should be able to access GNUnet's |
240 | binaries and run GNUnet's self check. | 323 | binaries and run GNUnet's self check. |
324 | |||
241 | @example | 325 | @example |
242 | $ which gnunet-arm | 326 | $ which gnunet-arm |
243 | @end example | 327 | @end example |
244 | should return $PREFIX/bin/gnunet-arm. It should be | 328 | |
245 | located in your GNUnet installation and the output should not be | 329 | @noindent |
246 | empty. If you see an output like: | 330 | should return $PREFIX/bin/gnunet-arm. It should be located in your |
331 | GNUnet installation and the output should not be empty. | ||
332 | If you see an output like: | ||
333 | |||
247 | @example | 334 | @example |
248 | $ which gnunet-arm | 335 | $ which gnunet-arm |
249 | @end example | 336 | @end example |
250 | check your PATH variable to ensure GNUnet's @file{bin} directory is included. | 337 | |
338 | @noindent | ||
339 | check your PATH variable to ensure GNUnet's @file{bin} directory is | ||
340 | included. | ||
251 | 341 | ||
252 | GNUnet provides tests for all of its subcomponents. Run | 342 | GNUnet provides tests for all of its subcomponents. Run |
343 | |||
253 | @example | 344 | @example |
254 | $ make check | 345 | $ make check |
255 | @end example | 346 | @end example |
256 | to execute tests for all components. make check traverses all subdirectories in src. | 347 | |
257 | For every subdirectory you should get a message like this: | 348 | @noindent |
349 | to execute tests for all components. @command{make check} traverses all | ||
350 | subdirectories in @file{src}. For every subdirectory you should | ||
351 | get a message like this: | ||
258 | 352 | ||
259 | @example | 353 | @example |
260 | make[2]: Entering directory `/home/$USER/gnunet/contrib' | 354 | make[2]: Entering directory `/home/$USER/gnunet/contrib' |
@@ -328,43 +422,50 @@ the programmer. | |||
328 | @node Configure your peer | 422 | @node Configure your peer |
329 | @section Configure your peer | 423 | @section Configure your peer |
330 | 424 | ||
331 | First of all we need to configure your peer. Each peer is started with a configuration | 425 | First of all we need to configure your peer. Each peer is started with |
332 | containing settings for GNUnet itself and its services. This configuration is based on the | 426 | a configuration containing settings for GNUnet itself and its services. |
333 | default configuration shipped with GNUnet and can be modified. The default configuration | 427 | This configuration is based on the default configuration shipped with |
334 | is located in the @file{$PREFIX/share/gnunet/config.d} directory. When starting a peer, you | 428 | GNUnet and can be modified. The default configuration is located in the |
335 | can specify a customized configuration using the the @command{-c} command line switch when | 429 | @file{$PREFIX/share/gnunet/config.d} directory. When starting a peer, you |
336 | starting the ARM service and all other services. When using a modified configuration the | 430 | can specify a customized configuration using the the @command{-c} command |
337 | default values are loaded and only values specified in the configuration file will replace | 431 | line switch when starting the ARM service and all other services. When |
338 | the default values. | 432 | using a modified configuration the default values are loaded and only |
339 | 433 | values specified in the configuration file will replace the default | |
340 | Since we want to start additional peers later, we need some modifications from the default | 434 | values. |
341 | configuration. We need to create a separate service home and a file containing our | 435 | |
342 | modifications for this peer: | 436 | Since we want to start additional peers later, we need some modifications |
437 | from the default configuration. We need to create a separate service | ||
438 | home and a file containing our modifications for this peer: | ||
439 | |||
343 | @example | 440 | @example |
344 | $ mkdir ~/gnunet1/ | 441 | $ mkdir ~/gnunet1/ |
345 | $ touch peer1.conf | 442 | $ touch peer1.conf |
346 | @end example | 443 | @end example |
347 | 444 | ||
348 | Now add the following lines to @file{peer1.conf} to use this directory. For | 445 | Now add the following lines to @file{peer1.conf} to use this directory. |
349 | simplified usage we want to prevent the peer to connect to the GNUnet | 446 | For simplified usage we want to prevent the peer to connect to the GNUnet |
350 | network since this could lead to confusing output. This modifications | 447 | network since this could lead to confusing output. This modifications |
351 | will replace the default settings: | 448 | will replace the default settings: |
449 | |||
352 | @example | 450 | @example |
353 | [PATHS] | 451 | [PATHS] |
354 | GNUNET_HOME = ~/gnunet1/ # Use this directory to store GNUnet data | 452 | # Use this directory to store GNUnet data |
453 | GNUNET_HOME = ~/gnunet1/ | ||
355 | [hostlist] | 454 | [hostlist] |
356 | SERVERS = # prevent bootstrapping | 455 | # prevent bootstrapping |
456 | SERVERS = | ||
357 | @end example | 457 | @end example |
358 | 458 | ||
359 | @node Start a peer | 459 | @node Start a peer |
360 | @section Start a peer | 460 | @section Start a peer |
361 | Each GNUnet instance (called peer) has an identity (peer ID) based on a | 461 | Each GNUnet instance (called peer) has an identity (peer ID) based on a |
362 | cryptographic public private key pair. The peer ID is the printable hash of the | 462 | cryptographic public private key pair. The peer ID is the printable hash |
363 | public key. | 463 | of the public key. |
364 | 464 | ||
365 | GNUnet services are controlled by a master service, the so called @dfn{Automatic Restart Manager} (ARM). | 465 | GNUnet services are controlled by a master service, the so called |
366 | ARM starts, stops and even restarts services automatically or on demand when a client connects. | 466 | @dfn{Automatic Restart Manager} (ARM). ARM starts, stops and even |
367 | You interact with the ARM service using the gnunet-arm tool. | 467 | restarts services automatically or on demand when a client connects. |
468 | You interact with the ARM service using the @command{gnunet-arm} tool. | ||
368 | GNUnet can then be started with @command{gnunet-arm -s} and stopped with | 469 | GNUnet can then be started with @command{gnunet-arm -s} and stopped with |
369 | @command{gnunet-arm -e}. An additional service not automatically started | 470 | @command{gnunet-arm -e}. An additional service not automatically started |
370 | can be started using @command{gnunet-arm -i <service name>} and stopped | 471 | can be started using @command{gnunet-arm -i <service name>} and stopped |
@@ -372,11 +473,16 @@ using @command{gnunet-arm -k <servicename>}. | |||
372 | 473 | ||
373 | Once you have started your peer, you can use many other GNUnet commands | 474 | Once you have started your peer, you can use many other GNUnet commands |
374 | to interact with it. For example, you can run: | 475 | to interact with it. For example, you can run: |
476 | |||
375 | @example | 477 | @example |
376 | $ gnunet-peerinfo -s | 478 | $ gnunet-peerinfo -s |
377 | @end example | 479 | @end example |
480 | |||
481 | @noindent | ||
378 | to obtain the public key of your peer. | 482 | to obtain the public key of your peer. |
483 | |||
379 | You should see an output containing the peer ID similar to: | 484 | You should see an output containing the peer ID similar to: |
485 | |||
380 | @example | 486 | @example |
381 | I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'. | 487 | I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'. |
382 | @end example | 488 | @end example |
@@ -384,25 +490,37 @@ I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'. | |||
384 | @node Monitor a peer | 490 | @node Monitor a peer |
385 | @section Monitor a peer | 491 | @section Monitor a peer |
386 | 492 | ||
387 | In this section, we will monitor the behaviour of our peer's DHT service with respect to a | 493 | In this section, we will monitor the behaviour of our peer's DHT |
388 | specific key. First we will start GNUnet and then start the DHT service and use the DHT monitor tool | 494 | service with respect to a specific key. First we will start |
389 | to monitor the PUT and GET commands we issue ussing the @command{gnunet-dht-put} and | 495 | GNUnet and then start the DHT service and use the DHT monitor tool |
390 | @command{gnunet-dht-get} commands. Using the ``monitor'' line given below, you can observe | 496 | to monitor the PUT and GET commands we issue ussing the |
391 | the behavior of your own peer's DHT with respect to the specified KEY: | 497 | @command{gnunet-dht-put} and @command{gnunet-dht-get} commands. |
498 | Using the ``monitor'' line given below, you can observe the behavior | ||
499 | of your own peer's DHT with respect to the specified KEY: | ||
392 | 500 | ||
393 | @example | 501 | @example |
394 | $ gnunet-arm -c ~/peer1.conf -s # start gnunet with all default services | 502 | # start gnunet with all default services: |
395 | $ gnunet-arm -c ~/peer1.conf -i dht # start DHT service | 503 | $ gnunet-arm -c ~/peer1.conf -s |
504 | # start DHT service: | ||
505 | $ gnunet-arm -c ~/peer1.conf -i dht | ||
396 | $ cd ~/gnunet/src/dht; | 506 | $ cd ~/gnunet/src/dht; |
397 | $ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY | 507 | $ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY |
398 | @end example | 508 | @end example |
399 | Now open a separate terminal and change again to the @file{gnunet/src/dht} directory: | 509 | |
510 | @noindent | ||
511 | Now open a separate terminal and change again to | ||
512 | the @file{gnunet/src/dht} directory: | ||
513 | |||
400 | @example | 514 | @example |
401 | $ cd ~/gnunet/src/dht | 515 | $ cd ~/gnunet/src/dht |
402 | $ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE # put VALUE under KEY in the DHT | 516 | # put VALUE under KEY in the DHT: |
403 | $ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY # get key KEY from the DHT | 517 | $ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE |
404 | $ gnunet-statistics -c ~/peer1.conf # print statistics about current GNUnet state | 518 | # get key KEY from the DHT: |
405 | $ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service | 519 | $ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY |
520 | # print statistics about current GNUnet state: | ||
521 | $ gnunet-statistics -c ~/peer1.conf | ||
522 | # print statistics about DHT service: | ||
523 | $ gnunet-statistics -c ~/peer1.conf -s dht | ||
406 | @end example | 524 | @end example |
407 | 525 | ||
408 | @node Starting Two Peers by Hand | 526 | @node Starting Two Peers by Hand |
@@ -424,18 +542,23 @@ In practice, you might prefer the automated method | |||
424 | We will now start a second peer on your machine. | 542 | We will now start a second peer on your machine. |
425 | For the second peer, you will need to manually create a modified | 543 | For the second peer, you will need to manually create a modified |
426 | configuration file to avoid conflicts with ports and directories. | 544 | configuration file to avoid conflicts with ports and directories. |
427 | A peers configuration file is by default located in @file{~/.gnunet/gnunet.conf}. | 545 | A peers configuration file is by default located |
428 | This file is typically very short or even empty as only the differences to the | 546 | in @file{~/.gnunet/gnunet.conf}. This file is typically very short |
429 | defaults need to be specified. The defaults are located in | 547 | or even empty as only the differences to the defaults need to be |
430 | many files in the @file{$PREFIX/share/gnunet/config.d} directory. | 548 | specified. The defaults are located in many files in the |
549 | @file{$PREFIX/share/gnunet/config.d} directory. | ||
431 | 550 | ||
432 | To configure the second peer, use the files | 551 | To configure the second peer, use the files |
433 | @file{$PREFIX/share/gnunet/config.d} as a template for your main | 552 | @file{$PREFIX/share/gnunet/config.d} as a template for your main |
434 | configuration file: | 553 | configuration file: |
554 | |||
435 | @example | 555 | @example |
436 | $ cat $PREFIX/share/gnunet/config.d/*.conf > peer2.conf | 556 | $ cat $PREFIX/share/gnunet/config.d/*.conf > peer2.conf |
437 | @end example | 557 | @end example |
558 | |||
559 | @noindent | ||
438 | Now you have to edit @file{peer2.conf} and change: | 560 | Now you have to edit @file{peer2.conf} and change: |
561 | |||
439 | @itemize | 562 | @itemize |
440 | @item @code{GNUNET\_TEST\_HOME} under @code{PATHS} | 563 | @item @code{GNUNET\_TEST\_HOME} under @code{PATHS} |
441 | @item Every (uncommented) value for ``@code{PORT}'' (add 10000) in any | 564 | @item Every (uncommented) value for ``@code{PORT}'' (add 10000) in any |
@@ -454,6 +577,7 @@ Now, generate the 2nd peer's private key: | |||
454 | $ gnunet-peerinfo -s -c peer2.conf | 577 | $ gnunet-peerinfo -s -c peer2.conf |
455 | @end example | 578 | @end example |
456 | 579 | ||
580 | @noindent | ||
457 | This may take a while, generate entropy using your keyboard or mouse | 581 | This may take a while, generate entropy using your keyboard or mouse |
458 | as needed. Also, make sure the output is different from the | 582 | as needed. Also, make sure the output is different from the |
459 | gnunet-peerinfo output for the first peer (otherwise you made an | 583 | gnunet-peerinfo output for the first peer (otherwise you made an |
@@ -463,34 +587,46 @@ error in the configuration). | |||
463 | @subsection Start the second peer and connect the peers | 587 | @subsection Start the second peer and connect the peers |
464 | 588 | ||
465 | Then, you can start a second peer using: | 589 | Then, you can start a second peer using: |
590 | |||
466 | @example | 591 | @example |
467 | $ gnunet-arm -c peer2.conf -s | 592 | $ gnunet-arm -c peer2.conf -s |
468 | $ gnunet-arm -c peer2.conf -i dht | 593 | $ gnunet-arm -c peer2.conf -i dht |
469 | $ ~/gnunet/src/dht/gnunet-dht-put -c peer2.conf -k KEY -d VALUE | 594 | $ ~/gnunet/src/dht/gnunet-dht-put -c peer2.conf -k KEY -d VALUE |
470 | $ ~/gnunet/src/dht/gnunet-dht-get -c peer2.conf -k KEY | 595 | $ ~/gnunet/src/dht/gnunet-dht-get -c peer2.conf -k KEY |
471 | @end example | 596 | @end example |
597 | |||
472 | If you want the two peers to connect, you have multiple options: | 598 | If you want the two peers to connect, you have multiple options: |
599 | |||
473 | @itemize | 600 | @itemize |
474 | @item UDP neighbour discovery (automatic) | 601 | @item UDP neighbour discovery (automatic) |
475 | @item Setup a bootstrap server | 602 | @item Setup a bootstrap server |
476 | @item Connect manually | 603 | @item Connect manually |
477 | @end itemize | 604 | @end itemize |
605 | |||
478 | To setup peer 1 as bootstrapping server change the configuration of | 606 | To setup peer 1 as bootstrapping server change the configuration of |
479 | the first one to be a hostlist server by adding the following lines to | 607 | the first one to be a hostlist server by adding the following lines to |
480 | @file{peer1.conf} to enable bootstrapping server: | 608 | @file{peer1.conf} to enable bootstrapping server: |
609 | |||
481 | @example | 610 | @example |
482 | [hostlist] | 611 | [hostlist] |
483 | OPTIONS = -p | 612 | OPTIONS = -p |
484 | @end example | 613 | @end example |
485 | 614 | ||
486 | Then change @file{peer2.conf} and replace the ``@code{SERVERS}'' line in the ``@code{[hostlist]}'' section with | 615 | @noindent |
616 | Then change @file{peer2.conf} and replace the ``@code{SERVERS}'' | ||
617 | line in the ``@code{[hostlist]}'' section with | ||
487 | ``@code{http://localhost:8080/}''. Restart both peers using: | 618 | ``@code{http://localhost:8080/}''. Restart both peers using: |
619 | |||
488 | @example | 620 | @example |
489 | $ gnunet-arm -c peer1.conf -e # stop first peer | 621 | # stop first peer |
490 | $ gnunet-arm -c peer1.conf -s # start first peer | 622 | $ gnunet-arm -c peer1.conf -e |
491 | $ gnunet-arm -c peer2.conf -s # start second peer | 623 | # start first peer |
624 | $ gnunet-arm -c peer1.conf -s | ||
625 | # start second peer | ||
626 | $ gnunet-arm -c peer2.conf -s | ||
492 | @end example | 627 | @end example |
493 | 628 | ||
629 | @noindent | ||
494 | Note that if you start your peers without changing these settings, they | 630 | Note that if you start your peers without changing these settings, they |
495 | will use the ``global'' hostlist servers of the GNUnet P2P network and | 631 | will use the ``global'' hostlist servers of the GNUnet P2P network and |
496 | likely connect to those peers. At that point, debugging might become | 632 | likely connect to those peers. At that point, debugging might become |
@@ -511,6 +647,7 @@ If you want to use the @code{peerinfo} tool to connect your peers, you should: | |||
511 | 647 | ||
512 | Check that they are connected using @command{gnunet-core -c peer1.conf}, | 648 | Check that they are connected using @command{gnunet-core -c peer1.conf}, |
513 | which should give you the other peer's peer identity: | 649 | which should give you the other peer's peer identity: |
650 | |||
514 | @example | 651 | @example |
515 | $ gnunet-core -c peer1.conf | 652 | $ gnunet-core -c peer1.conf |
516 | Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG' | 653 | Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG' |
@@ -520,90 +657,108 @@ Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG' | |||
520 | @section Starting Peers Using the Testbed Service | 657 | @section Starting Peers Using the Testbed Service |
521 | @c \label{sec:testbed} | 658 | @c \label{sec:testbed} |
522 | 659 | ||
523 | GNUnet's testbed service is used for testing scenarios where a number of peers | 660 | GNUnet's testbed service is used for testing scenarios where |
524 | are to be started. The testbed can manage peers on a single host or on multiple | 661 | a number of peers are to be started. The testbed can manage peers |
525 | hosts in a distributed fashion. On a single affordable computer, it should be | 662 | on a single host or on multiple hosts in a distributed fashion. |
526 | possible to run around tens of peers without drastically increasing the load on the | 663 | On a single affordable computer, it should be possible to run |
664 | around tens of peers without drastically increasing the load on the | ||
527 | system. | 665 | system. |
528 | 666 | ||
529 | The testbed service can be access through its API | 667 | The testbed service can be access through its API |
530 | @file{include/gnunet\_testbed\_service.h}. The API provides many routines for | 668 | @file{include/gnunet\_testbed\_service.h}. The API provides many |
531 | managing a group of peers. It also provides a helper function | 669 | routines for managing a group of peers. It also provides a helper |
532 | @code{GNUNET\_TESTBED\_test\_run()} to quickly setup a minimalistic testing | 670 | function @code{GNUNET\_TESTBED\_test\_run()} to quickly setup a |
533 | environment on a single host. | 671 | minimalistic testing environment on a single host. |
534 | 672 | ||
535 | This function takes a configuration file which will be used as a template | 673 | This function takes a configuration file which will be used as a |
536 | configuration for the peers. The testbed takes care of modifying relevant | 674 | template configuration for the peers. The testbed takes care of |
537 | options in the peers' configuration such as @code{SERVICEHOME}, @code{PORT}, @code{UNIXPATH} to | 675 | modifying relevant options in the peers' configuration such as |
538 | unique values so that peers run without running into conflicts. It also checks | 676 | @code{SERVICEHOME}, @code{PORT}, @code{UNIXPATH} to unique values |
677 | so that peers run without running into conflicts. It also checks | ||
539 | and assigns the ports in configurations only if they are free. | 678 | and assigns the ports in configurations only if they are free. |
540 | 679 | ||
541 | Additionally, the testbed service also reads its options from the same | 680 | Additionally, the testbed service also reads its options from the |
542 | configuration file. Various available options and details about them can be | 681 | same configuration file. Various available options and details |
543 | found in the testbed default configuration file @file{src/testbed/testbed.conf}. | 682 | about them can be found in the testbed default configuration file |
683 | @file{src/testbed/testbed.conf}. | ||
544 | 684 | ||
545 | With the testbed API, a sample test case can be structured as follows: | 685 | With the testbed API, a sample test case can be structured as follows: |
686 | |||
546 | @example | 687 | @example |
547 | @verbatiminclude testbed_test.c | 688 | @verbatiminclude testbed_test.c |
548 | @end example | 689 | @end example |
690 | |||
691 | @noindent | ||
549 | The source code for the above listing can be found at | 692 | The source code for the above listing can be found at |
550 | @uref{https://gnunet.org/git/gnunet.git/tree/doc/testbed_test.c} | 693 | @uref{https://gnunet.org/git/gnunet.git/tree/doc/testbed_test.c} |
551 | or in the @file{doc/} folder of your repository check-out. | 694 | or in the @file{doc/} folder of your repository check-out. |
552 | After installing GNUnet, the above source code can be compiled as: | 695 | After installing GNUnet, the above source code can be compiled as: |
696 | |||
553 | @example | 697 | @example |
554 | $ export CPPFLAGS="-I/path/to/gnunet/headers" | 698 | $ export CPPFLAGS="-I/path/to/gnunet/headers" |
555 | $ export LDFLAGS="-L/path/to/gnunet/libraries" | 699 | $ export LDFLAGS="-L/path/to/gnunet/libraries" |
556 | $ gcc $CPPFLAGS $LDFLAGS -o testbed-test testbed_test.c -lgnunettestbed -lgnunetdht -lgnunetutil | 700 | $ gcc $CPPFLAGS $LDFLAGS -o testbed-test testbed_test.c \ |
557 | $ touch template.conf # Generate (empty) configuration | 701 | -lgnunettestbed -lgnunetdht -lgnunetutil |
558 | $ ./testbed-test # run it (press CTRL-C to stop) | 702 | # Generate (empty) configuration |
703 | $ touch template.conf | ||
704 | # run it (press CTRL-C to stop) | ||
705 | $ ./testbed-test | ||
559 | @end example | 706 | @end example |
560 | The @code{CPPFLAGS} and @code{LDFLAGS} are necessary if GNUnet is installed | 707 | |
561 | into a different directory other than @file{/usr/local}. | 708 | @noindent |
562 | 709 | The @code{CPPFLAGS} and @code{LDFLAGS} are necessary if GNUnet | |
563 | All of testbed API's peer management functions treat management actions as | 710 | is installed into a different directory other than @file{/usr/local}. |
564 | operations and return operation handles. It is expected that the operations | 711 | |
565 | begin immediately, but they may get delayed (to balance out load on the system). | 712 | All of testbed API's peer management functions treat management |
566 | The program using the API then has to take care of marking the operation as | 713 | actions as operations and return operation handles. It is expected |
567 | ``done'' so that its associated resources can be freed immediately and other | 714 | that the operations begin immediately, but they may get delayed (to |
568 | waiting operations can be executed. Operations will be canceled if they are | 715 | balance out load on the system). The program using the API then has |
716 | to take care of marking the operation as ``done'' so that its | ||
717 | associated resources can be freed immediately and other waiting | ||
718 | operations can be executed. Operations will be canceled if they are | ||
569 | marked as ``done'' before their completion. | 719 | marked as ``done'' before their completion. |
570 | 720 | ||
571 | An operation is treated as completed when it succeeds or fails. Completion of | 721 | An operation is treated as completed when it succeeds or fails. |
572 | an operation is either conveyed as events through @i{controller event callback} | 722 | Completion of an operation is either conveyed as events through |
573 | or through respective operation completion callbacks. In functions | 723 | @i{controller event callback} or through respective operation |
574 | which support completion notification through both controller event callback and | 724 | completion callbacks. In functions which support completion |
575 | operation completion callback, first the controller event callback will be | 725 | notification through both controller event callback and operation |
576 | called. If the operation is not marked as done in that callback or if the | 726 | completion callback, first the controller event callback will be |
577 | callback is given as NULL when creating the operation, the operation completion | 727 | called. If the operation is not marked as done in that callback |
578 | callback will be called. The API documentation shows which event are to be | 728 | or if the callback is given as NULL when creating the operation, |
579 | expected in the controller event notifications. It also documents any | 729 | the operation completion callback will be called. The API |
580 | exceptional behaviour. | 730 | documentation shows which event are to be expected in the |
581 | 731 | controller event notifications. It also documents any exceptional | |
582 | Once the peers are started, test cases often need to connect some of the peers' | 732 | behaviour. |
583 | services. Normally, opening a connect to a peer's service requires the peer's | 733 | |
584 | configuration. While using testbed, the testbed automatically generates | 734 | Once the peers are started, test cases often need to connect |
585 | per-peer configuration. Accessing those configurations directly through file | 735 | some of the peers' services. Normally, opening a connect to |
586 | system is discouraged as their locations are dynamically created and will be | 736 | a peer's service requires the peer's configuration. While using |
587 | different among various runs of testbed. To make access to these configurations | 737 | testbed, the testbed automatically generates per-peer configuration. |
588 | easy, testbed API provides the function | 738 | Accessing those configurations directly through file system is |
589 | @code{GNUNET\_TESTBED\_service\_connect()}. This function fetches the | 739 | discouraged as their locations are dynamically created and will be |
590 | configuration of a given peer and calls the @i{Connect Adapter}. | 740 | different among various runs of testbed. To make access to these |
591 | In the example code, it is the @code{dht\_ca}. A connect adapter is expected | 741 | configurations easy, testbed API provides the function |
592 | to open the connection to the needed service by using the provided configuration | 742 | @code{GNUNET\_TESTBED\_service\_connect()}. This function fetches |
593 | and return the created service connection handle. Successful connection to the | 743 | the configuration of a given peer and calls the @i{Connect Adapter}. |
594 | needed service is signaled through @code{service\_connect\_comp\_cb}. | 744 | In the example code, it is the @code{dht\_ca}. A connect adapter is |
595 | 745 | expected to open the connection to the needed service by using the | |
596 | A dual to connect adapter is the @i{Disconnect Adapter}. This callback is | 746 | provided configuration and return the created service connection handle. |
597 | called after the connect adapter has been called when the operation from | 747 | Successful connection to the needed service is signaled through |
598 | @code{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''. It has to | 748 | @code{service\_connect\_comp\_cb}. |
599 | disconnect from the service with the provided service handle (@code{op\_result}). | 749 | |
750 | A dual to connect adapter is the @i{Disconnect Adapter}. This callback | ||
751 | is called after the connect adapter has been called when the operation | ||
752 | from @code{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''. | ||
753 | It has to disconnect from the service with the provided service | ||
754 | handle (@code{op\_result}). | ||
600 | 755 | ||
601 | Exercise: Find out how many peers you can run on your system. | 756 | Exercise: Find out how many peers you can run on your system. |
602 | 757 | ||
603 | Exercise: Find out how to create a 2D torus topology by changing the | 758 | Exercise: Find out how to create a 2D torus topology by changing the |
604 | options in the configuration file. See @uref{https://gnunet.org/supported-topologies} | 759 | options in the configuration file. |
605 | Then use the DHT API to store and retrieve values in the | 760 | See @uref{https://gnunet.org/supported-topologies}, then use the |
606 | network. | 761 | DHT API to store and retrieve values in the network. |
607 | 762 | ||
608 | @node Developing Applications | 763 | @node Developing Applications |
609 | @chapter Developing Applications | 764 | @chapter Developing Applications |
@@ -635,9 +790,11 @@ $ make install | |||
635 | $ make check | 790 | $ make check |
636 | @end example | 791 | @end example |
637 | 792 | ||
638 | The GNUnet ext template includes examples and a working buildsystem for a new GNUnet service. | 793 | @noindent |
639 | A common GNUnet service consists of the following parts which will be discussed in detail in the | 794 | The GNUnet ext template includes examples and a working buildsystem |
640 | remainder of this document. The functionality of a GNUnet service is implemented in: | 795 | for a new GNUnet service. A common GNUnet service consists of the |
796 | following parts which will be discussed in detail in the remainder | ||
797 | of this document. The functionality of a GNUnet service is implemented in: | ||
641 | 798 | ||
642 | @itemize | 799 | @itemize |
643 | @item the GNUnet service (gnunet-ext/src/ext/gnunet-service-ext.c) | 800 | @item the GNUnet service (gnunet-ext/src/ext/gnunet-service-ext.c) |
@@ -646,6 +803,7 @@ remainder of this document. The functionality of a GNUnet service is implemented | |||
646 | @end itemize | 803 | @end itemize |
647 | 804 | ||
648 | The interfaces for these entities are defined in: | 805 | The interfaces for these entities are defined in: |
806 | |||
649 | @itemize | 807 | @itemize |
650 | @item client API interface (gnunet-ext/src/ext/ext.h) | 808 | @item client API interface (gnunet-ext/src/ext/ext.h) |
651 | @item the service interface (gnunet-ext/src/include/gnunet_service_SERVICE.h) | 809 | @item the service interface (gnunet-ext/src/include/gnunet_service_SERVICE.h) |
@@ -654,6 +812,7 @@ The interfaces for these entities are defined in: | |||
654 | 812 | ||
655 | 813 | ||
656 | In addition the ext systems provides: | 814 | In addition the ext systems provides: |
815 | |||
657 | @itemize | 816 | @itemize |
658 | @item a test testing the API (gnunet-ext/src/ext/test_ext_api.c) | 817 | @item a test testing the API (gnunet-ext/src/ext/test_ext_api.c) |
659 | @item a configuration template for the service (gnunet-ext/src/ext/ext.conf.in) | 818 | @item a configuration template for the service (gnunet-ext/src/ext/ext.conf.in) |
@@ -664,22 +823,24 @@ In addition the ext systems provides: | |||
664 | 823 | ||
665 | The first step for writing any extension with a new service is to | 824 | The first step for writing any extension with a new service is to |
666 | ensure that the @file{ext.conf.in} file contains entries for the | 825 | ensure that the @file{ext.conf.in} file contains entries for the |
667 | @code{UNIXPATH}, @code{PORT} and @code{BINARY} for the service in a section named after | 826 | @code{UNIXPATH}, @code{PORT} and @code{BINARY} for the service in a |
668 | the service. | 827 | section named after the service. |
669 | 828 | ||
670 | If you want to adapt the template rename the @file{ext.conf.in} to match your | 829 | If you want to adapt the template rename the @file{ext.conf.in} to |
671 | services name, you have to modify the @code{AC\_OUTPUT} section in @file{configure.ac} | 830 | match your services name, you have to modify the @code{AC\_OUTPUT} |
672 | in the @file{gnunet-ext} root. | 831 | section in @file{configure.ac} in the @file{gnunet-ext} root. |
673 | 832 | ||
674 | @node Writing a Client Application | 833 | @node Writing a Client Application |
675 | @section Writing a Client Application | 834 | @section Writing a Client Application |
676 | 835 | ||
677 | When writing any client application (for example, a command-line | 836 | When writing any client application (for example, a command-line |
678 | tool), the basic structure is to start with the @code{GNUNET\_PROGRAM\_run} | 837 | tool), the basic structure is to start with the |
679 | function. This function will parse command-line options, setup the scheduler | 838 | @code{GNUNET\_PROGRAM\_run} function. This function will parse |
680 | and then invoke the @code{run} function (with the remaining non-option arguments) | 839 | command-line options, setup the scheduler and then invoke the |
681 | and a handle to the parsed configuration (and the configuration file name that was | 840 | @code{run} function (with the remaining non-option arguments) |
682 | used, which is typically not needed): | 841 | and a handle to the parsed configuration (and the configuration |
842 | file name that was used, which is typically not needed): | ||
843 | |||
683 | @example | 844 | @example |
684 | @verbatiminclude tutorial-examples/001.c | 845 | @verbatiminclude tutorial-examples/001.c |
685 | @end example | 846 | @end example |
@@ -697,6 +858,7 @@ Options can then be added easily by adding global variables and | |||
697 | expanding the @code{options} array. For example, the following would | 858 | expanding the @code{options} array. For example, the following would |
698 | add a string-option and a binary flag (defaulting to @code{NULL} and | 859 | add a string-option and a binary flag (defaulting to @code{NULL} and |
699 | @code{GNUNET\_NO} respectively): | 860 | @code{GNUNET\_NO} respectively): |
861 | |||
700 | @example | 862 | @example |
701 | @verbatiminclude tutorial-examples/002.c | 863 | @verbatiminclude tutorial-examples/002.c |
702 | @end example | 864 | @end example |
@@ -753,10 +915,12 @@ file). | |||
753 | 915 | ||
754 | Before a client library can implement the application-specific protocol | 916 | Before a client library can implement the application-specific protocol |
755 | with the service, a connection must be created: | 917 | with the service, a connection must be created: |
918 | |||
756 | @example | 919 | @example |
757 | @verbatiminclude tutorial-examples/003.c | 920 | @verbatiminclude tutorial-examples/003.c |
758 | @end example | 921 | @end example |
759 | 922 | ||
923 | @noindent | ||
760 | As a result a @code{GNUNET\_MQ\_Handle} is returned | 924 | As a result a @code{GNUNET\_MQ\_Handle} is returned |
761 | which can to used henceforth to transmit messages to the service. | 925 | which can to used henceforth to transmit messages to the service. |
762 | The complete MQ API can be found in @file{gnunet\_mq\_lib.h}. | 926 | The complete MQ API can be found in @file{gnunet\_mq\_lib.h}. |
@@ -769,27 +933,35 @@ there are errors communicating with the service. | |||
769 | @node Sending messages | 933 | @node Sending messages |
770 | @subsubsection Sending messages | 934 | @subsubsection Sending messages |
771 | 935 | ||
772 | In GNUnet, messages are always sent beginning with a @code{struct GNUNET\_MessageHeader} | 936 | In GNUnet, messages are always sent beginning with a |
773 | in big endian format. This header defines the size and the type of the | 937 | @code{struct GNUNET\_MessageHeader} in big endian format. |
938 | This header defines the size and the type of the | ||
774 | message, the payload follows after this header. | 939 | message, the payload follows after this header. |
940 | |||
775 | @example | 941 | @example |
776 | @verbatiminclude tutorial-examples/004.c | 942 | @verbatiminclude tutorial-examples/004.c |
777 | @end example | 943 | @end example |
778 | 944 | ||
945 | @noindent | ||
779 | Existing message types are defined in @file{gnunet\_protocols.h}. | 946 | Existing message types are defined in @file{gnunet\_protocols.h}. |
780 | A common way to create a message is with an envelope: | 947 | A common way to create a message is with an envelope: |
948 | |||
781 | @example | 949 | @example |
782 | @verbatiminclude tutorial-examples/005.c | 950 | @verbatiminclude tutorial-examples/005.c |
783 | @end example | 951 | @end example |
784 | 952 | ||
953 | @noindent | ||
785 | Exercise: Define a message struct that includes a 32-bit | 954 | Exercise: Define a message struct that includes a 32-bit |
786 | unsigned integer in addition to the standard GNUnet MessageHeader. | 955 | unsigned integer in addition to the standard GNUnet MessageHeader. |
787 | Add a C struct and define a fresh protocol number for your message. | 956 | Add a C struct and define a fresh protocol number for your message. |
788 | Protocol numbers in gnunet-ext are defined in @file{gnunet-ext/src/include/gnunet_protocols_ext.h} | 957 | Protocol numbers in gnunet-ext are defined |
958 | in @file{gnunet-ext/src/include/gnunet_protocols_ext.h} | ||
789 | 959 | ||
790 | Exercise: Find out how you can determine the number of messages in a message queue. | 960 | Exercise: Find out how you can determine the number of messages |
961 | in a message queue. | ||
791 | 962 | ||
792 | Exercise: Find out how you can determine when a message you have queued was actually transmitted. | 963 | Exercise: Find out how you can determine when a message you |
964 | have queued was actually transmitted. | ||
793 | 965 | ||
794 | Exercise: Define a helper function to transmit a 32-bit | 966 | Exercise: Define a helper function to transmit a 32-bit |
795 | unsigned integer (as payload) to a service using some given client | 967 | unsigned integer (as payload) to a service using some given client |
@@ -817,7 +989,8 @@ Exercise: Expand your helper function to receive a response message | |||
817 | without any payload). Upon receiving the service's response, you | 989 | without any payload). Upon receiving the service's response, you |
818 | should call a callback provided to your helper function's API. | 990 | should call a callback provided to your helper function's API. |
819 | 991 | ||
820 | Exercise: Figure out where you can pass values to the closures (@code{cls}). | 992 | Exercise: Figure out where you can pass values to the |
993 | closures (@code{cls}). | ||
821 | 994 | ||
822 | @node Writing a user interface | 995 | @node Writing a user interface |
823 | @subsection Writing a user interface | 996 | @subsection Writing a user interface |
@@ -834,8 +1007,8 @@ command-line to the service. | |||
834 | @node Writing a Service | 1007 | @node Writing a Service |
835 | @section Writing a Service | 1008 | @section Writing a Service |
836 | 1009 | ||
837 | Before you can test the client you've written so far, you'll need to also | 1010 | Before you can test the client you've written so far, you'll |
838 | implement the corresponding service. | 1011 | need to also implement the corresponding service. |
839 | 1012 | ||
840 | @menu | 1013 | @menu |
841 | * Code Placement:: | 1014 | * Code Placement:: |
@@ -845,21 +1018,25 @@ implement the corresponding service. | |||
845 | @node Code Placement | 1018 | @node Code Placement |
846 | @subsection Code Placement | 1019 | @subsection Code Placement |
847 | 1020 | ||
848 | New services are placed in their own subdirectory under @file{gnunet/src}. | 1021 | New services are placed in their own subdirectory under |
849 | This subdirectory should contain the API implementation file @file{SERVICE\_api.c}, | 1022 | @file{gnunet/src}. This subdirectory should contain the API |
850 | the description of the client-service protocol @file{SERVICE.h} and P2P protocol | 1023 | implementation file @file{SERVICE\_api.c}, the description of |
1024 | the client-service protocol @file{SERVICE.h} and P2P protocol | ||
851 | @file{SERVICE\_protocol.h}, the implementation of the service itself | 1025 | @file{SERVICE\_protocol.h}, the implementation of the service itself |
852 | @file{gnunet-service-SERVICE.h} and several files for tests, including test code | 1026 | @file{gnunet-service-SERVICE.h} and several files for tests, |
853 | and configuration files. | 1027 | including test code and configuration files. |
854 | 1028 | ||
855 | @node Starting a Service | 1029 | @node Starting a Service |
856 | @subsection Starting a Service | 1030 | @subsection Starting a Service |
857 | 1031 | ||
858 | The key API definition for creating a service is the @code{GNUNET\_SERVICE\_MAIN} macro: | 1032 | The key API definition for creating a service is the |
1033 | @code{GNUNET\_SERVICE\_MAIN} macro: | ||
1034 | |||
859 | @example | 1035 | @example |
860 | @verbatiminclude tutorial-examples/007.c | 1036 | @verbatiminclude tutorial-examples/007.c |
861 | @end example | 1037 | @end example |
862 | 1038 | ||
1039 | @noindent | ||
863 | In addition to the service name and flags, the macro takes three | 1040 | In addition to the service name and flags, the macro takes three |
864 | functions, typically called @code{run}, @code{client\_connect\_cb} and | 1041 | functions, typically called @code{run}, @code{client\_connect\_cb} and |
865 | @code{client\_disconnect\_cb} as well as an array of message handlers | 1042 | @code{client\_disconnect\_cb} as well as an array of message handlers |
@@ -867,10 +1044,12 @@ that will be called for incoming messages from clients. | |||
867 | 1044 | ||
868 | A minimal version of the three central service funtions would look | 1045 | A minimal version of the three central service funtions would look |
869 | like this: | 1046 | like this: |
1047 | |||
870 | @example | 1048 | @example |
871 | @verbatiminclude tutorial-examples/008.c | 1049 | @verbatiminclude tutorial-examples/008.c |
872 | @end example | 1050 | @end example |
873 | 1051 | ||
1052 | @noindent | ||
874 | Exercise: Write a stub service that processes no messages at all | 1053 | Exercise: Write a stub service that processes no messages at all |
875 | in your code. Create a default configuration for it, integrate it | 1054 | in your code. Create a default configuration for it, integrate it |
876 | with the build system and start the service from | 1055 | with the build system and start the service from |
@@ -900,8 +1079,9 @@ FIXME: This section still needs to be updated to the lastest API! | |||
900 | One of the most important services in GNUnet is the @code{CORE} service | 1079 | One of the most important services in GNUnet is the @code{CORE} service |
901 | managing connections between peers and handling encryption between peers. | 1080 | managing connections between peers and handling encryption between peers. |
902 | 1081 | ||
903 | One of the first things any service that extends the P2P protocol typically does | 1082 | One of the first things any service that extends the P2P protocol |
904 | is connect to the @code{CORE} service using: | 1083 | typically does is connect to the @code{CORE} service using: |
1084 | |||
905 | @example | 1085 | @example |
906 | @verbatiminclude tutorial-examples/009.c | 1086 | @verbatiminclude tutorial-examples/009.c |
907 | @end example | 1087 | @end example |
@@ -916,13 +1096,16 @@ is connect to the @code{CORE} service using: | |||
916 | @node New P2P connections | 1096 | @node New P2P connections |
917 | @subsection New P2P connections | 1097 | @subsection New P2P connections |
918 | 1098 | ||
919 | Before any traffic with a different peer can be exchanged, the peer must be | 1099 | Before any traffic with a different peer can be exchanged, the peer must |
920 | known to the service. This is notified by the @code{CORE} @code{connects} callback, | 1100 | be known to the service. This is notified by the @code{CORE} |
921 | which communicates the identity of the new peer to the service: | 1101 | @code{connects} callback, which communicates the identity of the new |
1102 | peer to the service: | ||
1103 | |||
922 | @example | 1104 | @example |
923 | @verbatiminclude tutorial-examples/010.c | 1105 | @verbatiminclude tutorial-examples/010.c |
924 | @end example | 1106 | @end example |
925 | 1107 | ||
1108 | @noindent | ||
926 | Note that whatever you return from @code{connects} is given as the | 1109 | Note that whatever you return from @code{connects} is given as the |
927 | @i{cls} argument to the message handlers for messages from | 1110 | @i{cls} argument to the message handlers for messages from |
928 | the respective peer. | 1111 | the respective peer. |
@@ -1014,21 +1197,27 @@ PEERSTORE operations. | |||
1014 | @subsection Storing records | 1197 | @subsection Storing records |
1015 | 1198 | ||
1016 | To store a new record, use the following function: | 1199 | To store a new record, use the following function: |
1200 | |||
1017 | @example | 1201 | @example |
1018 | @verbatiminclude tutorial-examples/013.c | 1202 | @verbatiminclude tutorial-examples/013.c |
1019 | @end example | 1203 | @end example |
1020 | 1204 | ||
1021 | The @code{options} parameter can either be @code{GNUNET_PEERSTORE_STOREOPTION_MULTIPLE} | 1205 | @noindent |
1022 | which means that multiple values can be stored under the same key combination (subsystem, peerid, key), | 1206 | The @code{options} parameter can either be |
1023 | or @code{GNUNET_PEERSTORE_STOREOPTION_REPLACE} which means that PEERSTORE will replace any | 1207 | @code{GNUNET_PEERSTORE_STOREOPTION_MULTIPLE} which means that multiple |
1024 | existing values under the given key combination (subsystem, peerid, key) with the new given value. | 1208 | values can be stored under the same key combination (subsystem, peerid, key), |
1209 | or @code{GNUNET_PEERSTORE_STOREOPTION_REPLACE} which means that PEERSTORE will | ||
1210 | replace any existing values under the given key combination (subsystem, peerid, | ||
1211 | key) with the new given value. | ||
1212 | |||
1213 | The continuation function @code{cont} will be called after the store request | ||
1214 | is successfully sent to the PEERSTORE service. This does not guarantee that | ||
1215 | the record is successfully stored, only that it was received by the service. | ||
1025 | 1216 | ||
1026 | The continuation function @code{cont} will be called after the store request is successfully | 1217 | The @code{GNUNET_PEERSTORE_store} function returns a handle to the store |
1027 | sent to the PEERSTORE service. This does not guarantee that the record is successfully stored, only | 1218 | operation. This handle can be used to cancel the store operation only before |
1028 | that it was received by the service. | 1219 | the continuation function is called: |
1029 | 1220 | ||
1030 | The @code{GNUNET_PEERSTORE_store} function returns a handle to the store operation. This handle | ||
1031 | can be used to cancel the store operation only before the continuation function is called: | ||
1032 | @example | 1221 | @example |
1033 | void | 1222 | void |
1034 | GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); | 1223 | GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); |
diff --git a/doc/tutorial-examples/003.c b/doc/tutorial-examples/003.c index d13681ca6..f1105a070 100644 --- a/doc/tutorial-examples/003.c +++ b/doc/tutorial-examples/003.c | |||
@@ -1,7 +1,7 @@ | |||
1 | struct GNUNET_MQ_MessageHandlers handlers[] = { | 1 | struct GNUNET_MQ_MessageHandlers handlers[] = { |
2 | // ... | 2 | // ... |
3 | GNUNET_MQ_handler_end () | 3 | GNUNET_MQ_handler_end () |
4 | }; | 4 | }; |
5 | struct GNUNET_MQ_Handle *mq; | 5 | struct GNUNET_MQ_Handle *mq; |
6 | 6 | ||
7 | mq = GNUNET_CLIENT_connect (cfg, "service-name", handlers, &error_cb, NULL); | 7 | mq = GNUNET_CLIENT_connect (cfg, "service-name", handlers, &error_cb, NULL); |