Source

wiki_hacking / infocalypse / doc / infocalypse_howto.html

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<title>HOWTO: Infocalypse 2.0 hg extension</title>
</head>
<body>
<hr />
<h1>HOWTO: Infocalypse 2.0 hg extension</h1>
<hr />
<em>updated: 20110918</em><br />
<em><a href="#freenet_links">Note: Contains Freenet only
links</a></em>
<h2><a name="toc" id="toc">Table of Contents</a></h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#updating">Updating</a></li>
<li><a href="#background">Background</a></li>
<li><a href="#basic">Basic Usage</a>
<ul>
<li><a href="#fn_genkey">Generating a new private key</a></li>
<li><a href="#fn_create">Creating a new repository</a></li>
<li><a href="#fn_push">Pushing to a repository</a></li>
<li><a href="#fn_pull">Pulling from a repository</a></li>
</ul>
</li>
<li><a href="#fms_overview">Using FMS to send and receive update
notifications</a>
<ul>
<li><a href="#fms_trust_map">The update trust map</a></li>
<li><a href="#fms_read">Reading other people's
notifications</a></li>
<li><a href="#fms_post">Posting your own notifications</a></li>
<li><a href="#fms_pull_hash">Pulling an announced
repository</a></li>
</ul>
</li>
<li><a href="#fn_reinsert">Reinserting and 'sponsoring'
repositories</a></li>
<li><a href="#forking">Forking a repository onto a new USK</a></li>
<li><a href="#key_sharing">Sharing private keys</a></li>
<li><a href="#fn_putsite">Inserting a freesite</a></li>
<li><a href="#risks">Risks</a></li>
<li><a href="#advocacy">Advocacy</a></li>
<li><a href="#source_code">Source Code</a></li>
<li><a href="#version_info">Fixes and version information</a></li>
<li><a href="#freenet_links">Freenet-only links</a></li>
<li><a href="#contact">Contact</a></li>
</ul>
<hr />
<h2><a name="introduction" id="introduction">Introduction</a></h2>
The Infocalypse 2.0 hg extension is an extension for Mercurial that
allows you to create, publish and maintain <em>incrementally</em>
updateable repositories in Freenet.
<p>It works <a href="#advocacy">better</a> than the other DVCS
currently available for Freenet.</p>
<p>Most of the information you will find in this document can also
be found in the extension's online help. i.e.:</p>
<pre>
hg help infocalypse
</pre>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="requirements" id="requirements">Requirements</a></h2>
The extension has the following dependencies:
<ul>
<li>Freenet<br />
You can more information on Freenet here:<br />
<a href="http://freenetproject.org/">http://freenetproject.org/
[HTTP Link!]</a></li>
<li>Python<br />
I test on Python 2.5.4 and 2.6.1. Any 2.5.x or later version should
work. Earlier versions may work.
<p>You probably won't have to worry about installing Python. It's
included in the Windows binary Mercurial distributions and most
*nix flavor OS's should have a reasonably update to date version of
Python installed.</p>
</li>
<li>Mercurial<br />
You can find more information on Mercurial here:<br />
<a href=
"http://mercurial.selenic.com/wiki/">http://mercurial.selenic.com/wiki/
[HTTP Link!]</a>
<p>Version 1.0.2 won't work.</p>
<p>I use version 1.5 (x86 Gentoo) on a daily basis. Later
versions should work.</p>
<p>I've smoke tested 1.1.2 (on Ubuntu Jaunty Jackalope) and 1.3 (on
Windows XP) without finding any problems.</p>
</li>
<li>FMS<br />
Installation of the Freenet Messaging System (FMS) is
<em>optional</em> but <em>highly recommended</em>. The hg
fn-fmsread and hg fn-fmsnotify commands won't work without FMS.
Without fn-fmsread it is extremely difficult to reliably detect
repository updates.
<p>The official FMS freesite is here:</p>
<pre>
<a href=
"USK@0npnMrqZNKRCRoGojZV93UNHCMN-6UU3rRSAmP6jNLE,~BG-edFtdCC1cSH4O3BWdeIYa8Sw5DfyrSV-TKdO5ec,AQACAAE/fms/128/">USK@0npnMrqZNKRCRoGojZV93UNHCMN-6UU3rRSAmP6jNLE,~BG-edFtdCC1cSH4O3BWdeIYa8Sw5DfyrSV-TKdO5ec,AQACAAE/fms/128/
</a>
</pre></li>
<li>lib-pyFreenet<br />
Installing lib-pyFreenet is optional for many usages, but required to
use WebOfTrust plugin integration.
<p>The latest development of the library (as of this writing) is available
<a href="https://github.com/ArneBab/lib-pyFreenet-staging/tree/review-bab">here [HTTP Link!]</a>.
</p></li>
<li>Web of Trust<br />
Installing Web of Trust (or its counterpart,
<a href="https://github.com/tmarkus/LessCrappyWebOfTrust">Less Crappy Web of Trust [HTTP Link!]</a>)
is optional, but provides some helpful lookup features. TODO: Fill out when
feature list is more concrete.<br />
Web of Trust is an official plugin distributed with Freenet, and can be
added on the Plugins page in the Configuration menu.</li>
</ul>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="installation" id="installation">Installation</a></h2>
You checked the <a href="#requirements">requirements</a> and
understand the <a href="#risks">risks</a> right?
<p>Here are step-by-step instructions on how to install the
extension.</p>
<ul>
<li><a name="bootstrap_chk" id="bootstrap_chk">Download the
bootstrap hg bundle:</a>
<pre>
<a href=
"CHK@0R-dAUNvy7OLyHgN5sH50YUhEomk0XvlI~caIOM8dG0,NBLzCvJ1zpPSLyJUzZugg9tw12oSdb7YcOflbZI1YiQ,AAMC--8/infocalypse2_8521f306c915.hg">CHK@0R-dAUNvy7OLyHgN5sH50YUhEomk0XvlI~caIOM8dG0,NBLzCvJ1zpPSLyJUzZugg9tw12oSdb7YcOflbZI1YiQ,AAMC--8/infocalypse2_8521f306c915.hg</a>
</pre>
You'll get a <b>Potentially Dangerous Content</b> warning from
fproxy because the mime type isn't set. Choose 'Click here to force
your browser to download the file to disk.'.
<p>I'll refer to the directory that you saved the bundle file to as
DOWNLOAD_DIR.</p>
</li>
<li><a name="install_dir" id="install_dir">Create</a> an empty
directory where you want to install the extension. I'll refer to
that directory as INSTALL_DIR in the rest of these
instructions.</li>
<li>Create an empty hg repository there. i.e.:
<pre>
   cd INSTALL_DIR
   hg init
