README.port-numbering - lava/vland.git - Linaro Git Browser

 Port numbering and naming in VLANd
 ==================================

 This is a far more complex subject than it should be, and it may cause
 problems for end users depending on their usage models. This is
 particularly likely for those users with Cisco Catalyst 3750 switches
 configured with extra internal modules for extra copper/fibre ports.

 Terminology
 ===========

 For consistency, throughout this document and within VLANd two terms
 are used to identify switch ports:

  * a PORT NAME is the (typically) alphanumeric identifier for a switch
    port *in software*, i.e. when using the CLI to manage a
    switch. Common naming styles vary significantly here; examples from
    the VLANd test rack in Linaro's lab include "Gi1/0/6", "Gi1/1/4",
    "Te1/1/2", "fa24", "gi3", "1/0/23"

  * a PORT NUMBER is the (typically) numeric identifier for a switch
    port that is labelled visibly on the switch somewhere, typically
    next to the port or a group of ports. Not all switches limit
    themselves to numeric labels, though. The same examples from our
    test rack are described as "6", "G4/Te2", "24", "G3", "23G", "23T"

 These example include some of the problems - try and match tnem up!

 The problem
 ===========

 On all of the switch models that we currently support, there is a
 disconnect between the port names and the associated port numbers. The
 port names are not directly shown to the user on any of our switches,
 which is not a good start.

 To a human operator, it is likely not very difficult to perform the
 mapping from one scheme to the other in most cases. However, multiple
 cases exist where it is difficult to map reliably from one identifier
 to the other in software without needing extensive manual
 configuration. For our VLAN control to be useful, we need to be able
 to identify ports in a recognisable way for our users who have
 connected devices to their network.

 In the examples above, I showed 6 identifiers in each list but they
 only correspond to 5 physical ports on the switches!

 Problem 1: Disjoint port numbers
 --------------------------------

 On our Cisco SF300, there are two sets of ports: 48 10/100M RJ45 ports
 and a further four 1G RJ45 ports. They're labelled externally as ports
 1-48 and G1-G4; internally the names are fa1-fa48 and
 gi1-gi4. Thankfully, this particular case isn't too hard to deal
 with. The SG300 we have (which works with the same driver) simply has
 52 ports labelled 1-52 and named gi1-gi52.

 Problem 2: Single physical ports with multiple possible port names
 ------------------------------------------------------------------

 On our Cisco Catalyst 3750-X 24P, most of this is easy. It has 24 1G
 ports, labelled 1 to 24 on the front panel. The port name "Gi/1/0/6"
 corresponds to "6". However, we also have an extra SFP module fitted
 that exposes 4 extra 1G interfaces (labelled G1 to G4). However,
 there's more complication yet: G2 and G4 are dual-personality ports
 and can also work as 10G ports when appropriate SFP+ modules are
 inserted. These 1G and 10G ports are named differently in software
 depending on which speed is in use:

   G1      ->  Gi1/1/1
   G2/Te1  ->  Gi1/1/2 OR Te1/1/1
   G3	  ->  Gi1/1/3
   G4/Te2  ->  Gi1/1/4 OR Te1/1/2

 Our Catalyst 3750 also has an extra 10/100M port on the back as a
 management port; VLANd explicitly ignores this port. Various other
 models in the 3750 range can come in a whole range of different
 configurations with 10/100M, 1G and 10G ports and it's very difficult
 to identify naming and numbering schemes for all of these without
 physical access to all of them.

 Problem 3: Multiple physical ports which map to the same port name
 ------------------------------------------------------------------

 Our Netgear M7300-24XF (aka XSM7224S) has 24 10G SFP+ ports and a
 further 4 10G RJ45 ports. Those 4 copper ports replace the last 4 of
 the SFP+ ports in a "combo" arrengement - if an SFP module is
 inserted, the RJ45 port is disabled. Thus, on this switch we have the
 following port numbers and port names:

   1       ->  1/0/1
   ...
   20      ->  1/0/2
   21F/21T ->  1/0/21
   ...
   24F/24T ->  1/0/24

 This combo approach is also used on the TP-Link TL-SG2216; it has 16
 1G RJ45 ports and 2 1G SFP ports which over-ride them:

   1       ->  Gi1/0/1
   ...
   14      ->  Gi1/0/14
   15/15F  ->  Gi1/0/15
   16/16F  ->  Gi1/0/16

 These show the opposite problem to the Catalyst 3750 - if a user
 connects to port 16 on the TP-Link, that at least will show up as one
 consistent name in the CLI. However, should we be looking for port
 number 16 or 16F when talking to the user?

 A (partial) solution in VLANd 0.4 onwards
 =========================================

 Hopefully the above descriptions will make it clear that this is a
 hard problem to solve 100% reliably. However, it's a problem that must
 at least partially be solved as end-users supplying port numbers
 cannot be expected to know the port names that are used internally by
 the switches but not exposed externally. Yet port names must be used
 internally for all the interactions with the switches directly - this
 is the only way that the software can work.

 So, port numbers have been added as an extra column in the port
 database. New APIs and methods have been added to do lookups by port
 number as alternatives to lookups by port name, to make things easier
 for end users. When adding ports using the admin interface, a port
 number is now required too.

 The backend of the auto_import_switch admin command (the recommended
 way to add switches) will attempt to automatically allocate sensible
 port numbers as it probes switches and finds new ports. The algorithm
 chosen here for assigning port numbers is the simplest one that might
 work for most of the switches and configurations that we
 have. *Numeric* port numbers (i.e. without any prefix or suffix
 letters) will be assigned to port names simply in the order that the
 port names are listed via a switch's CLI, starting with "1". For
 almost all our supported switches, this should make sense for a user
 when trying to supply port numbers. However, *BE AWARE* of the
 possbility that your port numbers may not always match the port
 numbers written on your switch in some cases (e.g. the Cisco Catalyst
 3750 as described above).

 If this port number to port name mapping algorithm proves not to be
 sufficient, future releases of VLANd may include options in the config
 file to provide exact mappings. We'd prefer not to have to do this due
 to the admin overhead it will impose (and the attendant possibility of
 errors).
	Port numbering and naming in VLANd
	==================================

	This is a far more complex subject than it should be, and it may cause
	problems for end users depending on their usage models. This is
	particularly likely for those users with Cisco Catalyst 3750 switches
	configured with extra internal modules for extra copper/fibre ports.

	Terminology
	===========

	For consistency, throughout this document and within VLANd two terms
	are used to identify switch ports:

	* a PORT NAME is the (typically) alphanumeric identifier for a switch
	port in software, i.e. when using the CLI to manage a
	switch. Common naming styles vary significantly here; examples from
	the VLANd test rack in Linaro's lab include "Gi1/0/6", "Gi1/1/4",
	"Te1/1/2", "fa24", "gi3", "1/0/23"

	* a PORT NUMBER is the (typically) numeric identifier for a switch
	port that is labelled visibly on the switch somewhere, typically
	next to the port or a group of ports. Not all switches limit
	themselves to numeric labels, though. The same examples from our
	test rack are described as "6", "G4/Te2", "24", "G3", "23G", "23T"

	These example include some of the problems - try and match tnem up!

	The problem
	===========

	On all of the switch models that we currently support, there is a
	disconnect between the port names and the associated port numbers. The
	port names are not directly shown to the user on any of our switches,
	which is not a good start.

	To a human operator, it is likely not very difficult to perform the
	mapping from one scheme to the other in most cases. However, multiple
	cases exist where it is difficult to map reliably from one identifier
	to the other in software without needing extensive manual
	configuration. For our VLAN control to be useful, we need to be able
	to identify ports in a recognisable way for our users who have
	connected devices to their network.

	In the examples above, I showed 6 identifiers in each list but they
	only correspond to 5 physical ports on the switches!

	Problem 1: Disjoint port numbers
	--------------------------------

	On our Cisco SF300, there are two sets of ports: 48 10/100M RJ45 ports
	and a further four 1G RJ45 ports. They're labelled externally as ports
	1-48 and G1-G4; internally the names are fa1-fa48 and
	gi1-gi4. Thankfully, this particular case isn't too hard to deal
	with. The SG300 we have (which works with the same driver) simply has
	52 ports labelled 1-52 and named gi1-gi52.

	Problem 2: Single physical ports with multiple possible port names
	------------------------------------------------------------------

	On our Cisco Catalyst 3750-X 24P, most of this is easy. It has 24 1G
	ports, labelled 1 to 24 on the front panel. The port name "Gi/1/0/6"
	corresponds to "6". However, we also have an extra SFP module fitted
	that exposes 4 extra 1G interfaces (labelled G1 to G4). However,
	there's more complication yet: G2 and G4 are dual-personality ports
	and can also work as 10G ports when appropriate SFP+ modules are
	inserted. These 1G and 10G ports are named differently in software
	depending on which speed is in use:

	G1 -> Gi1/1/1
	G2/Te1 -> Gi1/1/2 OR Te1/1/1
	G3 -> Gi1/1/3
	G4/Te2 -> Gi1/1/4 OR Te1/1/2

	Our Catalyst 3750 also has an extra 10/100M port on the back as a
	management port; VLANd explicitly ignores this port. Various other
	models in the 3750 range can come in a whole range of different
	configurations with 10/100M, 1G and 10G ports and it's very difficult
	to identify naming and numbering schemes for all of these without
	physical access to all of them.

	Problem 3: Multiple physical ports which map to the same port name
	------------------------------------------------------------------

	Our Netgear M7300-24XF (aka XSM7224S) has 24 10G SFP+ ports and a
	further 4 10G RJ45 ports. Those 4 copper ports replace the last 4 of
	the SFP+ ports in a "combo" arrengement - if an SFP module is
	inserted, the RJ45 port is disabled. Thus, on this switch we have the
	following port numbers and port names:

	1 -> 1/0/1
	...
	20 -> 1/0/2
	21F/21T -> 1/0/21
	...
	24F/24T -> 1/0/24

	This combo approach is also used on the TP-Link TL-SG2216; it has 16
	1G RJ45 ports and 2 1G SFP ports which over-ride them:

	1 -> Gi1/0/1
	...
	14 -> Gi1/0/14
	15/15F -> Gi1/0/15
	16/16F -> Gi1/0/16

	These show the opposite problem to the Catalyst 3750 - if a user
	connects to port 16 on the TP-Link, that at least will show up as one
	consistent name in the CLI. However, should we be looking for port
	number 16 or 16F when talking to the user?

	A (partial) solution in VLANd 0.4 onwards
	=========================================

	Hopefully the above descriptions will make it clear that this is a
	hard problem to solve 100% reliably. However, it's a problem that must
	at least partially be solved as end-users supplying port numbers
	cannot be expected to know the port names that are used internally by
	the switches but not exposed externally. Yet port names must be used
	internally for all the interactions with the switches directly - this
	is the only way that the software can work.

	So, port numbers have been added as an extra column in the port
	database. New APIs and methods have been added to do lookups by port
	number as alternatives to lookups by port name, to make things easier
	for end users. When adding ports using the admin interface, a port
	number is now required too.

	The backend of the auto_import_switch admin command (the recommended
	way to add switches) will attempt to automatically allocate sensible
	port numbers as it probes switches and finds new ports. The algorithm
	chosen here for assigning port numbers is the simplest one that might
	work for most of the switches and configurations that we
	have. Numeric port numbers (i.e. without any prefix or suffix
	letters) will be assigned to port names simply in the order that the
	port names are listed via a switch's CLI, starting with "1". For
	almost all our supported switches, this should make sense for a user
	when trying to supply port numbers. However, BE AWARE of the
	possbility that your port numbers may not always match the port
	numbers written on your switch in some cases (e.g. the Cisco Catalyst
	3750 as described above).

	If this port number to port name mapping algorithm proves not to be
	sufficient, future releases of VLANd may include options in the config
	file to provide exact mappings. We'd prefer not to have to do this due
	to the admin overhead it will impose (and the attendant possibility of
	errors).