SCHED.CONF(5) Clique Reference Manual SCHED.CONF(5) NAME sched.conf - Clique scheduler configuration file SYNOPSIS sched.conf specifies the configuration for clique-scheduler(1). This often can be a very short file with as few as three lines: GlobalName clique BitsPerSecond 25000 Seed seed.clique4.us DESCRIPTION The ordinary purpose of this file is to setup the cliques the local machine will be joining. A secondary purpose is to tackle some odd configuration needs and test scenarios that may arise. In many instances, it is enough to specify the clique's case-sensitive Global- Name and indicate how many BitsPerSecond the local machine is allowed to send and receive by it. A complete list of directives appears in the next two sections. If clique-scheduler(1) is invoked using the -c command line option, its argument will be used as the configuration filename. Otherwise, the 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. SYSTEM-WIDE DIRECTIVES DropsPerMillion dpm Used for testing Clique's positive and negative acknowledgment mechanisms and other protocol features, DropsPerMillion causes Clique to neglect to send packets with a probability 0.000001 * dpm, an integer. LagSeconds lag When Clique is ready to transmit a packet, it waits for a brief interval, generally two seconds by default. The main reason for this delay is to allow the cipherer and deliverer time to decide if they have anything they would like to transmit to the remote peer at that time. You may adjust lag to any number that is not negative; however, you should consider adjusting NakSeconds in cipher.conf(5) to account for the change. A decimal point is permitted in the number you choose. Q-u-i-t something This was never meant as a user command; it's used internally to tell the program that we've reached the end of the sched.conf file. But it does work and has application when a tester wants to comment out most of the file. You must put one or more non- white symbols in something, or a syntax error will result. Socket name The scheduler and cipherer communicate via two datagram sockets. Ordinarily these are UNIX domain sockets using the abstract namespace offered by Linux, but regular filesystem sockets are also supported so that non-Linux operating systems like macOS can work. In either mechanism, the socket names in the two con- figuration files much be identical and indicate the name of the socket the cipherer will open to receive data from the sched- uler. Another socket is opened by the scheduler to communicate in the opposite direction; its name is slightly different in that a + (plus sign) is appended to it. The cipherer and sched- uler remove their listening sockets when they terminate nor- mally. The default setting when Socket is not specified is "@clique4.us", with the @ indicating that the abstract namespace is used. To use UNIX domain sockets accessible via the filesys- tem, provide a fully-qualified filesystem name that begins with /. Any directories needed to reach this name must exist and have all permissions to create and use the sockets. Relative filesys- tem names are not supported. If filesystem-based sockets are used, the sockets must not already exist. This safeguard prevents accidental startup of more than one scheduler or cipherer in a given configuration. If the scheduler or cipherer terminates abnormally, it may be nec- essary to manually remove orphaned filesystem sockets. Platforms that do not implement UNIX domain sockets exist, including at this writing the Windows Subsystem for Linux that is available for Windows 10. To work around this, the cipherer and scheduler can communicate using UDP connections through the loopback adapter. Two consecutively numbered ports are used, with the lower-numbered port specified in name. One might wonder if, given that loopback connections are sup- ported, Clique can be configured to use ordinary IPv4 so that the cipherer and scheduler can execute on different machines. There is no way to specify a non-loopback address at this time, mainly because the protocol between the scheduler and cipherer is not intended for insecure environments. Another consequence of this insecure protocol is that on multiuser machines, using filesystem-based sockets with user access restrictions rather than abstract sockets or UDP might provide the most secure con- figuration. Syslog 0 The scheduler and cipherer always start up using syslogd to out- put messages. If you would rather they don't, you have two choices: change the source code, or use this directive. But it only becomes effective after the configuration file is loaded, meaning that it won't preclude all syslog output entirely. Sim- ilarly, if you change your mind later and delete the line or use some non-zero integer for the setting, this decision to re- employ syslogd only becomes after sched.conf is completely reloaded. If you're wondering how to make syslogd work on Linux Subsystem for Windows, we don't know either and think that platform's ven- dor is in the best position to make it work. Trace flags Not intended as a user command, this enables additional debug- ging output, optionally highlighting some of the output in red on ANSI terminals. For usage, you either need to experiment or refer to an authority such as the Clique source code. flags is a string of symbols which, when present, enable specific fea- tures. Often this would look like the 52-character alphabet in both cases. A symbol that is prefixed with an asterisk (*) turns on the red highlighting for that symbol. To disable trac- ing, you must either omit this line or provide some bogus flags to meet the file's syntax requirements. CLIQUE-SPECIFIC DIRECTIVES Address w.x.y.z This causes clique-scheduler to bind to a specific local inter- face, such as 198.51.100.191, instead of to all interfaces. This is useful when your machine has more than one IP address, or when testing locally with the loopback adapter. It should be noted that if the scheduler binds a single clique to more than one address, all but one address will be non-functional, since that clique's packets will only be sent from a single address. Note also that it is perfectly valid to bind different cliques to different interfaces. BitsPerSecond bps This required directive specifies how much of your Internet con- nection bandwidth you are willing to allocate to this clique. Every clique defined must have a BitsPerSecond directive. Note that if you use a metered Internet service, you're likely to incur twice this charge because the system is used symmetri- cally for transmitting and receiving. This setting is actually a cap on how fast you send data on average; we have to rely on peers' correct behavior to obtain a similar limit on how much you receive. There is some approximateness in this setting; brief intervals may exist when this average figure is exceeded. The BitsPerSecond limit includes overhead for IP and UDP headers for each packet; thus your net throughput will be somewhat less. With additional overhead used for cryptography, acknowledgments, and length indication, about 92% of each packet remains avail- able (assuming default settings) for plaintext transmission. BytesPerPacket bpp This really isn't a figure you should be changing; the default value of 576 represents a good compromise between having a lot of room for data in Clique packets and having messages arrive relatively frequently. Moreover, BytesPerPacket is an essential parameter that defines cliques; if two cliques with the same name have different BytesPerPacket settings, then they are actu- ally two different cliques, and eavesdroppers have a much expanded opportunity to infer more from the metadata available. Transmission delays can occur if cliques with incompatible BytesPerPacket parameters happen to connect the same endpoints with the same keys. This is because packets must be individu- ally acknowledged and assembled in their correct sequence by the receiver. If a 576-byte packet is missing, it is not feasible to send a 512-byte replacement by means of a different clique. The default value of 576 parallels an old RFC 6691 requirement that all Internet hosts be able to receive packets of at least this length. You are right to infer this number includes 20 octets for the IP header and 8 octets for the UDP header. clique-cipherer requires another 16 octets for its message con- trol block, 1 for acknowledgments, and 1 for plaintext length, leaving a maximum plaintext size of 530 bytes in each 576 byte datagram. If you must depart from the default packet size, numbers as small as 61 (with 15 plaintext bytes) to as large as 65535 (UDP length limit) may work for certain applications. Be advised that choices larger than your network's maximum transmission unit will force packets to split, a choice that increases the frequency of packet loss. GlobalName name This required directive gives the name of the clique you will join. It must be the first of the clique-specific directives for each clique you define, as it also serves to separate cliques within sched.conf. For many users, GlobalName should simply specify "clique", the name of the worldwide "clique for everyone", without quotation marks. This clique is intended to be the most secure because it has the largest number and most diverse set of users, but it is also the slowest. Clique names are case-sensitive. Public cliques as a convention do not use any capital letters. If you use capital letters by mistake in a clique name, you either will not be able to connect at all, or you will end up connected in some other clique than the one you intended to be in. That is dangerous, because to keep your metadata private you will want to be in a large clique, not a small one that you and your secret friend drifted into unknowingly. Higher-speed (because of lower participation) regional cliques are available. These use two-letter country codes as defined by ISO 3166-1 alpha-2, prefixed by "clique-". For example, a United States-only regional clique would have a GlobalName of "clique-us", Antarctica would be "clique-aq", and Great Britain would be "clique-gb" (NOT "clique-uk", or you will fractionate your user base and put metadata on the table for eavesdroppers to scoop up). Again, all of these names should be in lowercase and not contain quotation marks. If more geographic specificity is needed than country, the ISO 3166-2 country subdivision codes may be followed. For example, "clique-us-ks" (Kansas), "clique-pk-sd" (Sindh). But the gen- eral rule is, always join the largest clique that is remotely fast enough for your application. You should understand that naming cliques after countries and regions may be convenient for organizing users, but does not in fact exclude anyone located anywhere in the world from partici- pating in a given clique. You may have reason to have your own private clique(s), such as for a very small company like IBM. If you wish to prevent any- one else from joining your clique (and being able to view all its users around the planet), use a GlobalName that is known only to those participating. Clique names are HMAC-protected, which is a fancy way of saying that eavesdropping is not enough to determine a clique's name. UUIDs are excellent for this pur- pose, and the uuid(1) command line tool is a good one for gener- ating names if you have it. MinimumSecondsBetween seconds This directive may be used to slow down transmissions to the same peer in the event you gain more bandwidth than necessary. For example if you join a small clique, you might configure more transmission speed than you require in the event that the clique increases in size dramatically later, but limit your speed at the outset in order to conserve other users' bandwidth. If this directive is not used, a default value of one second is imposed; a setting of zero will remove the minimum entirely. If you can tolerate a modest delay between packets, using this directive is great etiquette. A figure between 1800 and 10800 (30 minutes to 3 hours) is reasonable and corresponds to 2.56 down to 0.43 bits per second per connected peer. Port number As with BytesPerPacket, this is not a directive you want to be using. The Clique protocol is designed to load as many cliques as you desire onto a single UDP port, and using the default of 1866 ensures that users will not fractionate among various ports and thereby assist eavesdroppers in classifying who is communi- cating with whom. And as with BytesPerPacket and GlobalName, changes to this setting separate cliques, and it is not possible to exchange information between differing setpoints. You may wonder why Clique makes any port number distinction at all, instead of allow every peer to select its own port number as protocols such as HTTP and SSH do. The reason the Clique protocol is so overbearing with rules like this is to protect the rest of the Internet from attacks that exploit the protocol. Clique's peer referral process would require port numbers to be specified, meaning that a malicious peer would be able to cause many computers to send unsolicited packets to any UDP port of any system in a format that is unlikely to be understood, proba- bly with harmful consequences that cannot be anticipated today. Seed w.x.y.z Seed seed.clique4.us In order to get into a clique, we need to find a peer that we can start from for collecting IP addresses of the members. The exception is in the event we are the very first peer, in which case hopefully someone will come straight to us. Up to 16 such peers per clique may be specified using the Seed directive, although one should be adequate for most applications. It doesn't matter within a clique which peer(s) are used as seeds, because in point of fact ALL of the peers (including yours) are used in this way. But it is helpful to specify one or more seeds which have high availability. Ideally seeds would be specified using dotted quads such as 198.51.100.16, but DNS is more convenient for obvious reasons and is supported. But the price of DNS is either complexity or responsiveness, and this implementation sacrifices the latter. Your Clique scheduler makes all DNS requests one at a time, doing nothing else until all DNS tasks have been completed. That means you will disrupt your participation in all cliques briefly every time this file is loaded, particularly if you have a resolution problem and a request has to time out. For this reason, DNS requests that fail for any reason other than a non- existent name will preclude any further DNS requests from hap- pening for 15 seconds, which is intended to and probably will prevent all other name lookups from happening this time sched.conf is loaded. The author operates a public seed peer at seed.clique4.us for at least the global name "clique" and many national variants. But try to collect some other seed addresses to fall back on, and consider announcing your own public seed peer if you have a con- nection with good availability. EXAMPLE A short example appears in the SYNOPSIS section above. A longer exam- ple is included with the Clique source code. SEE ALSO clique-cipherer(1), clique-deliverer(1), clique-keygen(1), clique- scheduler(1), cipher.conf(5), clique(7) 2016-12-20 SCHED.CONF(5)