</pre></li>
<li>Unbundle the bootstrap bundle into the new repository. i.e:
<pre>
   hg pull DOWNLOAD_DIR/infocalypse2_1723a8de6e7c.hg
   hg update
</pre></li>
<li>Edit the '[extensions]' section of your .hgrc/mercurial.ini
file to point to the infocalypse directory in the unbundled source.
<pre>
     # .hgrc/mercurial.ini snippet
     [extensions]
     infocalypse = INSTALL_DIR/infocalypse

   
</pre>
where INSTALL_DIR is the directory you unbundled into.
<p>If you don't known where to find/create your .hgrc/mercurial.ini
file this link may be useful:<br />
<a href=
"http://www.selenic.com/mercurial/hgrc.5.html">http://www.selenic.com/mercurial/hgrc.5.html
[HTTP Link!]</a></p>
</li>
<li>Run fn-setup to create the config file and temp dir. i.e.
<pre>
   hg fn-setup
   
</pre>
If you run your Freenet node on another machine or on a
non-standard port you'll need to use the --fcphost and/or --fcpport
parameters to set the FCP host and port respectively.
<p>By default fn-setup will write the configuration file for the
extension (.infocalype on *nix, infocalypse.ini on Windows) into
your home directory and also create a temp directory called
infocalypse_tmp there.</p>
<p>You can change the location of the temp directory by using the
--tmpdir argument.</p>
<p>If you want to put the config file in a different location set
the cfg_file option in the [infocalypse] section of your
.hgrc/mercurial.ini file <em>before</em> running fn-setup.</p>
<pre>
   Example .hgrc entry:
   # Snip, from .hgrc
   [infocalypse]
   cfg_file = /mnt/usbkey/s3kr1t/infocalypse.cfg
   
