parsav  Check-in [2fef9385da]

	proc_active = global(true);
	ipckey = 0x8e037c6;
}

terra m.signum(reqsig: int)
	var sig = S._max() - reqsig
	-- we implement this in contradiction to the recommendations of the manpages
	-- because they make no goddamn sense. if SIGRTMIN can vary, using as a basis
	-- for signals is really rather stupid -- there's no guarantee a signal sent
	-- by one process will be interpreted correctly by another, as its SIGRTMIN
	-- might well be different! so we use SIGRTMAX as the base instead, assuming
	-- that it's more likely to remain constant across the whole system.
	if reqsig > S._max() or sig < S._min() then lib.bail('realtime signal error - requested signal number is greater than the available number of realtime signals') end
	return sig
end

	proc_active = global(true);
	ipckey = 0x8e037c6;
}

terra m.signum(reqsig: int)
	var sig = S._max() - reqsig
	-- we implement this in contradiction to the recommendations of the manpages
	-- because they make no goddamn sense. if SIGRTMIN can vary, using it as a basis
	-- for signals is really rather stupid -- there's no guarantee a signal sent
	-- by one process will be interpreted correctly by another, as its SIGRTMIN
	-- might well be different! so we use SIGRTMAX as the base instead, assuming
	-- that it's more likely to remain constant across the whole system.
	if reqsig > S._max() or sig < S._min() then lib.bail('realtime signal error - requested signal number is greater than the available number of realtime signals') end
	return sig
end

## invoking
the build process generates two binaries, `parsav` and `parsavd`. `parsav` is a driver tool that can be used to set up and start a `parsav` instance, as well as administer it from the command line. it accesses databases directly and uses the same backend configuration file as parsav, but can also send IPC messages directly to running `parsavd` instances.

as a convenience, the `parsav start` command can be used to start and daemonize a `parsav` instance. additionally, the `-l` option to `parsav start` can be used to redirect `parsavd`'s logging output to a file; without `-l`, logging output will be discarded and can be viewed only by connecting to the running instance with `parsav attach`. `parsav start` passes its arguments on to `parsavd`; you can use this to pass options by separating `parsav`'s arguments from `parsavd`'s with `--`. if you launch an instance with `parsav start -- -i chungus`, you can then stop that instance with `parsav -i chungus stop`. `parsav stop` can be used on its own if only one `parsavd` instance is running; otherwise, `parsav -a stop` will cleanly terminate all running instances.

you generally should not invoke `parsavd` directly except for debugging purposes, or in the context of an init daemon (particularly systemd). if you launch `parsavd` directly it will not fork to the background. 




## authentication 
below is a full list of authentication types we intend/hope to one day support. contributors should consider this a to-do list. a checked box indicates the scheme has been implemented.

* ☑ pw-sha{512,384,256,224}: an ordinary password, hashed with the appropriate algorithm

* ☐ pw-{sha1,md5,clear} (insecure, must be manually enabled at compile time with the config variable `parsav_let_me_be_a_dumbass="i know what i'm doing"`)
* ☐ pw-pbkdf2-hmac-sha{…}: a password hashed with the Password-Based Key Derivation Function 2 instead of plain SHA2
* ☐ pw-extern-ldap: try to authenticate by binding against an LDAP server
* ☐ pw-extern-cyrus: try to authenticate against saslauthd
* ☐ pw-extern-dovecot: try to authenticate against a dovecot SASL socket
* ☐ pw-extern-krb5: abuse MIT kerberos as a password verifier
* ☐ pw-extern-imap: abuse an email server as a password verifier
* (extra credit) ☐ pw-extern-radius: verify a user against a radius server
* ☐ http-oauth: automatically created when a user grants access to an oauth application, consisting of a series of TLVs. these generally should not be created or fiddled with manually
* ☐ http-gssapi: log in with a kerberos principle through the http-authenticate "negotiate" mechanism. do any browsers actually support this??
* ☐ http-extern-header: a value of `H=V` where `H` is a header passed by an app server such as nginx, and `V` is the required value. could be used to e.g. tie parsav into an existing client certificate verification infrastructure with minimal effort.
* ☐ http-extern-header: a value of `H=V` where `H` is a header passed by an app server such as nginx, and `V` is the required value. could be used to tie parsav into an existing client certificate verification infrastructure with minimal effort.
* ☐ api-digest-sha{…}: a value that can be hashed with the current epoch to derive a temporary access key without logging in. these are used for API calls, sent in the header `X-API-Key`.

