Lookup contexts aka "ACL as a service" {#acl_lookup_context}
======================================

The initial implementation of the ACL plugin had tightly tied the policy (L3-L4) ACLs
to ingress/egress processing on an interface.

However, some uses outside of pure traffic control have appeared, for example,
ACL-based forwarding, etc. Also, improved algorithms of the ACL lookup
could benefit of the more abstract representation, not coupled to the interfaces.

This describes a way to accommodate these use cases by generalizing the ACL
lookups into "ACL lookup contexts", not tied to specific interfaces, usable
by other portions of the code by utilizing the exports.h header file,
which provides the necessary interface.


Why "lookup contexts" and not "match me an ACL#" ?
================================================

The first reason is the logical grouping of multiple ACLs.

The interface matching code currently allows for matching multiple ACLs
in a 'first-match' fashion. Some other use cases also fall into a similar
pattern: they attempt to match a sequence of ACLs, and the first matched ACL
determines what the outcome is, e.g. where to forward traffic. Thus,
a match never happens on an ACL in isolation, but always on a group of
ACLs.

The second reason is potential optimizations in matching.

A naive match on series of ACLs each represented as a vector of ACEs
does not care about the API level - it could be "match one ACL", or
"match the set of ACLs" - there will be just a simple loop iterating over
the ACLs to match, returning the first match. Be it in the ACL code or
in the user code.

However, for more involved lookup methods, providing a more high-level
interface of matching over the entire group of ACLs allows for future
improvements in the algorithms, delivered at once to all the users
of the API.

What is a "lookup context" ?
============================

An ACL lookup context is an entity that groups the set of ACL#s
together for the purposes of a first-match lookup, and may store
additional internal information needed to optimize the lookups
for that particular vector of ACLs.

Using ACL contexts in your code
===============================

In order to use the ACL lookup contexts, you need to include
plugins/acl/exports.h into your code. This header includes
all the necessary dependencies required.

As you probably will invoke this code from another plugin,
the non-inline function calls are implemented via function pointers,
which you need to initialize by calling acl_plugin_exports_init(&acl_plugin), which,
if everything succeeds, returns 0 and fills in the acl_plugin structure
with pointers to the exported methods - else it will return clib_error_t with
more information about what went wrong.

When you have initialized the symbols, you also need to register yourself
as a user of the ACL lookups - this allows to track the ACL lookup context
ownership, as well as make the debug show outputs more user friendly.

To do that, call acl_plugin.register_user_module(caller_module_string, val1_label, val2_label) -
and record the returned value. This will bethe first parameter that you pass to create a new
lookup context. The passed strings must be static, and are used as descriptions for the ACL
contexts themselves, as well as labels for up to two user-supplied u32 labels, used to
differentiate the lookup contexts for the debugging purposes.

Creating a new context is done by calling acl_plugin.get_lookup_context_index(user_id, val1, val2).
The first argument is your "user" ID obtained in a registration call earlier, the other two
arguments are u32s with semantics that you designate. They are used purely for debugging purposes
in the "show acl lookup context" command.

To set the vector of ACL numbers to be looked up within the context, use the function
acl_plugin.set_acl_vec_for_context(lc_index, acl_list). The first parameter specifies the context
that you have created, the second parameter is a vector of u32s, each u32 being the index of the ACL
which we should be looking up within this context. The command is idempotent, i.e.
it unapplies the previously applied list of ACLs, and then sets the new list of ACLs.

Subsequent ACL updates for the already applied ACLs will cause the re-application
on an as-needed basis. Note, that the ACL application is potentially a relatively costly operation,
so it is only expected that these changes will be done in the control plane, NOT in the datapath.

The matching within the context is done using two functions - acl_plugin.fill_5tuple() and
acl_plugin.match_5tuple() and their corresponding inline versions, named acl_plugin_fill_5tuple_inline()
and acl_plugin_match_5tuple_inline(). The inline and non-inline versions have the equivalent functionality,
in that the non-inline version calls the inline version. These two variants are provided
for debugging/maintenance reasons.

When you no longer need a particular context, you can return the allocated resources by calling
acl_plugin.put_lookup_context_index() to mark it as free. The lookup structured associated with
the vector of ACLs set for the lookup are cleaned up automatically. However, the ACLs themselves
are not deleted and are available for subsequent reuse by other lookup contexts
#!/bin/bash
# Copyright (c) 2016 Cisco and/or its affiliates.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a ght (c) 2016 Cisco and/or its affiliates.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not usecopy of the License at:
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -x

RETURN_STATUS=0

cat /etc/hostname
cat /etc/hosts

PYBOT_ARGS="--noncritical MULTI_THREAD"

ARCHIVE_ARTIFACTS=(log.html output.xml report.html)

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
export PYTHONPATH=${SCRIPT_DIR}

if [ -f "/etc/redhat-release" ]; then
    DISTRO="CENTOS"
    sudo yum install -y python-devel python-virtualenv
else
    DISTRO="UBUNTU"
    export DEBIAN_FRONTEND=noninteractive
    sudo apt-get -y update
    sudo apt-get -y install libpython2.7-dev python-virtualenv
fi

# 1st step: Download and prepare VPP packages

# Temporarily download VPP packages from nexus.fd.io
if [ "${#}" -ne "0" ]; then
    arr=(${@})
    echo ${arr[0]}
else
    case "$DISTRO" in
        CENTOS )
            PACKAGE=rpm
            ;;
        UBUNTU )
            PACKAGE=deb
    esac
    # Download the latest VPP build install packages
    rm -f *.${PACKAGE}
    echo Downloading VPP packages...
    bash ${SCRIPT_DIR}/resources/tools/download_install_vpp_pkgs.sh --skip-install