</pre></li>
<li><a name="setup_fms" id="setup_fms">Edit the fms_id and possibly
fms_host/fms_port information in the .infocalyse/infocalypse.ini
file. i.e.:</a><br />
<pre>
     # Example .infocalypse snippet
     fms_id = YOUR_FMS_ID

     fms_host = 127.0.0.1
     fms_port = 1119
   
</pre>
where YOUR_FMS_ID is the part of your fms id before the '@' sign.
<p>If you run FMS with the default settings on the same machine you
are running Mercurial on you probably won't need to adjust the
fcp_host or fcp_port.</p>
<p>You can <em>skip</em> this step if you're not running fms.</p>
</li>
<li>Read the latest know version of the extension's repository USK
index from Freenet.
<pre>
   hg fn-fmsread -v
   
</pre>
<p>You can <em>skip</em> this step if you're not running fms.</p>
</li>
<li><a name="pull_example" id="pull_example">Pull the latest
changes to the extension from Freenet for the first time. <em>Don't
skip this step!</em> i.e.:</a>
<pre>
   hg fn-pull --aggressive --debug --uri USK@kRM~jJVREwnN2qnA8R0Vt8HmpfRzBZ0j4rHC2cQ-0hw,2xcoQVdQLyqfTpF2DpkdUIbHFCeL4W~2X1phUYymnhM,AQACAAE/wiki_hacking.R1/20
   hg update
   
</pre>
You may have trouble finding the top key if you're not using
fn-fmsread. Just keep retrying. If you know the index has
increased, use the new index in the URI.
<p>After the first pull, you can <a href="#updating">update</a>
without the URI.</p>
</li>
</ul>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="updating" id="updating">Updating</a></h2>
This extension is under active development. You should periodically
update to get the latest bug fixes and new features.
<p>Once you've installed the extension and <a href=
"#pull_example">pulled</a> it for the first time, you can get
updates by cd'ing into the initial <a href=
"#install_dir">INSTALL_DIR</a> and typing:</p>
<pre>
hg fn-fmsread -v
hg fn-pull --aggressive
hg update
</pre>
If you're not running FMS you can skip the fn-fmsread step. You may
have trouble getting the top key. Just keep retrying.
<p>If you're having trouble updating and you know the index has
increased, use the full URI with the new index as <a href=
"#pull_example">above</a>.</p>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="background" id="background">Background</a></h2>
Here's background information that's useful when using the
extension. See the <a href=
"USK@-bk9znYylSCOEDuSWAvo5m72nUeMxKkDmH3nIqAeI-0,qfu5H3FZsZ-5rfNBY-jQHS5Ke7AT2PtJWd13IrPZjcg,AQACAAE/feral_codewright/17/infocalypse_hg.html">
Infocalypse 2.0 hg extension</a> page on my freesite for a more
detailed description of how the extension works.
<h3><a name="repo_bundles" id="repo_bundles">Repositories are
collections of hg bundle files</a></h3>
An Infocalypse repository is just a collection of hg bundle files
which have been inserted into Freenet as CHKs and some metadata
describing how to pull the bundles to reconstruct the repository
that they represent. When you 'push' to an infocalypse repository a
new bundle CHK is inserted with the changes since the last update.
When you 'pull', only the CHKs for bundles for changesets not
already in the local repository need to be fetched.
Bundles are a strict subset of a complete insert, and can be inserted
by a third party without the private keys.
<h3><a name="repo_usks" id="repo_usks">Repository USKs</a></h3>
The latest version of the repository's metadata is stored on a
Freenet Updateable Subspace Key (USK) as a small binary file.
<p>You'll notice that repository USKs end with a number without a
trailing '/'. This is an important distinction. A repository USK
<em>is not</em> a freesite. If you try to view one with fproxy
you'll just get a 'Potentially Dangerous Content' warning. This is
harmless, and ugly but unavoidable at the current time because of
limitation in fproxy/FCP.</p>
<h3><a name="repo_redundancy" id="repo_redundancy">Repository top
key redundancy</a></h3>
Repository USKs that end in *.R1/&lt;number&gt; are inserted
redundantly, with a second USK insert done on *.R0/&lt;number&gt;.
Top key redundancy makes it easier for other people to fetch your
repository.
<p>Inserting to a redundant repository USK makes the inserter more
vulnerable to <a href="#correlation_attacks">correlation
attacks</a>. Don't use '.R1' USKs if you're worried about this.</p>
<h3><a name="repo_hashes" id="repo_hashes">Repository
Hashes</a></h3>
Repository USKs can be long and cumbersome. A repository hash is
the first 12 bytes of the SHA1 hash of the zero index version of a
repository USK. e.g.:<br />
<pre>
SHA1( USK@kRM~jJVREwnN2qnA8R0Vt8HmpfRzBZ0j4rHC2cQ-0hw,2xcoQVdQLyqfTpF2DpkdUIbHFCeL4W~2X1phUYymnhM,AQACAAE/wiki_hacking.R1/0 )
  == 'c856b1653f0b'
