NAME
upscli_read_authconf_file - Read the authentication configuration file
SYNOPSIS
#include <authconf.h>
int upscli_read_authconf_file(const char *filename, int fatal_errors,
int debug_level);DESCRIPTION
The upscli_read_authconf_file() function reads the specified filename (which is usually the path to nutauth.conf) and populates an internal list of authentication and SSL configurations.
If the filename is NOT NULL, for security reasons it must be either an
absolute path, or one resolved relatively to NUT configuration file location
(a built-in path defined by configure script, or NUT_CONFPATH environment
variable).
If filename is NULL, the function first tries to locate either a file
whose path and name is fully provided in ${NUT_AUTHCONF_FILE} environment
variable, or a ${NUT_AUTHCONF_PATH}/nutauth.conf, and would not try any
other locations IFF these environment variables are provided. Otherwise it
tries per-user ${HOME}/.config/nut/nutauth.conf or ${HOME}/.nutauth.conf,
or a site default ${NUT_CONFDIR}/nutauth.conf (whichever is found first).
Such a file may INCLUDE further configurations (e.g. hop from a per-user
file to load server-wide defaults), if desired.
If filename is NULL and the file is not found in a default location, the
method posts an upslogx(LOG_WARNING, ...) about this if debug_level < 0
or logs an upsdebugx(debug_level, ...) message (note that level zero usually
goes to stderr right away). This allows to reduce console noise during
"best-effort" attempts to use the file if present.
The file structure is similar to ups.conf, with global defaults and
per-server sections named like [@localhost:12345] for host defaults,
or [username@localhost:12345] for specific account overrides.
If fatal_errors is non-zero, the function may call abort the program on critical failures (like memory allocation errors or if the file cannot be opened).
See the nutauth.conf(5) manual page for supported configuration keywords.
NESTING (INCLUDE FILES)
Included files are supported via the INCLUDE directive for optionally
present files, and INCLUDE_REQUIRED for files which must be there
(otherwise the program exits with a fatal error).
Non-absolute paths would be resolved relatively to NUT configuration file location.
Global-scope includes may modify global default items and define new sections.
Section-scope includes (nested within a section) can only modify data within that section.
RETURN VALUE
The upscli_read_authconf_file() function returns 1 on success, or -1 if an error occurs (and fatal_errors was zero).