Server sessions

# Init

Server takes an argument for its initialization function. In it, you set the server context, which determines what modules it supports and what capabilities to advertise. Few capabilities that cannot be learnt from the context are set with separate functions nc_server_set_capab_withdefaults() and generally nc_server_set_capability(). Timeout for receiving the hello message on a new session can be set by nc_server_set_hello_timeout() and the timeout for disconnecting an inactive session by nc_server_set_idle_timeout().

Context does not only determine server modules, but its overall functionality as well. For every RPC the server should support, an nc_rpc_clb callback should be set on that node in the context using nc_set_rpc_callback(). Server then calls these as appropriate during poll.

Just like in the client, you can let libnetconf2 establish SSH or TLS transport or do it yourself and only provide the file descriptors of the connection.

Server options can be only set, there are no getters.

To be able to accept any connections, endpoints must first be added with nc_server_add_endpt() and configured with nc_server_endpt_set_address() and nc_server_endpt_set_port(). For unix sockets, nc_server_endpt_set_perms() is available to set the unix socket file permissions, and nc_server_endpt_set_port() is invalid.

## Functions List

Available in nc_server.h.

- nc_server_set_capab_withdefaults()
- nc_server_set_capability()
- nc_server_set_hello_timeout()
- nc_server_set_idle_timeout()
- nc_server_add_endpt()
- nc_server_del_endpt()
- nc_server_endpt_set_address()
- nc_server_endpt_set_port()
- nc_server_endpt_set_perms()

# SSH

To successfully accept an SSH session you must set at least the host key using nc_server_ssh_endpt_add_hostkey(), which are ordered. This way you simply add some hostkey identifier, but the key itself will be retrieved always when needed by calling the callback set by nc_server_ssh_set_hostkey_clb().

There are also some other optional settings. Note that authorized public keys are set for the server as a whole, not endpoint-specifically.

## Functions List

Available in nc_server.h.

- nc_server_ssh_endpt_add_hostkey()
- nc_server_ssh_endpt_del_hostkey()
- nc_server_ssh_endpt_mov_hostkey()
- nc_server_ssh_endpt_mod_hostkey()
- nc_server_ssh_endpt_set_auth_methods()
- nc_server_ssh_endpt_set_auth_attempts()
- nc_server_ssh_endpt_set_auth_timeout()
- nc_server_ssh_set_hostkey_clb()
- nc_server_ssh_add_authkey()
- nc_server_ssh_add_authkey_path()
- nc_server_ssh_del_authkey()

# TLS

TLS works with endpoints too, but its options differ significantly from the SSH ones, especially in the cert-to-name options that TLS uses to derive usernames from client certificates. So, after starting listening on an endpoint you need to set the server certificate (nc_server_tls_endpt_set_server_cert()). Its actual content together with the matching private key will be loaded using a callback from nc_server_tls_set_server_cert_clb(). Additional certificates needed for the client to verify the server's certificate chain can be loaded using a callback from nc_server_tls_set_server_cert_chain_clb().

To accept client certificates, they must first be considered trusted, which you have three ways of achieving. You can add each of their Certificate Authority certificates to the trusted ones or mark a specific client certificate as trusted. Lastly, you can set paths with all the trusted CA certificates with nc_server_tls_endpt_set_trusted_ca_paths(). Adding specific certificates is also performed only as an arbitrary identificator and later retrieved from callback set by nc_server_tls_set_trusted_cert_list_clb(). But, you can add certficates as whole lists, not one-by-one.

Then, from each trusted client certificate a username must be derived for the NETCONF session. This is accomplished by finding a matching cert-to-name entry. They are added using nc_server_tls_endpt_add_ctn().

If you need to remove trusted certificates, you can do so with nc_server_tls_endpt_del_trusted_cert_list(). To clear all Certificate Revocation Lists use nc_server_tls_endpt_clear_crls().

## Functions List

Available in nc_server.h.

- nc_server_tls_endpt_set_server_cert()
- nc_server_tls_endpt_add_trusted_cert_list()
- nc_server_tls_endpt_del_trusted_cert_list()
- nc_server_tls_endpt_set_trusted_ca_paths()
- nc_server_tls_endpt_set_crl_paths()
- nc_server_tls_endpt_clear_crls()
- nc_server_tls_endpt_add_ctn()
- nc_server_tls_endpt_del_ctn()
- nc_server_tls_endpt_get_ctn()
- nc_server_tls_set_server_cert_clb()
- nc_server_tls_set_server_cert_chain_clb()
- nc_server_tls_set_trusted_cert_list_clb()

# FD

If you used a tunneling software, which does its own authentication, you can accept a NETCONF session on its file descriptors with nc_accept_inout().

## Functions List

Available in nc_server.h.

- nc_accept_inout()

# Call Home

Call Home works with endpoints just like standard sessions, but the options are organized a bit differently and endpoints are added for CH clients. However, one important difference is that once all the mandatory options are set, libnetconf2 will not immediately start connecting to a client. It will do so only after calling nc_connect_ch_client_dispatch() in a separate thread.

Lastly, monitoring of these sessions is up to the application.

## Functions List

Available in nc_server.h.

- nc_server_ch_add_client()
- nc_server_ch_del_client()
- nc_server_ch_is_client()
- nc_server_ch_client_add_endpt()
- nc_server_ch_client_del_endpt()
- nc_server_ch_client_is_endpt()
- nc_server_ch_client_endpt_set_address()
- nc_server_ch_client_endpt_set_port()
- nc_server_ch_client_endpt_enable_keepalives()
- nc_server_ch_client_endpt_set_keepalives()
- nc_server_ch_client_set_conn_type()
- nc_server_ch_client_periodic_set_period()
- nc_server_ch_client_periodic_set_anchor_time()
- nc_server_ch_client_periodic_set_idle_timeout()
- nc_server_ch_client_set_start_with()
- nc_server_ch_client_set_max_attempts()
- nc_connect_ch_client_dispatch()
- nc_server_ssh_ch_client_endpt_add_hostkey()
- nc_server_ssh_ch_client_endpt_del_hostkey()
- nc_server_ssh_ch_client_endpt_mov_hostkey()
- nc_server_ssh_ch_client_endpt_set_auth_methods()
- nc_server_ssh_ch_client_endpt_get_auth_methods()
- nc_server_ssh_ch_client_endpt_set_auth_attempts()
- nc_server_ssh_ch_client_endpt_set_auth_timeout()
- nc_server_tls_ch_client_endpt_set_server_cert()
- nc_server_tls_ch_client_endpt_add_trusted_cert_list()
- nc_server_tls_ch_client_endpt_del_trusted_cert_list()
- nc_server_tls_ch_client_endpt_set_trusted_ca_paths()
- nc_server_tls_ch_client_endpt_set_crl_paths()
- nc_server_tls_ch_client_endpt_clear_crls()
- nc_server_tls_ch_client_endpt_add_ctn()
- nc_server_tls_ch_client_endpt_del_ctn()
- nc_server_tls_ch_client_endpt_get_ctn()

# Connecting And Cleanup

When accepting connections with nc_accept(), all the endpoints are examined and the first with a pending connection is used. To remove all CH clients, endpoints, and free any used dynamic memory, destroy the server.

## Functions List

Available in nc_server.h.

- nc_accept()