</pre>
You can get the repository hash for a repository USK using:<br />
<pre>
hg fn-info
</pre>
from a directory the repository USK has been fn-pull'd into.
<p>You can get the hashes of repositories that other people have
announced via fms with:</p>
<pre>
hg fn-fmsread --listall
</pre>
<p>Repository hashes are used in the <a href="#fms_trust_map">fms
update trust map</a>.</p>
<h3><a name="repo_private" id="repo_private">The default private
key</a></h3>
When you run fn-setup, it creates a default SSK private key, which
it stores in the default_private_key parameter in your
.infocalypse/infocalypse.ini file.
<p>You can edit the config file to substitute any valid SSK private
key you want.</p>
<p>If you specify an Insert URI without the key part for an
infocalypse command the default private key is filled in for you.
i.e<br /></p>
<pre>
hg fn-create --uri USK@/test.R1/0
</pre>
Inserts the local hg repository into a new USK in Freenet, using
the private key in your config file.
<h3><a name="repo_mappings" id="repo_mappings">USK &lt;--&gt;
Directory mappings</a></h3>
The extension's commands 'remember' the insert and request
repository USKs they were last run with when run again from the
same directory.
<p>This makes it unnecessary to retype cumbersome repository USK
values once a repository has been successfully pulled or pushed
from a directory.</p>
<h3><a name="arg_aggressive" id="arg_aggressive">Aggressive topkey
searching</a></h3>
fn-pull and fn-push have an --aggressive command line argument
which causes them to search harder for the latest request URI.
<p>This can be slow, especially if the USK index is much lower than
the latest index in Freenet.</p>
<p>You will need to use it if you're not using FMS update
notifications.</p>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="basic" id="basic">Basic Usage</a></h2>
Here are examples of basic commands.
<h3><a name="fn_genkey" id="fn_genkey">Generating a new private
key</a></h3>
You can generate an new private key with:<br />
<pre>
hg fn-genkey
</pre>
This has no effect on the stored default private key.
<p>Make sure to change the 'SSK' in the InsertURI to 'USK' when
supplying the insert URI on the command line.</p>
<h3><a name="fn_create" id="fn_create">Creating a new
repository</a></h3>
<pre>
hg fn-create --uri USK@/test.R1/0
</pre>
Inserts the local hg repository into a new USK in Freenet, using
the private key in your config file. You can use a full insert URI
value if you want.
<p>If you see an "update -- Bundle too big to salt!" warning
message when you run this command you should consider running
<a href="#fn_reinsert">fn-reinsert --level 4</a>.</p>
<h3><a name="fn_push" id="fn_push">Pushing to a repository</a></h3>
<pre>
hg fn-push --uri USK@/test.R1/0
</pre>
Pushes incremental changes from the local directory into an
existing Infocalypse repository.
<p>The &lt;keypart&gt;/test.R1/0 repository must already exist in
Freenet. In the example above the default private key is used. You
could have specified a full Insert URI. The URI must end in a
number but the value doesn't matter because fn-push searches for
the latest unused index.</p>
<p>You can <a href="#repo_mappings">ommit the --uri argument</a>
when you run from the same directory the fn-create (or a previous
fn-push) was run from.</p>
<h3><a name="fn_pull" id="fn_pull">Pulling from a
repository</a></h3>
<pre>
hg fn-pull --uri &lt;request uri&gt;
</pre>
pulls from an Infocalypse repository in Freenet into the local
repository. <a href="#pull_example">Here's</a> an example with a
fully specified uri.
<p>You can <a href="#repo_mappings">ommit the --uri argument</a>
when you run from the same directory a previous fn-pull was
successfully run from.</p>
<p>For maximum reliability use the <a href=
"#arg_aggressive">--aggressive</a> argument.</p>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="fms_overview" id="fms_overview">Using FMS to send and
receive update notifications</a></h2>
The extension can send and receive repository update notifications
via FMS. It is <em>highly recommended</em> that you <a href=
"#setup_fms">setup this feature</a>.
<h3><a name="fms_trust_map" id="fms_trust_map">The update trust
map</a></h3>
There's a trust map in the .infocalypse/infocalypse.ini config file
which determines which fms ids can update the index values for
which repositories. It is purely local and completely separate from
the trust values which appear in the FMS web of trust.
<p>The format is:<br />
&lt;number&gt; =
&lt;fms_id&gt;|&lt;usk_hash0&gt;|&lt;usk_hash1&gt;| ...
|&lt;usk_hashn&gt;</p>
<p>The number value must be unique, but is ignored.</p>
<p>The fms_id values are the full FMS ids that you are trusting to
update the repositories with the listed hashes.</p>
<p>The usk_hash* values are <a href="#repo_hashes">repository
hashes</a>.</p>
<p>Here's an example trust map config entry:</p>
<pre>
   # Example .infocalypse snippet
   [fmsread_trust_map]
   1 = test0@adnT6a9yUSEWe5p8J-O1i8rJCDPqccY~dVvAmtMuC9Q|55833b3e6419
   0 = djk@isFiaD04zgAgnrEC5XJt1i4IE7AkNPqhBG5bONi6Yks|be68e8feccdd|5582404a9124
   2 = test1@SH1BCHw-47oD9~B56SkijxfE35M9XUvqXLX1aYyZNyA|fab7c8bd2fc3
