src/plugins/acl/acl_lookup_context.md

   1 Lookup contexts aka "ACL as a service" {#acl_lookup_context}
   2 ======================================
   3
   4 The initial implementation of the ACL plugin had tightly tied the policy (L3-L4) ACLs
   5 to ingress/egress processing on an interface.
   6
   7 However, some uses outside of pure traffic control have appeared, for example,
   8 ACL-based forwarding, etc. Also, improved algorithms of the ACL lookup
   9 could benefit of the more abstract representation, not coupled to the interfaces.
  10
  11 This describes a way to accommodate these use cases by generalizing the ACL
  12 lookups into "ACL lookup contexts", not tied to specific interfaces, usable
  13 by other portions of the code by utilizing the exports.h header file,
  14 which provides the necessary interface.
  15
  16
  17 Why "lookup contexts" and not "match me an ACL#" ?
  18 ================================================
  19
  20 The first reason is the logical grouping of multiple ACLs.
  21
  22 The interface matching code currently allows for matching multiple ACLs
  23 in a 'first-match' fashion. Some other use cases also fall into a similar
  24 pattern: they attempt to match a sequence of ACLs, and the first matched ACL
  25 determines what the outcome is, e.g. where to forward traffic. Thus,
  26 a match never happens on an ACL in isolation, but always on a group of
  27 ACLs.
  28
  29 The second reason is potential optimizations in matching.
  30
  31 A naive match on series of ACLs each represented as a vector of ACEs
  32 does not care about the API level - it could be "match one ACL", or
  33 "match the set of ACLs" - there will be just a simple loop iterating over
  34 the ACLs to match, returning the first match. Be it in the ACL code or
  35 in the user code.
  36
  37 However, for more involved lookup methods, providing a more high-level
  38 interface of matching over the entire group of ACLs allows for future
  39 improvements in the algorithms, delivered at once to all the users
  40 of the API.
  41
  42 What is a "lookup context" ?
  43 ============================
  44
  45 An ACL lookup context is an entity that groups the set of ACL#s
  46 together for the purposes of a first-match lookup, and may store
  47 additional internal information needed to optimize the lookups
  48 for that particular vector of ACLs.
  49
  50 Using ACL contexts in your code
  51 ===============================
  52
  53 In order to use the ACL lookup contexts, you need to include
  54 plugins/acl/exports.h into your code. This header includes
  55 all the necessary dependencies required.
  56
  57 As you probably will invoke this code from another plugin,
  58 the non-inline function calls are implemented via function pointers,
  59 which you need to initialize by calling acl_plugin_exports_init(&acl_plugin), which,
  60 if everything succeeds, returns 0 and fills in the acl_plugin structure
  61 with pointers to the exported methods - else it will return clib_error_t with
  62 more information about what went wrong.
  63
  64 When you have initialized the symbols, you also need to register yourself
  65 as a user of the ACL lookups - this allows to track the ACL lookup context
  66 ownership, as well as make the debug show outputs more user friendly.
  67
  68 To do that, call acl_plugin.register_user_module(caller_module_string, val1_label, val2_label) -
  69 and record the returned value. This will bethe first parameter that you pass to create a new
  70 lookup context. The passed strings must be static, and are used as descriptions for the ACL
  71 contexts themselves, as well as labels for up to two user-supplied u32 labels, used to
  72 differentiate the lookup contexts for the debugging purposes.
  73
  74 Creating a new context is done by calling acl_plugin.get_lookup_context_index(user_id, val1, val2).
  75 The first argument is your "user" ID obtained in a registration call earlier, the other two
  76 arguments are u32s with semantics that you designate. They are used purely for debugging purposes
  77 in the "show acl lookup context" command.
  78
  79 To set the vector of ACL numbers to be looked up within the context, use the function
  80 acl_plugin.set_acl_vec_for_context(lc_index, acl_list). The first parameter specifies the context
  81 that you have created, the second parameter is a vector of u32s, each u32 being the index of the ACL
  82 which we should be looking up within this context. The command is idempotent, i.e.
  83 it unapplies the previously applied list of ACLs, and then sets the new list of ACLs.
  84
  85 Subsequent ACL updates for the already applied ACLs will cause the re-application
  86 on an as-needed basis. Note, that the ACL application is potentially a relatively costly operation,
  87 so it is only expected that these changes will be done in the control plane, NOT in the datapath.
  88
  89 The matching within the context is done using two functions - acl_plugin.fill_5tuple() and
  90 acl_plugin.match_5tuple() and their corresponding inline versions, named acl_plugin_fill_5tuple_inline()
  91 and acl_plugin_match_5tuple_inline(). The inline and non-inline versions have the equivalent functionality,
  92 in that the non-inline version calls the inline version. These two variants are provided
  93 for debugging/maintenance reasons.
  94
  95 When you no longer need a particular context, you can return the allocated resources by calling
  96 acl_plugin.put_lookup_context_index() to mark it as free. The lookup structured associated with
  97 the vector of ACLs set for the lookup are cleaned up automatically. However, the ACLs themselves
  98 are not deleted and are available for subsequent reuse by other lookup contexts if needed.
  99
 100 There is one delicate detail that you might want to be aware of.
 101 When the non-inline functions reference the inline functions,
 102 they are compiled as part of ACL plugin; whereas when you refer to the inline
 103 functions from your code, they are compiled as part of your code.
 104 This makes referring to a single acl_main structure a little trickier.
 105
 106 It is done by having a static p_acl_main within the .h file,
 107 which points to acl_main of the ACL plugin, and is initialized by a static constructor
 108 function.
 109
 110 This way the multiple includes and inlines will "just work" as one would expect.
 111
 112
 113 Debug CLIs
 114 ==========
 115
 116 To see the state of the ACL lookup contexts, you can issue "show acl-plugin lookup user" to see
 117 all of the users which registered for the usage of the ACL plugin lookup contexts,
 118 and "show acl-plugin lookup context" to show the actual contexts created. You will notice
 119 that the latter command uses the values supplied during the module registration in order to
 120 make the output more friendly.
 121
 122 The "show acl-plugin acl" and "show acl-plugin interface" commands have also acquired the
 123 notion of lookup context, but there it is used from the client perspective, since
 124 with this change the interface ACL lookup itself is a user of ACL lookup contexts.
 125