fi

# Take vpp package and get the vpp version
VPP_PKGS=(*.$PACKAGE)
case "$DISTRO" in
        CENTOS )
            VPP_VER="$( expr match $(ls *.rpm | head -n 1) 'vpp-\(.*\).rpm' )"
            ;;
        UBUNTU )
            VPP_VER="$( expr match $(ls *.deb | head -n 1) 'vpp-\(.*\)-deb.deb' )"
esac

echo ${VPP_PKGS[@]}

set +x
echo "****************************************************************************************************************************************"
echo "1st step: Download VPP packages                                                                                                 FINISHED"
echo "VPP version to be tested: ${VPP_VER}"
echo "****************************************************************************************************************************************"
set -x


# 2nd step: Start virtual env and install requirements

echo Starting virtual env...
virtualenv --system-site-packages env
. env/bin/activate

echo Installing requirements...
pip install -r ${SCRIPT_DIR}/requirements.txt

set +x
echo "****************************************************************************************************************************************"
echo "2nd step: Start virtual env and install requirements                                                                            FINISHED"
echo "****************************************************************************************************************************************"
set -x


# 3rd step: Prepare VIRL system
echo Preparing VIRL system...

VIRL_SERVERS=("10.30.51.28" "10.30.51.29" "10.30.51.30")
VIRL_SERVER=""

VIRL_USERNAME=jenkins-in
VIRL_PKEY=priv_key
VIRL_SERVER_STATUS_FILE="status"
VIRL_SERVER_EXPECTED_STATUS="PRODUCTION"

case "$DISTRO" in
        CENTOS )
            VIRL_TOPOLOGY=$(cat ${SCRIPT_DIR}/VIRL_TOPOLOGY_CENTOS)
            VIRL_RELEASE=$(cat ${SCRIPT_DIR}/VIRL_RELEASE_CENTOS)
            ;;
        UBUNTU )
            VIRL_TOPOLOGY=$(cat ${SCRIPT_DIR}/VIRL_TOPOLOGY_UBUNTU)
            VIRL_RELEASE=$(cat ${SCRIPT_DIR}/VIRL_RELEASE_UBUNTU)
esac

SSH_OPTIONS="-i ${VIRL_PKEY} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o BatchMode=yes -o LogLevel=error"

function ssh_do() {
    echo
    echo "### "  ssh $@
    ssh ${SSH_OPTIONS} $@
}