</pre>
<p>You <em>must</em> update the trust map to enable index updating
for repos other than the one this code lives in (c856b1653f0b). You
can edit the config file directly if you want.</p>
<p>However, the easiest way to update the trust map is by using the
--trust and --untrust options on fn-fmsread.</p>
<p>For example to trust
falafel@IxVqeqM0LyYdTmYAf5z49SJZUxr7NtQkOqVYG0hvITw to notify you
about changes to the repository with repo hash 2220b02cf7ee,
type:</p>
<pre>
hg fn-fmsread --trust --hash 2220b02cf7ee --fmsid falafel@IxVqeqM0LyYdTmYAf5z49SJZUxr7NtQkOqVYG0hvITw
</pre>
<p>And to stop trusting that FMS id for updates to 2220b02cf7ee,
you would type:</p>
<pre>
hg fn-fmsread --untrust --hash 2220b02cf7ee --fmsid falafel@IxVqeqM0LyYdTmYAf5z49SJZUxr7NtQkOqVYG0hvITw
</pre>
<p>To show the trust map type:</p>
<pre>
hg fn-fmsread --showtrust
</pre>
<h3><a name="fms_read" id="fms_read">Reading other people's
notifications</a></h3>
<pre>
hg fn-fmsread -v
</pre>
Will read update notifications for all the repos in the trust map
and locally cache the new latest index values. If you run with -v
it prints a message when updates are available which weren't used
because the sender(s) weren't in the trust map.
<pre>
hg fn-fmsread --list
</pre>
Displays announced repositories from fms ids that appear in the
trust map.
<pre>
hg fn-fmsread --listall
</pre>
Displays all announced repositories including ones from unknown fms
ids.
<h3><a name="fms_pull_hash" id="fms_pull_hash">Pulling an announced
repository</a></h3>
You can use the --hash option with fn-pull to pull any repository
you see in the fn-read --list or fn-read --listall lists.
<p>For example to pull the latest version of the infocalypse
extension code, cd to an empty directory and type:</p>
<pre>
hg init
hg fn-pull --hash c856b1653f0b --aggressive
</pre>
<h3><a name="fms_post" id="fms_post">Posting your own
notifications</a></h3>
<pre>
hg fn-fmsnotify -v
</pre>
Posts an update notification for the current repository to fms.
<p>You MUST <a href="#setup_fms">set the fms_id value in the config
file</a> to your fms id for this to work.</p>
<p>Use --dryrun to double check before sending the actual fms
message.</p>
<p>Use --announce at least once if you want your USK to show up in
the fmsread --listall list.</p>
<p>By default notifications are written to and read from the
infocalypse.notify fms group.</p>
<p>The read and write groups can be changed by editing the
following variables in the config file:</p>
<p>fmsnotify_group = &lt;group&gt;<br />
fmsread_groups = &lt;group0&gt;[|&lt;group1&gt;|...]</p>
<p>fms can have pretty high latency. Be patient. It may take hours
(sometimes a day!) for your notification to appear. Don't send lots
of redundant notifications.</p>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="fn_reinsert" id="fn_reinsert">Reinserting and
'sponsoring' repositories</a></h2>
<pre>
hg fn-reinsert
</pre>
will re-insert the bundles for the repository that was last pulled
into the directory.
<p>The exact behavior is determined by the level argument.</p>
<p>level:</p>
<ul>
<li>1 - re-inserts the top key(s)</li>
<li>2 - re-inserts the top keys(s), graphs(s) and the most recent
update.</li>
<li>3 - re-inserts the top keys(s), graphs(s) and all keys required
to bootstrap the repo.
<p>This is the default level.</p>
</li>
<li>4 - adds redundancy for big (&gt;7Mb) updates.</li>
<li>5 - re-inserts existing redundant big updates.</li>
</ul>
<p>Levels 1 and 4 require that you have the private key for the
repository. For other levels, the top key insert is skipped if you
don't have the private key.</p>
<p>DO NOT use fn-reinsert if you're concerned about <a href=
"#correlation_attacks">correlation attacks</a>. The risk is on the
order of re-inserting a freesite, but may be worse if you use
redundant (i.e. USK@&lt;line noise&gt;/name.R1/0) top keys.</p>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="forking" id="forking">Forking a repository onto a new
USK</a></h2>
<pre>
hg fn-copy --inserturi USK@/name_for_my_copy.R1/0
</pre>
copies the Infocalypse repository which was fn-pull'd into the
local directory onto a new repository USK under your default
private key. You can use a full insert URI if you want.
<p>This only requires copying the top key data (a maximum of 2 SSK
inserts).</p>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="key_sharing" id="key_sharing">Sharing private
keys</a></h2>
It is possible for multiple people to collaborate anonymously over
Freenet by sharing the private key to a single Infocalypse
repository.
<p>The <a href=
"USK@EbQbLWtWLRBgQl4Ly-SjQJvzADdJPfIXNQfCbKzgCFI,XDLYQTC0nYD4rhIIP~Ff~itkvVVF2u4WU8YVSL2f5RA,AQACAAE/freefaq/23/">
FreeFAQ</a> is an example of this technique.</p>
Here are some things to keep in mind when sharing private keys.
<ul>
<li>There is no (explict) key revocation in Freenet<br />
If you decide to share keys, you should generate a special key on a
per repo basis with fn-genkey. There is <em>no way</em> to revoke a
private key once it has been shared. This could be mitigated with
an ad-hoc convention. e.g. if I find any file named
<code>USK@&lt;public_key&gt;/revoked.txt</code>, I stop using the
key.</li>
<li>Non-atomic top key inserts<br />
Occasionally, you might end up overwriting someone elses commits
because the FCP insert of the repo top key isn't atomic. I think
you should be able to merge and re fn-push to resolve this. You can
fn-pull a specific version of the repo by specify the full URI
including the version number with --uri and including the
--nosearch option.</li>
<li>All contributors should be in the <a href=
"#fms_trust_map">fn-fmsread trust map</a></li>
</ul>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="fn_putsite" id="fn_putsite">Inserting a
freesite</a></h2>
<pre>
hg fn-putsite --index &lt;n&gt;
</pre>
inserts a freesite based on the configuration in the freesite.cfg
file in the root of the repository. Use:<br />
<pre>
hg fn-putsite --createconfig
</pre>
to create a basic freesite.cfg file that you can modify. Look at
the comments in it for an explanation of the supported parameters.
<p>The default freesite.cfg file inserts using the same private key
as the repo and a site name of 'default'. Editing the name is
highly recommended.</p>
<p>You can use --key CHK@ to insert a test version of the site to a
CHK key before writing to the USK.</p>
<p>Limitations:</p>
<ul>
<li>You MUST have fn-pushed the repo at least once in order to
insert using the repo's private key. If you haven't fn-push'd
you'll see this error: "You don't have the insert URI for this
repo. Supply a private key with --key or fn-push the repo."</li>
<li>Inserts <em>all</em> files in the site_dir directory in the
freesite.cfg file. Run with --dryrun to make sure that you aren't
going to insert stuff you don't want too.</li>
<li>You must manually specify the USK edition you want to insert
on. You will get a collision error if you specify an index that was
already inserted.</li>
<li>Don't use this for big sites. It should be fine for notes on
your project. If you have lots of images or big binary files use a
tool like jSite instead.</li>
<li>Don't modify site files while the fn-putsite is running.</li>
</ul>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="risks" id="risks">Risks</a></h2>
I don't believe that using this extension is significantly more
dangerous that using any other piece of Freenet client code, but
here is a list of the risks which come to mind:
<ul>
<li>Freenet is beta software<br />
The authors of Freenet don't pretend to guarantee that it is free
of bugs that could that could compromise your anonymity or worse.
<p>While written in Java, Freenet loads native code via JNI (FEC
codecs, bigint stuff, wrapper, etc.) that makes it vulnerable to
the same kinds of attacks as any other C/C++ code.</p>
</li>
<li>FMS == anonymous software<br />
FMS is published anonymously on Freenet and it is written in C++
with dependencies on large libraries which could contain security
defects.
<p>I personally build FMS from source and run it in a chroot
jail.</p>
<p>Somedude, the author of FMS, seems like a reputable guy and has
conducted himself as such for more than a year.</p>
</li>
<li><a name="correlation_attacks" id=
"correlation_attacks">correlation attacks</a><br />
There is a concern that any system which inserts keys that can be
predicted ahead of time could allow an attacker with control over
many nodes in the network to eventually find the IP of your node.
<p><em>Any</em> system which has this property is vulnerable. e.g.
fproxy Freesite insertion, Freetalk, FMS, FLIP. This extension's
<em>optional</em> use of <a href="#repo_redundancy">redundant top
keys</a> may make it particularly vulnerable. If you are concerned
don't use '.R1' keys.</p>
<p>Running your node in pure darknet mode with trusted peers may
somewhat reduce the risk of correlation attacks.</p>
</li>
<li>Bugs in my code, Mercurial or Python<br />
I do my best but no one's perfect.
<p>There are lots of eyes over the Mercurial and Python source.</p>
</li>
</ul>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="advocacy" id="advocacy">Advocacy</a></h2>
Here are some reasons why I think the Infocalypse 2.0 hg extension
is better than <a href=
"USK@MYLAnId-ZEyXhDGGbYOa1gOtkZZrFNTXjFl1dibLj9E,Xpu27DoAKKc8b0718E-ZteFrGqCYROe7XBBJI57pB4M,AQACAAE/pyFreenetHg/31/">
pyFreenetHg</a> and <a href=
"USK@VoFcfs8Y3VQfwD66ZgXAb4HBiS~WJe8w9mOy2hS9Mh8,OS6~bhX8LHxMLw-sruBkWDeACo-fg4yBZqueMPVj1Uc,AQACAAE/egit-freenet/14/">
egit-freenet</a>:
<ul>
<li>Incremental
<p>You only need to insert/retrieve what has actually changed.
Changes of up to 32k of compressed deltas can be fetched in as
little as one SSK fetch and one CHK fetch.</p>
</li>
<li>Redundant
<p>The top level SSK and the CHK with the representation of the
repository state are inserted redundantly so there are no 'critical
path' keys. Updates of up to ~= 7Mb are inserted redundantly by
cloning the splitfile metadata at the cost of a single 32k CHK
insert.</p>
</li>
<li>Re-insertable
<p>Anyone can re-insert all repository data except for the top
level SSKs with a simple command (hg fn-reinsert). The repository
owner can re-insert the top level SSKs as well.</p>
</li>
<li>Automatic rollups
<p>Older changes are automatically 'rolled up' into large
splitfiles, such that the entire repository can almost always be
fetched in 4 CHK fetches or less.</p>
</li>
</ul>
<p><a href="#toc">[TOC]</a></p>
<hr />
<h2><a name="source_code" id="source_code">Source Code</a></h2>
The authoritative repository for the extension's code is hosted in
Freenet:
<pre>
hg init
hg fn-fmsread -v
hg fn-pull --aggressive --debug --uri USK@kRM~jJVREwnN2qnA8R0Vt8HmpfRzBZ0j4rHC2cQ-0hw,2xcoQVdQLyqfTpF2DpkdUIbHFCeL4W~2X1phUYymnhM,AQACAAE/wiki_hacking.R1/20
hg update

