src/plugins/acl/acl_lookup_context.rst

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