swad provides a http service for cookie authentication with a HTML login form. The intended usage is to put it behind a reverse proxy that can do sub-requests for authentication, like nginx' auth_request module.
It supports authentication methods using a username and a password as credentials. For these, different credential checkers can be configured.
Login is offered for configurable realms, which have a name and a stack of credential checkers. These checkers are tried in the order they are configured for the realm.
The options are as follows:
Path to the configuration file.
Don't detach from the controlling terminal, instead run in foreground. In this mode, log output goes directly to the terminal.
Run as the given group name or gid. Only works when swad is started as root.
Print a help text and exit.
Attempt to resolve remote hostnames.
Run as the given user name or uid. Only works when swad is started as root.
Set the log level to debug to enable verbose output.
Don't attempt to resolve remote hostnames. This is the default unless the configuration file enables resolving.
Print version information and exit.
Reload configuration, which includes the configuration file, TLS certificate and key files, and files read from the resource directory (custom templates and custom style.css).
Changes to the user/group to run as, the pidfile location and all thread-pool configurations are ignored because they cannot be applied while running.
For configured servers, the listening sockets are left untouched as long as neither port, listen nor proto are changed. Otherwise, the old server will stop listening, but wait for all active connections to end, and a new server will replace it immediately.
Credential checkers are simply re-created without any further action, so if you change settings for one without changing its name, a login that used it will still be considered valid after configuration reload.
For realms, changes are detected and any login for a realm is considered invalid after the realm's configuration changed, so users are forced to login again.
WARNING: When you launch swad as root, but configure it to drop privileges, some actions might fail on configuration reload. Be careful when modifying server configurations that use a privileged port number (below 1024), they can't be used any more once privileges are dropped, so don't touch port, listen and proto for such servers. Also for the PAM credentials checker, the little helper process must run as root for some PAM modules (notably pam_unix(8)), but launching it as root is no longer possible after dropping privileges, so if you need PAM, make sure your configuration already includes it when first starting swad. In general, pay attention to the permissions of required files (like TLS certificates), so the unprivileged user swad is running as is allowed to read them.
Same as SIGTERM.
Shut down swad. Cleanup is performed, but all currently active connections will be closed.
The configuration file. An example is installed with a .sample suffix, all the settings are documented in there. For settings that also have a commandline flag, the commandline overrides the configuration file.