-sfatables is a tool for defining access and admission control policies in an SFA network, in much the same way as iptables is for ip networks. This file gives an overview of the tool and then describes its design and implementation.
+sfatables is a tool for defining access and admission control policies
+in an SFA network, in much the same way as iptables is for ip
+networks. This file gives an overview of the tool and then describes
+its design and implementation.
-EXAMPLES
---------
+Example command
+---------------
+
+An sfatables configuration consists of lists of rules that are applied
+to incoming and outgoing rspecs. Each rule consists of a 'match', to
+evaluate a given request against a certain set of criteria and a
+'target', to perform a corresponding action. Rules are manipulated by
+using the 'sfatables' command.
+
+Consider the following example:
+
+sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
+
+The statement in this example has three parts: the command, the match
+and the target, separated by the token '--'.
+
+* The command is '-A', which means 'Add rule.'
+
+* The match is defined in the segment '-m hrn --user-hrn
+ plc.princeton.' Here, '-m hrn' specifies the 'match type', and
+ '--user-hrn' provides an argument specific to the match type.
+
+* The target is defined by the segment '-j RESTRICT_TO_NODES
+ --blacklist plc.princeton.' '-j RESTRICT_TO_NODES' defines the
+ target type (RESTRICT_TO_NODES) and '--blacklist' defines a
+ parameter specific to this type.
+
+sfatables comes with a default set of matches and targets, which can
+be extended using a simple interface.
+
+When you execute this command, you should see it in your current
+configuration by running 'sfatables -L INCOMING'
+
+# ./sfatables -L INCOMING
+
+# Rule Match Arguments Target Arguments
+# 1 hrn user-hrn=plc.princeton.* RESTRICT_TO_NODES blacklist=plc.mit
+
+With this configuration, every time a request is received from
+plc.princeton.*, nodes matching the blacklist prefix (plc.mit) are
+dropped from the rspec.
+
+The basis for deploying rules using sfatables is the library of
+matches and targets. A set of such rules constitutes a 'policy', which
+as we will see is a portable piece of information that can be
+exchanged with users, peers, and policy makers to make resource
+allocation and peering a more effective process.
+
+XPath crash course -- read this now, or deal with frustration in the
+remainder of the document
+-----------------------------------------------------
+
+XPath is used to select sets of nodes in an XML file. It is like the
+'SELECT' command in SQL, but has the advantage of applying to tree
+structures, which are more general than relations. That is, while a
+relation (a table) has a depth = 2, a tree can have an arbitrary
+depth. This property allows us to consicely refer to criteria such as 'the nodes in the
+site corresponding to a user named Alice.' This particular command
+might look like: '/user[name='Alice']/site/node.'
+
+An XPath expression is like a directory path, with the following key
+differences.
+
+* In a directory path the relationship between X/Y is a parent-child
+ relationship. In XPath, this can be one of a large number of
+ relationships, including 'sibling', 'parent', 'ancestor',
+ 'descendant' etc. The most frequently used relationships are:
+
+ child - e.g. site/node
+
+ and
+
+ descendant - e.g. user//node
-An sfatables configuration consists of lists of rules that are applied to incoming and outgoing rspecs. Each rule consists of a 'match spec' and a 'target spec.' A match spec evaluates a request and determines if it matches a given set of criteria, and the corresponding 'target spec' specifies the action in such a case.
+* Each level can be filtered with a predicate; e.g.,
+ 'site[startswith(@hrn,'plc')]/nodes' means all nodes in sites that
+ have the prefix 'plc'.
-Let's start by defining a few policies
+* Some terms have an '@' in them, meaning that they are attributes;
+ e.g., to retrieve the value of p in the following data, we would use
+ the expression "/x/y/@p"
-Examples:
+ <x>
+ <y p="q"/>
+ </x>
-Add rules:
+Example match
+-------------
-e.g.
-* sfatables -A INCOMING --requester-hrn ple.emaniacs.* -j ACCEPT
-* sfatables -A INCOMING --requester-hrn ple.* -j RESTRICT_NODES --include-only-nodegroup ple.emaniacs.pool_ple
+A match specification consists of a 'context', a set of arguments, and
+a 'processor.' The context defines the information associated with a
+request that this match operates on. Think of it as the input
+parameters to the match. The arguments define values specific to the
+rule. The processor refers to the program that actually evaluates the
+match.
-or
+<match name="hrn">
+ <context select="//sfa/current/user@hrn"/>
+ <rule>
+ <argument>
+ <name>user-hrn</name>
+ <help>HRN of the user requesting resouces</help>
+ <operand>HRN</operand>
+ </argument>
+ </rule>
+ <processor filename="hrn.xsl"/>
+</match>
-Default policy:
+Now, when we run the command in the previous example:
-* sfatables -P INCOMING REJECT
+sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
+... this match specification is parameterized and dropped in the
+sfatables configuration directory. The paramterized version of the
+match is given below:
-Overview:
+<match name="hrn">
+ <!-- Empty context. We _always_ get the hrn of the current user -->
+ <context select="//sfa/current/user@hrn"/>
+ <rule>
+ <argument>
+ <name>user-hrn</name>
+ <help>HRN of the user requesting resouces</help>
+ <operand>HRN</operand>
+ <value>plc.princeton</value> <------------------
+ </argument>
+ </rule>
+ <processor filename="hrn.xsl"/>
+</match>
-- The OUTGOING chain is for restricting access by hiding resources. Run as a filter on the output of get_resources. Good for resources to be marked 'unavailable.'
+Notice the additional 'value' tag. Let's list the entries in the
+configuration directory.
-- The INCOMING chain is for restricting access through denial. Run as a filter on the input to set_resources. Good for restricting access to resources.
+# ls -l /etc/sfatables/INCOMING
+
+sapan@joyce ~/Projects/planetlab/sfa/sfatables/targets $
+total 16
+-rw-r--r-- 1 sapan sapan 671 Sep 11 12:13 sfatables-1-match
+-rw-r--r-- 1 sapan sapan 646 Sep 11 12:13 sfatables-1-target
+
+As you can see, a configuration is simply a set of match-target pairs.
+
+Finally, this is what the match processor looks like:
+
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <xsl:variable name="context-hrn" select="hrn"/>
+ <xsl:template match="user">
+ <xsl:choose>
+ <xsl:when test="starts-with($context-hrn, hrn)">
+ True <!--Match -->
+ </xsl:when>
+ <xsl:otherwise>
+ False <!-- No match -->
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:value-of select="$result"/>
+ </xsl:template>
+
+</xsl:stylesheet>
+
+It is written in XSLT. If the syntax of XSLT were not XML-based, then
+it might have looked as follows:
+
+context-hrn = //sfa/user/hrn
+request-hrn = //request/user/hrn
+
+result =
+ if (starts_with(context-hrn,request-hrn)) then
+ True
+ else
+ False
+ return result
+
+This is exactly what the previous fragment of code says, albeit in a
+different format.
+
+Example target
+--------------
+
+Targets are specified just like matches. If you haven't read the match
+example, then now is a good time to do that. Here's an example target:
+
+<target name="RESTRICT_TO_NODES">
+ <!-- The context is empty, since this target does not require any input from SFA -->
+ <context select=""/>
+ <rule>
+ <argument>
+ <name>whitelist</name>
+ <help>Prefix of nodes to whitelist for this match.</help>
+ <operand>PREFIX</operand>
+ </argument>
+ <argument>
+ <name>blacklist</name>
+ <help>Prefix of nodes to blacklist for this match.</help>
+ <operand>PREFIX</operand>
+ </argument>
+ </rule>
+ <processor filename="restrict_to_nodes.xsl"/>
+</target>
+
+and the corresponding target processor:
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <!-- Magic sauce copied from a manual. This fragment basically copies everything except for
+ stuff that explicitly matches with the templates defined below. In the case of such a match,
+ the matched node is treated differently.-->
+ <xsl:template match="@* | node()">
+ <xsl:copy>
+ <xsl:apply-templates select="@* | node()"/>
+ </xsl:copy>
+ </xsl:template>
+
+ <xsl:variable name="whitelist_prefix" select="//rspec//rule/argument[name='whitelist']/value"/>
+ <xsl:variable name="blacklist_prefix" select="//rspec//rule/argument[name='blacklist']/value"/>
+
+ <!-- Drop nodes that are not in the whitelist -->
+ <xsl:template match="node">
+ <xsl:choose>
+ <xsl:when test="starts-with(@name,$whitelist_prefix) and not($blacklist_prefix and starts-with(@name,$blacklist_prefix))">
+ <xsl:copy-of select="."/>
+ </xsl:when>
+ <xsl:otherwise/>
+ </xsl:choose>
+ </xsl:template>
+
+ <xsl:template match="sfatables-input"/>
+</xsl:stylesheet>
+
+[TODO: explain this target]
+
+
+Contexts
+--------
-- A 'match' is a program that decides if a certain request matches a set of specified criteria (e.g. user.hrn==x or slice.site.slices > 20)
+Matches and targets are associated with specific contexts. A target may use a
+variety of criteria to process a request, and may need to look them up in the
+SFA database. The 'context' contains an xpath expression that isolates the
+items that a match or target may refer to. For example, if a match needs access
+to the nodes corresponding to a slice's site, then the context may be '/sfa/slice[@name=/context/slice/@name]/nodes'.
-- A 'target' is an action to perform as a result of a match (e.g. remove nodes plc.tp.* or restrict nodes to plc.some_nodegroup)
-Additionally, specifying rules in this chain and making the resulting policy available to users lets them optimize their allocation within the space of possibilities they have.
-E.g. if the policy is that your site is limited to < 1000 slivers (e.g. sfatables -A INCOMING --requester-hrn plc.* -j GLOBAL_LIMIT --site-sliver-limit 1000).
+Here's a summary of the model:
+-----------------------------
-- On startup, sfa loads the available set of matches and targets. In doing so, it remembers the input that these matches and targets need. E.g., a 'user hrn' match
-only requires the user's HRN. A site's slice count match may require the number of slices/site. The config file consists of a set of
+An AM can inherit from a set of elements (E).
-- When sfa needs to invoke sfatables, it passes a 'rule context' (i.e. the parameter to the sfatables command line) along with the input from the current context to the appropriate match. If it returns True, then it goes on to invoke target specified by the rule, and uses the filtered version of the rspec that it produces.
+Each element in E is associated with three things:
+ * A er... 'micro-rspec'
-Specifics:
+ * an abstract database schema - S, which the AM is expected to be
+ able to generate on the fly.
-- On startup sfa calls sfatables.load(), which loads available commands, matches and targets
+ * a set of matches and targets.
-- When invoking sfatables
+Matches and targets may use pieces of information from S by specifying
+them in their context (see the 'context' part of matches and targets
+above).
git://git.onelab.eu / sfa.git / blobdiff