libnsconf - Name services configuration library

libnsconf - Name services configuration library

Contents

• 1   Introduction
• 2   Why is libnsconf needed?
• 3   Interfaces provided by libnsconf
  • 3.1   Library initialization and de-initialization
  • 3.2   Configuration access
    • 3.2.1   Configuration Iterators
  • 3.3   Property access
    • 3.3.1   Property and value iterators
  • 3.4   Administration
  • 3.5   Backend configuration discovery
  • 3.6   Error reporting
    • 3.6.1   Return values and error reporting
• 4   Notes
  • 4.1   Components we see using libnsconf
• 5   Glossary

1   Introduction

We propose to implement a library to handle configuration repository access for all client-side name service components. We call this library libnsconf. The interface of this library is Consolidation Private.

libnsconf abstracts the configuration repository and provides interfaces to work with Name Service Switch Profiles (NSSP) and Name Service Back-End Configurations (BEC). For description of NSSP and NSBEC, please see "Duckwater: Simplified Name Services Management - Profiles" [profiles].

2   Why is libnsconf needed?

The idea is that we will have a simple (repository independent) interface to access local configuration data that all name service components can use.

Our goal is to use the SMF repository to store our configuration data, but we expect that accessing the SMF configuration repository through libscf(3LIB) will require a lot of duplicated programming. We want to have this code only in one place (libnsconf) and not duplicate it in other name service components.

3   Interfaces provided by libnsconf

Please note, that this interface is supposed to be the lower-level part of name service configuration API. The upper-level, which will be used directly by applications like nscfg(1M), nsadm(1M) etc. will reside in back-end specific name service switch modules - i.e. /usr/lib/nss_*.so. For more information, please refer to "Duckwater: Configuration APIs for Name Service Switch Modules" design document [nssconfig].

3.1   Library initialization and de-initialization

Users of libnsconf have to call nsconf_init before using any of the APIs. To ensure, that the connection to the svc.configd is properly closed, that users have to call nsconf_fini.

int nsconf_init();

void nsconf_fini();

int nsconf_is_initialized();

3.2   Configuration access

Group of functions to create/modify/delete/find and iterate through configurations (NSSPs and NSBECs) stored in repository.

nsconf_config_t *nsconf_config_create(nsconf_type_t type,
        const char *name);

void nsconf_config_destroy(nsconf_config_t *config);

int nsconf_config_clone(nsconf_config_t **to,
        nsconf_config_t *from, const char *new_name);

int nsconf_config_get(nsconf_type_t type,
        const char *name, nsconf_config_t **config);

int nsconf_config_put(const nsconf_config_t *config);

int nsconf_config_remove(nsconf_type_t type, const char *name);

3.2.1   Configuration Iterators

nsconf_iter_t *nsconf_iter_create(nsconf_type_t type);

int nsconf_iter_next_config(nsconf_iter_t *iter,
    nsconf_config_t **config);

void nsconf_iter_destroy(nsconf_iter_t *iter);

3.3   Property access

int nsconf_config_get_prop(nsconf_config_t *config,
    const char *name, nsconf_property_t **prop);

int nsconf_prop_set_val(nsconf_config_t *config,
    const char *name, const char *value);

int nsconf_prop_get_val(nsconf_config_t *config,
    const char *name, const char **value);

int nsconf_prop_unset_val(nsconf_config_t *config,
    const char *name);

int nsconf_prop_add_val(nsconf_config_t *config,
    const char *name,
    const char *value);

3.3.1   Property and value iterators

nsconf_property_t * nsconf_config_next_prop(
    nsconf_config_t *config,
    nsconf_property_t *ref_prop);

nsconf_value_t * nsconf_prop_next_val(
    nsconf_property_t *prop,
    nsconf_value_t *ref_val);

3.4   Administration

Marking configurations is enabled or disabled. The actual work needed to activate a configuration will be done partially in nsadm(1M) and partially in particular NSS modules.

int nsconf_config_activate(
    nsconf_type_t type,
    const char *name);

int nsconf_config_deactivate(
    nsconf_type_t type);

3.5   Backend configuration discovery

int nscfg_discover_backends(
    int *n_becs,
    nsconf_config_t ***becs,
    int timeout_sec);

Will be redesigned.

3.6   Error reporting

These functions give access to libnsconf error codes and their string representations:

int nsconf_error(void);
const char *nsconf_strerror(int err);

This functions give access to error codes and their string representations of lower-level repository access library - i.e. libscf(3C):

int nsconf_repo_error(void);
const char *nsconf_repo_strerror(int err);

3.6.1   Return values and error reporting

Most of the functions in libnsconf library return 0 on success and -1 on error. Exceptions to this rule are these functions:

* nsconf_config_create returns pointer to newly created nsconf_config_t structure (or NULL on error).

• nsconf_iter_create returns pointer to newly created nsconf_iter_t structure (or NULL on error).
• nsconf_iter_next_config returns 1 when next configuration was successfully handed to caller, 0 when no more configurations were available and -1 on error.

To get error code after last nsconf_* function invocation, use nsconf_error() function. To get string representation of the error, use nsconf_strerror(int). nsconf_erorr() return value is valid only immediately after the previous call to a libnsconf function failed.

4   Notes

4.1   Components we see using libnsconf

1. libsldap.so.1

1. nscd(1M)
2. nsadm(1M)
3. nscfg(1M)
4. nss_*.so.1

5   Glossary

 |=NSSP:|Name Service Switch Profile - high level configuration entity, describing the whole set of name service configurations.