Server-side NETCONF session manipulation. More...

Collaboration diagram for Server Session:

Macros
#define	NC_PSPOLL_BAD_RPC 0x0008

#define	NC_PSPOLL_ERROR 0x0080

#define	NC_PSPOLL_NOSESSIONS 0x0001

#define	NC_PSPOLL_REPLY_ERROR 0x0010

#define	NC_PSPOLL_RPC 0x0004

#define	NC_PSPOLL_SESSION_ERROR 0x0040

#define	NC_PSPOLL_SESSION_TERM 0x0020

#define	NC_PSPOLL_SSH_CHANNEL 0x0200

#define	NC_PSPOLL_SSH_MSG 0x00100

#define	NC_PSPOLL_TIMEOUT 0x0002

Typedefs
typedef void(*	nc_cert_exp_notif_clb )(const char expiration_time, const char xpath, void *user_data)
	Callback for certificate expiration notification. More...

typedef int(*	nc_ps_session_match_cb )(struct nc_session session, void cb_data)
	Callback for finding a session in a pollsession structure. More...

typedef struct nc_server_reply (	nc_rpc_clb )(struct lyd_node rpc, struct nc_session session)
	Prototype of callbacks that are called if some RPCs are received. More...

Functions
NC_MSG_TYPE	nc_accept (int timeout, const struct ly_ctx ctx, struct nc_session *session)
	Accept new sessions on all the listening endpoints. More...

NC_MSG_TYPE	nc_accept_inout (int fdin, int fdout, const char username, const struct ly_ctx ctx, struct nc_session **session)
	Accept a new session on a pre-established transport session. More...

struct nc_server_reply *	nc_clb_default_close_session (struct lyd_node rpc, struct nc_session session)
	Default RPC callback used for "ietf-netconf:close-session" RPC if no other specific or global callback is set. More...

struct nc_server_reply *	nc_clb_default_get_schema (struct lyd_node rpc, struct nc_session session)
	Default RPC callback used for "ietf-netconf-monitoring:get-schema" RPC if no other specific or global callback is set. More...

NC_MSG_TYPE	nc_ps_accept_ssh_channel (struct nc_pollsession ps, struct nc_session *session)
	Accept a new NETCONF session on an SSH session of a running NETCONF session that was polled in `ps`. Call this function only when nc_ps_poll() on `ps` returns NC_PSPOLL_SSH_CHANNEL. The new session is only returned in `session`, it is not added to `ps`. More...

int	nc_ps_add_session (struct nc_pollsession ps, struct nc_session session)
	Add a session to a pollsession structure. More...

void	nc_ps_clear (struct nc_pollsession ps, int all, void(data_free)(void *))
	Remove sessions from a pollsession structure and call nc_session_free() on them. More...

int	nc_ps_del_session (struct nc_pollsession ps, struct nc_session session)
	Remove a session from a pollsession structure. More...

struct nc_session *	nc_ps_find_session (const struct nc_pollsession ps, nc_ps_session_match_cb match_cb, void cb_data)
	Find a session in a pollsession structure using a matching callback. More...

void	nc_ps_free (struct nc_pollsession *ps)
	Free a pollsession structure. More...

struct nc_session *	nc_ps_get_session (const struct nc_pollsession *ps, uint16_t idx)
	Get a session from a pollsession structure matching the session ID. More...

struct nc_pollsession *	nc_ps_new (void)
	Create an empty structure for polling sessions. More...

int	nc_ps_poll (struct nc_pollsession ps, int timeout, struct nc_session *session)
	Poll sessions and process any received RPCs. More...

uint16_t	nc_ps_session_count (struct nc_pollsession *ps)
	Learn the number of sessions in a pollsession structure. More...

int	nc_server_notif_cert_expiration_thread_start (nc_cert_exp_notif_clb cert_exp_notif_clb, void user_data, void(free_data)(void *))
	Start the certificate expiration notification thread. More...

void	nc_server_notif_cert_expiration_thread_stop (int wait)
	Stop the certificate expiration notification thread. More...

NC_MSG_TYPE	nc_session_accept_ssh_channel (struct nc_session orig_session, struct nc_session *session)
	Accept a new NETCONF session on an SSH session of a running NETCONF `orig_session`. Call this function only when nc_ps_poll() returns NC_PSPOLL_SSH_CHANNEL on `orig_session`. More...

void	nc_session_dec_notif_status (struct nc_session *session)
	Decrease session notification subscription flag count. Supports multiple subscriptions on one session. More...

int	nc_session_get_notif_status (const struct nc_session *session)
	Get session notification subscription flag. More...

