Server

NETCONF server functionality. More...

Collaboration diagram for Server:

## Modules

| Server Messages
| Functions to create NETCONF Event notifications and replies to the NETCONF RPCs (or actions).
| Server SSH
| Server-side settings for SSH connections.
| Server Session
| Server-side NETCONF session manipulation.
| Server TLS
| Server-side settings for TLS connections.
| Server-side Call Home
| Call Home functionality for server-side applications.

## Functions

int | nc_server_add_endpt (const char *name, NC_TRANSPORT_IMPL ti)
| Add a new endpoint. More...
int | nc_server_del_endpt (const char *name, NC_TRANSPORT_IMPL ti)
| Stop listening on and remove an endpoint. More...
void | nc_server_destroy (void)
| Destroy any dynamically allocated libssh and/or libssl/libcrypto and server resources. More...
int | nc_server_endpt_count (void)
| Get the number of currently configured listening endpoints. Note that an ednpoint without address and/or port will be included even though it is not, in fact, listening. More...
int | nc_server_endpt_enable_keepalives (const char *endpt_name, int enable)
| Change endpoint keepalives state. Affects only new connections. More...
int | nc_server_endpt_set_address (const char *endpt_name, const char *address)
| Change endpoint listening address. More...
int | nc_server_endpt_set_keepalives (const char *endpt_name, int idle_time, int max_probes, int probe_interval)
| Change endpoint keepalives parameters. Affects only new connections. More...
int | nc_server_endpt_set_perms (const char *endpt_name, mode_t mode, uid_t uid, gid_t gid)
| Change endpoint permissions. More...
int | nc_server_endpt_set_port (const char *endpt_name, uint16_t port)
| Change endpoint listening port. More...
void | nc_server_get_capab_withdefaults (NC_WD_MODE *basic_mode, int *also_supported)
| Get with-defaults capability extra parameters. More...
const char ** | nc_server_get_cpblts (struct ly_ctx *ctx)
| Get all the server capabilities including all the schemas. More...
const char ** | nc_server_get_cpblts_version (struct ly_ctx *ctx, LYS_VERSION version)
| Get the server capabilities including the schemas with the specified YANG version. More...
uint16_t | nc_server_get_hello_timeout (void)
| get server timeout for receiving a hello message. More...
uint16_t | nc_server_get_idle_timeout (void)
| Get server timeout for dropping an idle session. More...
int | nc_server_init (struct ly_ctx *ctx)
| Initialize libssh and/or libssl/libcrypto and the server using a libyang context. More...
int | nc_server_is_endpt (const char *name)
| Check if an endpoint exists. More...
int | nc_server_set_capab_withdefaults (NC_WD_MODE basic_mode, int also_supported)
| Set the with-defaults capability extra parameters. More...
int | nc_server_set_capability (const char *value)
| Set capability of the server. More...
void | nc_server_set_content_id_clb (char *(*content_id_clb)(void *user_data), void *user_data, void(*free_user_data)(void *user_data))
| Set the callback for getting yang-library capability identifier. If none is set, libyang context change count is used. More...
void | nc_server_set_hello_timeout (uint16_t hello_timeout)
| Set server timeout for receiving a hello message. More...
void | nc_server_set_idle_timeout (uint16_t idle_timeout)
| Set server timeout for dropping an idle session. More...

## Detailed Description

NETCONF server functionality.

## Function Documentation

## nc_server_add_endpt()

int nc_server_add_endpt | ( | const char * | name,
|  | NC_TRANSPORT_IMPL | ti
| ) |  |

Add a new endpoint.

Before the endpoint can accept any connections, its address and port must be set via nc_server_endpt_set_address() and nc_server_endpt_set_port().

Parameters

  [in] | name | Arbitrary unique endpoint name.
  [in] | ti | Transport protocol to use.

Returns
  0 on success, -1 on error.

## nc_server_del_endpt()

int nc_server_del_endpt | ( | const char * | name,
|  | NC_TRANSPORT_IMPL | ti
| ) |  |

Stop listening on and remove an endpoint.

