oracular (3) upscli_init.3.gz

NAME

       upscli_init - Initialize upsclient module specifying security properties.

SYNOPSIS

       #include <upsclient.h>

       int upscli_init(int certverify, const char *certpath,
                              const char *certname, const char *certpasswd);

DESCRIPTION

       The upscli_init() function initialize upsclient module and set many TLS/SSL-related properties:
       certverify to 1 makes certificate verification required for all SSL connections and certpath is the
       location of certificate database.

       If compiled with OpenSSL, certpath refers to directory containing certificates where the certificates
       must be named according to their hash values ending in a ".0" extension. If two certificates result in
       the same hash value (thus file name), the ".0" can be incremented to ".1" and so on, as needed. The bash
       command for creating links in this manner would be:

           ln -s ca.pem ./$(openssl x509 -hash -noout -in ca.pem).0

       Alternatively, the c_rehash utility (provided by openssl-perl) can take a directory and iterate it to
       link all certificates found in that directory, in the manner described above.

       If compiled with NSS, certpath refers to a directory containing database files.

       If compiled with NSS and using SSL, you can specify certname the name of the certificate to send to upsd
       and certpasswd the password used to decrypt certificate private key.

       If compiled with NSS, it would normally log either the infamous message "Init SSL without certificate
       database" if no certpath was provided, or "Init SSL with certificate database located at %s" otherwise.
       Since some programmatic consumers become confused by such extra text on the stderr of tools they call
       (such as monitoring systems doing upsc queries), you can export an environment variable
       NUT_QUIET_INIT_SSL with string values "true", "TRUE" or "1", to avoid logging these messages and just
       emit them as debug stream (at verbosity 1 or higher).

       You can call upscli_add_host_cert(3) to register specific host security policy before initialize
       connections to them.

       You must call upscli_cleanup(3) when exiting application.

RETURN VALUE

       The upscli_init() function returns 1 on success, or -1 if an error occurs.

SEE ALSO

       upscli_add_host_cert(3), upscli_cleanup(3), upscli_disconnect(3), upscli_fd(3), upscli_splitaddr(3),
       upscli_splitname(3), upscli_ssl(3), upscli_strerror(3), upscli_upserror(3)