Loading...
Searching...
No Matches
Server Session
Server

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.
typedef int(* | nc_ps_session_match_cb) (struct nc_session *session, void *cb_data)
| Callback for finding a session in a pollsession structure.
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.

## 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.
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.
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.
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.
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`.
int | nc_ps_add_session (struct nc_pollsession *ps, struct nc_session *session)
| Add a session to a pollsession structure.
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.
int | nc_ps_del_session (struct nc_pollsession *ps, struct nc_session *session)
| Remove a session from a pollsession structure.
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.
void | nc_ps_free (struct nc_pollsession *ps)
| Free a pollsession structure.
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.
struct nc_pollsession * | nc_ps_new (void)
| Create an empty structure for polling sessions.
int | nc_ps_poll (struct nc_pollsession *ps, int timeout, struct nc_session **session)
| Poll sessions and process any received RPCs.
uint16_t | nc_ps_session_count (struct nc_pollsession *ps)
| Learn the number of sessions in a pollsession structure.
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.
void | nc_server_notif_cert_expiration_thread_stop (int wait)
| Stop the certificate expiration notification thread.
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`.
void | nc_session_dec_notif_status (struct nc_session *session)
| Decrease session notification subscription flag count. Supports multiple subscriptions on one session.
int | nc_session_get_notif_status (const struct nc_session *session)
| Get session notification subscription flag.
struct timespec | nc_session_get_start_time (const struct nc_session *session)
| Get 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.
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.
void | nc_session_set_status (struct nc_session *session, NC_STATUS status)
| Set the status of a session.
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.
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.

## Detailed Description

Server-side NETCONF session manipulation.

## Macro Definition Documentation

## NC_PSPOLL_NOSESSIONS

#define NC_PSPOLL_NOSESSIONS 0x0001

No sessions to poll.

Definition at line 336 of file session_server.h.

## NC_PSPOLL_TIMEOUT

#define NC_PSPOLL_TIMEOUT 0x0002

Timeout elapsed.

Definition at line 337 of file session_server.h.

## NC_PSPOLL_RPC

#define NC_PSPOLL_RPC 0x0004

RPC was correctly parsed and processed.

Definition at line 338 of file session_server.h.

## NC_PSPOLL_BAD_RPC

#define NC_PSPOLL_BAD_RPC 0x0008

RPC was received, but failed to be parsed.

Definition at line 339 of file session_server.h.

## NC_PSPOLL_REPLY_ERROR

#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.

## NC_PSPOLL_SESSION_TERM

#define NC_PSPOLL_SESSION_TERM 0x0020

Some session was terminated.

Definition at line 341 of file session_server.h.

## NC_PSPOLL_SESSION_ERROR

#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.

## NC_PSPOLL_ERROR

#define NC_PSPOLL_ERROR 0x0080

Other fatal errors (they are printed).

Definition at line 343 of file session_server.h.

## NC_PSPOLL_SSH_MSG

#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.

## NC_PSPOLL_SSH_CHANNEL

#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

## nc_rpc_clb

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 1 of file session_server.h.

## nc_cert_exp_notif_clb

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.

## nc_ps_session_match_cb

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

## nc_session_set_term_reason()

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.

## nc_session_set_killed_by()

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.

## nc_session_set_status()

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.

## nc_set_global_rpc_clb()

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.

## nc_clb_default_get_schema()

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.

## nc_clb_default_close_session()

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_accept_inout()

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.

## nc_ps_new()

struct nc_pollsession * nc_ps_new | ( | void |  | ) |

Create an empty structure for polling sessions.

Returns
  Empty pollsession structure, NULL on error.

## nc_ps_free()

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.

## nc_ps_add_session()

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.

## nc_ps_del_session()

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.

## nc_ps_get_session()

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.

## nc_ps_find_session()

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.

## nc_ps_session_count()

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.

## nc_ps_poll()

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.

## nc_ps_clear()

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_accept()

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_session_accept_ssh_channel()

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_ps_accept_ssh_channel()

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.

## nc_session_get_start_time()

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.

## nc_session_inc_notif_status()

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.

## nc_session_dec_notif_status()

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.

## nc_session_get_notif_status()

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.

## nc_server_notif_cert_expiration_thread_start()

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.

## nc_server_notif_cert_expiration_thread_stop()

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.