rm -f ${VIRL_PKEY}
cat > ${VIRL_PKEY} <<EOF
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA+IHXq87GcqMR1C47rzx6Cbip5Ghq8pKrbqKrP5Nf41HcYrT6
GOXl9nFWKsMOzIlIn+8y7Il27eZh7csQGApbg8QLiHMtcYEmWNzKZpkqg4nuAPxX
VXwlKgnKX902SrET9Gp9TDayiHtCRWVfrlPPPSA0UEXW6BjLN/uHJ+W/Xzrrab+9
asBVa05vT2W6n0KJ66zfCaeDM912mQ6SttscAwFoWDmdHlegiVqrlIG2ABxOvxxz
L3dM3iSmlmQlzv9bThjo+nI4KFYh6m5wrZmAo5r/4q9CIJc21HVnTqkGOWJIZz6J
73lePJVSq5gYqaoGw3swFEA/MDkOx7baWKSoLQIDAQABAoIBAQCNBeolNp+JWJ76
gQ4fwLsknyXSV6sxYyhkDW4PEwwcTU06uqce0AAzXVffxne0fMe48x47+zqBgPbb
4huM+Pu8B9nfojUMr5TaYtl9Zbgpk3F8H7dT7LKOa6XrxvZTZrADSRc30+Z26zPN
e9zTaf42Gvt0/l0Zs1BHwbaOXqO+XuwJ3/F9Sf3PQYWXD3EOWjpHDP/X/1vAs6lV
SLkm6J/9KKE1m6I6LTYjIXuYt4SXybW6N2TSy54hhQtYcDUnIU2hR/PHVWKrGA0J
kELgrtTNTdbML27O5gFWU4PLUEYTZ9fN11D6qUZKxLcPOiPPHXkiILMRCCnG5DYI
ksBAU/YlAoGBAPxZO9VO18TYc8THV1nLKcvT2+1oSs1UcA2wNQMU55t910ZYinRa
MRwUhMOf8Mv5wOeiZaRICQB1PnVWtDVmGECgPpK6jUxqAwn8rgJcnoafLGL5YKMY
RVafTe6N5LXgCaOcJrk21wxs6v7ninEbUxxc575urOvZMBkymDw91dwbAoGBAPwa
YRhKhrzFKZzdK0RadVjnxKvolUllpoqqg3XuvmeAJHAOAnaOgVWq68NAcp5FZJv0
2D2Up7TX8pjf9MofP1SJbcraKBpK4NzfNkA0dSdEi+FhVofAJ9umB2o5LW1n7sab
UIrjsdzSJK/9Zb9yTTHPyibYzNEgaJV1HsbxfEFXAoGAYO2RmvRm0phll18OQVJV
IpKk9kLKAKZ/R/K32hAsikBC8SVPQTPniyaifFWx81diblalff2hX4ipTf7Yx24I
wMIMZuW7Im/R7QMef4+94G3Bad7p7JuE/qnAEHJ2OBnu+eYfxaK35XDsrq6XMazS
NqHE7hOq3giVfgg+C12hCKMCgYEAtu9dbYcG5owbehxzfRI2/OCRsjz/t1bv1seM
xVMND4XI6xb/apBWAZgZpIFrqrWoIBM3ptfsKipZe91ngBPUnL9s0Dolx452RVAj
yctHB8uRxWYgqDkjsxtzXf1HnZBBkBS8CUzYj+hdfuddoeKLaY3invXLCiV+PpXS
U4KAK9kCgYEAtSv0m5+Fg74BbAiFB6kCh11FYkW94YI6B/E2D/uVTD5dJhyEUFgZ
cWsudXjMki8734WSpMBqBp/J8wG3C9ZS6IpQD+U7UXA+roB7Qr+j4TqtWfM+87Rh
maOpG56uAyR0w5Z9BhwzA3VakibVk9KwDgZ29WtKFzuATLFnOtCS46E=
-----END RSA PRIVATE KEY-----
EOF
chmod 600 ${VIRL_PKEY}

