sfatables/README

   1 sfatables is a tool for defining access and admission control policies
   2 in an SFA network, in much the same way as iptables is for ip
   3 networks. This file gives an overview of the tool and then describes
   4 its design and implementation.
   5
   6 Example command
   7 ---------------
   8
   9 An sfatables configuration consists of lists of rules that are applied
  10 to incoming and outgoing rspecs. Each rule consists of a 'match', to
  11 evaluate a given request against a certain set of criteria and a
  12 'target', to perform a corresponding action. Rules are manipulated by
  13 using the 'sfatables' command.
  14
  15 Consider the following example:
  16
  17 sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
  18
  19 The statement in this example has three parts: the command, the match
  20 and the target, separated by the token '--'.
  21
  22 * The command is '-A', which means 'Add rule.'
  23
  24 * The match is defined in the segment '-m hrn --user-hrn
  25   plc.princeton.' Here, '-m hrn' specifies the 'match type', and
  26   '--user-hrn' provides an argument specific to the match type.
  27
  28 * The target is defined by the segment '-j RESTRICT_TO_NODES
  29   --blacklist plc.princeton.' '-j RESTRICT_TO_NODES' defines the
  30   target type (RESTRICT_TO_NODES) and '--blacklist' defines a
  31   parameter specific to this type.
  32
  33 sfatables comes with a default set of matches and targets, which can
  34 be extended using a simple interface.
  35
  36 When you execute this command, you should see it in your current
  37 configuration by running 'sfatables -L INCOMING'
  38
  39 # ./sfatables -L INCOMING
  40
  41 # Rule  Match Arguments                Target            Arguments
  42 # 1     hrn   user-hrn=plc.princeton.* RESTRICT_TO_NODES blacklist=plc.mit
  43
  44 With this configuration, every time a request is received from
  45 plc.princeton.*, nodes matching the blacklist prefix (plc.mit) are
  46 dropped from the rspec.
  47
  48 The basis for deploying rules using sfatables is the library of
  49 matches and targets. A set of such rules constitutes a 'policy', which
  50 as we will see is a portable piece of information that can be
  51 exchanged with users, peers, and policy makers to make resource
  52 allocation and peering a more effective process.
  53
  54 XPath crash course -- read this now, or deal with frustration in the
  55 remainder of the document
  56 -----------------------------------------------------
  57
  58 XPath is used to select sets of nodes in an XML file. It is like the
  59 'SELECT' command in SQL, but has the advantage of applying to tree
  60 structures, which are more general than relations. That is, while a
  61 relation (a table) has a depth = 2, a tree can have an arbitrary
  62 depth. This property allows us to consicely refer to criteria such as 'the nodes in the
  63 site corresponding to a user named Alice.' This particular command
  64 might look like: '/user[name='Alice']/site/node.'
  65
  66 An XPath expression is like a directory path, with the following key
  67 differences.
  68
  69 * In a directory path the relationship between X/Y is a parent-child
  70   relationship. In XPath, this can be one of a large number of
  71   relationships, including 'sibling', 'parent', 'ancestor',
  72   'descendant' etc. The most frequently used relationships are:
  73
  74     child - e.g. site/node
  75
  76   and
  77
  78     descendant - e.g. user//node
  79
  80 * Each level can be filtered with a predicate; e.g.,
  81   'site[startswith(@hrn,'plc')]/nodes' means all nodes in sites that
  82   have the prefix 'plc'.
  83
  84 * Some terms have an '@' in them, meaning that they are attributes;
  85   e.g., to retrieve the value of p in the following data, we would use
  86   the expression "/x/y/@p"
  87
  88    <x>
  89    <y p="q"/>
  90    </x>
  91
  92 Example match
  93 -------------
  94
  95 A match specification consists of a 'context', a set of arguments, and
  96 a 'processor.' The context defines the information associated with a
  97 request that this match operates on. Think of it as the input
  98 parameters to the match. The arguments define values specific to the
  99 rule. The processor refers to the program that actually evaluates the
 100 match.
 101
 102 <match name="hrn">
 103     <context select="//sfa/current/user@hrn"/>
 104     <rule>
 105         <argument>
 106             <name>user-hrn</name>
 107             <help>HRN of the user requesting resouces</help>
 108             <operand>HRN</operand>
 109         </argument>
 110     </rule>
 111     <processor filename="hrn.xsl"/>
 112 </match>
 113
 114 Now, when we run the command in the previous example:
 115
 116 sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
 117
 118 ... this match specification is parameterized and dropped in the
 119 sfatables configuration directory. The paramterized version of the
 120 match is given below:
 121
 122 <match name="hrn">
 123     <!-- Empty context. We _always_ get the hrn of the current user -->
 124     <context select="//sfa/current/user@hrn"/>
 125     <rule>
 126         <argument>
 127             <name>user-hrn</name>
 128             <help>HRN of the user requesting resouces</help>
 129             <operand>HRN</operand>
 130         <value>plc.princeton</value>   <------------------
 131     </argument>
 132     </rule>
 133     <processor filename="hrn.xsl"/>
 134 </match>
 135
 136 Notice the additional 'value' tag. Let's list the entries in the
 137 configuration directory.
 138
 139 # ls -l /etc/sfatables/INCOMING
 140
 141 sapan@joyce ~/Projects/planetlab/sfa/sfatables/targets $
 142 total 16
 143 -rw-r--r-- 1 sapan sapan 671 Sep 11 12:13 sfatables-1-match
 144 -rw-r--r-- 1 sapan sapan 646 Sep 11 12:13 sfatables-1-target
 145
 146 As you can see, a configuration is simply a set of match-target pairs.
 147
 148 Finally, this is what the match processor looks like:
 149
 150 <?xml version="1.0" encoding="ISO-8859-1"?>
 151 <xsl:stylesheet version="1.0"
 152     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 153     <xsl:variable name="context-hrn" select="hrn"/>
 154     <xsl:template match="user">
 155                     <xsl:choose>
 156                     <xsl:when test="starts-with($context-hrn, hrn)">
 157                         True <!--Match -->
 158                     </xsl:when>
 159                     <xsl:otherwise>
 160                         False <!-- No match -->
 161                     </xsl:otherwise>
 162                 </xsl:choose>
 163         <xsl:value-of select="$result"/>
 164     </xsl:template>
 165
 166 </xsl:stylesheet>
 167
 168 It is written in XSLT. If the syntax of XSLT were not XML-based, then
 169 it might have looked as follows:
 170
 171 context-hrn = //sfa/user/hrn
 172 request-hrn = //request/user/hrn
 173
 174 result =
 175   if (starts_with(context-hrn,request-hrn)) then
 176     True
 177   else
 178     False
 179   return result
 180
 181 This is exactly what the previous fragment of code says, albeit in a
 182 different format.
 183
 184 Example target
 185 --------------
 186
 187 Targets are specified just like matches. If you haven't read the match
 188 example, then now is a good time to do that. Here's an example target:
 189
 190 <target name="RESTRICT_TO_NODES">
 191     <!-- The context is empty, since this target does not require any input from SFA -->
 192     <context select=""/>
 193     <rule>
 194         <argument>
 195             <name>whitelist</name>
 196             <help>Prefix of nodes to whitelist for this match.</help>
 197             <operand>PREFIX</operand>
 198         </argument>
 199         <argument>
 200             <name>blacklist</name>
 201             <help>Prefix of nodes to blacklist for this match.</help>
 202             <operand>PREFIX</operand>
 203         </argument>
 204     </rule>
 205     <processor filename="restrict_to_nodes.xsl"/>
 206 </target>
 207
 208 and the corresponding target processor:
 209
 210 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 211     <!-- Magic sauce copied from a manual. This fragment basically copies everything except for
 212     stuff that explicitly matches with the templates defined below. In the case of such a match,
 213     the matched node is treated differently.-->
 214     <xsl:template match="@* | node()">
 215         <xsl:copy>
 216             <xsl:apply-templates select="@* | node()"/>
 217         </xsl:copy>
 218     </xsl:template>
 219
 220     <xsl:variable name="whitelist_prefix" select="//rspec//rule/argument[name='whitelist']/value"/>
 221     <xsl:variable name="blacklist_prefix" select="//rspec//rule/argument[name='blacklist']/value"/>
 222
 223     <!-- Drop nodes that are not in the whitelist -->
 224     <xsl:template match="node">
 225             <xsl:choose>
 226                 <xsl:when test="starts-with(@name,$whitelist_prefix) and not($blacklist_prefix and starts-with(@name,$blacklist_prefix))">
 227                     <xsl:copy-of select="."/>
 228                 </xsl:when>
 229                 <xsl:otherwise/>
 230             </xsl:choose>
 231     </xsl:template>
 232
 233     <xsl:template match="sfatables-input"/>
 234 </xsl:stylesheet>
 235
 236 [TODO: explain this target]
 237
 238
 239 Contexts
 240 --------
 241
 242 Matches and targets are associated with specific contexts. A target may use a
 243 variety of criteria to process a request, and may need to look them up in the
 244 SFA database. The 'context' contains an xpath expression that isolates the
 245 items that a match or target may refer to. For example, if a match needs access
 246 to the nodes corresponding to a slice's site, then the context may be '/sfa/slice[@name=/context/slice/@name]/nodes'.
 247
 248
 249 Here's a summary of the model:
 250 -----------------------------
 251
 252 An AM can inherit from a set of elements (E).
 253
 254 Each element in E is associated with three things:
 255
 256     * A er... 'micro-rspec'
 257
 258     * an abstract database schema - S, which the AM is expected to be
 259       able to generate on the fly.
 260
 261     * a set of matches and targets.
 262
 263 Matches and targets may use pieces of information from S by specifying
 264 them in their context (see the 'context' part of matches and targets
 265 above).