RackTablesUserGuide

Port and links

A port or physical interface is a small thingy on your box you can connect a cable to. 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. 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. 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.

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.

---

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.

$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.

$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.

$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.

$any_file

Set, when current focus is a file.

$fileid_000

Holds file ID, if the current focus is a file.

$any_rsp

set for all RS pools (which is now the same as $any_ipv4rsp, and will change only after IPv6 implementation)

$any_ipv4rsp

set for IPv4 RS pools

$ipv4rspid_000

set to RS pool ID

$any_vs

set for any virtual service (likewise, there is no current IPv6 implementation)

$any_ipv4vs

set for any IPv4 VS

$ipv4vsid_000

set to ID of IPv4 virtual service

$any_rack

set, when current focus is a rack

$rackid_000

set to the ID of the current rack

$lgcn_somename

LDAP group CN. Groups are taken from user's memberOf LDAP attribute during authentication.

$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.

$untagged

Set for any entity (but except users), which __can__ have tags, but __doesn't__ have any tags set.

$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)

$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

$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.

Temporal feature (frozen)

One of new feature arriving us Temporal feature or as sometimes called Time machine.

The idea is to make almost all things (Racks, RackObjects, Ports, Links, IP Addresses, etc.) have complete history of changes. We will call those "things" just "objects". Then, if someone wants to see what was an object before, he or she would have just "rewind" the history and see what was happening some time ago. It's somewhat like Time Machine thingy in MacOS X Leopard.

Revisions

Because of most of the objects are "connected" to each other, for example, a server is mounted into a rack, it's impossible to "rewind" just one object and examine it without rewinding other objects, as it may happen, that connected objects wouldn't even exist back in time. To deal with that, we will not focus on every object version, rather than that we'll have a common timeline and every change of every object would get us a step further on this timeline.

When we say "every object", we don't actually mean "every". In fact, some objects are not "versionized" this way. User accounts are not versionized, and that's done on purpose. More interestingly, for versionized objects, not every properties are versionized. Sometimes we don't care about history of some properties. But anyways, back to the point...

So, let's say that every single change of any versionized object moves us forward on the timeline. We'll call those steps "revisions". Revision is a number that represents a point on the timeline. When revision increases we can be sure that something has changed. And, almost anytime, if revision is increased by one, only one object has changed. That's true with one exception. Revision number 0 can have many objects. It's the initial state, and if you are upgrading from previous version, you'll see a lot of objects sitting in that revision.

Operations

Sometimes, a user with a single mouseclick can change multiple objects. For example, if he remounts a server, multiple objects will be changed. To group those changes into one, operations are used. Operation is a group of revisions and only one operation is created by one button click. Operations have numbers too. Mostly, users will deal with operations and user interface represent operations rather than revisions. So for a normal user, operations are quite atomic.

Milestones

Milestones are groups of operations. They are used to finalize a set of operations. A user can set a milestone on the latest operation, like saying "Ok, i've done this work, my repository is in correct state now". Milestones can have comments, and in fact, users should write good comments when they set milestones.

The suggested practice is the following: User makes some series of changes, then he goes to the history page, reviews what is done, does more changes if necessary and sets a milestone with a good comment, explaining what was done and why. Later on, users can look at the list of the milestones and review changes done.

User interface

One major addition to user interface is the temporal panel. It provides functionality for traveling history back and forth. Here it is.

The buttons are:

1. Brings you back to one operation. If there is no operation before the current one (i.e. you are in the beginning of the history), it's disabled.

2. Brings you to the closest previous milestone. Again, may be disabled.

3. Shows the number of the current operation. If the current operation is the last one, i.e. the "head" of the history, this will be a bit greenish. If not in the head, it will be white. Like on this picture.

4. If no milestone is registered at the current operation, it will be empty. If one is set, you'll see its number.

5. Brings you to the closest next milestone.

6. Brings you to the next operation.

7. When in head, shows you the number of operations (say, changes) since the last milestone. Also brings you to the history of all changes since the last milestone if you click on it. When not in head, it will show the button that will bring you to the head, if clicked.