Parameters

  [in] | name | Endpoint name. NULL matches all endpoints.
  [in] | ti | Endpoint transport protocol. NULL matches any protocol. Redundant to set if `name` is set, endpoint names are unique disregarding their protocol.

Returns
  0 on success, -1 on not finding any match.

## nc_server_destroy()

void nc_server_destroy | ( | void |  | ) |

Destroy any dynamically allocated libssh and/or libssl/libcrypto and server resources.

## nc_server_endpt_count()

int nc_server_endpt_count | ( | void |  | ) |

Get the number of currently configured listening endpoints. Note that an ednpoint without address and/or port will be included even though it is not, in fact, listening.

Returns
  Number of added listening endpoints.

## nc_server_endpt_enable_keepalives()

int nc_server_endpt_enable_keepalives | ( | const char * | endpt_name,
|  | int | enable
| ) |  |

Change endpoint keepalives state. Affects only new connections.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | enable | Whether to enable or disable keepalives.

Returns
  0 on success, -1 on error.

## nc_server_endpt_set_address()

int nc_server_endpt_set_address | ( | const char * | endpt_name,
|  | const char * | address
| ) |  |

Change endpoint listening address.

On error the previous listening socket (if any) is left untouched.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | address | New listening address.

Returns
  0 on success, -1 on error.

## nc_server_endpt_set_keepalives()

int nc_server_endpt_set_keepalives | ( | const char * | endpt_name,
|  | int | idle_time,
|  | int | max_probes,
|  | int | probe_interval
| ) |  |

Change endpoint keepalives parameters. Affects only new connections.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | idle_time | Keepalive idle time in seconds, 1 by default, -1 to keep previous value.
  [in] | max_probes | Keepalive max probes sent, 10 by default, -1 to keep previous value.
  [in] | probe_interval | Keepalive probe interval in seconds, 5 by default, -1 to keep previous value.

Returns
  0 on success, -1 on error.

## nc_server_endpt_set_perms()

int nc_server_endpt_set_perms | ( | const char * | endpt_name,
|  | mode_t | mode,
|  | uid_t | uid,
|  | gid_t | gid
| ) |  |

Change endpoint permissions.

This is only valid on UNIX transport endpoint. On error the previous listening socket (if any) is left untouched.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | mode | New mode, -1 to use default.
  [in] | uid | New uid, -1 to use default.
  [in] | gid | New gid, -1 to use default.

Returns
  0 on success, -1 on error.

## nc_server_endpt_set_port()

int nc_server_endpt_set_port | ( | const char * | endpt_name,
|  | uint16_t | port
| ) |  |

Change endpoint listening port.

This is only valid on SSH/TLS transport endpoint. On error the previous listening socket (if any) is left untouched.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | port | New listening port.

Returns
  0 on success, -1 on error.

## nc_server_get_capab_withdefaults()

void nc_server_get_capab_withdefaults | ( | NC_WD_MODE * | basic_mode,
|  | int * | also_supported
| ) |  |

Get with-defaults capability extra parameters.

At least one argument must be non-NULL.

Parameters

  [in,out] | basic_mode | basic-mode parameter.
  [in,out] | also_supported | also-supported parameter.

## nc_server_get_cpblts()

const char** nc_server_get_cpblts | ( | struct ly_ctx * | ctx | ) |

Get all the server capabilities including all the schemas.

A few capabilities (with-defaults, interleave) depend on the current server options.

Parameters

  [in] | ctx | Context to read most capabilities from.

Returns
  Array of capabilities stored in the `ctx` dictionary, NULL on error.

## nc_server_get_cpblts_version()

const char** nc_server_get_cpblts_version | ( | struct ly_ctx * | ctx,
|  | LYS_VERSION | version
| ) |  |

Get the server capabilities including the schemas with the specified YANG version.

A few capabilities (with-defaults, interleave) depend on the current server options.

Parameters

  [in] | ctx | Context to read most capabilities from.
  [in] | version | YANG version of the schemas to be included in result, with LYS_VERSION_UNDEF the result is the same as from nc_server_get_cpblts().

