The tenant is one of the foundational data model elements within the 128T Session Smart router, and represents a consumer of network services. Tenancy is the logical partitioning of a network’s resources, done in the interest of restricting access to network services to only the users and groups for which they’re intended.
This document provides an overview of tenancy in the 128T router, how it is configured, and provides guidance for modeling the segmentation of a network using the 128T's data modeling language.
This document is intended for network architects, to assist them in the fomulation of a design for a tenancy structure in their network. It is also intended as a reference guide for network administrators and network operations personnel, to help understand the principles behind 128T's tenancy.
Tenancy is the logical partitioning of a network’s resources, done in the interest of restricting access to network services to only the users and groups for which they’re intended. Tenants are defined within an authority, and span each router within that authority. I.e., the services made available to that tenant can exist anywhere within the authority, irrespective of router, and the 128T solution propagates routing information throughout the tenant to advertise the service’s availability. At their core, tenants are intended to provide complete network segregation.
An example for how tenants could be used would be segregating two distinct user populations within an organization; e.g., "developers" from "administrators." Another example would be multiple customers within the AWS infrastructure; in this case, each tenant would likely be organized by customer.
Basic Tenant Workflow
To segment your network using tenants, you follow a simple, three step workflow:
- Define the tenants for your network. Strategies for how to define tenants are described later in this document, in the Tenancy Strategies section.
- Assign the rules for how a router identifies inbound traffic as belonging to a tenant. This is described in the Tenant Configuration section below.
- Selectively allow or deny tenants to your network's services using
By following this workflow, you'll grant access to your network's services only to those that should be allowed access. This is the basis of 128 Technology's approach to Zero Trust Networking: every
service expressly identifies who (via tenancy) will have a route to it.
But the 128T approach to Zero Trust Networking does not make configuring all possible sources and destinations of network traffic onerous; through the use of CIDR Services (described in the Services and Service Policies documentation, and Tenant Hierarchies (described below), you can jumpstart your network implementation right away.
As new sessions arrive at a 128T router, the router will attempt to classify the source of that session request into one of its configured tenants. This classification is done in one of three ways:
- The session request arrives on an interface that has been designated as exclusively belonging to a single tenant; this is accomplished using the per-interface tenancy approach, described below
- The session request arrives on an interface from a prefix that has been specified as belonging to a tenant (i.e., a single interface can be partitioned into separate tenants based upon subnet mask); this is accomplished using the per-neighborhood tenancy approach, described below
- The session request arrives containing 128T metadata, supplied by an adjacent instance of the 128T router, which has already classified this packet as belonging to a specific tenant
Should none of these result in a definitive determination on the tenant of the source of this session request, the session is associated with the global tenant (see the section on "Special Tenants" for more information on the global tenant). Once the tenant has been identified – either as a specific tenant, or as the global tenant – this acts as a filter into the 128T router’s FIB. Only the routes associated with that tenant are available to that user group. While this somewhat resembles the way a legacy router uses VRFs to create separate RIBs and FIBs, the segment by tenant is pervasive among all routers within an Authority by design, and is applied ubiquitously among all varieties of networks: public IP space, private, cloud, IPv4, IPv6, etc.
Viewing a Router's Tenancy
The PCLI command
show tenant members is used to display the rules for tenant assignment on any router. For each interface on the target router you will see the tenant assignments based on the source address of the inbound packets.
The 128T data model includes the ability to construct hierarchical tenancies, where a “parent” tenant may have one or more “child” tenants. This hierarchical tenant model allows administrators to create arbitrary groups of tenants and apply policies to that group as a whole, rather than piecemeal. Creating groups of tenants affords the maximum flexibility and minimizes the amount of redundant configuration, as well as improving overall readability of the configuration.
The 128T system uses a dotted notation naming scheme for grouping hierarchies of tenants. For example, a tenant named
engineering.128technology is a child of the tenant
128technology. Wherever other configuration objects refer to tenants, the effective scope can be controlled by specifying only a portion of a tenant’s name. For example, a service that specifies
128technology within an
access-policy is available to
128technology. However, the policy is applied in only one direction, from parent to child: a service accessible only to
engineering.128technology will not be available to members of the general
Tenant hierarchies are configured in virtually every 128T deployment. The most common implementation is to configure a top level enterprise tenant; this lets administrators easily grant access to corporate services to all tenants with a single
It is not necessary for an administrator to explicitly create a “parent” tenant prior to creating a “child” tenant (the UI will perform validation and warn an administrator that their action of creating a child tenant will also create a parent tenant). The UI will prevent the deletion of a parent tenant if it has any child tenants.
Tenant hierarchies can have an unlimited number of tiers, although it is generally unnecessary to have more than two or three levels of parentage. For recommendations on tenancy and organizational tips, refer to the Tenant Strategies section below.
Each tenant configured on a 128T conductor is propagated to all managed assets, irrespective of whether that router has any configuration (via interface definition or neighborhood definition) to assign that tenant to inbound traffic. This is because a 128T router can receive Secure Vector Routing (SVR) sessions from a peer, identifying the origin as belonging to a permissible tenant.
For example, a branch router may segment its traffic into several, well-known tenants: employee workstations are in a tenant named
workstations.acme and their VoIP phones are in a tenant named
voice.acme. There are no employee workstations or VoIP phones at the corporate data center, but the head end router there needs to understand how to forward sessions for these traffic segments. Thus the head end is aware of the existence of these tenants for access control and traffic forwarding purposes.
Assigning a tenant to a
network-interface will cause all traffic arriving on that interface to be considered part of the tenant. Consider the following configuration fragment:
Assigning tenant membership using neighborhoods requires two distinct, coordinated configuration elements. First, you define one or more neighborhoods within a network-interface. (Conceptually, a "neighborhood" is a named, Layer 3 routed network.) Second, within one or more
tenant configurations you define which prefixes in that neighborhood are to be considered "members" of that tenant.
Here is a basic neighborhood configuration, as seen on our branch router:
In this example we've used the neighborhood name "internet" on the WAN interface of the branch router. (This is a common, and recommended neighborhood name with 128T devices attached to the public internet.)
Here are several
tenant definitions to illustrate how to define tenancy within that neighborhood:
We've created two tenants,
VA.Europe, and within each tenant's
member block we've indicated that within the neighborhood (router Layer 3 network) named
internet, the sets of IP addresses that are allocated for these two countries.
Thus, if an inbound session arrives from the IP address 188.8.131.52 on an interface that is "in" the
internet neighborhood, it will be considered to be part of the
Yes, these are really the IP addresses associated with Christmas Island and Vatican City. No, you cannot fill out the rest of the world's GeoIP addresses as tenant members. You'll almost certainly run out of space in your tenant table (officially called the "source tenant table"). You can see how much room you have in your source tenant table as well as its current utilization by using the PCLI command
The 128T Session Smart software has several tenants it creates automatically. These tenants are used for specific software functions, and have special meaning described here.
The Fabric Tenant
When combining two nodes into a highly available router (dual node high availability), it is commonplace – and recommended – to configure a "fabric" interface between them. A 128T router with a fabric interface will use install the special
<fabric> tenant on the fabric interface. This is neither user-configurable nor user-modifiable. This tenant can be seen in the output of
show tenant members as shown here:
The Global Tenant
The "global tenant" is what a 128T router will use when it cannot determine the tenant of an inbound session, based on the configuration it has. This means three things must be true:
- The session is arriving on an interface with no tenant assigned; and
- The session is arriving on an interface with no applicable per-neighborhood tenant; and
- The session is not carrying metadata from a previous 128T instance that has a tenant identified
Said another way, the global tenant "fills in the holes" in the tenancy on an interface without a tenant explicitly defined, and which uses neighborhood-based tenant assignations.
The global tenant is not user-modifiable, and administrators cannot create
access-policy configuration stanzas that reference the global tenant. Instead, access to a service by the global tenant is controlled through the use of the
scope toggle within a
service configuration. Setting
public is semantically equivalent to having an
access-policy that allows the global tenant. Setting
private will only allow tenants that have been explicitly granted access via
The global tenant can be seen in the output of
show tenant members as shown here:
The Internal Tenant
The internal tenant (named
_internal_), is arguably the most useful of all of the special tenants. It is immutably assigned to the built-in Kernel NIC Interface (KNI) named
kni254, which is used for communication to and from the Linux host operating system on the platform on which the 128T software is running.
By adding an
access-policy allowing (or denying)
_internal_ on your service, you can selectively permit processes running in Linux outbound network access. This is commonplace for "host originated" traffic, such as DNS queries, outbound SSH connections, SNMP traps, syslog, etc. The
_internal_ tenant is also critical to the success of Conductor Host Services, described in our documentation; this is because the outbound
salt-minion and NETCONF requests destined for the conductor are initiated within the Linux host operating system.
For more information on
kni254 and the
_internal_ tenant refer to the section in our documentation titled Linux Host Networking.
Designing a scalable, cohesive tenant strategy is one of the primary keys to success with a 128T-powered network. This section of the guide, assuming you are migrating an existing network to one powered by 128T, will help you perform the following tasks:
- Establish a basic tenancy framework for your network topology
- Identify sources of existing segmentation data
- Migrate data into the 128T data model
- Refine and adapt the design
Before You Begin
There are several steps you can take at the outset of designing a tenancy strategy to improve your chances for success. These are:
- Assess the current security profile of your network. Because tenancy lets you segment (partition) your network, it will act as the guard rails around how consumers access network destinations.
- Choose an appropriate baseline tenancy model.
- Plan for a "discovery process" to identify the rules at each site to map to your baseline tenant structure.
Assess the Current Profile
Assessing your current security profile entails identifying the unique categories of users/devices at all of your locations. We recommend to do one location "type" at a time; e.g., start with your similarly-equipped branch offices. For each of the different site types in your network, list out all of the different major categories devices on the network. For typical branch office deployments, this will include things such as:
- Employee workstations (including such things as point-of-sale systems, etc.)
- Guest wifi
- IP phones
- Various "things" such as security cameras, printers, scanners, etc.
- Application servers, DHCP servers, DNS servers, and other network services
The objective for this profiling is to group the devices into categories, where a category contains devices expected to have roughly equivalent network policy. A tenant (network segment) carves off access for all of its devices equally; two devices belonging to the same tenant will have equal network access. Thus, it is important to categorize the devices based on which of them share common profiles.
To baseline your tenancy model, it is not necessary to perform exhaustive research, to identify (for example) what distinguishes a finance employee's workstation from a developer's workstation – we'll get to that in future iterations of the tenancy design. For now, we're just interested in establishing the basic framework.
Choose a Baseline Model
A standard baseline for all tenancy models is to consider:
- Trusted devices: equipment that is generally given access to internal systems and applications hosted by the enterprise. While the equipment may have some access restrictions, it is generally trusted. E.g., employee workstations
- Untrusted devices: equipment that is not trusted by default, and will typically only have access to the internet. E.g., guest wifi
- Restricted devices: equipment that may be on a trusted network, but should ideally have limited network access based upon its type. This also includes limited function devices in your DMZ network); e.g., "things"
Collate the different devices that you enumerated in your profiling exercise into these three categories. We will refine the model later, to provide differentiation between devices within each category.
Last is the process for site-specific discovery. For each of the major categories of devices at your site, understand how (or if) each site has rules in place for assigning devices today. Look for things such as:
- VLAN assignments. Usually sites will have distinct VLANs for trusted traffic, guest wifi, VoIP services, etc. Map each of the specific VLANs to your tenants. For VLANs that are entirely comprised of one variety of device (typical with guest wifi and voice), assign that tenant directly to the
network-interfacefor that VLAN on your 128T
- DHCP scopes/IPAM systems. How does the site issue out IP addresses? Does the DHCP server give out specific addresses to specific categories of equipment? Use the intelligence provisioned in the DHCP server to model that same configuration in the 128T. (And while you're at it, consider moving DHCP services to the 128T.)
- NAC. If your site has a NAC, presumably it has configuration rules in it that can identify how the equipment is deployed at that site.
The goal for the site discovery is to understand the rules for how IP addresses are assigned at the site and ensure the 128T model matches. For environments where there is a lot of homogeneity in the site (e.g., financial institutions, retail, oil and gas, etc.), the rules for IP assignment are usually predictable and well known. Use that information to your advantage, to bootstrap the discovery process.
Refining and Adapting the Design
Now that you have a basic design in place, consider each category to understand the similarities and differences with each of the items you've placed into that category. For example, you've identified employee workstations in the "trusted" category, but there are many types of employee workstations. There are workstations that are used by the finance team that have access to payroll systems and sensitive back office data. There are workstations used by your internal development team that have access to source code repositories and test harnesses. And there are workstations used by your IT team that need access to absolutely everything.
This is where you refine and adapt the design. For each category, establish the common policy associated with all of them. In our case, all of the workstations need access to the internet and to the corporate intranet. We will use the tenant
workstations and apply it as the
access-policy for the internet/intranet services.
We will create the child tenants for each subcategory (
it.workstations, etc.) to selectively allow/deny access to specific services needed by those user populations. Within each of these subcategories we can further differentiate between user personas or roles.
General Considerations and Best Practices
Regardless of which baseline model you choose, there are some general considerations we recommend for all deployments.
- Make tenancy ubiquitous on LAN-side interfaces; everything entering into the LAN side interface of one of your 128T devices should have a tenant defined.
- Create an enterprise-wide tenant to be used as the "parent" to quickly allow or deny network service access to your entire user population.
- If you have a lab environment that can faithfully reproduce a branch location, create lab-specific prefixes for each of your baseline tenants as described in Application Discovery on the 128T.
- Start with basic categorization, and don't get too fancy out of the gates. We can (and inevitably will) refine the model over time, as we start to learn more about how the network works.
- When in doubt about how to categorize your tenants, use a service-oriented approach. List the services you want to make available to each of your network constituents. When you find significant overlap between any subsets of these constituents, consider organizing them into hierarchies to simplify the configuration model.
Use Case: Retail SD-WAN
A nationwide retail franchise ("Acme, Inc.") is adopting 128T across their environment to provide SD-WAN services. The retail franchise has three different types of sites:
- Legacy Acme stores
- The "green stores," a retail franchise acquired by Acme in 2012
- The "yellow stores" acquired by Acme in 2018
The Network Architecture team at Acme did site surveys of all of the equipment in place at all three site varieties and came up with the following list:
- Cash registers (point-of-sale systems), also responsible for inventory moves/adds/changes
- Security cameras
- Handheld barcode scanners
- Employee wifi for BYOD
- Guest wifi access points
- VoIP phones
The team categorized things as follows:
- Trusted: cash registers, barcode scanners, BYOD
- Untrusted: guest wifi access points
- Restricted: security cameras, VoIP phones, printers
This lent itself to the following tenant model:
acme: the parent tenant for all devices at the retail locations
trusted.acme: the parent tenant for all trusted devices, used for common network policy (such as internet offload, service function chaining, etc.)
byod.trusted.acme: employee-owned BYOD
pos.trusted.acme: the point-of-sale systems
handheld.trusted.acme: the handheld scanners
guest.acme: the guest wifi
voice.acme: the voice equipment
restricted.acme: security cameras, printers, etc.
Notes about the Model
The Network Architecture team realized they have a very simple network at each of their retail stores, and kept the model basic. They needed to make some tough decisions, and here was their thought process:
- Decision: how to categorize BYOD? Employees frequently bring in their own smartphones and tablets to work with them, and modern employers embrace the gains in productivity. But these are not company-owned devices. Should they be considered untrusted or trusted? In the end they decided that the BYOD need access to a lot of core services common with the customer-managed POS systems, so they consider them as part of the
trustedhierarchy. However, by breaking them out into their own category (
byod.trusted.acme) they can add
access-policystanzas to deny the tenant from services that are too sensitive to trust to BYOD.
In the end they decided the overlap between BYOD and POS was greater than the overlap between BYOD and untrusted; thus, it is easier to selectively deny it access to sensitive services than to selectively permit it access to trusted services.
- Decision: why is voice its own category? Voice over IP uses networks in a peculiar way, with no predictable port usage, sessions initiating asymmetrically, and a mix of transport protocols. Also, in most deployments voice is broken out into its own VLAN. For services that are isolated and relegated to their own VLAN, it is simplest to carve out a top-level tenant for it.
The Architecture team then went through each of the three store types, to understand how to map the devices into these core tenants. They found that each of the three varieties of stores (legacy, green, yellow) used different IP allocation strategies for everything. Legacy stores had everything segmented by VLAN. This made the mapping exercise straightforward for the team: each VLAN could be mapped to a single tenant cleanly.
The green stores had a VLAN for voice, but used DHCP scoping to assign IP addresses to everything else based on role. The network team decided to keep this enforcement, and migrated the DHCP to the 128T using the same rules. The team then used per-neighborhood tenancy to segment the traffic. The yellow store design... well, that was a bit of a mess. There was very little control in place, with all traffic comingled on the same per-store
From the surveys, they created three configuration templates, segmenting the traffic according to the VLAN
In the end, the tenant model is flexible and there is no "one correct way" to organize your devices. Do what works best for you and your network. In the end, readability and the ability to easily document and train your hierarchy to your colleagues will outweigh a perfectly manicured, but hard-to-understand structure.