]>
git.proxmox.com Git - mirror_frr.git/blob - lib/northbound.h
2 * Copyright (C) 2018 NetDEF, Inc.
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the Free
7 * Software Foundation; either version 2 of the License, or (at your option)
10 * This program is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
15 * You should have received a copy of the GNU General Public License along
16 * with this program; see the file COPYING; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 #ifndef _FRR_NORTHBOUND_H_
21 #define _FRR_NORTHBOUND_H_
26 #include "openbsd-tree.h"
28 #include "yang_translator.h"
30 /* Forward declaration(s). */
33 /* Northbound events. */
36 * The configuration callback is supposed to verify that the changes are
37 * valid and can be applied.
42 * The configuration callback is supposed to prepare all resources
43 * required to apply the changes.
48 * Transaction has failed, the configuration callback needs to release
49 * all resources previously allocated.
54 * The configuration changes need to be applied. The changes can't be
55 * rejected at this point (errors are logged and ignored).
61 * Northbound operations.
63 * Refer to the documentation comments of nb_callbacks for more details.
85 * Configuration callback.
87 * A presence container, list entry, leaf-list entry or leaf of type
88 * empty has been created.
90 * For presence-containers and list entries, the callback is supposed to
91 * initialize the default values of its children (if any) from the YANG
95 * The transaction phase. Refer to the documentation comments of
96 * nb_event for more details.
99 * libyang data node that is being created.
102 * Pointer to store resource(s) allocated during the NB_EV_PREPARE
103 * phase. The same pointer can be used during the NB_EV_ABORT and
104 * NB_EV_APPLY phases to either release or make use of the allocated
105 * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
108 * - NB_OK on success.
109 * - NB_ERR_VALIDATION when a validation error occurred.
110 * - NB_ERR_RESOURCE when the callback failed to allocate a resource.
111 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
112 * - NB_ERR for other errors.
114 int (*create
)(enum nb_event event
, const struct lyd_node
*dnode
,
115 union nb_resource
*resource
);
118 * Configuration callback.
120 * The value of a leaf has been modified.
122 * List keys don't need to implement this callback. When a list key is
123 * modified, the northbound treats this as if the list was deleted and a
124 * new one created with the updated key value.
127 * The transaction phase. Refer to the documentation comments of
128 * nb_event for more details.
131 * libyang data node that is being modified
134 * Pointer to store resource(s) allocated during the NB_EV_PREPARE
135 * phase. The same pointer can be used during the NB_EV_ABORT and
136 * NB_EV_APPLY phases to either release or make use of the allocated
137 * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
140 * - NB_OK on success.
141 * - NB_ERR_VALIDATION when a validation error occurred.
142 * - NB_ERR_RESOURCE when the callback failed to allocate a resource.
143 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
144 * - NB_ERR for other errors.
146 int (*modify
)(enum nb_event event
, const struct lyd_node
*dnode
,
147 union nb_resource
*resource
);
150 * Configuration callback.
152 * A presence container, list entry, leaf-list entry or optional leaf
155 * The callback is supposed to delete the entire configuration object,
156 * including its children when they exist.
159 * The transaction phase. Refer to the documentation comments of
160 * nb_event for more details.
163 * libyang data node that is being deleted.
166 * - NB_OK on success.
167 * - NB_ERR_VALIDATION when a validation error occurred.
168 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
169 * - NB_ERR for other errors.
171 int (*delete)(enum nb_event event
, const struct lyd_node
*dnode
);
174 * Configuration callback.
176 * A list entry or leaf-list entry has been moved. Only applicable when
177 * the "ordered-by user" statement is present.
180 * The transaction phase. Refer to the documentation comments of
181 * nb_event for more details.
184 * libyang data node that is being moved.
187 * - NB_OK on success.
188 * - NB_ERR_VALIDATION when a validation error occurred.
189 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
190 * - NB_ERR for other errors.
192 int (*move
)(enum nb_event event
, const struct lyd_node
*dnode
);
195 * Optional configuration callback.
197 * The 'apply_finish' callbacks are called after all other callbacks
198 * during the apply phase (NB_EV_APPLY). These callbacks are called only
199 * under one of the following two cases:
200 * - The data node has been created or modified (but not deleted);
201 * - Any change was made within the descendants of the data node (e.g. a
202 * child leaf was modified, created or deleted).
204 * In the second case above, the 'apply_finish' callback is called only
205 * once even if multiple changes occurred within the descendants of the
209 * libyang data node associated with the 'apply_finish' callback.
211 void (*apply_finish
)(const struct lyd_node
*dnode
);
214 * Operational data callback.
216 * The callback function should return the value of a specific leaf,
217 * leaf-list entry or inform if a typeless value (presence containers or
218 * leafs of type empty) exists or not.
221 * YANG data path of the data we want to get.
224 * Pointer to list entry (might be NULL).
227 * Pointer to newly created yang_data structure, or NULL to indicate
228 * the absence of data.
230 struct yang_data
*(*get_elem
)(const char *xpath
,
231 const void *list_entry
);
234 * Operational data callback for YANG lists and leaf-lists.
236 * The callback function should return the next entry in the list or
237 * leaf-list. The 'list_entry' parameter will be NULL on the first
241 * Pointer to parent list entry.
244 * Pointer to (leaf-)list entry.
247 * Pointer to the next entry in the (leaf-)list, or NULL to signal
248 * that the end of the (leaf-)list was reached.
250 const void *(*get_next
)(const void *parent_list_entry
,
251 const void *list_entry
);
254 * Operational data callback for YANG lists.
256 * The callback function should fill the 'keys' parameter based on the
257 * given list_entry. Keyless lists don't need to implement this
261 * Pointer to list entry.
264 * Structure to be filled based on the attributes of the provided
268 * NB_OK on success, NB_ERR otherwise.
270 int (*get_keys
)(const void *list_entry
, struct yang_list_keys
*keys
);
273 * Operational data callback for YANG lists.
275 * The callback function should return a list entry based on the list
276 * keys given as a parameter. Keyless lists don't need to implement this
280 * Pointer to parent list entry.
283 * Structure containing the keys of the list entry.
286 * Pointer to the list entry if found, or NULL if not found.
288 const void *(*lookup_entry
)(const void *parent_list_entry
,
289 const struct yang_list_keys
*keys
);
292 * RPC and action callback.
294 * Both 'input' and 'output' are lists of 'yang_data' structures. The
295 * callback should fetch all the input parameters from the 'input' list,
296 * and add output parameters to the 'output' list if necessary.
299 * XPath of the YANG RPC or action.
302 * Read-only list of input parameters.
305 * List of output parameters to be populated by the callback.
308 * NB_OK on success, NB_ERR otherwise.
310 int (*rpc
)(const char *xpath
, const struct list
*input
,
311 struct list
*output
);
314 * Optional callback to show the CLI command associated to the given
318 * The vty terminal to dump the configuration to.
321 * libyang data node that should be shown in the form of a CLI
325 * Specify whether to display default configuration values or not.
326 * This parameter can be ignored most of the time since the
327 * northbound doesn't call this callback for default leaves or
328 * non-presence containers that contain only default child nodes.
329 * The exception are commands associated to multiple configuration
330 * nodes, in which case it might be desirable to hide one or more
331 * parts of the command when this parameter is set to false.
333 void (*cli_show
)(struct vty
*vty
, struct lyd_node
*dnode
,
338 * Northbound-specific data that is allocated for each schema node of the native
342 /* Back pointer to the libyang schema node. */
343 const struct lys_node
*snode
;
345 /* Data path of this YANG node. */
346 char xpath
[XPATH_MAXLEN
];
348 /* Priority - lower priorities are processed first. */
351 /* Callbacks implemented for this node. */
352 struct nb_callbacks cbs
;
355 * Pointer to the parent node (disconsidering non-presence containers).
357 struct nb_node
*parent
;
359 /* Pointer to the nearest parent list, if any. */
360 struct nb_node
*parent_list
;
366 /* ConfD hash value corresponding to this YANG path. */
370 /* The YANG container or list contains only config data. */
371 #define F_NB_NODE_CONFIG_ONLY 0x01
372 /* The YANG list doesn't contain key leafs. */
373 #define F_NB_NODE_KEYLESS_LIST 0x02
375 struct frr_yang_module_info
{
376 /* YANG module name. */
379 /* Northbound callbacks. */
381 /* Data path of this YANG node. */
384 /* Callbacks implemented for this node. */
385 struct nb_callbacks cbs
;
387 /* Priority - lower priorities are processed first. */
392 /* Northbound error codes. */
401 NB_ERR_INCONSISTENCY
,
404 /* Default priority. */
405 #define NB_DFLT_PRIORITY (UINT32_MAX / 2)
407 /* Default maximum of configuration rollbacks to store. */
408 #define NB_DLFT_MAX_CONFIG_ROLLBACKS 20
410 /* Northbound clients. */
417 /* Northbound configuration. */
419 struct lyd_node
*dnode
;
423 /* Northbound configuration callback. */
424 struct nb_config_cb
{
425 RB_ENTRY(nb_config_cb
) entry
;
426 enum nb_operation operation
;
427 char xpath
[XPATH_MAXLEN
];
428 const struct nb_node
*nb_node
;
429 const struct lyd_node
*dnode
;
431 RB_HEAD(nb_config_cbs
, nb_config_cb
);
432 RB_PROTOTYPE(nb_config_cbs
, nb_config_cb
, entry
, nb_config_cb_compare
);
434 /* Northbound configuration change. */
435 struct nb_config_change
{
436 struct nb_config_cb cb
;
437 union nb_resource resource
;
441 /* Northbound configuration transaction. */
442 struct nb_transaction
{
443 enum nb_client client
;
445 struct nb_config
*config
;
446 struct nb_config_cbs changes
;
449 /* Callback function used by nb_oper_data_iterate(). */
450 typedef int (*nb_oper_data_cb
)(const struct lys_node
*snode
,
451 struct yang_translator
*translator
,
452 struct yang_data
*data
, void *arg
);
454 /* Iterate over direct child nodes only. */
455 #define NB_OPER_DATA_ITER_NORECURSE 0x0001
457 DECLARE_HOOK(nb_notification_send
, (const char *xpath
, struct list
*arguments
),
460 extern int debug_northbound
;
461 extern struct nb_config
*running_config
;
464 * Create a northbound node for all YANG schema nodes.
466 void nb_nodes_create(void);
469 * Delete all northbound nodes from all YANG schema nodes.
471 void nb_nodes_delete(void);
474 * Find the northbound node corresponding to a YANG data path.
477 * XPath to search for (with or without predicates).
480 * Pointer to northbound node if found, NULL otherwise.
482 extern struct nb_node
*nb_node_find(const char *xpath
);
485 * Create a new northbound configuration.
488 * Pointer to a libyang data node containing the configuration data. If NULL
489 * is given, an empty configuration will be created.
492 * Pointer to newly created northbound configuration.
494 extern struct nb_config
*nb_config_new(struct lyd_node
*dnode
);
497 * Delete a northbound configuration.
500 * Pointer to the config that is going to be deleted.
502 extern void nb_config_free(struct nb_config
*config
);
505 * Duplicate a northbound configuration.
508 * Northbound configuration to duplicate.
511 * Pointer to duplicated configuration.
513 extern struct nb_config
*nb_config_dup(const struct nb_config
*config
);
516 * Merge one configuration into another.
519 * Configuration to merge to.
522 * Configuration to merge config_dst with.
525 * Specify whether config_src should be deleted or not after the merge
529 * NB_OK on success, NB_ERR otherwise.
531 extern int nb_config_merge(struct nb_config
*config_dst
,
532 struct nb_config
*config_src
, bool preserve_source
);
535 * Replace one configuration by another.
538 * Configuration to be replaced.
541 * Configuration to replace config_dst.
544 * Specify whether config_src should be deleted or not after the replace
547 extern void nb_config_replace(struct nb_config
*config_dst
,
548 struct nb_config
*config_src
,
549 bool preserve_source
);
552 * Edit a candidate configuration.
555 * Candidate configuration to edit.
558 * Northbound node associated to the configuration being edited.
561 * Operation to apply.
564 * XPath of the configuration node being edited.
567 * Previous value of the configuration node. Should be used only when the
568 * operation is NB_OP_MOVE, otherwise this parameter is ignored.
571 * New value of the configuration node.
574 * - NB_OK on success.
575 * - NB_ERR_NOT_FOUND when the element to be deleted was not found.
576 * - NB_ERR for other errors.
578 extern int nb_candidate_edit(struct nb_config
*candidate
,
579 const struct nb_node
*nb_node
,
580 enum nb_operation operation
, const char *xpath
,
581 const struct yang_data
*previous
,
582 const struct yang_data
*data
);
585 * Check if a candidate configuration is outdated and needs to be updated.
588 * Candidate configuration to check.
591 * true if the candidate is outdated, false otherwise.
593 extern bool nb_candidate_needs_update(const struct nb_config
*candidate
);
596 * Update a candidate configuration by rebasing the changes on top of the latest
597 * running configuration. Resolve conflicts automatically by giving preference
598 * to the changes done in the candidate configuration.
601 * Candidate configuration to update.
604 * NB_OK on success, NB_ERR otherwise.
606 extern int nb_candidate_update(struct nb_config
*candidate
);
609 * Validate a candidate configuration. Perform both YANG syntactic/semantic
610 * validation and code-level validation using the northbound callbacks.
612 * WARNING: the candidate can be modified as part of the validation process
613 * (e.g. add default nodes).
616 * Candidate configuration to validate.
619 * NB_OK on success, NB_ERR_VALIDATION otherwise.
621 extern int nb_candidate_validate(struct nb_config
*candidate
);
624 * Create a new configuration transaction but do not commit it yet. Only
625 * validate the candidate and prepare all resources required to apply the
626 * configuration changes.
629 * Candidate configuration to commit.
632 * Northbound client performing the commit.
635 * Optional comment describing the commit.
638 * Output parameter providing the created transaction when one is created
639 * successfully. In this case, it must be either aborted using
640 * nb_candidate_commit_abort() or committed using
641 * nb_candidate_commit_apply().
644 * - NB_OK on success.
645 * - NB_ERR_NO_CHANGES when the candidate is identical to the running
647 * - NB_ERR_LOCKED when there's already another transaction in progress.
648 * - NB_ERR_VALIDATION when the candidate fails the validation checks.
649 * - NB_ERR_RESOURCE when the system fails to allocate resources to apply
650 * the candidate configuration.
651 * - NB_ERR for other errors.
653 extern int nb_candidate_commit_prepare(struct nb_config
*candidate
,
654 enum nb_client client
,
656 struct nb_transaction
**transaction
);
659 * Abort a previously created configuration transaction, releasing all resources
660 * allocated during the preparation phase.
663 * Candidate configuration to abort. It's consumed by this function.
665 extern void nb_candidate_commit_abort(struct nb_transaction
*transaction
);
668 * Commit a previously created configuration transaction.
671 * Configuration transaction to commit. It's consumed by this function.
674 * Specify whether the transaction should be recorded in the transactions log
678 * Optional output parameter providing the ID of the committed transaction.
680 extern void nb_candidate_commit_apply(struct nb_transaction
*transaction
,
681 bool save_transaction
,
682 uint32_t *transaction_id
);
685 * Create a new transaction to commit a candidate configuration. This is a
686 * convenience function that performs the two-phase commit protocol
687 * transparently to the user. The cost is reduced flexibility, since
688 * network-wide and multi-daemon transactions require the network manager to
689 * take into account the results of the preparation phase of multiple managed
693 * Candidate configuration to commit. It's preserved regardless if the commit
694 * operation fails or not.
697 * Northbound client performing the commit.
700 * Specify whether the transaction should be recorded in the transactions log
704 * Optional comment describing the commit.
707 * Optional output parameter providing the ID of the committed transaction.
710 * - NB_OK on success.
711 * - NB_ERR_NO_CHANGES when the candidate is identical to the running
713 * - NB_ERR_LOCKED when there's already another transaction in progress.
714 * - NB_ERR_VALIDATION when the candidate fails the validation checks.
715 * - NB_ERR_RESOURCE when the system fails to allocate resources to apply
716 * the candidate configuration.
717 * - NB_ERR for other errors.
719 extern int nb_candidate_commit(struct nb_config
*candidate
,
720 enum nb_client client
, bool save_transaction
,
721 const char *comment
, uint32_t *transaction_id
);
724 * Iterate over operetional data.
727 * Data path of the YANG data we want to iterate over.
730 * YANG module translator (might be NULL).
733 * NB_OPER_DATA_ITER_ flags to control how the iteration is performed.
736 * Function to call with each data node.
739 * Arbitrary argument passed as the fourth parameter in each call to 'cb'.
742 * NB_OK on success, NB_ERR otherwise.
744 extern int nb_oper_data_iterate(const char *xpath
,
745 struct yang_translator
*translator
,
746 uint32_t flags
, nb_oper_data_cb cb
, void *arg
);
749 * Validate if the northbound operation is valid for the given node.
752 * Operation we want to check.
755 * libyang schema node we want to check.
758 * true if the operation is valid, false otherwise.
760 extern bool nb_operation_is_valid(enum nb_operation operation
,
761 const struct lys_node
*snode
);
764 * Send a YANG notification. This is a no-op unless the 'nb_notification_send'
765 * hook was registered by a northbound plugin.
768 * XPath of the YANG notification.
771 * Linked list containing the arguments that should be sent. This list is
772 * deleted after being used.
775 * NB_OK on success, NB_ERR otherwise.
777 extern int nb_notification_send(const char *xpath
, struct list
*arguments
);
780 * Return a human-readable string representing a northbound event.
786 * String representation of the given northbound event.
788 extern const char *nb_event_name(enum nb_event event
);
791 * Return a human-readable string representing a northbound operation.
794 * Northbound operation.
797 * String representation of the given northbound operation.
799 extern const char *nb_operation_name(enum nb_operation operation
);
802 * Return a human-readable string representing a northbound error.
808 * String representation of the given northbound error.
810 extern const char *nb_err_name(enum nb_error error
);
813 * Return a human-readable string representing a northbound client.
819 * String representation of the given northbound client.
821 extern const char *nb_client_name(enum nb_client client
);
824 * Initialize the northbound layer. Should be called only once during the
825 * daemon initialization process.
828 * Array of YANG modules to parse and initialize.
831 * Size of the modules array.
833 extern void nb_init(struct thread_master
*tm
, const struct frr_yang_module_info
*modules
[],
837 * Finish the northbound layer gracefully. Should be called only when the daemon
840 extern void nb_terminate(void);
842 #endif /* _FRR_NORTHBOUND_H_ */