--- name: "sks" section: "8" platform: "linux" package: "sks" version: "1.1.6+git20210302.c3ba6d5a-4+b2" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/sks" --- # sks(8) Synchronizing Key Server ## NAME SKS - Synchronizing Key Server ## SYNOPSIS sks \[options\] -debug ## 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. ## 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 ## OPTIONS SKS binary command options are as follows: - db ``` Initiates database server. ``` - recon Initiates reconciliation server. - cleandb Apply filters to all keys in database, fixing some common problems. - build Build key database, including body of keys directly in database. - 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. - 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. - dump numkeys dumpdir \ 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,... - merge Adds key from key files to existing database. - drop Drops key from database. - 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. - version prints SKS version and linked version of Berkeley DB to stdout - help Prints the help message. ## 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. - \-debug Debugging mode. - \-debuglevel Debugging level -- sets verbosity of logging. - \-q ``` Number of bits defining a bin. ``` - \-mbar Number of errors that can be corrected in one shot. - \-seed Seed used by RNG. - \-hostname Current hostname. - \-nodename Current nodename. - \-d ``` Number of keys to drop at random when synchronizing. ``` - \-n ``` Number of keydump files to load at once. ``` - \-max\_internal\_matches Maximum number of matches for most specific word in a multi-word search. - \-max\_matches Maximum number of matches that will be returned from a query. - \-max\_uid\_fetches Maximum number of uid fetches performed in a verbose index query. - \-pagesize Pagesize in 512 byte chucks for key db. - \-keyid\_pagesize Pagesize in 512 byte chucks for keyid db. - \-meta\_pagesize Pagesize in 512 byte chucks for metadata db. - \-subkeyid\_pagesize Pagesize in 512 byte chucks for subkeyid db. - \-time\_pagesize Pagesize in 512 byte chucks for time db. - \-tqueue\_pagesize Pagesize in 512 byte chucks for tqueue db. - \-word\_pagesize Pagesize in 512 byte chunks for word db. - \-cache Cache size in megs for key db. - \-ptree\_pagesize Pagesize in 512 byte chunks for prefix tree db. - \-ptree\_cache Cache size in megs for prefix tree db. - \-baseport Set base port number. - \-recon\_port Set recon port number. - \-recon\_address Set recon binding addresses. Can be a list of whitespace separated IP addresses or domain names. - \-hkp\_port Set hkp port number. - \-hkp\_address Set hkp binding addresses. Can be a list of whitespace separated IP addresses or domain names. - \-use\_port\_80 Have the HKP interface listen on port 80, as well as the hkp\_port. - \-basedir Set base directory. - \-stdoutlog Send log messages to stdout instead of log file. - \-diskptree Use a disk-based ptree implementation. Slower, but requires far less memory. - \-nodiskptree Use in-mem ptree. - \-max\_ptree\_nodes Maximum number of allowed ptree nodes. Only meaningful if -diskptree is set. - \-prob Set probability. Used for testing code only. - \-recon\_sync\_interval Set sync interval for reconserver. - \-gossip\_interval Set time between gossips in minutes. - \-dontgossip Don't gossip automatically. Host will still respond to requests from other hosts. - \-db\_sync\_interval Set sync interval for dbserver. - \-checkpoint\_interval Time period between checkpoints. - \-recon\_checkpoint\_interval Time period between checkpoints for reconserver. - \-ptree\_thresh\_mult Multiple of thresh which specifies minimum node size in prefix tree. - \-recon\_thresh\_mult Multiple of thresh which specifies minimum node size that is included in reconciliation. - \-max\_recover Maximum number of differences to recover in one round. - \-http\_fetch\_size Number of keys for reconserver to fetch from dbserver in one go. - \-wserver\_timeout Timeout in seconds for webserver requests. - \-reconciliation\_timeout Timeout for reconciliation runs in minutes. - \-stat\_hour Hour at which to run database statistics. - \-initial\_stat Runs database statistics calculation on boot. - \-reconciliation\_config\_timeout Set timeout in seconds for initial exchange of config info in reconciliation. - \-missing\_keys\_timeout Timeout in seconds for get\_missing\_keys. - \-command\_timeout Timeout in seconds for commands set over command socket. - \-sendmail\_cmd Command used for sending mail. - \-from\_addr From address used in synchronization emails used to communicate with PKS. - \-dump\_new\_only When doing a database dump, only dump new keys, not keys already contained in a keydump file. - \-max\_outstanding\_recon\_requests Maximum number of outstanding requests in reconciliation. - \-membership\_reload\_interval Maximum interval (in hours) at which membership file is reloaded. - \-disable\_mailsync Disable sending of PKS mailsync messages. ONLY FOR STANDALONE SERVERS! THIS IS THE MECHANIASM FOR SENDING UPDATES TO NON-SKS SERVERS. - \-disable\_log\_diffs Disable logging of recent hashset diffs. - \-server\_contact Set OpenPGP KeyID of the server contact - \--help, -help - \-stdin Read keyids from stdin (sksclient only) Displays list of options. ## FILES Information about important files located in your SKS basedir. - bin/sks The main SKS executable. - bin/sks\_add\_mail The executable responsible for parsing incoming mails from PKS key servers. - bin/sks\_build.sh Script to generate an initial database. - 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! - 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. - sksconf The configuration file for your SKS server. ## EXAMPLES - membership ``` keyserver.ahost.org 11370 # Comments are allowed keyserver.foo.org 11370 # Another host with default ports ``` - sksconf ``` membership_reload_interval: 1 initial_stat: hostname: keyserver.example.com from_addr: pgp-public-keys@keyserver.example.com ``` - Procmail ``` PATH=/path/of/sks/exectuables :0 * ^Subject: incremental | /path/of/sks_add_mail /path/to/sks/directory ``` - /etc/aliases ``` pgp-public-keys: "|/path/of/sks_add_mail /path/to/sks/directory" ``` ## SEE ALSO ``` The SKS website is located at https://github.com/SKS-Keyserver/sks-keyserver. ``` ## AUTHOR The first draft was written by Thomas Sjogren \.