NSS config API draft

Duckwater: Configuration APIs for name service switch modules

Contents

• 1   Introduction
• 2   Interface Taxonomy
• 3   Configuration management functions
  • 3.1   Prototypes
  • 3.2   Initialization and de-initialization
  • 3.3   Accessing repository
  • 3.4   Cleaning up memory
  • 3.5   Administration
  • 3.6   Legacy configuration files support
  • 3.7   Verification and status
  • 3.8   Discover name service

1   Introduction

This is a description of new configuration management APIs in nss modules to enable us to deliver back-end agnostic nscfg(1m), nsadm(1m) etc. It will also allow 3rd parties to deliver configuration support for their nss modules (e.g. cluster) without the need to modify our tools (e.g. nscfg(1m)).

These functions will be accessed through Finder API introduced as part of project duckwater and extension to versioning API introduced by PSARC/2008/035.

2   Interface Taxonomy

Volatile because the new development is being pursued via OpenSolaris.

One of the goals of the sparks and duckwater efforts are to document all the name service switch interfaces and eventually expose the interfaces first as volatile, and eventually committed at some point in the future.

3   Configuration management functions

3.1   Prototypes

Init/fini:

nss_status_t _nss_<be>_config_init(void **priv);

nss_status_t _nss_<be>_config_fini(void **priv);

Accessing repository:

/*
 * Create in-memory structure with configuration data and
 * optionally load the data from repository.
 */
nss_status_t _nss_<be>_config_create(void **priv,
        nsconf_config_t **cfg,
        char *name,
        int load);

/* Store in-memory configuration structure to repository. */
nss_status_t _nss_<be>_config_save(void **priv,
        nsconf_config_t *cfg);

/* Remove configuration from repository. */
nss_status_t _nss_<be>_config_delete(void **priv,
        char *name);

/* Get list of available stored configurations. */
nss_status_t _nss_<be>_config_list(void **priv,
        char **cfg_names);

Accessing properties and property values:

/* Iterate through properties. */
nss_status_t _nss_<be>_config_next_prop(void **priv,
        nsconf_config_t *cfg,
        nsconf_property_t *ref_prop,
        nsconf_property_t **out_prop);

/* Iterate through property values. */
nss_status_t _nss_<be>_config_prop_next_val(void **priv,
        nsconf_property_t *prop
        nsconf_value_t *ref_val,
        nsconf_value_t **out_val);

/* Get specific property. */
nss_status_t _nss_<be>_config_get_prop(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        nsconf_property_t **prop);

/* Set single value. */
nss_status_t _nss_<be>_config_prop_set_val(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        const char *val);

/* Get single value. */
nss_status_t _nss_<be>_config_prop_get_val(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        const char **val);

/* Add value to property. No ordering guaranteed. */
nss_status_t _nss_<be>_config_prop_add_val(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        const char *value);

/* Unset (all) property's value(s). */
nss_status_t _nss_<be>_config_prop_unset_val(void **priv,
        nsconf_config_t *cfg,
        const char *name);

Cleanup:

/* Destroy in-memory configuration structure. */
nss_status_t _nss_<be>_config_destroy(void **priv,
        nsconf_config_t *cfg);

Administration:

/* Enable stored configuration. */
nss_status_t _nss_<be>_config_enable(void **priv,
        const char *config_name,
        int dryrun);

/* Disable any configuration. */
nss_status_t _nss_<be>_config_disable(void **priv,
        int dryrun);

Legacy configuration files support:

/* Generate legacy configuration file(s). */
nss_status_t _nss_<be>_config_export(void **priv,
        nsconf_config_t *cfg,
        char *alt_root,
        char *alt_full_path);

/* Import from legacy configuration file(s). */
nss_status_t _nss_<be>_config_import(void **priv,
        nsconf_config_t *cfg,
        char *alt_root,
        char *alt_full_path);

Verification and status:

/* Verify in-memory configuration structure. */
nss_status_t _nss_<be>_config_verify(void **priv,
        nsconf_config_t *cfg);

/* Get back-end status information. */
nss_status_t _nss_<be>_config_get_status(void **priv,
        nsconf_config_t *cfg,
        void *status);

Discovery:

/* Discover configuration. could be called repeatedly. */
nss_status_t _nss_<be>_config_discover(void **priv,
        nsconf_config_t **cfg);

3.2   Initialization and de-initialization

nss_status_t _nss_<be>_config_init(void **priv);

nss_status_t _nss_<be>_config_fini(void **priv);

Users are supposed to call config_init before calling any other of the APIs. after an user is done using the APIs, it is advisable, that config_fini is called.

3.3   Accessing repository

Creating in-memory structure and possibly loading it from the repository:

nss_status_t _nss_<be>_config_create(void **priv,
        nsconf_config_t **cfg,
        char *name,
        int load)

Creates configuration structure, add all appropriate back-end specific properties with preloaded defaults, property descriptions, possible values etc. If load is 1, _config_create tries to also load the configuration from repository.

nsconf_config_t and nsconf_property_t structures looks like this:

typedef struct nsconf_property {
        char            *name;
        char            *visible_name;
        uu_list_node_t  node;
        uu_list_t       *values;
        char            *default_value;
        char            *description;
        char            *help;
        char            **choices;
} nsconf_property_t;

typedef struct nsconf_config {
        nsconf_type_t   type;
        char            *name;
        uu_list_t       *props;
        uu_list_pool_t  *prop_pool;
        uu_list_pool_t  *val_pool;
} nsconf_config_t;