struct timespec	nc_session_get_start_time (const struct nc_session *session)
	Get session start time. More...

void	nc_session_inc_notif_status (struct nc_session *session)
	Increase session notification subscription flag count. Supports multiple subscriptions on one session. More...

void	nc_session_set_killed_by (struct nc_session *session, uint32_t sid)
	Set the session-id of the session responsible for this session's termination. More...

void	nc_session_set_status (struct nc_session *session, NC_STATUS status)
	Set the status of a session. More...

void	nc_session_set_term_reason (struct nc_session *session, NC_SESSION_TERM_REASON reason)
	Set the termination reason for a session. Use only in nc_rpc_clb callbacks. More...

void	nc_set_global_rpc_clb (nc_rpc_clb clb)
	Set a global nc_rpc_clb that is called if the particular RPC request is received and the private field in the corresponding RPC schema node is NULL. More...

Detailed Description

Server-side NETCONF session manipulation.

Macro Definition Documentation

#define NC_PSPOLL_NOSESSIONS 0x0001

No sessions to poll.

Definition at line 336 of file session_server.h.

#define NC_PSPOLL_TIMEOUT 0x0002

Timeout elapsed.

Definition at line 337 of file session_server.h.

#define NC_PSPOLL_RPC 0x0004

RPC was correctly parsed and processed.

Definition at line 338 of file session_server.h.

#define NC_PSPOLL_BAD_RPC 0x0008

RPC was received, but failed to be parsed.

Definition at line 339 of file session_server.h.

#define NC_PSPOLL_REPLY_ERROR 0x0010

Response to the RPC was a <rpc-reply> of type error.

Definition at line 340 of file session_server.h.

#define NC_PSPOLL_SESSION_TERM 0x0020

Some session was terminated.

Definition at line 341 of file session_server.h.

#define NC_PSPOLL_SESSION_ERROR 0x0040

Some session was terminated incorrectly (not by a <close-session> or <kill-session> RPC).

Definition at line 342 of file session_server.h.

#define NC_PSPOLL_ERROR 0x0080

Other fatal errors (they are printed).

Definition at line 343 of file session_server.h.

#define NC_PSPOLL_SSH_MSG 0x00100

SSH message received (and processed, if relevant, only with SSH support).

Definition at line 346 of file session_server.h.

#define NC_PSPOLL_SSH_CHANNEL 0x0200

New SSH channel opened on an existing session (only with SSH support).

Definition at line 347 of file session_server.h.

Typedef Documentation

typedef struct nc_server_reply*(* nc_rpc_clb)(struct lyd_node *rpc, struct nc_session *session)

Prototype of callbacks that are called if some RPCs are received.

If session termination reason is changed in the callback, one last reply is sent and then the session is considered invalid.

The callback is set via nc_set_global_rpc_clb().

Parameters

[in]	rpc	Parsed client RPC request.
[in]	session	Session the RPC arrived on.

Returns: Server reply. If NULL, an operation-failed error will be sent to the client.

Definition at line 56 of file session_server.h.

typedef void(* nc_cert_exp_notif_clb)(const char *expiration_time, const char *xpath, void *user_data)

Callback for certificate expiration notification.

This callback is called when a certificate expiration notification is generated. It is up to the user to decide what to do with the notification.

In case an error occurs and you wish to terminate the notification thread, call nc_server_notif_cert_expiration_thread_stop().

Parameters

[in]	expiration_time	Expiration time of the certificate obtained via ly_time_time2str().
[in]	xpath	Xpath of the certificate. Can be used to create the notification data.
[in]	user_data	Arbitrary user data.

Definition at line 71 of file session_server.h.

typedef int(* nc_ps_session_match_cb)(struct nc_session *session, void *cb_data)

Callback for finding a session in a pollsession structure.

Parameters

[in]	session	Considered NETCONF session.
[in]	cb_data	User data.

Returns: 0 if the session does not match.; non-zero if the session matches and should be returned.

Definition at line 314 of file session_server.h.

Function Documentation

void nc_session_set_term_reason	(	struct nc_session *	session,
		NC_SESSION_TERM_REASON	reason
	)

Set the termination reason for a session. Use only in nc_rpc_clb callbacks.

Parameters

[in]	session	Session to modify.
[in]	reason	Reason of termination.

void nc_session_set_killed_by	(	struct nc_session *	session,
		uint32_t	sid
	)

Set the session-id of the session responsible for this session's termination.

Parameters

[in]	session	Session to modify. Must have term_reason set to NC_SESSION_TERM_KILLED.
[in]	sid	SID of the killing session.

