FreeBSD Manual Pages
PIZAUTH(1) General Commands Manual PIZAUTH(1) NAME pizauth -- OAuth2 authentication daemon SYNOPSIS pizauth command DESCRIPTION pizauth requests, shows, and refreshes OAuth2 tokens. It is formed of two components: a persistent "server" which interacts with the user to obtain tokens, and refreshes them as necessary; and a command-line in- terface which can be used by other programs to show the OAuth2 token for a current account. The top-level commands are: dump Writes the current pizauth state to stdout: this can later be fed back into pizauth with restore. The dump format is stable within a pizauth major release (but not across major releases) and stable across platforms, though it includes timestamps that may be affected by clock drift on either the machine performing dump or restore. Clock drift does not not affect security, though it may cause dumped access tokens to be refreshed unduly early or late upon a restore. Refreshed access tokens will then be refreshed at the expected intervals. Note that while the dump output may look like it is encrypted, it is trivial for an attacker to recover access and refresh to- kens from it: it is strongly recommended that you use external encryption on the output so that your data cannot be compro- mised. info [-j] Writes output about pizauth to stdout including: the cache di- rectory path; the config file path; and pizauth version. De- faults to human-readable output in an unspecified format that may change freely between pizauth versions. -j specifies JSON output. The "info_format_version" field is an integer value specifying the version of the JSON output: if incompatible changes are made, this integer will be monotoni- cally increased. refresh [-u] account Request a refresh of the access token for account. Exits with 0 upon success. If there is not currently a valid access or refresh token, reports an error to stderr, initiates a new to- ken request, and exits with 1. Unless -u is specified, the er- ror will include an authorization URL. Note that this command does not block and will not start a new refresh if one is ongo- ing. reload Reload the server's configuration. Exits with 0 upon success or 1 if there is a problem in the configuration. restore Reads previously dumped pizauth state from stdin and updates those parts of the current state it determines to be less use- ful than the dumped state. This does not change the running instance's configuration: any changes in security relevant con- figuration between the dumping and restoring pizauth instances causes those parts of the dump to be silently ignored. See dump for information about the dump format, timestamp warnings, and encryption suggestions. revoke account Removes any token, and cancels any ongoing authentication, for account. Note that OAuth2 provides no standard way of remotely revoking a token: revoke thus only affects the local pizauth instance. Exits with 0 upon success. server [-c config-file] [-dv] Start the server. If not specified with -c, pizauth checks for the configuration file (in order) at: $XDG_CONFIG_HOME/pizauth.conf, $HOME/.config/pizauth.conf. The server will daemonise itself unless -d is specified. Exits with 0 if the server started successfully or 1 otherwise. -v enables more verbose logging. -v can be used up to 4 times, with each repetition increasing the quantity of logging. show [-u] account If there is an access token for account, print that access to- ken to stdout and exit with 0. If there is not currently a valid access token, prints an error to stderr and exits with 1. If refreshing might obtain a valid access token, refreshing is initiated in the background. Otherwise (unless -u is speci- fied), the error will include an authorization URL. Note that this command does not block: commands must expect that they might encounter an error when showing an access token. shutdown Shut the server down. Note that shutdown occurs asynchro- nously: the server may still be alive for a period of time af- ter this command returns. status Writes output about the current accounts and whether they have access tokens to stdout. The format is human-readable and in an unspecified format that may change freely between pizauth ver- sions. SEE ALSO pizauth.conf(5) https://tratt.net/laurie/src/pizauth/ AUTHORS pizauth was written by Laurence Tratt https://tratt.net/laurie/ FreeBSD Ports 14.quarterly September 13, 2022 PIZAUTH(1)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pizauth&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>