Saving in-memory structure to repository:

nss_status_t _nss_<be>_config_save(void **priv,
        nsconf_config_t *cfg)

Removing configuration from repository:

nss_status_t _nss_<be>_config_delete(void **priv,
        char *name);

Getting names of all available configurations in repository:

nss_status_t _nss_<be>_config_list(void **priv,
        char **cfg_names);

Iterating through all properties of given configuration:

nss_status_t _nss_<be>_config_next_prop(void **priv,
        nsconf_config_t *cfg,
        nsconf_property_t *ref_prop,
        nsconf_property_t **out_prop);

If ref_prop is NULL, first property is returned (through out_prop) otherwise property "next to" ref_prop is returned. Order is not guaranteed to be the same when the same configuration is retrieved from repository again.

Iterating through all values of given property:

nss_status_t _nss_<be>_config_prop_next_val(void **priv,
        nsconf_property_t *prop
        nsconf_value_t *ref_val,
        nsconf_value_t **out_val);

This function is similar to the one above iterating though properties and same limitation w.r.t. ordering apply here too.

Find particular named property in in-memory configuration structure:

nss_status_t _nss_<be>_config_get_prop(void **priv,
        nsconf_config_t *cfg,
        const char *name, nsconf_property_t **prop);

Set (or replace) single value of property:

nss_status_t _nss_<be>_config_prop_set_val(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        const char *val);

This is a simple function to support setting single value properties very easily. It also does ensure to replace any value(s) should they exist.

Get a single value from property:

nss_status_t _nss_<be>_config_prop_get_val(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        const char **val);

The purpose of this function is similar to config_prop_set_val - simple access to single value properties. Should this function fail if it detects more values in property?

Add another value to list of property values:

nss_status_t _nss_<be>_config_prop_add_val(void **priv,
        nsconf_config_t *cfg,
        const char *name,
        const char *value);

Again - no ordering of values is guaranteed after saving to and retrieving from the repository.

Unset (all) property's value(s):

nss_status_t _nss_<be>_config_prop_unset_val(void **priv,
        nsconf_config_t *cfg,
        const char *name);

3.4   Cleaning up memory

nss_status_t _nss_<be>_config_destroy(void **priv,
        nsconf_config_t *cfg)

Destroy the in-memory structure.

3.5   Administration

To enable given configuration:

nss_status_t _nss_<be>_config_enable(void **priv,
        const char *config_name,
        int dryrun);

Function to enable given configuration. Can be run in dry-run report what would happen next - i.e. back-end would be started or back-end would be just refreshed. In both real and dry modes, configuration is verified using config_verify() before any other action takes place to ensure, the configuration is valid.

To disable any configuration of a given back-end:

nss_status_t _nss_<be>_config_disable(void **priv,
        int dryrun);

Function to disable back-end's active configuration and possibly to clean up legacy configuration files. Should this function also notify nscd(1M) that certain back-end has been disabled?

Once we have Enhanced SMF Profiles, this will be pretty much handled by SMF itself.

3.6   Legacy configuration files support

Export configuration to legacy configuration file(s):

nss_status_t _nss_<be>_config_export(void **priv,
        nsconf_config_t *cfg,
        char *alt_root,
        char *alt_full_path)

Function to generate legacy configuration file(s). If alt_root and alt_full_path are both NULL, the legacy configuration file(s) is (are) generated to usual location and the filename(s) are as usual. E.g. calling (void) _nss_ldap_config_export(cfg, NULL, NULL); results in ldap_client_file and ldap_client_cred files being generated in /var/ldap directory.

If alt_full_path is not NULL then regardless of value in alt_root the name of the legacy configuration file generated matches exactly the value of alt_full_path.

In case of LDAP, where legacy configuration consists of two files, the rule is, that "main" configuration file name is <alt_full_path>_file and credential configuration file is <alt_full_path>_cred. E.g. calling (void) _nss_ldap_config_export(cfg, NULL, "/temp/my_test_ldap"); results in my_test_ldap_file and my_test_ldap_cred files being generated in /temp directory.

If alt_root is not NULL and alt_full_path is NULL, the legacy configuration file(s) is (are) generated in usual directories but under the alt_root directory. E.g. calling (void) _nss_ldap_config_export(cfg, "/temp", NULL); results in my_test_ldap_file and my_test_ldap_cred files being generated in /temp/var/ldap directory.

Import from legacy configuration file(s):

nss_status_t _nss_<be>_config_import(void **priv,
        nsconf_config_t *cfg,
        char *alt_root,
        char *alt_full_path)

This function imports configuration data from legacy configuration file and stores it in cfg structure.

Handling of alt_root and alt_full_path is analogous to export function.

3.7   Verification and status

Verify configuration:

nss_status_t _nss_<be>_config_verify(void **priv,
        nsconf_config_t *cfg)

Verifies configuration and in case of error, annotates cfg structure with messages. Every run replaces all messages (frees memory also). More details TBD as we prototype.

Get status of back-end:

nss_status_t _nss_<be>_config_status(void **priv,
        nsconf_config_t *cfg,
        void *status)

We still need to define what exactly this means for the main back-ends (LDAP, NIS, NIS+ etc.), but the main idea is to check, whether the back-end daemon (e.g. ldap_cachemgr(1M), ypbind(1M)) is alive, well, and able to communicate with the networked repository (e.g. directory server(s), NIS server(s) etc.)

3.8   Discover name service

nss_status_t _nss_<be>_config_discover(void **priv,
        nsconf_config_t **cfg)

Automatic discovery. TBD