NOTE:
This repository has some other unmaintained and abandoned stuff in it.
e.g. the pre jfniki python server based wiki code, python incremental archive stuff.

</pre>
<p>It is also mirrored on <code>bitbucket.org</code>:</p>
<pre>
<code>hg clone http://bitbucket.org/dkarbott/wiki_hacking/
</code>
</pre>
<a href="#toc">[TOC]</a>
<hr />
<h2><a name="version_info" id="version_info">Fixes and version
information</a></h2>
<ul>
<li>hg version: 0c5ce9e6b3b4<br />
Fixed intermittent stall when bootstrapping from an empty
repo.</li>
<li>hg version: 7f39b20500f0<br />
Fixed bug that kept fn-pull --hash from updating the initial USK
index.</li>
<li>hg version: 7b10fa400be1<br />
Added fn-fmsread --trust and --untrust and fn-pull --hash
support.<br />
<em>fn-pull --hash isn't really usable until 7f39b20500f0</em></li>
<li>hg version: ea6efac8e3f6<br />
Fixed a bug that was causing the berkwood binary 1.3 Mercurial
distribution (<a href=
"http://mercurial.berkwood.com/binaries/Mercurial-1.3.exe">http://mercurial.berkwood.com/binaries/Mercurial-1.3.exe
[HTTP Link!]</a>) not to work.</li>
</ul>
<a href="#toc">[TOC]</a>
<hr />
<h2><a name="freenet_links" id="freenet_links">Freenet-only
links</a></h2>
<p>This document is meant to inserted into Freenet.</p>
<p>It contains links (starting with '<code>CHK@</code>' and
'<code>USK@</code>') to Freenet keys that will only work from
within <a href=
"http://wiki.freenetproject.org/FreenetFProxy">fproxy [HTTP
link!]</a>.</p>
<p>You can find reasonably up to date version of this document on
my freesite:</p>
<pre>
<code><a href=
"USK@-bk9znYylSCOEDuSWAvo5m72nUeMxKkDmH3nIqAeI-0,qfu5H3FZsZ-5rfNBY-jQHS5Ke7AT2PtJWd13IrPZjcg,AQACAAE/feral_codewright/17/infocalypse_howto.html">USK@-bk9znYylSCOEDuSWAvo5m72nUeMxKkDmH3nIqAeI-0,qfu5H3FZsZ-5rfNBY-jQHS5Ke7AT2PtJWd13IrPZjcg,AQACAAE/feral_codewright/17/infocalypse_howto.html</a>
</code>
</pre>
<a href="#toc">[TOC]</a>
<hr />
<h2><a name="contact" id="contact">Contact</a></h2>
<b>FMS:</b><br />
djk@isFiaD04zgAgnrEC5XJt1i4IE7AkNPqhBG5bONi6Yks
<p>I lurk on the freenet and fms boards.</p>
<p>If you really need to you can email me at d kar bott at com cast
dot net but I prefer FMS.</p>
<pre>
<b>freesite:</b>
<a href=
"USK@-bk9znYylSCOEDuSWAvo5m72nUeMxKkDmH3nIqAeI-0,qfu5H3FZsZ-5rfNBY-jQHS5Ke7AT2PtJWd13IrPZjcg,AQACAAE/feral_codewright/17/">USK@-bk9znYylSCOEDuSWAvo5m72nUeMxKkDmH3nIqAeI-0,qfu5H3FZsZ-5rfNBY-jQHS5Ke7AT2PtJWd13IrPZjcg,AQACAAE/feral_codewright/17/</a>

</pre>
<p><a href="#toc">[TOC]</a></p>
<hr />
</body>
</html>