resources/libraries/python/Classify.py

   1 # Copyright (c) 2016 Cisco and/or its affiliates.
   2 # Licensed under the Apache License, Version 2.0 (the "License");
   3 # you may not use this file except in compliance with the License.
   4 # You may obtain a copy of the License at:
   5 #
   6 #     http://www.apache.org/licenses/LICENSE-2.0
   7 #
   8 # Unless required by applicable law or agreed to in writing, software
   9 # distributed under the License is distributed on an "AS IS" BASIS,
  10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 # See the License for the specific language governing permissions and
  12 # limitations under the License.
  13
  14
  15 from robot.api import logger
  16
  17 from resources.libraries.python.VatExecutor import VatExecutor, VatTerminal
  18
  19
  20 class Classify(object):
  21     """Classify utilities."""
  22
  23     @staticmethod
  24     def vpp_creates_classify_table_l3(node, ip_version, direction):
  25         """Create classify table for IP address filtering.
  26
  27         :param node: VPP node to create classify table.
  28         :param ip_version: Version of IP protocol.
  29         :param direction: Direction of traffic - src/dst.
  30         :type node: dict
  31         :type ip_version: str
  32         :type direction: str
  33         :return (table_index, skip_n, match_n)
  34         table_index: Classify table index.
  35         skip_n: Number of skip vectors.
  36         match_n: Number of match vectors.
  37         :rtype: tuple(int, int, int)
  38         :raises RuntimeError: If VPP can't create table.
  39         """
  40         output = VatExecutor.cmd_from_template(node, "classify_add_table.vat",
  41                                                ip_version=ip_version,
  42                                                direction=direction)
  43
  44         if output[0]["retval"] == 0:
  45             table_index = output[0]["new_table_index"]
  46             skip_n = output[0]["skip_n_vectors"]
  47             match_n = output[0]["match_n_vectors"]
  48             logger.trace('Classify table with table_index {} created on node {}'
  49                          .format(table_index, node['host']))
  50         else:
  51             raise RuntimeError('Unable to create classify table on node {}'
  52                                .format(node['host']))
  53
  54         return table_index, skip_n, match_n
  55
  56     @staticmethod
  57     def vpp_creates_classify_table_l2(node, direction):
  58         """Create classify table for MAC address filtering.
  59
  60         :param node: VPP node to create classify table.
  61         :param direction: Direction of traffic - src/dst.
  62         :type node: dict
  63         :type direction: str
  64         :return (table_index, skip_n, match_n)
  65         table_index: Classify table index.
  66         skip_n: Number of skip vectors.
  67         match_n: Number of match vectors.
  68         :rtype: tuple(int, int, int)
  69         :raises RuntimeError: If VPP can't create table.
  70         """
  71         output = VatExecutor.cmd_from_template(node,
  72                                                "classify_add_table_l2.vat",
  73                                                direction=direction)
  74
  75         if output[0]["retval"] == 0:
  76             table_index = output[0]["new_table_index"]
  77             skip_n = output[0]["skip_n_vectors"]
  78             match_n = output[0]["match_n_vectors"]
  79             logger.trace('Classify table with table_index {} created on node {}'
  80                          .format(table_index, node['host']))
  81         else:
  82             raise RuntimeError('Unable to create classify table on node {}'
  83                                .format(node['host']))
  84
  85         return table_index, skip_n, match_n
  86
  87     @staticmethod
  88     def vpp_creates_classify_table_hex(node, hex_mask):
  89         """Create classify table with hex mask.
  90
  91         :param node: VPP node to create classify table based on hex mask.
  92         :param hex_mask: Classify hex mask.
  93         :type node: dict
  94         :type hex_mask: str
  95         :return (table_index, skip_n, match_n)
  96         table_index: Classify table index.
  97         skip_n: Number of skip vectors.
  98         match_n: Number of match vectors.
  99         :rtype: tuple(int, int, int)
 100         :raises RuntimeError: If VPP can't create table.
 101         """
 102         output = VatExecutor.cmd_from_template(node,
 103                                                "classify_add_table_hex.vat",
 104                                                hex_mask=hex_mask)
 105
 106         if output[0]["retval"] == 0:
 107             table_index = output[0]["new_table_index"]
 108             skip_n = output[0]["skip_n_vectors"]
 109             match_n = output[0]["match_n_vectors"]
 110             logger.trace('Classify table with table_index {} created on node {}'
 111                          .format(table_index, node['host']))
 112         else:
 113             raise RuntimeError('Unable to create classify table on node {}'
 114                                .format(node['host']))
 115
 116         return table_index, skip_n, match_n
 117
 118     @staticmethod
 119     def vpp_configures_classify_session_l3(node, acl_method, table_index, skip_n,
 120                                           match_n, ip_version, direction,
 121                                           address):
 122         """Configuration of classify session for IP address filtering.
 123
 124         :param node: VPP node to setup classify session.
 125         :param acl_method: ACL method - deny/permit.
 126         :param table_index: Classify table index.
 127         :param skip_n: Number of skip vectors based on mask.
 128         :param match_n: Number of match vectors based on mask.
 129         :param ip_version: Version of IP protocol.
 130         :param direction: Direction of traffic - src/dst.
 131         :param address: IPv4 or IPv6 address.
 132         :type node: dict
 133         :type acl_method: str
 134         :type table_index: int
 135         :type skip_n: int
 136         :type match_n: int
 137         :type ip_version: str
 138         :type direction: str
 139         :type address: str
 140         """
 141         with VatTerminal(node) as vat:
 142             vat.vat_terminal_exec_cmd_from_template("classify_add_session.vat",
 143                                                     acl_method=acl_method,
 144                                                     table_index=table_index,
 145                                                     skip_n=skip_n,
 146                                                     match_n=match_n,
 147                                                     ip_version=ip_version,
 148                                                     direction=direction,
 149                                                     address=address)
 150
 151     @staticmethod
 152     def vpp_configures_classify_session_l2(node, acl_method, table_index, skip_n,
 153                                           match_n, direction, address):
 154         """Configuration of classify session for MAC address filtering.
 155
 156         :param node: VPP node to setup classify session.
 157         :param acl_method: ACL method - deny/permit.
 158         :param table_index: Classify table index.
 159         :param skip_n: Number of skip vectors based on mask.
 160         :param match_n: Number of match vectors based on mask.
 161         :param direction: Direction of traffic - src/dst.
 162         :param address: IPv4 or IPv6 address.
 163         :type node: dict
 164         :type acl_method: str
 165         :type table_index: int
 166         :type skip_n: int
 167         :type match_n: int
 168         :type direction: str
 169         :type address: str
 170         """
 171         with VatTerminal(node) as vat:
 172             vat.vat_terminal_exec_cmd_from_template("classify_add_session_l2.vat",
 173                                                     acl_method=acl_method,
 174                                                     table_index=table_index,
 175                                                     skip_n=skip_n,
 176                                                     match_n=match_n,
 177                                                     direction=direction,
 178                                                     address=address)
 179
 180     @staticmethod
 181     def vpp_configures_classify_session_hex(node, acl_method, table_index,
 182                                            skip_n, match_n, hex_value):
 183         """Configuration of classify session with hex value.
 184
 185         :param node: VPP node to setup classify session.
 186         :param acl_method: ACL method - deny/permit.
 187         :param table_index: Classify table index.
 188         :param skip_n: Number of skip vectors based on mask.
 189         :param match_n: Number of match vectors based on mask.
 190         :param hex_value: Classify hex value.
 191         :type node: dict
 192         :type acl_method: str
 193         :type table_index: int
 194         :type skip_n: int
 195         :type match_n: int
 196         :type hex_value: str
 197         """
 198         with VatTerminal(node) as vat:
 199             vat.vat_terminal_exec_cmd_from_template(
 200                 "classify_add_session_hex.vat",
 201                 acl_method=acl_method,
 202                 table_index=table_index,
 203                 skip_n=skip_n,
 204                 match_n=match_n,
 205                 hex_value=hex_value)
 206
 207     @staticmethod
 208     def compute_classify_hex_mask(ip_version, protocol, direction):
 209         """Compute classify hex mask for TCP or UDP packet matching.
 210
 211         :param ip_version: Version of IP protocol.
 212         :param protocol: Type of protocol.
 213         :param direction: Traffic direction.
 214         :type ip_version: str
 215         :type protocol: str
 216         :type direction: str
 217         :return: Classify hex mask.
 218         :rtype : str
 219         :raises ValueError: If protocol is not TCP or UDP.
 220         :raises ValueError: If direction is not source or destination or
 221                             source + destination.
 222         """
 223         if protocol == 'TCP' or protocol == 'UDP':
 224             base_mask = Classify._compute_base_mask(ip_version)
 225
 226             if direction == 'source':
 227                 return base_mask + 'FFFF0000'
 228             elif direction == 'destination':
 229                 return base_mask + '0000FFFF'
 230             elif direction == 'source + destination':
 231                 return base_mask + 'FFFFFFFF'
 232             else:
 233                 raise ValueError("Invalid direction!")
 234         else:
 235             raise ValueError("Invalid protocol!")
 236
 237     @staticmethod
 238     def compute_classify_hex_value(hex_mask, source_port, destination_port):
 239         """Compute classify hex value for TCP or UDP packet matching.
 240
 241         :param hex_mask: Classify hex mask.
 242         :param source_port: Source TCP/UDP port.
 243         :param destination_port: Destination TCP/UDP port.
 244         :type hex_mask: str
 245         :type source_port: str
 246         :type destination_port: str
 247         :return: Classify hex value.
 248         :rtype: str
 249         """
 250         source_port_hex = Classify._port_convert(source_port)
 251         destination_port_hex = Classify._port_convert(destination_port)
 252
 253         return hex_mask[:-8] + source_port_hex + destination_port_hex
 254
 255     @staticmethod
 256     def _port_convert(port):
 257         """Convert port number for classify hex table format.
 258
 259         :param port: TCP/UDP port number.
 260         :type port: str
 261         :return: TCP/UDP port number in 4-digit hexadecimal format.
 262         :rtype: str
 263         """
 264         return '{0:04x}'.format(int(port))
 265
 266     @staticmethod
 267     def _compute_base_mask(ip_version):
 268         """Compute base classify hex mask based on IP version.
 269
 270         :param ip_version: Version of IP protocol.
 271         :type ip_version: str
 272         :return: Base hex mask.
 273         :rtype: str
 274         """
 275         if ip_version == 'ip4':
 276             return 68 * '0'
 277             # base value of classify hex table for IPv4 TCP/UDP ports
 278         elif ip_version == 'ip6':
 279             return 108 * '0'
 280             # base value of classify hex table for IPv6 TCP/UDP ports
 281         else:
 282             raise ValueError("Invalid IP version!")
 283
 284     @staticmethod
 285     def get_classify_table_data(node, table_index):
 286         """Retrieve settings for classify table by ID.
 287
 288         :param node: VPP node to retrieve classify data from.
 289         :param table_index: Index of a specific classify table.
 290         :type node: dict
 291         :type table_index: int
 292         :return: Classify table settings.
 293         :rtype: dict
 294         """
 295         with VatTerminal(node) as vat:
 296             data = vat.vat_terminal_exec_cmd_from_template(
 297                 "classify_table_info.vat",
 298                 table_id=table_index
 299             )
 300         return data[0]
 301
 302     @staticmethod
 303     def get_classify_session_data(node, table_index, session_index=None):
 304         """Retrieve settings for all classify sessions in a table,
 305         or for a specific classify session.
 306
 307         :param node: VPP node to retrieve classify data from.
 308         :param table_index: Index of a classify table.
 309         :param session_index: Index of a specific classify session. (Optional)
 310         :type node: dict
 311         :type table_index: int
 312         :type session_index: int
 313         :return: List of classify session settings, or a dictionary of settings
 314          for a specific classify session.
 315         :rtype: list or dict
 316         """
 317         with VatTerminal(node) as vat:
 318             data = vat.vat_terminal_exec_cmd_from_template(
 319                 "classify_session_dump.vat",
 320                 table_id=table_index
 321             )
 322         if session_index is not None:
 323             return data[0][session_index]
 324         else:
 325             return data[0]