RackTablesUserGuide
Contents
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
New 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.
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)
- MyWebServer1 (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).
- $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.