Revert "- rebase against master branch"
[racktables] / README.patchpanel
1 OVERVIEW
2 The patchpanel branch was created by adoom42. It adds support for linking ports
3 multiple times and tracing cable paths. Several people have created patches
4 for this already. I haven't seen one which handles all potential use cases.
5
6 Generally speaking, a port is linked to one other port, but there are
7 exceptions.
8 1. Patch panels. The front of the port is linked to an object's port. The
9 back of the port is usually linked to the back of a port on another patch panel.
10 2. "Y" power cables and other splitters. Example: the male end connects to an
11 outlet, and each female end connects to an object's power supply. The cable
12 has a varying number of female ends (my personal favorite is the 'octo-cable').
13 3. Multi-point wireless links. Although less common in data centers, they are
14 used in areas such as college campuses. An access point is mounted in a central
15 location and multiple buildings have client units, with multiple clients
16 associating to the same AP.
17
18 CHANGELOG
19 The installer & upgrader check for the GraphViz PEAR module. A non-blocking
20 warning is displayed if it is not found.
21
22 The port linker pop-up includes a checkbox which allows already-linked ports to
23 be linked again.
24
25 Triggers are used to prevent duplicate links. They ensure that the value of
26 portb is always greater than porta, which forces the UNIQUE KEY (porta,portb)
27 to take effect. They also ensure that porta is compatible with portb.
28
29 The (porta,portb) primary key was removed from the Link table. An
30 auto-increment id column was added to uniquely identify links. This results in
31 less PHP code. For example, assume that rows exist where porta > portb
32 (they were entered manually before the triggers were installed). In that case,
33 all update and delete operations would need to identify a specific row using
34 something like ((porta = X AND portb = Y) OR (porta = Y AND portb = X)). Now
35 such operations can identify the row using a single id.
36
37 Triggers are used to maintain integrity of the PortCompat table. Without them,
38 you would be able to add a compatibility rule, link ports using that rule, then
39 delete the rule without warning. The ports would still be linked, even though
40 they are now incompatible. The trigger checks for the existence of such links
41 before allowing rules to be updated or deleted. MySQL doesn't support trigger
42 exceptions, so I used a workaround to display a more meaningful error message:
43 UPDATE `Cannot update: rule still used` SET x = 1.
44
45
46 HELP/FEEDBACK REQUESTED
47 fetchPortList() has been modified to include all links as a nested array. The
48 SQL query works but is not optimal. Performance tips would be appreciated.
49
50 A new pop-up provides the ability to link two patch panels. The link is only
51 displayed for objects of the type "PatchPanel". The list includes all patch
52 panels with the same number of ports. It doesn't check for port compatibility.
53 When the form is submitted, the handler function adds a link for each port.
54 The handler function does check for port compatibility. If any port is
55 incompatible, the entire linking operation is rolled back. Ideally, the pop-up
56 would only list panels which are fully compatible. SQL help in this area would
57 also be appreciated. It should be possible using a single query, but I'm not
58 sure how to do it.
59
60 A common usage scenario involves connecting an object's port to patch panel A,
61 which is connected to patch panel B, which is then connected to another
62 object's port. When the patch panel A's ports are linked to patch panel B's,
63 the ports will be excluded from the 'Link this port' pop-up unless you check
64 the 'Include linked ports' box. Patch panel ports which are linked less than
65 twice should be included without having to check the 'Include linked ports'
66 box. I'm not sure how to deal with this efficiently.
67
68 MISC. NOTES
69 This branch should only be tested in a development environment. It sets the
70 RackTables version to 0.21.0 which will break any future upgrades to 0.20.x.