void nc_session_set_status	(	struct nc_session *	session,
		NC_STATUS	status
	)

Set the status of a session.

Parameters

[in]	session	Session to modify.
[in]	status	Status of the session.

void nc_set_global_rpc_clb ( nc_rpc_clb clb )

Set a global nc_rpc_clb that is called if the particular RPC request is received and the private field in the corresponding RPC schema node is NULL.

If this callback is set, the default callbacks for "get-schema" and "close-session" are not used.

Parameters

[in] clb An user-defined nc_rpc_clb function callback, NULL to default.

struct nc_server_reply* nc_clb_default_get_schema	(	struct lyd_node *	rpc,
		struct nc_session *	session
	)

Default RPC callback used for "ietf-netconf-monitoring:get-schema" RPC if no other specific or global callback is set.

Parameters

[in]	rpc	Received RPC.
[in]	session	NC session `rpc` was received on.

Returns: Server reply.

struct nc_server_reply* nc_clb_default_close_session	(	struct lyd_node *	rpc,
		struct nc_session *	session
	)

Default RPC callback used for "ietf-netconf:close-session" RPC if no other specific or global callback is set.

Parameters

[in]	rpc	Received RPC.
[in]	session	NC session `rpc` was received on.

Returns: Server reply.

NC_MSG_TYPE nc_accept_inout	(	int	fdin,
		int	fdout,
		const char *	username,
		const struct ly_ctx *	ctx,
		struct nc_session **	session
	)

Accept a new session on a pre-established transport session.

For detailed description, look at nc_accept().

Parameters

[in]	fdin	File descriptor to read (unencrypted) XML data from.
[in]	fdout	File descriptor to write (unencrypted) XML data to.
[in]	username	NETCONF username as provided by the transport protocol.
[in]	ctx	Context for the session to use.
[out]	session	New session on success.

Returns: NC_MSG_HELLO on success, NC_MSG_BAD_HELLO on client <hello> message parsing fail, NC_MSG_WOULDBLOCK on timeout, NC_MSG_ERROR on other errors.

struct nc_pollsession* nc_ps_new ( void )

Create an empty structure for polling sessions.

Returns: Empty pollsession structure, NULL on error.

void nc_ps_free ( struct nc_pollsession * ps )

Free a pollsession structure.

!IMPORTANT! Make sure that ps is not accessible (is not used) by any thread before and after this call!

Parameters

[in] ps Pollsession structure to free.

int nc_ps_add_session	(	struct nc_pollsession *	ps,
		struct nc_session *	session
	)

Add a session to a pollsession structure.

Parameters

[in]	ps	Pollsession structure to modify.
[in]	session	Session to add to `ps`.

Returns: 0 on success, -1 on error.

int nc_ps_del_session	(	struct nc_pollsession *	ps,
		struct nc_session *	session
	)

Remove a session from a pollsession structure.

Parameters

[in]	ps	Pollsession structure to modify.
[in]	session	Session to remove from `ps`.

Returns: 0 on success, -1 on not found.

struct nc_session* nc_ps_get_session	(	const struct nc_pollsession *	ps,
		uint16_t	idx
	)

Get a session from a pollsession structure matching the session ID.

Parameters

[in]	ps	Pollsession structure to read from.
[in]	idx	Index of the session.

Returns: Session on index, NULL if out-of-bounds.

struct nc_session* nc_ps_find_session	(	const struct nc_pollsession *	ps,
		nc_ps_session_match_cb	match_cb,
		void *	cb_data
	)

Find a session in a pollsession structure using a matching callback.

Parameters

[in]	ps	Pollsession structure to read from.
[in]	match_cb	Matching callback to use.
[in]	cb_data	User data passed to `cb`.

Returns: Found session, NULL if none matched.

uint16_t nc_ps_session_count ( struct nc_pollsession * ps )

Learn the number of sessions in a pollsession structure.

Does not lock ps structure for efficiency.

Parameters

[in] ps Pollsession structure to check.

Returns: Number of sessions (even invalid ones) in ps, -1 on error.

int nc_ps_poll	(	struct nc_pollsession *	ps,
		int	timeout,
		struct nc_session **	session
	)

Poll sessions and process any received RPCs.

Only one event on one session is handled in one function call. If this event is a session termination (NC_PSPOLL_SESSION_TERM returned), the session should be removed from ps.

Parameters

[in]	ps	Pollsession structure to use.
[in]	timeout	Poll timeout in milliseconds. 0 for non-blocking call, -1 for infinite waiting.
[in]	session	Session that was processed and that specific return bits concern. Can be NULL.

