Difference between revisions of "RackTablesUserGuide"

From RackTables Wiki
Jump to navigation Jump to search
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= Port and links =
 
= Port and links =
A port or physical interface is a small thingy on your box you can connect a cable to.
+
A port or physical interface is part of an object which you can connect a cable to. Each port can have a local name, that is how this port is visible from the OS point of view. For a Linux system that will be eth0, eth1, etc. Visible label is what is physically written on the port.
So far this software can only handle network ports. No power outlets yet. Each port can
 
have a local name, that is how this port is visible from the OS point of view. For linux box
 
that will be eth0, eth1, etc. Visible lable is what is written on the port on the box
 
  
Depending on the manufacturer you may observe labels as "1", "2", etc or something else.
+
Depending on the manufacturer you may observe labels as "1", "2", etc. or something else. Port type is an essential property that allows port connections to be properly arranged. It lets you know that you won't be able to connect optical and copper ports together with one cable. Some ports have an L2 address. It's helpful to populate those, as you may find it handy to find ports by L2 addresses while investigating your STP tree.
Port type is an essential property that allows port connections to be properly arranged.
 
It lets you know that you won't be able to connect optical and copper ports together with one cable.
 
Some ports have an L2 address. It's helpful to populate those, as you may find it handy to
 
find ports by L2 addresses while investigating your STP tree. Now you can link or reserve ports.
 
  
Reserving a port is simply adding a comment to it, thus preventing it to be linked.
+
Reserving a port is simply adding a comment to it, thus preventing it to be linked. A good reservation can be "Reserved for a field engineer laptop". Linking ports is creating a connection between them. That is plugging a cable to them. Only ports with compatible types can be linked. Say, RJ-45/100-Base TX can be linked to RJ-45/1000-Base TX, but can't be linked to LC/100-BASE FX. In many cases you'll need to add a bunch of ports from a switch. In this case there is a text area and a format selector. Just choose your device and format, paste the output to the textarea and click "Parse output" button. Also, you need to choose which port type is to be used, since it's not possible to guess that from the output.
A good reservation can be "Reserved for a field engineer laptop". Linking ports is creating
 
a connection between them. That is plugging a cable to them. Only ports with compatible
 
types can be linked. Say, RJ-45/100-Base TX can be linked to RJ-45/1000-Base TX, but can't
 
be linked to LC/100-BASE FX. In many cases you'll need to add a bunch of ports from a switch.
 
In this case there is a text area and a format selector. Just choose your device and format,
 
paste the output to the textarea and click "Parse output" button. Also, you need to
 
choose which port type is to be used, since it's not possible to guess that from the output.
 
 
----
 
----
  
Line 65: Line 51:
 
== Rack design tab ==
 
== Rack design tab ==
 
Rack design defines the physical layout of a rack cabinet. Most common reason to use the tab is absence of back rails, although any other design can be defined. In this tab you can change mounting atoms' state between 'free' and 'absent'. A selected checkbox means atom presence.
 
Rack design defines the physical layout of a rack cabinet. Most common reason to use the tab is absence of back rails, although any other design can be defined. In this tab you can change mounting atoms' state between 'free' and 'absent'. A selected checkbox means atom presence.
 +
 +
=== Reversing Rack Numbering ===
 +
