8021Q

abstract

This page describes 802.1Q VLAN management feature in RackTables, which has been added in 0.18.0 release.

RackTables server setup

RackTables has a special component named "deviceconfig" to deliver configuration from and to managed switches. This component is a set of executable scripts located in gateways/deviceconfig directory (which is probably located in the main RackTables directory). Description below is accurate for RackTables 0.18.x, but was changed in future versions.

In deviceconfig directory one can see a sample file named switch.secrets.php-sample. The real file, which will be used by the system, is switch.secrets.php, and the simplest way to have it created properly is to copy it from the sample file. Before you proceed and put real configuration into that file, please understand the following!

1. This component uses telnet protocol to communicate to managed switches. It is your responsibility to setup your network so, that the passwords cannot be easily intercepted on the way, and that the RackTables server is only allowed to telnet to devices of your own.
2. RackTables, like most software, can fail during operation. Consequences of that may be serious technical, financial and other losses. Redundancy and backups are also your responsibility.
3. Please make sure, that the server, where you install RackTables, is setup appropriately to store sensitive data. If the password file is leaked, that is a major problem regardless of any software.

The switch.secrets.php file has the following format:

Any text (this is by default a piece of PHP code,
which hides contents of the whole file, when the file is
accessed with HTTP).

Marker below enables password scanning and must be left intact.
# S-T-A-R-T
<hostname pattern> telnet - - <user_name|-> <user_password|-> <super_password|->
<hostname pattern> telnet - - <user_name|-> <user_password|-> <super_password|->
<hostname pattern> telnet - - <user_name|-> <user_password|-> <super_password|->
<hostname pattern> telnet - - <user_name|-> <user_password|-> <super_password|->
# S-T-O-P
Marker above disables password scanning and must be left intact.

Any text (again, a piece of PHP code).

Column 1 is a hostname pattern, which is matched against "management address" of a given switch, which is:

• FQDN attribute of the switch, if it is set (the recommended practice is to have "FQDN" set for each managed switch)
• otherwise it is IP address of the switch, if it has one and only one IP address allocated (on "IPv4" tab of object page)
• otherwise it is the "common name" of the switch, if its common name is a valid hostname

Again, this "management address" is matched against the pattern. This pattern is a so called "shell pattern", which can use expressions "*", "?" and "[...]" (like those in filename patterns in UNIX shell). It is important to have patterns matching only devices, which one really intends to log into. Without this measure (when one uses "*" as hostname pattern) RackTables would always use a real password for any device. This way the real password would be compromised as soon, as an object in the database resolves into IP address outside your network. This way, to match every hostname in "example.com" domain, one can write "*.example.com" or "switch*.example.com".

Columns 2-4 (telnet minus minus) don't do anything, they are there solely for compatibility reasons and are likely to be discarded in future.

Columns 5 and 6 are respectively the username and the password strings, which the device expects to receive. If the device expects no username/password, respective column must be set to "-" (minus). Depending on the configuration device may be expecting: username with password, username without password, password without username, and neither username nor password. All these cases can be configured here.

Column 7 is the master (enable, super) password, which some systems require for "administrator" access level. When this password is supplied, it is used along with appropriate (depending on switch software) command to proceed to that access level. When the master password is not set ("-"), it is one's responsibility to configure the switch in a way, which allows the specified account to make configuration changes.

RackTables objects setup

802.1Q code needs to know if an object is a managed Ethernet switch (a switch that RackTables can manage, to be precise). This is decided based on certain records about an object (the object must belong to "network switch" type):

• "IOS 12.0", "IOS 12.1" or "IOS 12.2" SW type
• "NX-OS 4.0" or "NX-OS 4.1" SW type
• "Extreme XOS 12" SW type
• "Huawei VRP 5.30" SW type (since 0.18.4)
• "Huawei VRP 5.50" SW type (since 0.18.4)
• "IronWare 5" SW type (since 0.18.4)
• "Foundry FastIron GS xxx" HW type (not used since 0.18.4)
• "Huawei Quidway S53xx" HW type (not used since 0.18.4)

For most hardware that is supported by 802.1Q feature "SW type" is set automatically during "SNMP sync" execution round.

side effects

A configured "deviceconfig" gateway will also enable "Live CDP" and "Live LLDP" features.

vendor-specific switch setup

• Cisco IOS
  • Every port that is intended to perform switching must have "switchport mode" and "switchport trunk encapsulation" explicitly set in its "interface" section.
  • VTP mode must be set to "transparent".
  • 12.2(SXH) version has a broken telnet server
• Extreme Networks XOS 12
  • telnet operations are very slow
  • Every VLAN besides "Default" and "Mgmt" (that is, any VLAN created by the user) must be named "VLANx", where x is VLAN tag ID. For example, "VLAN2", "VLAN123", "VLAN4000".