Returns: Bitfield of NC_PSPOLL_* macros.

void nc_ps_clear	(	struct nc_pollsession *	ps,
		int	all,
		void()(void )	data_free
	)

Remove sessions from a pollsession structure and call nc_session_free() on them.

Calling this function with all false makes sense if nc_ps_poll() returned NC_PSPOLL_SESSION_TERM.

Parameters

[in]	ps	Pollsession structure to clear.
[in]	all	Whether to free all sessions, or only the invalid ones.
[in]	data_free	Session user data destructor.

NC_MSG_TYPE nc_accept	(	int	timeout,
		const struct ly_ctx *	ctx,
		struct nc_session **	session
	)

Accept new sessions on all the listening endpoints.

Once a new (TCP/IP) conection is established a different (quite long) timeout is used for waiting for transport-related data, which means this call can block for much longer that timeout, but only with slow/faulty/malicious clients.

Server capabilities are generated based on the content of ctx. The context must not be destroyed before the accepted NETCONF session is freed. Basic usable context may be created by calling nc_server_init_ctx().

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]	timeout	Timeout for receiving a new connection in milliseconds, 0 for non-blocking call, -1 for infinite waiting.
[in]	ctx	Context for the session to use.
[out]	session	New session.

Returns: NC_MSG_HELLO on success, NC_MSG_BAD_HELLO on client <hello> message parsing fail, NC_MSG_WOULDBLOCK on timeout, NC_MSG_ERROR on other errors.

NC_MSG_TYPE nc_session_accept_ssh_channel	(	struct nc_session *	orig_session,
		struct nc_session **	session
	)

Accept a new NETCONF session on an SSH session of a running NETCONF orig_session. Call this function only when nc_ps_poll() returns NC_PSPOLL_SSH_CHANNEL on orig_session.

Parameters

[in]	orig_session	Session that has a new SSH channel ready.
[out]	session	New session.

Returns: NC_MSG_HELLO on success, NC_MSG_BAD_HELLO on client <hello> message parsing fail, NC_MSG_WOULDBLOCK on timeout, NC_MSG_ERROR on other errors.

NC_MSG_TYPE nc_ps_accept_ssh_channel	(	struct nc_pollsession *	ps,
		struct nc_session **	session
	)

Accept a new NETCONF session on an SSH session of a running NETCONF session that was polled in ps. Call this function only when nc_ps_poll() on ps returns NC_PSPOLL_SSH_CHANNEL. The new session is only returned in session, it is not added to ps.

Parameters

[in]	ps	Unmodified pollsession structure from the previous nc_ps_poll() call.
[out]	session	New session.

Returns: NC_MSG_HELLO on success, NC_MSG_BAD_HELLO on client <hello> message parsing fail, NC_MSG_WOULDBLOCK on timeout, NC_MSG_ERROR on other errors.

struct timespec nc_session_get_start_time ( const struct nc_session * session )

Get session start time.

Parameters

[in] session Session to get the information from.

Returns: Session start time.

void nc_session_inc_notif_status ( struct nc_session * session )

Increase session notification subscription flag count. Supports multiple subscriptions on one session.

It is used only to ignore timeouts, because they are ignored for sessions with active subscriptions.

Parameters

[in] session Session to modify.

void nc_session_dec_notif_status ( struct nc_session * session )

Decrease session notification subscription flag count. Supports multiple subscriptions on one session.

Parameters

[in] session Session to modify.

int nc_session_get_notif_status ( const struct nc_session * session )

Get session notification subscription flag.

Parameters

[in] session Session to get the information from.

Returns: 0 for no active subscription, non-zero for an active subscription.

int nc_server_notif_cert_expiration_thread_start	(	nc_cert_exp_notif_clb	cert_exp_notif_clb,
		void *	user_data,
		void()(void )	free_data
	)

Start the certificate expiration notification thread.

The thread will periodically check the expiration time of all certificates in the configuration. When a notification is about to be generated, the callback cert_exp_notif_clb is called. The times of when these notifications are generated are based on the expiration times of certificates in the configuration and on the values of intervals set in the configuration. For more information, see the libnetconf2-netconf-server YANG module.

Parameters

[in]	cert_exp_notif_clb	The callback to be called when a notification is generated.
[in]	user_data	Arbitrary user data to pass to the callback.
[in]	free_data	Optional callback to free the user data.

Returns: 0 on success, 1 on error.

void nc_server_notif_cert_expiration_thread_stop ( int wait )

Stop the certificate expiration notification thread.

Parameters

[in] wait Boolean representing whether to block and wait for the thread to finish.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation