File: sks.pod

package info (click to toggle)
sks 1.1.6-14
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 2,296 kB
  • sloc: ml: 15,228; ansic: 1,069; sh: 358; makefile: 347
file content (403 lines) | stat: -rw-r--r-- 9,588 bytes parent folder | download | duplicates (5)
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
=head1 NAME

SKS - Synchronizing Key Server

=head1 SYNOPSIS

sks [options] -debug

=head1 DESCRIPTION

SKS is a OpenPGP keyserver whose goal is to provide easy to deploy, decentralized, and highly reliable synchronization. That means that a key submitted to one SKS server will quickly be distributed to all key servers, and even wildly out-of-date servers, or servers that experience spotty connectivity, can fully synchronize with rest of the system.

The design of SKS is deliberately simple. The server consists of two single-threaded processes. The first, "sks db", fulfills the normal jobs associated with a public key server, such as answering web requests. The only special functionality of "sks db" is that it keeps a log summarizing the changes to the key database. "sks recon" does all the work with respect to reconciling hosts databases. "sks recon" keeps track of specialized summary information about the database, and can use that information to efficiently determine the differences between its database and that of another host.

=head1 FEATURES

Highly efficient and reliable reconciliation algorithm

Follows RFC2440 and RFC2440bis carefully - unlike PKS, SKS supports new and old style packets, photoID packets, multiple subkeys, and pretty much everything allowed by the RFCs.

Fully compatible with PKS system - can both send and receive syncs from PKS servers, ensuring seamless connectivity.

Simple configuration:  each host just needs a (partial) list of the other participating key servers. Gossip is used to distribute information without putting a heavy load an any one host.

Supports HKP/web-based querying, and soon-to-be-standard machine readable indices

=head1 OPTIONS

SKS binary command options are as follows:

=over

=item db

 Initiates database server.

=item recon

Initiates reconciliation server.

=item cleandb

Apply filters to all keys in database, fixing some common problems.

=item build

Build key database, including body of keys directly in database.

=item fastbuild -n [size] -cache [mbytes]

Build key database, doesn't include keys directly in database, faster than build. -n specifies the number of keydump files to read per pass when used with build and the multiple of 15,000 keys to be read per pass when used with fastbuild.  -cache specifies the database cache to use in megabytes.

=item pbuild -cache [mbytes] -ptree_cache [mbytes]

Build prefix-tree database, used by reconciliation server, from key database. Allows for specification of cache for key database and for ptree database.

=item dump numkeys dumpdir <filename-prefix>

Create a raw dump of the keys in the database. The dump is split into multiple files; the numkeys parameter determines the number of keys dumped in each file. The optional filename-prefix is prepended to the dump file names. Without it the dump files are named 0000.pgp, 0001.pgp,...

=item merge

Adds key from key files to existing database.

=item drop

Drops key from database.

=item update_subkeys [-n # of updates / 1000]

Updates subkey keyid index to include all current keys. Only useful when upgrading versions 1.0.4 or before of SKS.

=item version

prints SKS version and linked version of Berkeley DB to stdout

=item help

Prints the help message.

=back

=head1 ADDITIONAL OPTIONS

You won't need most of the options below for normal operation. These options can be given in basedir/sksconf or as command line option for the sks binary.

=over

=item -debug

Debugging mode.

=item -debuglevel

Debugging level -- sets verbosity of logging.

=item -q

 Number of bits defining a bin.

=item -mbar

Number of errors that can be corrected in one shot.

=item -seed

Seed used by RNG.

=item -hostname

Current hostname.

=item -nodename

Current nodename.

=item -d

 Number of keys to drop at random when synchronizing.

=item -n

 Number of keydump files to load at once.

=item -max_internal_matches

Maximum number of matches for most specific word in a multi-word search.

=item -max_matches

Maximum number of matches that will be returned from a query.

=item -max_uid_fetches

Maximum number of uid fetches performed in a verbose index query.

=item -pagesize

Pagesize in 512 byte chucks for key db.

=item -keyid_pagesize

Pagesize in 512 byte chucks for keyid db.

=item -meta_pagesize

Pagesize in 512 byte chucks for metadata db.

=item -subkeyid_pagesize

Pagesize in 512 byte chucks for subkeyid db.

=item -time_pagesize

Pagesize in 512 byte chucks for time db.

=item -tqueue_pagesize

Pagesize in 512 byte chucks for tqueue db.

=item -word_pagesize

Pagesize in 512 byte chunks for word db.

=item -cache

Cache size in megs for key db.

=item -ptree_pagesize

Pagesize in 512 byte chunks for prefix tree db.

=item -ptree_cache

Cache size in megs for prefix tree db.

=item -baseport

Set base port number.

=item -recon_port

Set recon port number.

=item -recon_address

Set recon binding addresses.  Can be a list of whitespace separated IP addresses or domain names.

=item -hkp_port

Set hkp port number.

=item -hkp_address

Set hkp binding addresses.  Can be a list of whitespace separated IP addresses or domain names.

=item -use_port_80

Have the HKP interface listen on port 80, as well as the hkp_port.

=item -basedir

Set base directory.

=item -stdoutlog

Send log messages to stdout instead of log file.

=item -diskptree

Use a disk-based ptree implementation. Slower, but requires far less memory.

=item -nodiskptree

Use in-mem ptree.

=item -max_ptree_nodes

Maximum number of allowed ptree nodes. Only meaningful if -diskptree is set.

=item -prob

Set probability. Used for testing code only.

=item -recon_sync_interval

Set sync interval for reconserver.

=item -gossip_interval

Set time between gossips in minutes.

=item -dontgossip

Don't gossip automatically. Host will still respond to requests from other hosts.

=item -db_sync_interval

Set sync interval for dbserver.

=item -checkpoint_interval

Time period between checkpoints.

=item -recon_checkpoint_interval

Time period between checkpoints for reconserver.

=item -ptree_thresh_mult

Multiple of thresh which specifies minimum node size in prefix tree.

=item -recon_thresh_mult

Multiple of thresh which specifies minimum node size that is included in reconciliation.

=item -max_recover

Maximum number of differences to recover in one round.

=item -http_fetch_size

Number of keys for reconserver to fetch from dbserver in one go.

=item -wserver_timeout

Timeout in seconds for webserver requests.

=item -reconciliation_timeout

Timeout for reconciliation runs in minutes.

=item -stat_hour

Hour at which to run database statistics.

=item -initial_stat

Runs database statistics calculation on boot.

=item -reconciliation_config_timeout

Set timeout in seconds for initial exchange of config info in reconciliation.

=item -missing_keys_timeout

Timeout in seconds for get_missing_keys.

=item -command_timeout

Timeout in seconds for commands set over command socket.

=item -sendmail_cmd

Command used for sending mail.

=item -from_addr

From address used in synchronization emails used to communicate with PKS.

=item -dump_new_only

When doing a database dump, only dump new keys, not keys already contained in a keydump file.

=item -max_outstanding_recon_requests

Maximum number of outstanding requests in reconciliation.

=item -membership_reload_interval

Maximum interval (in hours) at which membership file is reloaded.

=item -disable_mailsync

Disable sending of PKS mailsync messages.  ONLY FOR STANDALONE SERVERS!
THIS IS THE MECHANIASM FOR SENDING UPDATES TO NON-SKS SERVERS.

=item -disable_log_diffs

Disable logging of recent hashset diffs.

=item -server_contact

Set OpenPGP KeyID of the server contact

=item  --help, -help

=item  -stdin

Read keyids from stdin (sksclient only)

Displays list of options.

=back

=head1 FILES

Information about important files located in your SKS basedir.

=over

=item bin/sks

The main SKS executable.

=item bin/sks_add_mail

The executable responsible for parsing incoming mails from PKS key servers.

=item bin/sks_build.sh

Script to generate an initial database.

=item mailsync

The mailsync should contains a list of email addresses of PKS keyservers. This file is important, because it ensures that keys submitted directly to an SKS keyserver are also forwarded to PKS keyservers. IMPORTANT : don't add someone to your mailsync file without getting their permission first!

=item membership

With SKS, two hosts can efficiently compare their databases then repair whatever differences are found.  In order to set up reconciliation, you first need to find other SKS servers that will agree to gossip with you. The hostname and port of the server that has agreed to do so should be added to this file.

=item sksconf

The configuration file for your SKS server.

=back

=head1 EXAMPLES

=over

=item membership

 keyserver.ahost.org 11370 # Comments are allowed
 keyserver.foo.org 11370   # Another host with default ports

=item sksconf

 membership_reload_interval: 1
 initial_stat:
 hostname: keyserver.example.com
 from_addr: pgp-public-keys@keyserver.example.com

=item Procmail

 PATH=/path/of/sks/exectuables
 :0
 * ^Subject: incremental
 | /path/of/sks_add_mail /path/to/sks/directory

=item /etc/aliases

 pgp-public-keys:      "|/path/of/sks_add_mail /path/to/sks/directory"

=back

=head1 SEE ALSO

 The SKS website is located at https://bitbucket.org/skskeyserver/sks-keyserver/.

=head1 AUTHOR

The first draft was written by Thomas Sjogren <thomas@northernsecurity.net>.