CLIQUE-SCHEDULER(1) Clique Reference Manual CLIQUE-SCHEDULER(1) NAME clique-scheduler - Clique endpoint daemon SYNOPSIS clique-scheduler [OPTION]... DESCRIPTION The clique-scheduler program is part of the reference implementation for the Clique(7) protocol for encrypted Internet communication with many types of metadata protected against eavesdropping. This program connects to and communicates with other Clique peers via the Internet. A majority of the time, the data sent and received is random noise, having no intrinsic value other than to prevent strong eavesdroppers from determining if and when any useful data is being exchanged. But between endpoints which share cryptographic keys gener- ated by clique-keygen(1), encrypted communication is possible which appears to an eavesdropper to be indistinguishable from random noise. clique-scheduler does no encryption or decryption of data; these func- tions are provided by a separate clique-cipherer(1) daemon if desired. The ability exists not to run the cipherer at all, in which case clique-scheduler will go through all of the motions (and use all of the bandwidth) associated with participating in one or more cliques, with- out tipping off eavesdroppers that no communication is actually happen- ing. This can be a good choice for new users who have not exchanged keys with any other users yet, but wish to get online early so that eavesdroppers cannot tell when they actually become active. It can also be useful to set run some "decoy" schedulers for smaller cliques in order to confuse unwelcome listeners. A notable feature of the scheduler is that installations can each have their own maximum bitrate, on a per-clique basis. This affords users with very slow Internet connections the same capabilities and peer reachability that fast connections permit, at proportionately reduced communication speeds. Another important capability for some users involves the establishment of private cliques, which parties who do not have knowledge of a common secret are unable to connect to or query information from. Because their membership can be restricted to a small number of peers, private cliques can operate at greatly increased speed; however, privacy sacri- fices are made in terms of what eavesdroppers are able to infer from cliques that have few peers. OPTIONS None of these command-line options are for normal use. clique-sched- uler is a daemon and is configured via sched.conf. -a FILE Writes output for diagnosing memory leaks to FILE. A script for auditing memory use and pinpointing leaks is distributed with the source code in alloc-audit.py, but you will not need it. -c FILE Use configuration file FILE instead of the default sched.conf(5). -f Stay in the foreground instead of detaching and running as a daemon. This is useful for testing, in part because you can terminate the program using Control-C. -h Prints version number and option summary. -r TEXT Substitutes TEXT for any occurrence of ~CUSTOM~ in sched.conf. This is useful when testing many instances of the program simul- taneously on a single computer, because they can share a single configuration file. -t Ignore the SIGTERM signal. This is useful when testing for pro- tecting designated scheduler instances from killall(1). Sched- ulers which ignore SIGTERM will still honor SIGINT. EXIT STATUS Not easily usable; this is a daemon. ENVIRONMENT The environment is completely ignored by the scheduler for security reasons. Except for macOS, which lacks a library function to accomplish this. FIREWALLS This peer-to-peer program communicates via UDP, ordinarily using port 1866. It is imperative that the local machine and any relevant routers be configured to allow incoming UDP packets on the appropriate port(s). NAT firewalls need to be taken into account and configured properly. In addition, outbound UDP packets must be allowed from any originating (e.g., ephemeral) port to the appropriate port(s) (usually just 1866) on remote peers. Clique's port numbering scheme is deliberately asymmetric; packets sent to a Clique port always originate from a different port. A clique con- figured to use the default port number of 1866 only uses this port for receiving packets; packets always originate from a differently numbered port, and in fact will be discarded if they originate with the same number as the reception port. This is intended to preclude consumer- grade routers from automatically opening "pinholes" for Clique connec- tions without the system administrator's knowledge. SIGNALS SIGHUP Reloads sched.conf and updates the configuration accordingly. SIGUSR1 Writes a short status message to the standard output of the process that sent the signal. Ordinarily this is the user's shell, so a kill -USR1 [pid] will cause the scheduler to "find" the user and write a status message. Note that killall(1) does not work for this, because it is a separate executable from the shell, and it is likely to exit before its standard output can be looked up and written to. A shell such as bash that has a built-in kill(1) command or a custom script is necessary. This "find the user" capability requires access to the /proc filesystem on Linux. On systems such as macOS without a working /proc, the output is automatically redirected to a regular file, hard-coded to be at /tmp/clique-scheduler-status. If this file already exists, it will be overwritten. SIGUSR2 Works like SIGUSR1, but includes information about every con- nected peer. You should not overuse this signal, because its response uses blocking writes and might stall the scheduler while the status information is being written. SIGINT Clean up and exit in an orderly manner. SIGTERM Clean up and exit in an orderly manner; however, this signal is ignored if the -t command line option is used. SIGPIPE This signal is ignored. FILES If the -c command line option is present, its argument will be used as the configuration filename. Otherwise, clique-scheduler looks for a file at ~/.clique/sched.conf, where ~ is the user's home directory as given in /etc/passwd. If that file does not exist, /etc/clique/sched.conf is tried next. If none of these files are present, the scheduler exits. NOTES Ordinarily only one clique-scheduler instance runs per machine, as it can be configured in sched.conf to use as many adapter addresses, UDP ports, and cliques as desired. All incoming traffic packets are sent to clique-cipherer(1) for testing to see if a matching key is on hand for decrypting them. Any packets which are decrypted by the cipherer are sent to clique-deliverer(1), a user-supplied and frequently user- written script for collecting and distributing plaintext within the local machine. The reason this program is a "scheduler" is that in order to evade metadata analysis by eavesdroppers, it is necessary to send traffic packets to every peer within our clique on a fixed schedule. It is this program which produces packets from cryptographically secure pseu- dorandom noise and queues them for sending. A short time before each packet is to be sent to a particular address, clique-cipherer(1) is queried to see if it wishes to substitute an encrypted packet in lieu of the decoy. If the cipherer responds on a timely basis, the packet it supplies is what will be sent. The cipherer coordinates this deci- sion with the user's clique-deliverer(1) script, which is queried for plaintext availability a moment before the packet is to go out. clique-scheduler is responsible for discovery of peers within a clique, as well as the referral of active peers to schedulers running on other machines. This is a decentralized process, with all peers within a clique having equal responsibility and authority. A scheduler can only join a clique if certain parameters match; consult sched.conf(1) for details. To be accepted into a clique, it is only necessary to query a single "seed" peer for referrals, and further peers will be recursively iden- tified and confirmed. Although all peers within a clique are usable as seeds, some cliques may find it convenient to designate convenient "well-known" seed machines via DNS. One such machine operates at seed.clique4.us; more information may be available at http://clique4.us. As the Clique network protocol is the focus of active graduate research, it should be regarded as experimental at this time. EXAMPLES clique-scheduler is ordinarily run with no command line arguments. BUGS All security mechanisms are accompanied by implicit convenience trade- offs, as well as security sacrifices made on other fronts. Clique is a slow protocol, because every peer shares its network capacity on an equal basis with all other peers, without regard to their usefulness or relevance. Plaintext throughput of 16 kilobytes per day between peers would be regarded as excellent. A peer's participation within a clique is visible to all peers. For a very large clique that has no barrier to participating, this means that anyone in the world can construct a list of every IP address in the clique, as well as the maximum peer-to-peer speed offered at each address. The SIGUSR1 and SIGUSR2 status updates are kludgy and likely to be scrapped in favor of another status reporting mechanism in a future release. The scheduler does not persist any information between runs. This means in particular that if you shut the scheduler down, all informa- tion about connected peers, their speeds, and schedules is lost. In large cliques with slower peers, this information is likely to take hours to regenerate if you need to stop the scheduler for some reason. The good news is that you can make changes to sched.conf(5) at any time, send the scheduler a SIGHUP, and the changes become live immedi- ately if the updated file has valid syntax and semantics. If the file is found to contain errors, the scheduler continues without change to its original configuration. The other good news is that if you abso- lutely must take the scheduler down for some reason, you may leave the cipherer running, as that program contains data that cannot be recov- ered after a shutdown. The documentation is likely to be incomplete in some respects, and dif- ficult to absorb in several respects. SEE ALSO clique-cipherer(1), clique-deliverer(1), clique-keygen(1), cipher.conf(5), sched.conf(5), clique(7) 2016-12-20 CLIQUE-SCHEDULER(1)