libnetconf's functions implementing NETCONF Call Home (both SSH and TLS) mechanism. More information can be found at Call Home page. More...

Functions
struct nc_session *	nc_callhome_accept (const char username, const struct nc_cpblts cpblts, int *timeout)
	Accept incoming Call Home connection and create NETCONF session on it. More...

int	nc_callhome_connect (struct nc_mngmt_server host_list, uint8_t reconnect_secs, uint8_t reconnect_count, const char server_path, char const argv[], int com_socket)
	Connect NETCONF server to a management center (NETCONF client) using Call Home mechanism. More...

int	nc_callhome_listen (unsigned int port)
	Start listening on client side for incoming Call Home connection. More...

int	nc_callhome_listen_stop (void)
	Stop listening on client side for incoming Call Home connection. More...

struct nc_mngmt_server *	nc_callhome_mngmt_server_add (struct nc_mngmt_server list, const char host, const char *port)
	Add a new management server specification to the end of a list. More...

int	nc_callhome_mngmt_server_free (struct nc_mngmt_server *list)
	Free a management server description structure(s). The function doesn't free only the item refered by given pointer, but the complete list of management servers is freed. More...

struct nc_mngmt_server *	nc_callhome_mngmt_server_getactive (struct nc_mngmt_server *list)
	Searches for the item from the list, which was marked and used by the last call to nc_callhome_connect() to a successfully establish Call Home connection. More...

int	nc_callhome_mngmt_server_rm (struct nc_mngmt_server list, struct nc_mngmt_server remove)
	Remove the specified management server description from the list. More...

Detailed Description

libnetconf's functions implementing NETCONF Call Home (both SSH and TLS) mechanism. More information can be found at Call Home page.

Function Documentation

struct nc_session* nc_callhome_accept	(	const char *	username,
		const struct nc_cpblts *	cpblts,
		int *	timeout
	)

Accept incoming Call Home connection and create NETCONF session on it.

This function uses transport protocol set by nc_session_transport(). If NC_TRANSPORT_SSH (default value) is set, configure's –disable-libssh option cannot be used. If NC_TRANSPORT_TLS is set, configure's –enable-tls must be used

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Parameters

[in]	username	Name of the user to login to the server. The user running the application (detected from the effective UID) is used if NULL is specified.
[in]	cpblts	NETCONF capabilities structure with capabilities supported by the client. Client can use nc_session_get_cpblts_default() to get the structure with the list of all the capabilities supported by libnetconf (this is used in case of a NULL parameter).
[in,out]	timeout	Timeout for waiting for incoming call home in milliseconds. Negative value means an infinite timeout, zero causes to return immediately. If a positive value is set and timeout is reached, NULL is returned and timeout is changed to 0.

Returns: Structure describing the NETCONF session or NULL in case of an error. NULL is also returned in case of timeout, but in that case also timeout value is changed to 0.

int nc_callhome_connect	(	struct nc_mngmt_server *	host_list,
		uint8_t	reconnect_secs,
		uint8_t	reconnect_count,
		const char *	server_path,
		char *const	argv[],
		int *	com_socket
	)

Connect NETCONF server to a management center (NETCONF client) using Call Home mechanism.

Use nc_session_transport() function to specify which transport protocol should be used.

Note that reconnect_secs and reconnect_count parameters are used only before a connection is established, then the function returns. It's up to the caller to reconnect if the session goes down. It can be detected using returned PID.

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Parameters

[in]	host_list	List of management servers descriptions where the function will try to connect to.
[in]	reconnect_secs	Time delay in seconds between connection attempts (even to the same server but it depends on reconnect_count). See /netconf/ssh/call-home/applications/application/reconnect-strategy/interval-secs value in ietf-netconf-server YANG data model.
[in]	reconnect_count	Number times the function tries to connect to a single server before moving on to the next server in the host_list. See /netconf/ssh/call-home/applications/application/reconnect-strategy/count-max value in ietf-netconf-server YANG data model.
[in]	server_path	Optional parameter to specify path to the transport server. If not specified, the function get transport protocol according to value set by nc_session_transport() (default value is SSH transport). For the NC_TRANSPORT_SSH the '/usr/sbin/sshd' path is used (OpenSSH server), in case of NC_TRANSPORT_TLS the '/usr/sbin/stunnel' path is used (OpenSSL server).
[in]	argv	List of arguments to be used by execv() when starting the server specified in server_path parameter. If server_path not specified (NULL), argv is ignored. Remember, that the server is supposed to read data from stdin and write data to stdout (inetd mode). So, for example sshd is running with -i option.
[out]	com_socket	If not NULL, function returns TCP socket used for Call Home connection. Caller is supposed to close returned socket when it is no more needed.

Returns: -1 on error. In case of success, function forks the current process running the transport protocol server and returns its PID.

int nc_callhome_listen ( unsigned int port )

Start listening on client side for incoming Call Home connection.

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Parameters

[in] port Port number where to listen.

Returns: EXIT_SUCCESS or EXIT_FAILURE on error.

int nc_callhome_listen_stop ( void )

Stop listening on client side for incoming Call Home connection.

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Returns: EXIT_SUCCESS or EXIT_FAILURE if libnetconf is not listening.

struct nc_mngmt_server* nc_callhome_mngmt_server_add	(	struct nc_mngmt_server *	list,
		const char *	host,
		const char *	port
	)

Add a new management server specification to the end of a list.

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Parameters

[in]	list	Current list where the server description will be added. If NULL, a new list is created and returned by the function.
[in]	host	Host name of the management server. It specifies either a numerical network address (for IPv4, numbers-and-dots notation as supported by inet_aton(3); for IPv6, hexadecimal string format as supported by inet_pton(3)), or a network host-name, whose network addresses are looked up and resolved.
[in]	port	Port of the management server. If this argument is a service name (see services(5)), it is translated to the corresponding port number.

Returns: NULL on error, created/modified management servers list.

int nc_callhome_mngmt_server_free ( struct nc_mngmt_server * list )

Free a management server description structure(s). The function doesn't free only the item refered by given pointer, but the complete list of management servers is freed.

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Parameters

[in] list List of management servers to be freed.

Returns: EXIT_SUCCESS or EXIT_FAILURE.

struct nc_mngmt_server* nc_callhome_mngmt_server_getactive ( struct nc_mngmt_server * list )

Searches for the item from the list, which was marked and used by the last call to nc_callhome_connect() to a successfully establish Call Home connection.

Parameters

[in] list List of management servers.

Returns: Pointer to the last connected management server.

int nc_callhome_mngmt_server_rm	(	struct nc_mngmt_server *	list,
		struct nc_mngmt_server *	remove
	)

Remove the specified management server description from the list.

To make this function available, you have to include libnetconf_ssh.h or libnetconf_tls.h.

Parameters

[in,out]	list	Management servers list to be modified.
[in,out]	remove	Management server to be removed from the given list. The structure itself is not freed, use nc_callhome_mngmt_server_free() to free it after calling nc_callhome_mngmt_server_rm().

Returns: EXIT_SUCCESS or EXIT_FAILURE.

Functions

Detailed Description

Function Documentation