Returns
  Array of capabilities stored in the `ctx` dictionary, NULL on error.

## nc_server_get_hello_timeout()

uint16_t nc_server_get_hello_timeout | ( | void |  | ) |

get server timeout for receiving a hello message.

Returns
  Hello message timeout, 0 is infinite.

## nc_server_get_idle_timeout()

uint16_t nc_server_get_idle_timeout | ( | void |  | ) |

Get server timeout for dropping an idle session.

Returns
  Idle session timeout, 0 for for never dropping a session because of inactivity.

## nc_server_init()

int nc_server_init | ( | struct ly_ctx * | ctx | ) |

Initialize libssh and/or libssl/libcrypto and the server using a libyang context.

The context is not modified internally, only its dictionary is used for holding all the strings, which is thread-safe. Reading models is considered thread-safe as models cannot be removed and are rarely modified (augments or deviations).

If the RPC callbacks on schema nodes (mentioned in Server sessions) are modified after server initialization with that particular context, they will be called (changes will take effect). However, there could be race conditions as the access to these callbacks is not thread-safe.

Server capabilities are generated based on its content. Changing the context in ways that result in changed capabilities (adding models, changing features) is discouraged after sessions are established as it is not possible to change capabilities of a session.

This context can safely be destroyed only after calling the last libnetconf2 function in an application.

Supported RPCs of models in the context are expected to have their callback in the corresponding RPC schema node set to a nc_rpc_clb function callback using nc_set_rpc_callback(). This callback is called by nc_ps_poll() if the particular RPC request is received. Callbacks for ietf-netconf:get-schema (supporting YANG and YIN format only) and ietf-netconf:close-session are set internally if left unset.

Parameters

  [in] | ctx | Core NETCONF server context.

Returns
  0 on success, -1 on error.

## nc_server_is_endpt()

int nc_server_is_endpt | ( | const char * | name | ) |

Check if an endpoint exists.

Parameters

  [in] | name | Endpoint name.

Returns
  0 if does not exists, non-zero otherwise.

## nc_server_set_capab_withdefaults()

int nc_server_set_capab_withdefaults | ( | NC_WD_MODE | basic_mode,
|  | int | also_supported
| ) |  |

Set the with-defaults capability extra parameters.

For the capability to be actually advertised, the server context must also include the ietf-netconf-with-defaults model.

Changing this option has the same ill effects as changing capabilities while sessions are already established.

Parameters

  [in] | basic_mode | basic-mode with-defaults parameter.
  [in] | also_supported | NC_WD_MODE bit array, also-supported with-defaults parameter.

Returns
  0 on success, -1 on error.

## nc_server_set_capability()

int nc_server_set_capability | ( | const char * | value | ) |

Set capability of the server.

Capability can be used when some behavior or extension of the server is not defined as a YANG module. The provided value will be advertised in the server's <hello> messages. Note, that libnetconf only checks that the provided value is non-empty string.

Parameters

  [in] | value | Capability string to be advertised in server's <hello> messages.

## nc_server_set_content_id_clb()

void nc_server_set_content_id_clb | ( | char *(*)(void *user_data) | content_id_clb,
|  | void * | user_data,
|  | void(*)(void *user_data) | free_user_data
| ) |  |

Set the callback for getting yang-library capability identifier. If none is set, libyang context change count is used.

Parameters

  [in] | content_id_clb | Callback that should return the yang-library content identifier.
  [in] | user_data | Optional arbitrary user data that will be passed to `content_id_clb`.
  [in] | free_user_data | Optional callback that will be called during cleanup to free any `user_data`.

## nc_server_set_hello_timeout()

void nc_server_set_hello_timeout | ( | uint16_t | hello_timeout | ) |

Set server timeout for receiving a hello message.

Parameters

  [in] | hello_timeout | Hello message timeout. 0 for infinite waiting.

## nc_server_set_idle_timeout()

void nc_server_set_idle_timeout | ( | uint16_t | idle_timeout | ) |

Set server timeout for dropping an idle session.

Parameters

  [in] | idle_timeout | Idle session timeout. 0 to never drop a session because of inactivity.