#
# Pick a random host from the array of VIRL servers, and attempt
# to reach it and verify it's status.
#
# The server must be reachable, and have a "status" file with
# the content "PRODUCTION", to be selected.
#
# If the server is not reachable, or does not have the correct
# status, remove it from the array and start again.
#
# Abort if there are no more servers left in the array.
#
while [[ ! "$VIRL_SERVER" ]]
do
    num_hosts=${#VIRL_SERVERS[@]}
    if [ $num_hosts == 0 ]
    then
        echo "No more VIRL candidate hosts available, failing."
        exit 127
    fi
    element=$[ $RANDOM % $num_hosts ]
    virl_server_candidate=${VIRL_SERVERS[$element]}
    virl_server_status=$(ssh ${SSH_OPTIONS} ${VIRL_USERNAME}@${virl_server_candidate} cat $VIRL_SERVER_STATUS_FILE 2>&1)
    echo VIRL HOST $virl_server_candidate status is \"$virl_server_status\"
    if [ "$virl_server_status" == "$VIRL_SERVER_EXPECTED_STATUS" ]
    then
        # Candidate is in good status. Select this server.
        VIRL_SERVER="$virl_server_candidate"
    else
        # Candidate is in bad status. Remove from array.
        VIRL_SERVERS=("${VIRL_SERVERS[@]:0:$element}" "${VIRL_SERVERS[@]:$[$element+1]}")
    fi
done


VIRL_DIR_LOC="/tmp"
VPP_PKGS_VIRL=(${VPP_PKGS[@]})

# Prepend directory location at remote host to deb file list
for index in "${!VPP_PKGS_VIRL[@]}"; do
    VPP_PKGS_VIRL[${index}]=${VIRL_DIR_LOC}/${VPP_PKGS_VIRL[${index}]}
done

echo "Updated file names: " ${VPP_PKGS_VIRL[@]}

cat ${VIRL_PKEY}
# Copy the files to VIRL host
scp ${SSH_OPTIONS} *.${PACKAGE} \
    ${VIRL_USERNAME}@${VIRL_SERVER}:${VIRL_DIR_LOC}/

result=$?
if [ "${result}" -ne "0" ]; then
    echo "Failed to copy vpp deb files to virl host"
    echo ${result}
    exit ${result}
fi

# Start a simulation on VIRL server
echo "Starting simulation on VIRL server"

function stop_virl_simulation {
    ssh ${SSH_OPTIONS} ${VIRL_USERNAME}@${VIRL_SERVER}\
        "stop-testcase ${VIRL_SID}"
}

VIRL_SID=$(ssh ${SSH_OPTIONS} \
    ${VIRL_USERNAME}@${VIRL_SERVER} \
    "start-testcase -c ${VIRL_TOPOLOGY} -r ${VIRL_RELEASE} ${VPP_PKGS_VIRL[@]}")
retval=$?
if [ ${retval} -ne "0" ]; then
    echo "VIRL simulation start failed"
    exit ${retval}
fi

if [[ ! "${VIRL_SID}" =~ session-[a-zA-Z0-9_]{6} ]]; then
    echo "No VIRL session ID reported."
    exit 127
fi

# Upon script exit, cleanup the VIRL simulation execution
trap stop_virl_simulation EXIT
echo ${VIRL_SID}

ssh_do ${VIRL_USERNAME}@${VIRL_SERVER} cat /scratch/${VIRL_SID}/topology.yaml

# Download the topology file from VIRL session
scp ${SSH_OPTIONS} \
    ${VIRL_USERNAME}@${VIRL_SERVER}:/scratch/${VIRL_SID}/topology.yaml \
    topologies/enabled/topology_VIRL.yaml

retval=$?
if [ ${retval} -ne "0" ]; then
    echo "Failed to copy topology file from VIRL simulation"
    exit ${retval}
fi

set +x
echo "****************************************************************************************************************************************"
echo "3rd step: Start the simulation on the VIRL server                                                                               FINISHED"
echo "****************************************************************************************************************************************"
set -x


# 4th step: Run functional test suites

RC=0
MORE_FAILS=0

echo Running functional tests on the VIRL system...

# There are used three iterations of functional tests there
# to check the stability and reliability of the results.
for test_set in 1 2 3
do
    echo
    echo Functional test loop: ${test_set}
    echo

    pybot -L TRACE -W 136\
        -v TOPOLOGY_PATH:${SCRIPT_DIR}/topologies/enabled/topology_VIRL.yaml \
        --suite "tests.func" \
        --include vm_envAND3_node_single_link_topo \
        --include vm_envAND3_node_double_link_topo \
        --exclude PERFTEST \
        --noncritical EXPECTED_FAILING \
        --output log_func_test_set${test_set} \
        tests/
    PARTIAL_RC=$(echo $?)
    if [ ${PARTIAL_RC} -eq 250 ]; then
        MORE_FAILS=1
    fi
    RC=$((RC+PARTIAL_RC))
done

set +x
echo "****************************************************************************************************************************************"
echo "4th step: Run functional tests                                                                                                  FINISHED"
echo "****************************************************************************************************************************************"
set -x

# Set RETURN_STATUS=1 if some critical test failed
if [ ! ${RC} -eq 0 ]; then
        RETURN_STATUS=1
fi

# Log the final result
if [ ${RC} -eq 0 ]; then
    set +x
    echo
    echo "========================================================================================================================================"
    echo "Final result of all test loops:                                                                                                 | PASS |"
    echo "All critical tests have passed."
    echo "========================================================================================================================================"
    echo
    set -x
elif [ ${MORE_FAILS} -eq 0 ]; then
    if [ ${RC} -eq 1 ]; then
        HLP_STR="test has"
    else
        HLP_STR="tests have"
    fi
    set +x
    echo
    echo "========================================================================================================================================"
    echo "Final result of all test loops:                                                                                                 | FAIL |"
    echo "${RC} critical ${HLP_STR} failed."
    echo "========================================================================================================================================"
    echo
    set -x
else
    set +x
    echo
    echo "========================================================================================================================================"
    echo "Final result of all test loops:                                                                                                 | FAIL |"
    echo "More then 250 critical tests have failed in one test loop."
    echo "========================================================================================================================================"
    echo
    set -x
fi

# 7th step: Post-processing test data
echo Post-processing test data...

# Rebot output post-processing
rebot --noncritical EXPECTED_FAILING \
      --output output.xml \
      ./log_func_test_set1.xml ./log_func_test_set2.xml ./log_func_test_set3.xml

# Remove unnecessary files
rm -f ./log_test_set1.xml ./log_test_set2.xml ./log_test_set3.xml

# Archive artifacts
mkdir archive
for i in ${ARCHIVE_ARTIFACTS[@]}; do
    cp $( readlink -f ${i} | tr '\n' ' ' ) archive/
done

echo Post-processing finished.

exit ${RETURN_STATUS}