]>
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 /* Forward declaration(s). */
31 /* Northbound events. */
34 * The configuration callback is supposed to verify that the changes are
35 * valid and can be applied.
40 * The configuration callback is supposed to prepare all resources
41 * required to apply the changes.
46 * Transaction has failed, the configuration callback needs to release
47 * all resources previously allocated.
52 * The configuration changes need to be applied. The changes can't be
53 * rejected at this point (errors are logged and ignored).
59 * Northbound operations.
61 * Refer to the documentation comments of nb_callbacks for more details.
83 * Configuration callback.
85 * A presence container, list entry, leaf-list entry or leaf of type
86 * empty has been created.
88 * For presence-containers and list entries, the callback is supposed to
89 * initialize the default values of its children (if any) from the YANG
93 * The transaction phase. Refer to the documentation comments of
94 * nb_event for more details.
97 * libyang data node that is being created.
100 * Pointer to store resource(s) allocated during the NB_EV_PREPARE
101 * phase. The same pointer can be used during the NB_EV_ABORT and
102 * NB_EV_APPLY phases to either release or make use of the allocated
103 * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
106 * - NB_OK on success.
107 * - NB_ERR_VALIDATION when a validation error occurred.
108 * - NB_ERR_RESOURCE when the callback failed to allocate a resource.
109 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
110 * - NB_ERR for other errors.
112 int (*create
)(enum nb_event event
, const struct lyd_node
*dnode
,
113 union nb_resource
*resource
);
116 * Configuration callback.
118 * The value of a leaf has been modified.
120 * List keys don't need to implement this callback. When a list key is
121 * modified, the northbound treats this as if the list was deleted and a
122 * new one created with the updated key value.
125 * The transaction phase. Refer to the documentation comments of
126 * nb_event for more details.
129 * libyang data node that is being modified
132 * Pointer to store resource(s) allocated during the NB_EV_PREPARE
133 * phase. The same pointer can be used during the NB_EV_ABORT and
134 * NB_EV_APPLY phases to either release or make use of the allocated
135 * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
138 * - NB_OK on success.
139 * - NB_ERR_VALIDATION when a validation error occurred.
140 * - NB_ERR_RESOURCE when the callback failed to allocate a resource.
141 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
142 * - NB_ERR for other errors.
144 int (*modify
)(enum nb_event event
, const struct lyd_node
*dnode
,
145 union nb_resource
*resource
);
148 * Configuration callback.
150 * A presence container, list entry, leaf-list entry or optional leaf
153 * The callback is supposed to delete the entire configuration object,
154 * including its children when they exist.
157 * The transaction phase. Refer to the documentation comments of
158 * nb_event for more details.
161 * libyang data node that is being deleted.
164 * - NB_OK on success.
165 * - NB_ERR_VALIDATION when a validation error occurred.
166 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
167 * - NB_ERR for other errors.
169 int (*delete)(enum nb_event event
, const struct lyd_node
*dnode
);
172 * Configuration callback.
174 * A list entry or leaf-list entry has been moved. Only applicable when
175 * the "ordered-by user" statement is present.
178 * The transaction phase. Refer to the documentation comments of
179 * nb_event for more details.
182 * libyang data node that is being moved.
185 * - NB_OK on success.
186 * - NB_ERR_VALIDATION when a validation error occurred.
187 * - NB_ERR_INCONSISTENCY when an inconsistency was detected.
188 * - NB_ERR for other errors.
190 int (*move
)(enum nb_event event
, const struct lyd_node
*dnode
);
193 * Optional configuration callback.
195 * The 'apply_finish' callbacks are called after all other callbacks
196 * during the apply phase (NB_EV_APPLY). These callbacks are called only
197 * under one of the following two cases:
198 * - The data node has been created or modified (but not deleted);
199 * - Any change was made within the descendants of the data node (e.g. a
200 * child leaf was modified, created or deleted).
202 * In the second case above, the 'apply_finish' callback is called only
203 * once even if multiple changes occurred within the descendants of the
207 * libyang data node associated with the 'apply_finish' callback.
209 void (*apply_finish
)(const struct lyd_node
*dnode
);
212 * Operational data callback.
214 * The callback function should return the value of a specific leaf or
215 * inform if a typeless value (presence containers or leafs of type
216 * empty) exists or not.
219 * YANG data path of the data we want to get.
222 * Pointer to list entry.
225 * Pointer to newly created yang_data structure, or NULL to indicate
226 * the absence of data.
228 struct yang_data
*(*get_elem
)(const char *xpath
,
229 const void *list_entry
);
232 * Operational data callback for YANG lists.
234 * The callback function should return the next entry in the list. The
235 * 'list_entry' parameter will be NULL on the first invocation.
238 * Data path of the YANG list.
241 * Pointer to list entry.
244 * Pointer to the next entry in the list, or NULL to signal that the
245 * end of the list was reached.
247 const void *(*get_next
)(const char *xpath
, const void *list_entry
);
250 * Operational data callback for YANG lists.
252 * The callback function should fill the 'keys' parameter based on the
256 * Pointer to list entry.
259 * Structure to be filled based on the attributes of the provided
263 * NB_OK on success, NB_ERR otherwise.
265 int (*get_keys
)(const void *list_entry
, struct yang_list_keys
*keys
);
268 * Operational data callback for YANG lists.
270 * The callback function should return a list entry based on the list
271 * keys given as a parameter.
274 * Structure containing the keys of the list entry.
277 * Pointer to the list entry if found, or NULL if not found.
279 const void *(*lookup_entry
)(const struct yang_list_keys
*keys
);
282 * RPC and action callback.
284 * Both 'input' and 'output' are lists of 'yang_data' structures. The
285 * callback should fetch all the input parameters from the 'input' list,
286 * and add output parameters to the 'output' list if necessary.
289 * XPath of the YANG RPC or action.
292 * Read-only list of input parameters.
295 * List of output parameters to be populated by the callback.
298 * NB_OK on success, NB_ERR otherwise.
300 int (*rpc
)(const char *xpath
, const struct list
*input
,
301 struct list
*output
);
304 * Optional callback to show the CLI command associated to the given
308 * The vty terminal to dump the configuration to.
311 * libyang data node that should be shown in the form of a CLI
315 * Specify whether to display default configuration values or not.
316 * This parameter can be ignored most of the time since the
317 * northbound doesn't call this callback for default leaves or
318 * non-presence containers that contain only default child nodes.
319 * The exception are commands associated to multiple configuration
320 * nodes, in which case it might be desirable to hide one or more
321 * parts of the command when this parameter is set to false.
323 void (*cli_show
)(struct vty
*vty
, struct lyd_node
*dnode
,
328 * Northbound-specific data that is allocated for each schema node of the native
332 /* Back pointer to the libyang schema node. */
333 const struct lys_node
*snode
;
335 /* Data path of this YANG node. */
336 char xpath
[XPATH_MAXLEN
];
338 /* Priority - lower priorities are processed first. */
341 /* Callbacks implemented for this node. */
342 struct nb_callbacks cbs
;
345 * Pointer to the parent node (disconsidering non-presence containers).
347 struct nb_node
*parent
;
349 /* Pointer to the nearest parent list, if any. */
350 struct nb_node
*parent_list
;
353 /* ConfD hash value corresponding to this YANG path. */
358 struct frr_yang_module_info
{
359 /* YANG module name. */
362 /* Northbound callbacks. */
364 /* Data path of this YANG node. */
367 /* Callbacks implemented for this node. */
368 struct nb_callbacks cbs
;
370 /* Priority - lower priorities are processed first. */
375 /* Northbound error codes. */
384 NB_ERR_INCONSISTENCY
,
387 /* Default priority. */
388 #define NB_DFLT_PRIORITY (UINT32_MAX / 2)
390 /* Default maximum of configuration rollbacks to store. */
391 #define NB_DLFT_MAX_CONFIG_ROLLBACKS 20
393 /* Northbound clients. */
400 /* Northbound configuration. */
402 struct lyd_node
*dnode
;
406 /* Northbound configuration callback. */
407 struct nb_config_cb
{
408 RB_ENTRY(nb_config_cb
) entry
;
409 enum nb_operation operation
;
410 char xpath
[XPATH_MAXLEN
];
411 const struct nb_node
*nb_node
;
412 const struct lyd_node
*dnode
;
414 RB_HEAD(nb_config_cbs
, nb_config_cb
);
415 RB_PROTOTYPE(nb_config_cbs
, nb_config_cb
, entry
, nb_config_cb_compare
);
417 /* Northbound configuration change. */
418 struct nb_config_change
{
419 struct nb_config_cb cb
;
420 union nb_resource resource
;
424 /* Northbound configuration transaction. */
425 struct nb_transaction
{
426 enum nb_client client
;
428 struct nb_config
*config
;
429 struct nb_config_cbs changes
;
432 DECLARE_HOOK(nb_notification_send
, (const char *xpath
, struct list
*arguments
),
435 extern int debug_northbound
;
436 extern struct nb_config
*running_config
;
439 * Find the northbound node corresponding to a YANG data path.
442 * XPath to search for (with or without predicates).
445 * Pointer to northbound node if found, NULL otherwise.
447 extern struct nb_node
*nb_node_find(const char *xpath
);
450 * Create a new northbound configuration.
453 * Pointer to a libyang data node containing the configuration data. If NULL
454 * is given, an empty configuration will be created.
457 * Pointer to newly created northbound configuration.
459 extern struct nb_config
*nb_config_new(struct lyd_node
*dnode
);
462 * Delete a northbound configuration.
465 * Pointer to the config that is going to be deleted.
467 extern void nb_config_free(struct nb_config
*config
);
470 * Duplicate a northbound configuration.
473 * Northbound configuration to duplicate.
476 * Pointer to duplicated configuration.
478 extern struct nb_config
*nb_config_dup(const struct nb_config
*config
);
481 * Merge one configuration into another.
484 * Configuration to merge to.
487 * Configuration to merge config_dst with.
490 * Specify whether config_src should be deleted or not after the merge
494 * NB_OK on success, NB_ERR otherwise.
496 extern int nb_config_merge(struct nb_config
*config_dst
,
497 struct nb_config
*config_src
, bool preserve_source
);
500 * Replace one configuration by another.
503 * Configuration to be replaced.
506 * Configuration to replace config_dst.
509 * Specify whether config_src should be deleted or not after the replace
512 extern void nb_config_replace(struct nb_config
*config_dst
,
513 struct nb_config
*config_src
,
514 bool preserve_source
);
517 * Edit a candidate configuration.
520 * Candidate configuration to edit.
523 * Northbound node associated to the configuration being edited.
526 * Operation to apply.
529 * XPath of the configuration node being edited.
532 * Previous value of the configuration node. Should be used only when the
533 * operation is NB_OP_MOVE, otherwise this parameter is ignored.
536 * New value of the configuration node.
539 * - NB_OK on success.
540 * - NB_ERR_NOT_FOUND when the element to be deleted was not found.
541 * - NB_ERR for other errors.
543 extern int nb_candidate_edit(struct nb_config
*candidate
,
544 const struct nb_node
*nb_node
,
545 enum nb_operation operation
, const char *xpath
,
546 const struct yang_data
*previous
,
547 const struct yang_data
*data
);
550 * Check if a candidate configuration is outdated and needs to be updated.
553 * Candidate configuration to check.
556 * true if the candidate is outdated, false otherwise.
558 extern bool nb_candidate_needs_update(const struct nb_config
*candidate
);
561 * Update a candidate configuration by rebasing the changes on top of the latest
562 * running configuration. Resolve conflicts automatically by giving preference
563 * to the changes done in the candidate configuration.
566 * Candidate configuration to update.
569 * NB_OK on success, NB_ERR otherwise.
571 extern int nb_candidate_update(struct nb_config
*candidate
);
574 * Validate a candidate configuration. Perform both YANG syntactic/semantic
575 * validation and code-level validation using the northbound callbacks.
577 * WARNING: the candidate can be modified as part of the validation process
578 * (e.g. add default nodes).
581 * Candidate configuration to validate.
584 * NB_OK on success, NB_ERR_VALIDATION otherwise.
586 extern int nb_candidate_validate(struct nb_config
*candidate
);
589 * Create a new configuration transaction but do not commit it yet. Only
590 * validate the candidate and prepare all resources required to apply the
591 * configuration changes.
594 * Candidate configuration to commit.
597 * Northbound client performing the commit.
600 * Optional comment describing the commit.
603 * Output parameter providing the created transaction when one is created
604 * successfully. In this case, it must be either aborted using
605 * nb_candidate_commit_abort() or committed using
606 * nb_candidate_commit_apply().
609 * - NB_OK on success.
610 * - NB_ERR_NO_CHANGES when the candidate is identical to the running
612 * - NB_ERR_LOCKED when there's already another transaction in progress.
613 * - NB_ERR_VALIDATION when the candidate fails the validation checks.
614 * - NB_ERR_RESOURCE when the system fails to allocate resources to apply
615 * the candidate configuration.
616 * - NB_ERR for other errors.
618 extern int nb_candidate_commit_prepare(struct nb_config
*candidate
,
619 enum nb_client client
,
621 struct nb_transaction
**transaction
);
624 * Abort a previously created configuration transaction, releasing all resources
625 * allocated during the preparation phase.
628 * Candidate configuration to abort. It's consumed by this function.
630 extern void nb_candidate_commit_abort(struct nb_transaction
*transaction
);
633 * Commit a previously created configuration transaction.
636 * Configuration transaction to commit. It's consumed by this function.
639 * Specify whether the transaction should be recorded in the transactions log
643 * Optional output parameter providing the ID of the committed transaction.
645 extern void nb_candidate_commit_apply(struct nb_transaction
*transaction
,
646 bool save_transaction
,
647 uint32_t *transaction_id
);
650 * Create a new transaction to commit a candidate configuration. This is a
651 * convenience function that performs the two-phase commit protocol
652 * transparently to the user. The cost is reduced flexibility, since
653 * network-wide and multi-daemon transactions require the network manager to
654 * take into account the results of the preparation phase of multiple managed
658 * Candidate configuration to commit. It's preserved regardless if the commit
659 * operation fails or not.
662 * Northbound client performing the commit.
665 * Specify whether the transaction should be recorded in the transactions log
669 * Optional comment describing the commit.
672 * Optional output parameter providing the ID of the committed transaction.
675 * - NB_OK on success.
676 * - NB_ERR_NO_CHANGES when the candidate is identical to the running
678 * - NB_ERR_LOCKED when there's already another transaction in progress.
679 * - NB_ERR_VALIDATION when the candidate fails the validation checks.
680 * - NB_ERR_RESOURCE when the system fails to allocate resources to apply
681 * the candidate configuration.
682 * - NB_ERR for other errors.
684 extern int nb_candidate_commit(struct nb_config
*candidate
,
685 enum nb_client client
, bool save_transaction
,
686 const char *comment
, uint32_t *transaction_id
);
689 * Validate if the northbound operation is valid for the given node.
692 * Operation we want to check.
695 * libyang schema node we want to check.
698 * true if the operation is valid, false otherwise.
700 extern bool nb_operation_is_valid(enum nb_operation operation
,
701 const struct lys_node
*snode
);
704 * Send a YANG notification. This is a no-op unless the 'nb_notification_send'
705 * hook was registered by a northbound plugin.
708 * XPath of the YANG notification.
711 * Linked list containing the arguments that should be sent. This list is
712 * deleted after being used.
715 * NB_OK on success, NB_ERR otherwise.
717 extern int nb_notification_send(const char *xpath
, struct list
*arguments
);
720 * Return a human-readable string representing a northbound event.
726 * String representation of the given northbound event.
728 extern const char *nb_event_name(enum nb_event event
);
731 * Return a human-readable string representing a northbound operation.
734 * Northbound operation.
737 * String representation of the given northbound operation.
739 extern const char *nb_operation_name(enum nb_operation operation
);
742 * Return a human-readable string representing a northbound error.
748 * String representation of the given northbound error.
750 extern const char *nb_err_name(enum nb_error error
);
753 * Return a human-readable string representing a northbound client.
759 * String representation of the given northbound client.
761 extern const char *nb_client_name(enum nb_client client
);
764 * Initialize the northbound layer. Should be called only once during the
765 * daemon initialization process.
768 * Array of YANG modules to parse and initialize.
771 * Size of the modules array.
773 extern void nb_init(const struct frr_yang_module_info
*modules
[],
777 * Finish the northbound layer gracefully. Should be called only when the daemon
780 extern void nb_terminate(void);
782 #endif /* _FRR_NORTHBOUND_H_ */