Rack numbering can be reversed through the global configuration parameter REVERSED_RACKS_LISTSRC available at Configuration->User interface. This value is a [[#RackCode|RackCode]] expression and can be a tag "{tag}" or "true" or "false" for global configuration.
  
 
== Rack problems tab ==
 
== Rack problems tab ==
Line 74: Line 63:
  
 
The feature allows matching description of each IP address of the current IP subnet with DNS PTR record, resolved online. !RackTables highlights each address accordingly to its current description and DNS data; however, it is a rough estimation if each particular description is correct or not. It is left up to the user to decide, if DNS data, as more accurate, should be imported into DB.
 
The feature allows matching description of each IP address of the current IP subnet with DNS PTR record, resolved online. !RackTables highlights each address accordingly to its current description and DNS data; however, it is a rough estimation if each particular description is correct or not. It is left up to the user to decide, if DNS data, as more accurate, should be imported into DB.
 +
----
 +
 +
= SNMP Sync =
 +
It is possible to initialise switch port and system data through SNMP on freshly created objects. If the switch model is known for RackTables (either as a part of the distribution or through [[RackTablesDevelGuide#SNMP_sync|local admin magic]]) and accessible through SNMP then by using the SNMP Sync tab Racktables try to connect the switch by version1, version2c or version3 protocol, using the user provided community (and/or authentication data) for access (the community can be set in general configuration) and fills the port data, firmware version etc.
 +
 +
The host used first looked up in the FQDN field, then if empty in the first IP adderess assigned to the object.
 
----
 
----
  
Line 88: Line 83:
  
 
== Physical Objects ==
 
== Physical Objects ==
New object types include Network chassis and Server chassis.
+
Object types include Network chassis and Server chassis.
  
 
Common container scenarios:
 
Common container scenarios:
Line 96: Line 91:
  
 
When mousing over the container object's name in the rackspace area, the hover displays a list of all contained objects.  Only immediate children are listed, grand-children, great-grand-children, etc. are not.
 
When mousing over the container object's name in the rackspace area, the hover displays a list of all contained objects.  Only immediate children are listed, grand-children, great-grand-children, etc. are not.
 +
 +
=== Visual Representation ===
 +
When adding a chassis HW type to the dictionary, the dimensions may be specified as follows :
 +
%L<rows>,<cols>[<layout>]%
 +
 +
<rows> is the number of rows, <cols> is the number of columns and <layout> is an optional layout hint (either H for horizonal or V for vertical).
 +
 +
Examples:
 +
* Cisco 6509-E (9 horizontal slots): %L9,1H%
 +
* Dell M1000e (2 rows, each with 8 vertical slots): %L2,8V%
 +
 +
If the layout hint is not supplied, a chassis with less than 6 slots will be laid out with horizontal slot names, otherwise vertical slot names will be used.
  
 
== Virtual Objects ==
 
== Virtual Objects ==
Line 145: Line 152:
 
** ProdAppServer1 (VM)
 
** ProdAppServer1 (VM)
 
** ProdAppServer2 (VM)
 
** ProdAppServer2 (VM)
 +
 +
Example 4: VM Host + VMs + Custom Objects
 +
 +
* MyHypervisor (Server)
 +
** MyWebServer1 (VM)
 +
*** MyCustomObject1 (Site-Foo)
 +
*** MyCustomObject1 (Site-Widget)
 +
** MyWebServer2 (VM)
 +
*** MyCustomObject1 (Site-Bar)
 +
*** MyCustomObject1 (Site-Gadget)
 +
** MyDatabaseServer (VM)
 
----
 
----
  

Latest revision as of 03:42, 11 June 2015

Port and links

A port or physical interface is part of an object which you can connect a cable to. Each port can have a local name, that is how this port is visible from the OS point of view. For a Linux system that will be eth0, eth1, etc. Visible label is what is physically written on the port.

Depending on the manufacturer you may observe labels as "1", "2", etc. or something else. Port type is an essential property that allows port connections to be properly arranged. It lets you know that you won't be able to connect optical and copper ports together with one cable. Some ports have an L2 address. It's helpful to populate those, as you may find it handy to find ports by L2 addresses while investigating your STP tree.

Reserving a port is simply adding a comment to it, thus preventing it to be linked. A good reservation can be "Reserved for a field engineer laptop". Linking ports is creating a connection between them. That is plugging a cable to them. Only ports with compatible types can be linked. Say, RJ-45/100-Base TX can be linked to RJ-45/1000-Base TX, but can't be linked to LC/100-BASE FX. In many cases you'll need to add a bunch of ports from a switch. In this case there is a text area and a format selector. Just choose your device and format, paste the output to the textarea and click "Parse output" button. Also, you need to choose which port type is to be used, since it's not possible to guess that from the output.


Networking

IP subnets

This tab manages IPv4 resources. All IPv4 addresses are grouped to subnets. Subnets make a hierarchy, which is computed and displayed automatically. An IPv4 address __can__ belong to a network. Sometimes it doesn't. There is an option ("Enable IPv4 address allocations w/o covering network") to deal with that. When it is enabled, the system refuses to assign "martian" IP addresses to objects. However, this option doesn't affect already assigned "martian" addresses.

IP addresses

Every IP address can be either bound to an interface or free. On the other hand, it can be either reserved or not. That makes 4 possible states: bound - reserved, bound - unreserved, free - reserved free - unreserved. The first state is considered as "conflicting" and will be shown red-highlited. An IP address may have a "Name" assigned to it, which is intended to be used as a short comment. An example would be "The default GW" or "Reserved for field engineer" Binding an address to an interface is called "allocation". The interface is a rack object plus an interface name. The interface name can be the same as a physical port label on that box or something else. If you are binding it to a linux box with 2 physical ports, you might want to name interfaces as eth0, eth1, eth0:4, eth1.110, etc, whereas your physical port names will be eth1 and eth2 The difference between ports and interfaces is that say a switch may have 24 ports and only 1 interface, which is accessable from any of those ports. Generally, one IP address can be bound only to one interface, otherwise it's considered as a "collision". However, there are exceptions and a tool to mark those exceptions. There is a "bond type" or "interface type", which can be either "Regular" or "Shared" or "Virtual". Shared means that 2 or more peers share the same IP address like it's done in VRRP or HSRP. Usually, there is only one box possessing it at a time but when it dies, another one will have it. Shared bonds will not conflict with each other, but will conflict with regular bindings of the same IP address. Virtual interface is an assignment that usually don't broadcast itself through the network, but will allow the OS to accept packets with that IP address sent to the box. This is widely used in loadbalancing technics where loadbalancers simply do ARP proxy; they rewrite L2 address in L2 frames with target's address and resend them back to the network. Virtual interfaces do not conflict with any other interface types. Note: do not use virtual interfaces if your loadbalancer uses NAT. There is a NAT tab for that instead.

NATv4

Boxes can translate their own L4 addresses to other L4 addresses on other boxes. This is called NAT. In protocol selection box you can choose 2 protocols so far, UDP and TCP. Source is one of IP addresses assigned to the box and after a colon is a box for numerical port. As a target you have to choose a target IP address and port it will be translated to. Add a decription if you like. After submitting the form you will find that if there was an object assined to the target IP address it will be shown as well. A single source IP address/port can be assigned to multiple target IP addresses/ports. That will represent an L4 loadbalancing. And vice versa, multiple sources can be translated to one target.


Rackspace

Rack design tab

Rack design defines the physical layout of a rack cabinet. Most common reason to use the tab is absence of back rails, although any other design can be defined. In this tab you can change mounting atoms' state between 'free' and 'absent'. A selected checkbox means atom presence.

Reversing Rack Numbering

Rack numbering can be reversed through the global configuration parameter REVERSED_RACKS_LISTSRC available at Configuration->User interface. This value is a RackCode expression and can be a tag "{tag}" or "true" or "false" for global configuration.

Rack problems tab

Rack problems prevent free rackspace from being used for mounting. Such rackspace is considered unusable. After the problem is gone, the atom can become free again. In this tab you can change atoms' state from free to unusable and back. A selected checkbox means a problem.


Live PTR

First of all, an important notice has to be done about names (or "descriptions") of IP addresses. If you know about the real objects, to which addresses belong, it is recommended to create those objects and then allocate IP addresses to them. This approach will keep your dataset consistent and cross-linked. Address descriptions normally should contain supplementary, but useful information: the role or a well-known DNS name of a particular address.

The feature allows matching description of each IP address of the current IP subnet with DNS PTR record, resolved online. !RackTables highlights each address accordingly to its current description and DNS data; however, it is a rough estimation if each particular description is correct or not. It is left up to the user to decide, if DNS data, as more accurate, should be imported into DB.


SNMP Sync

It is possible to initialise switch port and system data through SNMP on freshly created objects. If the switch model is known for RackTables (either as a part of the distribution or through local admin magic) and accessible through SNMP then by using the SNMP Sync tab Racktables try to connect the switch by version1, version2c or version3 protocol, using the user provided community (and/or authentication data) for access (the community can be set in general configuration) and fills the port data, firmware version etc.

The host used first looked up in the FQDN field, then if empty in the first IP adderess assigned to the object.


Containers

Container objects were introduced in version 0.19 to support various scenarios.

Similar to the port compatibility matrix, the object compatibility matrix defines valid relationships. It's located on the Configuration page.

You choose an object's container using the 'Select container' link on the object's Properties tab. This link is only visible if the object type exists as a child in the object compatibility matrix.

Objects may have multiple containers. This is to support unique scenarios such as a blade server which is used to host virtual machines. It could potentially have two valid containers - the blade server chassis as well as the VM cluster.

If an object contains any other objects, they are listed on the Object->View page.

Physical Objects

Object types include Network chassis and Server chassis.

Common container scenarios:

  • Blade server chassis -> blade (server or network switch blades)
  • Network chassis -> blade
  • Shelf -> modems (or any other small objects sitting on the shelf)

When mousing over the container object's name in the rackspace area, the hover displays a list of all contained objects. Only immediate children are listed, grand-children, great-grand-children, etc. are not.

Visual Representation

When adding a chassis HW type to the dictionary, the dimensions may be specified as follows : %L<rows>,<cols>[<layout>]%

<rows> is the number of rows, <cols> is the number of columns and <layout> is an optional layout hint (either H for horizonal or V for vertical).

Examples:

  • Cisco 6509-E (9 horizontal slots): %L9,1H%
  • Dell M1000e (2 rows, each with 8 vertical slots): %L2,8V%

If the layout hint is not supplied, a chassis with less than 6 slots will be laid out with horizontal slot names, otherwise vertical slot names will be used.

Virtual Objects

New object types include VM, VM Cluster, VM Resource Pool and VM Virtual Switch. Although the terminology is common to VMware environments, the object types may be used in a generic manner to support other scenarios.

The VIRTUAL_OBJ_LISTSRC Config option specifies which object types are virtual. Virtual objects may not be mounted in a rack. They also lack the asset tag, barcode and label fields.

A Virtual Resources link on the front page leads to a summary page detailing clusters, resource pools, hypervisors and virtual switches.

The Hypervisor attribute was added and associated with Server objects. It may be set to Yes or No. When selecting a container for a VM or VM Virtual Switch, the only servers listed are those with the Hypervisor attribute set to Yes. This was done to limit the number of entries displayed in the selector pop-up window.

The NATv4, RS pools, keepalived.conf and Live ports tabs are not associated with VMs. If you'd like them to be, edit the appropriate Config entries to include {$typeid_1504} which is the objtype_id of VMs.

Example Scenarios

The object type is in parentheses.

Example 1: Individual server hosting VMs

  • MyHypervisor (Server)
    • MyAppServer (VM)
    • MyWebServer (VM)
    • MyDatabaseServer (VM)

Example 2: Cluster of servers hosting VMs (VMware)

  • MyCluster (VM Cluster)
    • MyHypervisor1 (Server)
    • MyHypervisor2 (Server)
    • MyHypervisor3 (Server)
      • SpecialServer1 (VM)
    • MyDistributedSwitch (VM Virtual Switch)
    • DevPool (VM Resource Pool)
      • DevAppServer1 (VM)
      • DevAppServer2 (VM)
    • ProductionPool (VM Resource Pool)
      • ProdAppServer1 (VM)
      • ProdAppServer2 (VM)

Example 3: Cluster of servers hosting VMs (XenServer)

  • DevPool (VM Resource Pool)
    • MyHypervisor1 (Server)
    • MyHypervisor2 (Server)
    • DevAppServer1 (VM)
    • DevAppServer2 (VM)
  • ProductionPool (VM Resource Pool)
    • MyHypervisor3 (Server)
    • MyHypervisor4 (Server)
    • ProdAppServer1 (VM)
    • ProdAppServer2 (VM)

Example 4: VM Host + VMs + Custom Objects

  • MyHypervisor (Server)
    • MyWebServer1 (VM)
      • MyCustomObject1 (Site-Foo)
      • MyCustomObject1 (Site-Widget)
    • MyWebServer2 (VM)
      • MyCustomObject1 (Site-Bar)
      • MyCustomObject1 (Site-Gadget)
    • MyDatabaseServer (VM)

RackCode

Tags

The language operates on "tags", which are plain text strings, most commonly single words much like blog post tags. A tag usually indicates a fact of belonging to certain class or group, or it may express, that certain boolean predicate is true. In !RackTables, for example, several objects can be tagged with "development" and this will show their functional assignment. Some of those objects could be tagged with "room 112" to reflect their location. Tags may have parent tags. The "room 112" tag (and perhaps some others) could have "main building" as its parent, altogether corresponding to building plan.

Tags serve dual purpose: to classify entities for easier browsing or asset management and to form security context. Autotags are added into the context automatically and have dollar sign prepended to their ID. Lettercase in tag names sometimes matters: one can't create two tags, whose names only differ in case, but tag names referenced in the !RackCode are searched in the security context with case preserved. IOW, if some entity is tagged with "Dogs", a {dogs} tag test will never return true.

Tag chain

A tag chain is just an unordered set of tags with an important extension: if a tag is present on the chain, all its parent tags, up to the topmost one, are always present too. This is true for each tag on the chain.

Predicates

A predicate is a boolean non-recursive function, which returns either true or false. The function is referenced by its symbolic name and may use both tags and other predicates to build boolean expressions. The order of definitions matters, i.e. the predicate must be declared at the moment of a grant rule evaluation, if the rule is referencing it (this is verified automatically). A predicate can only be defined once (it cannot be redefined later).

Automatic tags

Autotags aren't shown by default, this may be changed on the "user interface" config page. Below is the list of currently used autotags (as for 0.20.0).

Navigation tags

$page_something
Always set; "something" is the name of the current page.
$tab_something
Always set; "something" is the name of the current tab.
$op_something
Only set when an operation (change request) "something" is being processed, usually immediately after hitting some kind of "submit" control. Everything happens behind the scenes, then the user is redirected to some view (often, but not always the same he arrived from) and a message log is displayed on the top of the page.
$any_op
Set, if any operation is being processes. Having this autotag in a deny rule should (not finished yet) block all modifications to the database.

Common tags

$lgcn_somename
LDAP group CN. Groups are taken from user's memberOf LDAP attribute during authentication.
$untagged
Set for any entity (but except users), which __can__ have tags, but __doesn't__ have any tags set.

Location tags

$any_location
set, when current focus is a location container
$locationid_000
set to the ID of the current location container

Row tags

$any_row
set, when current focus is a rack row
$rowid_000
set to the ID of the current rack row

Rack tags

$any_rack
set, when current focus is a rack
$rackid_000
set to the ID of the current rack

User tags

$userid_000
Numerical user ID of the current user account, if the account exists in the local database.
$username_somename
Username of the current user.

Object tags

$any_object
Always present in all views for objects (isn't it equivalent to $page_object?).
$id_000
When operating on a rack object (asset), this tag is always set with 000 being its database ID.
$typeid_000
Same as above, but for the ID of the type of the operated object. E. g., servers produce $typeid_4.
$cn_somename
If an object has such a common name "somename", which makes the above string be a valid tag name, this autotag is added to the context.
$attr_X_Y
Set, if object has a defined dictionary attribute. X is an attribute id and Y is a dictionary key of the value. For example, if the object has two assigned attributes: HW type(2) = Cisco Catalyst 6509-E(148), and SW type(4) = Cisco IOS 12.2(252), than two autotags are attached to this object: $attr_2_148 and $attr_4_252
$no_asset_tag
set if current object has no asset number
$unmounted
Set for objects, which have no IP addresses allocated.
$nameless
Set for objects, which __don't__ have a name, although they __should__ have one according to config ("List source: object, for which common name should be set").
$portless
Set for objects, which have zero ports.
$runs_8021Q
Set for any object, which has 802.1Q order (that is, a VLAN domain and a switch template) assigned (introduced in 0.18.0)
$8021Q_domain_000
Set for any object, which has 802.1Q order. Contains numeric ID of 802.1Q domain of the order
$8021Q_tpl_000
Set for any object, which has 802.1Q order. Contains numeric ID of 802.1Q template of the order

IP network tags

$any_net
set for any IP network
$any_ip4net
set for any IPv4 network
$any_ip6net
set for any IPv6 network
$ip4netid_000
set for IPv4 networks. Contains numeric network ID
$ip6netid_000
set for IPv6 networks. Contains numeric network ID
$masklen_eq_NNN
set for any IP network. Contains network prefix length in bits
$runs_8021Q
set for IP networks which have VLANs attached to it
$vlan_NNN
set for IP networks which have VLANs attached to it. Contains numeric VLAN ID (tag number).
$spare_NNN
set for IP networks which have unallocated space in them. Contains the numeric prefix length of unallocated range. If network has multiple unallocated ranges of different sizes, multiple such tags will be assigned to it.
$aggregate
set for IP networks which have subnetworks
$ip4net-192-168-0-0-24
set for any IPv4 network. Contains network IP and prefix length separated by dashes.

File tags

$any_file
Set, when current focus is a file.
$fileid_000
Holds file ID, if the current focus is a file.

802.1Q template tags

$any_vst
set for any 802.1Q template
$vstid_000
set for any 802.1Q template. Contains numeric ID of template

Virtual service tags

$any_vs
set for any virtual service
$any_ipv4vs
set for any IPv4 virtual service
$any_ipv6vs
set for any IPv6 virtual service
$ipvsid_000
set to ID of virtual service
$unused
set for such virtual services which do not have any RS Pool-Load Balancer links

Real server pool tags

$any_rsp
set for all RS pools (which is the same as $any_ipv4rsp)
$any_ipv4rsp
set for all RS pools (RS pools can contain both IPv4 and IPv6 addresses)
$ipv4rspid_000
set to RS pool ID
$unused
set for such RS poold which do not have any Virtual Service-Load Balancer links

Operation-specific tags

$fromvlan_NNNN
Set, when a port is being removed from VLAN with the given VLAN ID (by means of LiveVLANs or 802.1Q ports feature).
$tovlan_NNNN
Likewise, when a port is being added to a VLAN.
$vlan_NNNN
Likewise, when a port is being either added OR removed, equivalent to "{$fromvlan_NNNN} or {$tovlan_NNNN}" RackCode expression.