## invoking
the build process generates two binaries, `parsav` and `parsavd`. `parsav` is a driver tool that can be used to set up and start a `parsav` instance, as well as administer it from the command line. it accesses databases directly and uses the same backend configuration file as parsav, but can also send IPC messages directly to running `parsavd` instances.

as a convenience, the `parsav start` command can be used to start and daemonize a `parsav` instance. additionally, the `-l` option to `parsav start` can be used to redirect `parsavd`'s logging output to a file; without `-l`, logging output will be discarded and can be viewed only by connecting to the running instance with `parsav attach`. `parsav start` passes its arguments on to `parsavd`; you can use this to pass options by separating `parsav`'s arguments from `parsavd`'s with `--`. if you launch an instance with `parsav start -- -i chungus`, you can then stop that instance with `parsav -i chungus stop`. `parsav stop` can be used on its own if only one `parsavd` instance is running; otherwise, `parsav -a stop` will cleanly terminate all running instances.

you generally should not invoke `parsavd` directly except for debugging purposes, or in the context of an init daemon (particularly systemd). if you launch `parsavd` directly it will not fork to the background. 

## [TODO] server friending
parsav servers can "friend" other parsav servers. friendly servers cache at least some of each others' content. in contrast to the promiscuous caching of activitypub servers, parsav only caches content from servers that administrators explicitly mark for caching. friendly servers share each others' list of friends so that they can rely on each others' caches if the

## authentication 
below is a full list of authentication types we intend/hope to one day support. contributors should consider this a to-do list. a checked box indicates the scheme has been implemented.

* ☑ pw-sha{512,384,256,224}: an ordinary password, hashed with the appropriate algorithm
* ☐ pw-sha3: hashed using the configurable keccak sponge function
* ☐ pw-{sha1,md5,clear} (insecure, must be manually enabled at compile time with the config variable `parsav_let_me_be_a_dumbass="i know what i'm doing"`)
* ☐ pw-pbkdf2-hmac-sha{…}: a password hashed with the Password-Based Key Derivation Function 2 instead of plain SHA2
* ☐ pw-extern-ldap: try to authenticate by binding against an LDAP server
* ☐ pw-extern-cyrus: try to authenticate against saslauthd
* ☐ pw-extern-dovecot: try to authenticate against a dovecot SASL socket
* ☐ pw-extern-krb5: abuse MIT kerberos as a password verifier (very useful for SSO/single password store regimes; LDAP can do this too)
* ☐ pw-extern-imap: abuse an email server as a password verifier
* (extra credit) ☐ pw-extern-radius: verify a user against a radius server
* ☐ http-oauth: automatically created when a user grants access to an oauth application, consisting of a series of TLVs. these generally should not be created or fiddled with manually
* ☐ http-gssapi: log in with a kerberos principle through the http-authenticate "negotiate" mechanism. do any browsers actually support this??
* ☐ http-extern-header: a value of `H=V` where `H` is a header passed by an app server such as nginx, and `V` is the required value. could be used to e.g. tie parsav into an existing client certificate verification infrastructure with minimal effort.
* ☐ http-extern-header: a value of `H=V` where `H` is a header passed by an app server such as nginx, and `V` is the required value. could be used to tie parsav into an existing client certificate verification infrastructure with minimal effort.
* ☐ api-digest-sha{…}: a value that can be hashed with the current epoch to derive a temporary access key without logging in. these are used for API calls, sent in the header `X-API-Key`.