• Huawei S2300/S3300/S5300 VRP 5.30
  • Software patch V100R003SPH006 must be applied.
  • The device must have output paging disabled:

user-interface vty 0 4
 screen-length 0

• Huawei S9300 VRP 5.50
  • Software patch V100R002SPH009 must be applied.
  • All device ports must have "link-type" set to either "access" or "trunk" (default setting is "hybrid")
  • The device must have output paging disabled:

user-interface vty 0 4
 screen-length 0

known bugs and limitations

• port naming is fixed and cannot be changed
• importing configuration for a port that has VLANs 1~4094 allowed, is very slow
• for uplink-downlink reverb feature to work, both ports must have correct markup, have respective records on the Ports tab, and these records must be linked
• there is no support for configuration templates like those in LiveVLANs
• VLAN1 cannot be used on uplink or downlink ports
• VLAN domains require a special setup procedure to work properly
• unbinding of 802.1Q order hides existing 802.1Q ports config and blocks deletion of the object
• not all hardware supports trunk ports w/o allowed VLANs, and this is not handled by RackTables
• ExtemeOS requires a special VLAN naming scheme
• VRP's "hybrid untagged VLANs" (which are not to be confused with "native" VLAN) break normal management until they are "undone"
• Brocade FCX switch does not return member ports of VLAN1

VLAN switch templates

A VLAN switch template, or VST, is one of the principal structures of RackTables 802.1Q feature. The purpose of VST is to decide, what configuration which port of a VLAN switch can have. VST consists of an ordered list of rules, each rule consisting of the following fields:

Sequence

An integer number defining the order of a rule on the list. Each rule must have a sequence number unique within the VST.

Regexp

A PCRE regular expression (see the comment after this list).

Role

Either "none", which means, that the port cannot switch any VLANs and cannot have 802.1Q configuration, or one of the roles below:

• user: access only -- switches 1 VLAN in access mode, configuration can be changed by a user
• user: trunk only --- switches 0 or more VLANs (with 0 or 1 of VLANs being native) in trunk mode, configuration can be changed by a user
• user: anymode -- switches VLANs in any of the two modes above
• system: uplink trunk -- switches any number of tagged VLANs and its configuration is built automatically as a superset of all VLANs of all ports of the current switch
• system: downlink trunk -- switches any number of tagged VLANs and reflects the configuration of an "uplink" port, when is linked with one

VLAN IDs

A comma-delimited list of permitted VLANs or VLAN ranges (that is, two VLANs delimited with dash), for example: 10-20, 30, 40-50, 60. Regardless of the port mode (user or system) its configuration will never include the VLANs, which are not present on the configured list. A default empty value stands for "1-4094".

Comment

An optional text describing this rule. It does not affect processing in any way.

---

For a given VLAN switch a VST is executed as many times as there are ports in its configuration. Within each port VST rules are evaluated in the order of the sequence numbers. When short (e.g. gi0/20 or e1/2/3) port name matches the PCRE, the port is assigned the specified role and VLAN ID filter. A port, which had no matching rules, is assigned to "none" role.

PCRE is the currently recommended regular expressions engine of PHP, its full description is available here, but the features most likely to be used in a VST are:

• ^ (start of string)
• $ (end of string)
• [] (character class)
• () (subpattern)
• . (any symbol)

For example, matching a single interface is done with a PCRE like this: #^fa0/1$#. Note the delimiters around the PCRE (##) and the start/end metasymbols. The end anchor ($) makes sense in most VST rules to distinguish 1 from 10, 11, 12, 13, 14, 120 and any other number starting with the same digit (same applies for 2, 3 etc). The need for the start anchor (^) depends on the naming pattern of the remote software. With all interfaces named like e0/1/20 the purpose of the start anchor boils down to keeping the PCREs consistent. However, some software (such as XOS) does not prefix interface names with anything and ports are named 1, 2, 3, 4 and so on. In this case /1$/ and /^1$/ will produce differerent results.

There are multiple ways of matching several ports in one rule, for example:

• #^gi0/[1-8]$# matches 8 ports of the same slot
• #^gi1/[13579]$# matches 5 ports of the same slot
• #^gi2/(12|23|34|45)$# matches 4 ports of the same slot
• #^gi[0-9]/1$# matches first ports of all slots

adding and removing 802.1Q ports offline

802.1Q ports are normally created and deleted on "802.1Q sync" tab during a live session with the remote switch. Static editor can also create and delete 802.1Q ports, but offline. Before you proceed with the manual editing, note that the existing automatic procedure creates new 802.1Q ports much faster and very accurately.

To turn the manual editor on, change the "8021Q_EXTSYNC_LISTSRC" config option to RackCode matching the objects that should have it on. For example, if you had such switches tagged with "manual 802.1Q", the RackCode would be:

{manual 802.1Q}

Make sure the switch of interest has a 802.1Q template associated because "802.1Q sync" tab is only visible for an object with a 802.1Q template.