Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{ picto_cablemanagement.png}}
====== Cable Management ======
---- dataentry summary ----
name                : Cable Management
description_wiki    : Documents cable infrastructures and physical connections between devices
index_hidden        : yes
level_hidden        : 1
collector_hidden    : no
version             : 1.2.0
release_dt          : 2023-12-07
TeemIp              : 3.1+
iTop                : 3.1+
code                : teemip-cable-mgmt
localization        : English, French, German
state               : stable
diffusion_hidden    : TeemIp wiki
product_hidden      : Included
module-lists_hidden : 
keyword_tags        : cmdb, cable
dependencies_s      : teemip-framework, teemip-config-mgmt-adaptor
download_wiki       : [[https://sourceforge.net/projects/teemip/files/teemip%20-%20extensions/Cable%20Management/1.2.0/teemip-cable-mgmt-1.2.0-124.zip/download|teemip-cable-mgmt-1.2.0-124.zip]]
github_wiki         : [[https://github.com/TeemIp/teemip-cable-mgmt|teemip-cable-mgmt]]
php-max             : 8.1
----


This extension brings to TeemIp objects from the cabling world that will allow you to document the physical connections between CIs.

<note>Vocabulary: by "TeemIp solution" or "TeemIP", it should be understood: TeemIp standalone or the iTop solution on top of which TeemIp as a module has been installed.
</note>

===== Revision History =====
^  Version  ^  Release Date  ^  Status  ^  iTop \\ Min  ^  IPAM for iTop \\ Min  ^  Comments  ^
|  1.3.0  |  2024-0x-xx  |    |  3.1.1  |  3.1.4  | - A Patch Panel can be mounted in an enclosure \\ - Network Sockets can be automatically created for a given Patch Panel \\ - Back End Cables can be automatically created between the sockets of 2 Patch Panels \\ - Cross Connects and Breakout Cables are now modelized \\ - Wiring paths can be proposed to connect the 2 Patch Panels of a Cross Connect \\ - Documents can be attached to Network Cables |
|  **1.2.0**  |  2023-12-07  |  Supported  |  3.1.1  |  3.1.4  | - A new Direct Cable class enables the connection between 2 physical interfaces together \\ - The direct connection of 2 CIs is visible in the wiring diagram \\ - Audit rules have been enhanced \\ - Data samples have been added \\ - Objects brought by the extension have their summary card \\ - Add Chinese (simplified) translation |
|  1.1.0  |  2023-07-24  |  Obsolete  |  3.1.0  |  3.1.0  | - Interfaces with no connections have been removed from the wiring diagram \\ - Network cable class has been split into Backend, Frontend and Device network cable classes \\ - An audit rule identifies the cables connected to one end only \\ - Modelization of cables, sockets and interfaces have been enhanced \\ - A socket can be attached to a location or a patch panel \\ - A tab displays the list of patch panels mounted in a rack \\ - Patch panels can be handled by [[https://store.itophub.io/en_US/products/molkobain-datacenter-view-extended|Molkobain DC view extended]] |
|  1.0.0  |  2022-12-04  |  Obsolete  |  3.1.0  |  3.1.0  | - Initial revision |

===== Features =====
TeemIp cable management allows you to document the cable layouts of your organization. Connect physical interfaces to wall mounted network sockets, to patch panels hosted in racks or to other physical interfaces, document your patch cables and your underlying cabling layout: the extension enables a large scope of connection scenarios as the following drawing highlights:

{{ cabling_scenarios.png }}

Furthermore, the extension displays the wiring that links devices, physical interfaces and network sockets together, like:

{{ cabling_wiring3.png }}

Note that the drawing has been manually rearranged.

===== Licensing =====
The TeemIp Cable Management extension is licensed under the terms of the GNU Affero General Public License Version 3 as published by the Free Software Foundation. This gives you legal permission to copy, distribute and/or modify TeemIp Cable Management under certain conditions. Read the ’license.txt’ file in the TeemIp distribution. TeemIp Cable Management is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.

===== Limitations =====
There is no specific limitations with that extension.

===== Requirements =====
//TeemIp standalone//: The extension is embedded in TeemIp standalone, starting with TeemIp 3.1.

//iTop//: When installed on an iTop application, you need [[extensions:teemip-core-ip-mgmt|IPAM for iTop]] to be installed as well.

In both case, make sure that [[2_x:datamodel:teemip-datacenter-devices|Datacenter Management]] has been selected at installation time.
===== Installation =====
//TeemIp standalone//: Installation is done with the application itself, through the setup.

//iTop//: To add the extension on an iTop application, follow the [[https://wiki.openitop.org/doku.php?id=extensions:installation|Standard installation process]].

===== Configuration =====

No specific configuration is required in TeemIp's configuration file or in IP configs for that extension. However, the default settings used by the "Find wiring" action on Cross Connects may be overwritten by the following configuration lines.

<code>
	'teemip-cable-mgmt' => array (
		'find_wiring_paths' => array (
		  'max_rack_levels_to_cross' => 3,
		  'max_offers_to_display' => 16,
		),
	),
</code>

These should be added to the Modules specific part of the configuration file.

===== Patch Panel  =====
{{icons8-toolbar.svg  }} 

As everyone knows, a patch panel is a piece of hardware with multiple ports that helps organize a group of cables. Each of these ports contains a wire that goes to a different location and can be set for fiber optic cables, cat5 cables, RJ45 cables, and many others. That class allows you to register them in TeemIp's CMDB.

=== Patch Panel Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Name | Alphanumeric string | Yes |
| Organization | Foreign key to a(n) Organization | Yes | 
| Status| Possible values: Implementation, Production  | No |
| Location | Foreign key to a(n) Location | Yes |
| Capacity | Number of network sockets that the panel can host | No |
| Connector | Foreign key to a(n) Interface Connector \\ Brought by the [[extensions:teemip-network-mgmt-extended|Network Management Extended]] extension | No |
| External reference | Alphanumeric string | No |
| Description | Multiline character string | No |
| **Rack Information** |||
| Rack | Foreign key to a(n) Rack | Yes |
| Enclosure | Foreign key to a(n) Enclosure | no |


Should the extension [[https://store.itophub.io/en_US/products/molkobain-datacenter-view-extended|Datacenter View Extended]] be installed on TeemIp, the following additional attributes will appear.
^  Name  ^  Type  ^  Mandatory?  ^
| **More Information** |||
| Panel | Possible values: Front, Rear | Yes |
| Zero-U | Possible values: Yes, No | Yes |
| Vert. position | Integer | No |
| Height | Integer | No |
| Weight (kg) | Decimal | No |

=== Tabs ===
^  Tab  ^  Description  ^
| Network sockets | All the network sockets attached to the patch panel |
| Cables | All cables connected to a network socket hosted by the patch panel |
| Peer front end panels| List of other patch panels connected to the current one through the network socket port of its hosted sockets |
| Peer back end panels | List of other patch panels connected to the current one through the back end network socket port of its hosted sockets |

=== Displaying a Patch Panel ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Patch Panel dashlet, click on it and select the item you are interested in:

{{ classdisplay_patchpanel3x.png }}

With the extension [[https://store.itophub.io/en_US/products/molkobain-datacenter-view-extended|Datacenter View Extended]], Patch Panel display will look like:

{{ classdisplay_patchpanel-dcviewext.png }}

=== Creating network sockets ===
If the capacity is set, to value c for instance, TeemIP will offer to automatically create c network sockets and to attach them to the patch panel. If n network socket do already exist, with n < c, then the menu will still be displayed but only (c - n) network sockets will be created. When created, network socket will be set to inactive mode and will inherit of attributes location, rack, patch panel (obviously) and interface connector (if exists) from the patch panel.

=== Creating back end network cables ===
If some network sockets are already attached to the patch panel, TeemIP will offer to automatically connect the back end interface of these network sockets to remote sockets located in another patch panel of another Rack. Purpose of this action is remove to TeemIP administrator the burden of creatinf back end network cables for each network socket of a patch panel.

When action is launched, TeemIP offers first to select the remote patch panel...

{{ classdisplay_patchpanel_createbackendcables.png }}

.. before creting the links in accordance with the number of available sockets in the remote rack.

===== Network Socket =====
{{icons8-wired-network.png  }} 
A network socket is the passive physical piece of hardware where you plug a network cable to establish a link between different network devices.

=== Network Socket Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Code | Alphanumeric string | Yes |
| Status| Possible values: Inactive, Ready, Active | Automatically computed |
| Location | Foreign key to a(n) Location | Yes |
| Rack | Foreign key to a(n) Rack | No |
| Patch panel | Foreign key to a(n) Patch Panel | No |
| Organization | Organization that the patch panel belongs to | N/A |
| External reference | Alphanumeric string | No |
| Comment | Multiline character string | No |
| **Front End Information** |||
| Connector | Foreign key to a(n) Interface Connector | No |
| Device | Foreign key to a(n) Connectable CI | No |
| Physical interface | Foreign key to a(n) Physical Interface | No |
| Network socket | Foreign key to a(n) Network Socket | No |
| **Back End Information** |||
| Back end network socket | Foreign key to a(n) Network Socket | No |

Friendly name of a network socket is automatically computed as the concatenation of the location name, rack name (if exists), patch panel name (if exists) and code of the socket.

=== Tabs ===
^  Tab  ^  Description  ^
| Cables | All cables connected to the network socket |

<note tip>
A network socket can be installed in a patch panel or as a stand alone equipment in a room.
  * When installed in a patch panel, attributes Location, Rack and Patch panel are mandatory.
  * When standing alone, attribute Location is mandatory but Rack and Patch panel must **NOT** be set.
</note>

Network Sockets have 2 sides:
  * A front end where RJ45 cables or optical fibers are plugged in,
  * A back end that links the socket to another network socket. 

<note warning>
A few rules are enforced at front and back ends' levels.
  * On the front end side, a network socket cannot be connected to both a remote network socket and a connectable CI.
  * The front end network socket and the back end one cannot be the same.
</note>

Attribute Status is read only and automatically computed:
  * If no back end network socket is set, status is set to **Inactive**,
  * If a back end network socket is set but if no physical interface nor network socket is set, status is set to **Ready**, 
  * If a back end network socket is set and if a physical interface or a network socket is set, status is set to **Active**. 

Network sockets implements three 1:1 relations. As the datamodel doesn't provide such attributes by default, these 1:1 relations are automatically computed when objects are created, modified or deleted: when one side of the relation is changed, the other sides (new and old when appropriate) are changed. These relations are: 
  * 1:1 relation between the physical interface of a CI and the network socket attribute of the interface,
  * 1:1 relation between the network socket and a remote network socket,
  * 1:1 relation between the network socket and a back end one.

=== Displaying a Network Socket ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Network Socket dashlet, click on it and select the item you are interested in or select it directly from the Patch panel detailed display :

{{ classdisplay_networksocket3x.png }}

===== Cross Connect =====
{{icons8-data-transfer.svg  }} 
A cross connect represents the cabling necessary to establish a direct link between two separate organizations in a data center, thus allowing the establishment of a private network link and eliminating the need to connect them using the internet.

=== Cross Connect Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Name | Alphanumeric string | Yes |
| Organization | Foreign key to a(n) Organization | Yes |
| Reference | Alphanumeric string | No |
| Peer Organization | Foreign key to a(n) Organization | Yes |
| Peer Reference | Alphanumeric string | No |
| Status| Possible values: Construction, Production, Cancellation, Obsolete | Yes |
| Cable category & type | Foreign key to a(n) Cable type | No |
| Business criticality | Possible values: low, medium, high | No |
| Move to production date | Date (year-month-day)  | No |
| Description | Multiline character string | No |
| **Local Unit Information** |||
| Location | Foreign key to a(n) Location of Organization | Yes |
| Rack | Foreign key to a(n) Rack | Yes |
| Patch panel | Foreign key to a(n) Patch Panel  | Yes |
| Primary Network socket | Foreign key to a(n) Network Socket | No |
| Secondary Network socket | Foreign key to a(n) Network Socket | No |
| **Peer Unit Information** |||
| Location | Foreign key to a(n) Location of Peer Organization | Yes |
| Rack | Foreign key to a(n) Rack | Yes |
| Patch panel | Foreign key to a(n) Patch Panel  | Yes |
| Primary Network socket | Foreign key to a(n) Network Socket | No |
| Secondary Network socket | Foreign key to a(n) Network Socket | No |
| **Back End Information** |||
| Back end network socket | Foreign key to a(n) Network Socket | No |

=== Tabs ===
^  Tab  ^  Description  ^
| Contacts | All the contacts for the Cross Connect |
| Documents | All the documents linked to the Cross Connect |
| Wiring | Wiring diagram |


=== Displaying a Cross Connect ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Cross Connect dashlet, click on it and select the item you are interested in :

{{ classdisplay_crossconnect.png }}

=== Finding Wiring Paths ===
A cross connect documents a link between one or two network socket hosted in a patch panel sitting in a rack of a given organization and one or two peer network socket hosted in a peer patch panel sitting in a peer rak of a peer organization. This action will display all the available cabling paths that may be establish to connect 2 network sockets that answer to the previous conditions.

{{ classdisplay_crossconnect_find_path.png }}

Network admin may select one of the offered path and manually create it within TeemIP.

<note tip>
The **Find wiring paths** action doesn't scan the entire CMDB. By default:
  * The number of racks that the paths may cross is limited to **5**,
  * The maximum of offers or proposals made by the tool is set to **32**.

These value can be overwritten through the configuration file, as described [[extensions:teemip-cable-mgmt#configuration|here]].
</note>
===== Physical Interface =====
{{icons8-globe-wire.png  }} 
TeemIp Cable management extension alters Physical interfaces with new attributes that allow connections to a network socket or to the interface of another connectable CI.

=== Physical Interface Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **Wiring Information** |||
| Network socket | Foreign key to a(n) Network socket | No |
| Remote device | Foreign key to a(n) ConnectableCI | No |
| Remote physical interface | Foreign key to a(n) PhysicalInterface | No |

<note warning>
A physical interface cannot be connected to both a network socket and another physical interface
</note>

These 2 relations brought by the extension implement 1:1 relations. As the datamodel doesn't provide such attributes by default, these 1:1 relations are automatically computed when objects are created, modified or deleted: when one side of the relation is changed, the other sides (new and old when appropriate) are changed. These relations are:

  * 1:1 relation between the physical interface and the network socket attribute of the interface,
  * 1:1 relation between the physical interface and another physical interface.

A connection between a physical interface and a network socket will look as follows.

{{ classdisplay_networksocket_to_physicalinterface.png }}
{{ classdisplay_physicalinterface_to_networksocket.png }}


A connection between two physical interfaces will look as follows.

{{ classdisplay_physicalinterface_to_physicalinterface.png }}

===== Front End Network Cable =====
{{icons8-fe-network-cable.svg  }}
A front end network cable (known as well as patch cable, patch cord or patch lead) represents the piece of hardware that connects 2 network sockets through their front end.

=== Front End Network Cable Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Cable type| Foreign key to a(n) Cable Type| No |
| Cable category | Foreign key to a(n) Cable Category | No |
| Length (m) | Length of the cable, in meter | No |
| Label | Alphanumeric string | No |
| Comment | Multiline character string  | No |
| **Connecting  Points** |||
| Network socket #1 - Front end | Foreign key to a(n) Network Socket | Yes |
| Network socket #2 - Front end | Foreign key to a(n) Network Socket | Yes |Friendly name of a network cable is automatically computed as the concatenation of the 2 network socket names.

Friendly name of a front end network cable is automatically computed as the concatenation of the two network sockets' name.

=== Tabs ===
^  Tab  ^  Description  ^
| Documents | All documents linked to the front end network cable |

<note warning>
A few rules are enforced when creating or modifying front end network cables.
  * A cable must be connected to 2 different network sockets,
  * A cable connecting 2 sockets is unique, regardless the socket used (#1 or #2),
  * A cable is automatically updated when one of the sockets it connects is changing.
</note>

=== Displaying a Front End Network Cable ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Front End Network Cable dashlet, click on it and select the item you are interested in or select it directly from the Patch Panel or Network Socket detailed displays :

{{ classdisplay_frontendnetworkcable.png }}

===== Back End Network Cable =====
{{icons8-be-network-cable.svg  }}
A back end network cable represents the piece of hardware that connects 2 network sockets through their back end.

=== Back End Network Cable Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Cable type| Foreign key to a(n) Cable Type| No |
| Cable category | Foreign key to a(n) Cable Category | No |
| Length (m) | Length of the cable, in meter | No |
| Label | Alphanumeric string | No |
| Comment | Multiline character string  | No |
| **Connecting  Points** |||
| Network socket #1 - Back end | Foreign key to a(n) Network Socket | Yes |
| Network socket #2 - Back end | Foreign key to a(n) Network Socket | Yes |Friendly name of a network cable is automatically computed as the concatenation of the 2 network socket names.

Friendly name of a back end network cable is automatically computed as the concatenation of the two network sockets' name.

=== Tabs ===
^  Tab  ^  Description  ^
| Documents | All documents linked to the back end network cable |

<note warning>
A few rules are enforced when creating or modifying back end network cables.
  * A cable must be connected to 2 different network sockets,
  * A cable connecting 2 sockets is unique, regardless the socket used (#1 or #2),
  * A cable is automatically updated when one of the sockets it connects is changing.
</note>

=== Displaying a Back End Network Cable ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Back End Network Cable dashlet, click on it and select the item you are interested in or select it directly from the Patch Panel or Network Socket detailed displays :

{{ classdisplay_backendnetworkcable.png }}

===== Device Network Cable =====
{{icons8-dev-network-cable.svg  }}
A device network cable represents the piece of hardware that connects the front end of a network socket and the interface of a connectable CI.

=== Device Network Cable Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Cable type| Foreign key to a(n) Cable Type| No |
| Cable category | Foreign key to a(n) Cable Category | No |
| Length (m) | Length of the cable, in meter | No |
| Label | Alphanumeric string | No |
| Comment | Multiline character string  | No |
| **Connecting  Points** |||
| Network socket - Front end | Foreign key to a(n) Network Socket | Yes |
| Device | Foreign key to a(n) ConnectableCI | No |
| Physical interface | Foreign key to a(n) PhysicalInterface | No |

Friendly name of a device network cable is automatically computed as the concatenation of the network socket's name and the interface's name.

=== Tabs ===
^  Tab  ^  Description  ^
| Documents | All documents linked to the device network cable |

<note warning>
A few rules are enforced when creating or modifying device network cables,
  * A cable connecting a socket and a network interface is unique,
  * A cable is automatically updated when one of its end is changing.
</note>

=== Displaying a Device Network Cable ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Device Network Cable dashlet, click on it and select the item you are interested in or select it directly from the Patch Panel or Network Socket detailed displays :

{{ classdisplay_devicenetworkcable.png }}

===== Direct Network Cable =====
{{icons8-dir-network-cable.svg  }}
A direct network cable represents the piece of hardware that connects directly the interface of a connectable CI to the interface of another connectable CI.

=== Device Network Cable Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Cable type| Foreign key to a(n) Cable Type| No |
| Cable category | Foreign key to a(n) Cable Category | No |
| Length (m) | Length of the cable, in meter | No |
| Label | Alphanumeric string | No |
| Comment | Multiline character string  | No |
| **Connecting  Points** |||
| Device #1 | Foreign key to a(n) ConnectableCI | Yes |
| Physical interface #1 | Foreign key to a(n) PhysicalInterface | Yes |
| Device #2 | Foreign key to a(n) ConnectableCI | Yes |
| Physical interface #2 | Foreign key to a(n) PhysicalInterface | Yes |

Friendly name of a device network cable is automatically computed as the concatenation of the two interface's name.

=== Tabs ===
^  Tab  ^  Description  ^
| Documents | All documents linked to the direct network cable |

<note warning>
A few rules are enforced when creating or modifying device network cables,
  * A cable connecting two network interfaces is unique,
  * A cable is automatically updated when one of its end is changing.
</note>

=== Displaying a Direct Network Cable ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Direct Network Cable dashlet, click on it and select the item you are interested in or select it directly from the interace's display :

{{ classdisplay_directnetworkcable.png }}

===== Breakout Cable =====
{{icons8-split.svg  }}
Breakout cables are designed to split or combine optical fibers or copper wires into multiple individual connectors. They eliminate the need for separate cables by consolidating multiple fibers or wires into a single cable bundle which simplifies installation, reduces cable congestion, and improves cable management.

=== Breakout Cable Properties ===
^  Name  ^  Type  ^  Mandatory?  ^
| **General Information** |||
| Cable type| Foreign key to a(n) Cable Type| No |
| Cable category | Foreign key to a(n) Cable Category | No |
| Length (m) | Length of the cable, in meter | No |
| Label | Alphanumeric string | No |
| Comment | Multiline character string  | No |
| **Capacities** |||
| Capacity | Number of links carried by the cable | No |
| Free Links | Number of links still available in the cable | Automatically computed |
| **Connecting  Points** |||
| Rack #1 | Foreign key to a(n) Rack | Yes |
| Rack #2 | Foreign key to a(n) Rack | Yes |

Friendly name of a breakout cable is automatically computed as the concatenation of the two rack's name and the cable's label.

=== Tabs ===
^  Tab  ^  Description  ^
| Documents | All documents linked to the breakout cable  |
| Patch Panels * | All the patch panels that the cable is connected to |

(*) The relation holds a "UsedLinks" attribute which documents the number of wires consummed by the link.

<note tip>
  * The "Free Links" attribute is read only and automatically computed by the application.
    * Value is computed as the capacity minus the maximum of used links with a given rack.
  * The breakout cable / patch panel relation holds a "Used Links" parameter telling how many links are consummed by the connection.
    * When a relation is created, the "Used Links" attribute is initialized with the value of the patch panel's capacity.
</note>
<note warning>
Proper documentation requires that each breakout cable / patch panel relation that concerns a given  rack has a counterpart with the other rack.
</note>

=== Displaying a Breakout Cable ===
In the Network dashboard that is accessible from a submenu of the standard CMDB overview menu, find the Breakout Cable dashlet, click on it and select the item you are interested in or select it directly from the interace's display :

{{ classdisplay_breakoutcable.png }}

{{ classdisplay_breakoutcable2.png }}

===== Wiring diagram =====
Once connections between Devices, Physical interfaces and Network Sockets are documented, the physical path that connects them all can be visualized through the menu "Wiring..." displayed under the "Other Actions" menu of Connectable CIs, Physical Interfaces and Network Sockets.

{{ classdisplay_wiring_menu.png }}

That action displays the wiring layout that connects the device it has been launch from, and all the elements that are part of the cabling path. For instance, from a backend server application :

{{ cabling_wiring3.png }}

<note tip>
  * For clarity reasons, only active interfaces are represented on the diagram.
  * The layout here above has been rearranged with drag & drops for a better readalibity.
</note>
===== Typology Elements =====
{{icons8-new-item-48.png }} 

Two new typological elements are brought by the extension:

^  Name  ^  Description  ^  Attributes  ^  Example  ^
| Cable Type | Type of a Network Cable | Name, Description, List of Cable Categories using it | Single mode |
| Cable Category | Category of a Network Cable | Name, Cable Type, Description, | OS1, OS2 |

The extension groups network specific typological elements in the dashlet "Network typology configuration".

{{ overview_group_network_typology_cable.png }}
Documentation

User Tools

Site Tools

Page Tools
