doc/developer/path-internals-daemon.rst

   1 PATHD Internals
   2 ===============
   3
   4 Architecture
   5 ------------
   6
   7 Overview
   8 ........
   9
  10 The pathd deamon manages the segment routing policies, it owns the data
  11 structures representing them and can load modules that manipulate them like the
  12 PCEP module. Its responsibility is to select a candidate path for each
  13 configured policy and to install it into Zebra.
  14
  15 Zebra
  16 .....
  17
  18 Zebra manages policies that are active or pending to be activated due to the
  19 next hop not being available yet. In zebra, policy data structures and APIs are
  20 defined in `zebra_srte.[hc]`.
  21
  22 The responsibilities of Zebra are:
  23
  24  - Store the policies' segment list.
  25  - Install the policies when their next-hop is available.
  26  - Notify other daemons of the status of the policies.
  27
  28 Adding and removing policies is done using the commands `ZEBRA_SR_POLICY_SET`
  29 and `ZEBRA_SR_POLICY_DELETE` as parameter of the function `zebra_send_sr_policy`
  30 all defined in `zclient.[hc]`.
  31
  32 If the first segment of the policy is an unknown label, it is kept until
  33 notified by the mpls hooks `zebra_mpls_label_created`, and then it is installed.
  34
  35 To get notified when a policy status changes, a client can implement the
  36 `sr_policy_notify_status` callback defined in `zclient.[hc]`.
  37
  38 For encoding/decoding the various data structures used to comunicate with zebra,
  39 the following functions are available from `zclient.[hc]`:
  40 `zapi_sr_policy_encode`, `zapi_sr_policy_decode` and
  41 `zapi_sr_policy_notify_status_decode`.
  42
  43
  44 Pathd
  45 .....
  46
  47
  48 The pathd daemon manages all the possible candidate paths for the segment
  49 routing policies and selects the best one following the
  50 `segment routing policy draft <https://tools.ietf.org/html/draft-ietf-spring-segment-routing-policy-06#section-2.9>`_.
  51 It also supports loadable modules for handling dynamic candidate paths and the
  52 creation of new policies and candidate paths at runtime.
  53
  54 The responsibilities of the pathd base daemon, not including any optional
  55 modules, are:
  56
  57  - Store the policies and all the possible candidate paths for them.
  58  - Select the best candidate path for each policy and send it to Zebra.
  59  - Provide VTYSH configuration to set up policies and candidate paths.
  60  - Provide a Northbound API to manipulate **configured** policies and candidate paths.
  61  - Handle loadable modules for extending the functionality.
  62  - Provide an API to the loadable module to manipulate policies and candidate paths.
  63
  64
  65 Threading Model
  66 ---------------
  67
  68 The daemon runs completely inside the main thread using FRR event model, there
  69 is no threading involved.
  70
  71
  72 Source Code
  73 -----------
  74
  75 Internal Data Structures
  76 ........................
  77
  78 The main data structures for policies and candidate paths are defined in
  79 `pathd.h` and implemented in `pathd.c`.
  80
  81 When modifying these structures, either directly or through the functions
  82 exported by `pathd.h`, nothing should be deleted/freed right away. The deletion
  83 or modification flags must be set and when all the changes are done, the
  84 function `srte_apply_changes` must be called. When called, a new candidate path
  85 may be elected and sent to Zebra, and all the structures flagged as deleted
  86 will be freed. In addition, a hook will be called so dynamic modules can perform
  87 any required action when the elected candidate path changes.
  88
  89
  90 Northbound API
  91 ..............
  92
  93 The northbound API is defined in `path_nb.[ch]` and implemented in
  94 `path_nb_config.c` for configuration data and `path_nb_state.c` for operational
  95 data.
  96
  97
  98 Command Line Client
  99 ...................
 100
 101 The command-line client (VTYSH) is implemented in `path_cli.c`.
 102
 103
 104 Interface with Zebra
 105 ....................
 106
 107 All the functions interfacing with Zebra are defined and implemented in
 108 `path_zebra.[hc]`.
 109
 110
 111 Loadable Module API
 112 ...................
 113
 114 For the time being, the API the loadable module uses is defined by `pathd.h`,
 115 but in the future, it should be moved to a dedicated include file.