Endpoints

An endpoint is a single network device tracked by Taranac, keyed on its MAC address. Endpoints are the central objects of network access control: they are discovered (or added by hand), classified into one or more endpoint groups, and those groups become the conditions your NAC policies match on. A printer that lands in the Printers group can be put on the printer VLAN; a personal phone in BYOD can be given restricted access; an unrecognised device in Unclassified can be denied or quarantined.

This page covers how endpoints appear in Taranac, how classification rules sort them into groups, the OUI vendor database that powers vendor matching, and the day-to-day admin actions — adding a device by hand, block, and reassign.

status reflects where the endpoint sits in its lifecycle:

• known — recognised and classified into at least one group.
• unknown — seen on the network but not yet matched by any rule; waiting in Unclassified.
• blocked — denied by an administrator (authentication is rejected).
• inactive — not seen for a long time; hidden from lists by default.

persistence_type decides whether automatic cleanup may ever remove the endpoint:

• static — added manually, imported by LDAP computer sync, or pinned. Never auto-deleted.
• dynamic — discovered automatically (RADIUS, certificate). Eligible for cleanup once inactive.
• guest — created through a guest captive portal. Cleaned up after the guest session expires.

Taranac populates the endpoint table from several built-in sources. Each source it has seen the device through is recorded as a separate discovery record under the endpoint, so you can tell why and how a device is known.

The OUI prefix is derived from the MAC — the first three bytes — when the endpoint is created, and the MAC is immutable afterwards: it is the endpoint’s identity, which is why no form offers to edit it. The vendor name is looked up in the OUI database when a device is discovered, and again by classification whenever a rule needs a vendor and the stored row does not carry one.

The endpoints list — MAC, name, status, persistence, groups, vendor, IP, hostname, last seen and Used by. Columns can be hidden and their borders dragged; every list remembers its own widths in the browser.

Used by on an endpoint is informational: it lists the groups the device is in, and deleting the endpoint simply removes those memberships. On an endpoint group the same column can block a delete — see endpoint groups.

Groups are how you organise endpoints into policy-relevant buckets. Taranac ships with a set of seed groups so the system is useful on day one.

Two groups are system groups and cannot be deleted:

• Unclassified — where every new endpoint lands until a rule matches it.
• Blocked — blocked endpoints.

The rest are ordinary, editable seed groups: Corporate Devices, BYOD, Printers, IP Phones, IoT / Sensors, Security Cameras, and Guest Devices. Each carries a colour and icon for the UI, and you can create your own (for example, a per-location Building A group).

Because an endpoint can belong to multiple groups at once, you can classify along several independent axes — device type and location and access tier — without the groups fighting each other.

Endpoint groups — system groups (Unclassified, Blocked) plus editable seed groups, each with a member count and a Used by count. Re-apply rules runs classification over every endpoint without waiting for them to authenticate again.

A group is not deleted out from under the things that name it. Two checks run before the row goes:

• It must be empty. A group that still has members is refused, and the message says how many. Empty it from the group’s own Members panel first. If the members are there because a rule put them there, delete the rule too, or the next classification pass puts them straight back.
• Nothing may depend on it. The Used by column shows where the group is referenced, and a group used as the WHAT condition of a NAC policy rule cannot be deleted at all: the refusal names the rules instead of failing with a database error. A captive portal that assigns endpoints to the group is listed too, but does not block — deleting the group just clears the portal’s target.

System groups (Unclassified, Blocked) have no delete action at all.

A classification rule lives on a group and says: any endpoint matching this condition belongs in this group. Taranac evaluates rules with all-matches semantics — there is no priority and no “first match wins”. Every enabled rule that matches fires, and the endpoint joins every group whose rule matched. If nothing matches, the endpoint stays in Unclassified.

This is deliberate: you never have to reason about a global ordering of all rules across all groups to predict where a device lands. Rules are independent.

For vendor_name and oui_prefix, the rule form offers a searchable picker backed by the OUI database, so you can find a manufacturer or prefix without typing it from memory and see how many MAC prefixes a vendor owns. For cert_issuer, you pick a CA from a list rather than typing a DN. For the two directory types, the form browses the directory itself — see directory-based classification.

When a device authenticates with EAP-TLS, Taranac extracts the certificate issuer and identity from the RADIUS exchange and runs classification immediately — the device is sorted into the right group as an in-memory decision on its very first authentication, without waiting on any database write. The resulting endpoint and certificate record are then persisted off the authentication path: the write is enqueued to an async writer and lands on the next cache refresh, so the auth reply is never held up by a database write (this also keeps authentication answering from cache during an HA failover). Classification is therefore effective at authentication time, even though the stored row appears a moment later. On later, non-TLS authentications, the stored certificate data is reused.

For cert_issuer rules, the CA you selected is resolved to its subject DN and compared to the endpoint’s issuer using DN normalisation, so both OpenSSL one-line form (/DC=pro/DC=taranac/CN=Root CA) and RFC 2253 form (CN=Root CA,DC=taranac,DC=pro) compare equal. If the CA is later disabled or deleted, the rule stops matching.

Two match types read the directory rather than the wire: ldap_dn asks where the machine’s object sits, ldap_group asks which groups it is in. Between them they replace the hand-maintained list — “every machine under OU=Workstations gets this profile” — that had no expression before 1.2.7.

Both need the machine’s endpoint to be linked to a directory object, which is what computer sync does. ldap_group additionally needs Group membership switched on for that connection; a directory that does not collect it can never satisfy such a rule, and the rule form says so instead of saving something that would silently never fire.

An ldap_dn rule being written. The directory comes before the value on purpose: it decides which tree the picker walks, so choosing it second would mean picking a DN out of one directory and then pointing the rule at another.

Every directory rule names its directory. With more than one forest joined, the same DN exists in several of them, and an unscoped rule is how a machine from one domain lands in a group written for another with nobody finding out. The form’s directory list offers the connections that have computer sync enabled, and offers no “any directory” option — two forests that want the same thing get two rules.

The value is a container, chosen from the directory tree, and the rule covers that container and its whole subtree. Matching compares DN components, not characters: a rule for OU=Computers does not also capture OU=Computers-Test, which a plain “ends with” would have done — quietly widening every rule you write. Spacing and letter case in the DN do not matter, since directory tools copy DNs in more than one style.

The picker deliberately offers containers only, never an individual computer, although a rule holding one machine’s full DN would work:

1. A container with thousands of machines makes an unusable tree to pick one from.
2. A DN naming a machine stops matching the moment that machine is renamed or moved — silently. exact_mac says the same thing and never breaks.
3. Only the first network card to authenticate is bound to the directory object, so a per-machine DN rule would miss a laptop’s second interface and look like a product defect.

The rule stores the group’s immutable identifier, not its name and not its DN — either of those would stop matching the day somebody renames or moves the group, and stop silently, since the rule would still be perfectly valid. You never see or type that identifier: the picker browses the directory and shows DNs, and the rule form translates back when it displays a saved rule.

The picker browses the directory live rather than listing the groups already collected, so you can write a rule for a group no machine has joined yet — otherwise you could only ever react to a rollout, never prepare for one. A group that has not yet been seen by a sync is shown as exactly that, not as an error.

Nesting is resolved when membership is imported, not while matching: the endpoint holds a flat set of groups, so a rule written against an outer group matches a machine that is only a direct member of an inner one. How each directory type answers the membership question — and why Active Directory’s primary group is invisible to it — is covered in LDAP directories.

When a rule does not fire and you want to know why, open the endpoint and expand its LDAP discovery record: it lists every group the directory reports for that machine, not only the ones some rule happens to name — which is a different question from “what did the rules do”, and the one you actually need answered. An empty list is an answer too: either the machine is in no group, or membership collection is off for that directory. Machines still waiting in Pending Computers have no endpoint to hang membership on, so they have no groups either.

MAC addresses and vendors never change while a device is connected; an OU or a group does. Classification therefore no longer runs only at authentication:

• a pass over the affected directory runs automatically after each computer sync;
• Re-apply rules on the Endpoint Groups page runs one on demand, after you edit a rule.

An endpoint that gets its directory data late is handled without a pass: on Active Directory, where a pending computer is bound to an endpoint only when the machine authenticates by certificate, that binding re-runs classification with the DN it has just written — so a ldap_dn rule fires on that first authentication instead of waiting for the next one.

A pass checks every endpoint against every enabled rule and updates only rule-assigned membership. Groups you assigned by hand are left alone, and rule hit counters are not touched — the “is this rule doing anything?” signal would drown in a bulk pass.

Out of the box Taranac seeds vendor-based rules so common devices classify themselves:

Taranac includes a classification tester, which shows exactly which groups a device would join and which rules fired — grouped by target group, with no side effects. It runs in one of two modes, and the choice matters more than it looks:

The tester’s two modes. Each field states which match types it exercises, so an empty one is a rule the test is not covering rather than a rule that failed.

A hypothetical device. You supply every fact yourself: a MAC, and optionally a vendor override, certificate identity, certificate issuer, hostname, or a directory DN and the directory it belongs to. This answers “would a device like this match?”.

MAC:           80:5E:C0:11:22:33
Vendor:        (auto-resolved from OUI, or override here)
Cert identity: PC-LAB1.taranac.pro
Hostname:      PC-LAB1
Directory DN:  CN=PC-LAB1,OU=Workstations,DC=corp,DC=local
Directory:     corp (the connection the DN belongs to)

An existing endpoint. You pick one endpoint and the server reads every fact from the stored record. This answers the question people actually ask — “why is this machine not in the group?” — which the hypothetical mode structurally cannot: it only ever confirms what you typed into it, and will not tell you that the endpoint has no directory DN yet, or that its computer object is still sitting in the pending table. Group-membership (ldap_group) rules can only be exercised this way, since membership is imported, not typed.

The two modes are mutually exclusive; mixing an endpoint with hand-typed facts is refused rather than silently resolved one way or the other.

The OUI database is a local copy of the IEEE MA-L registry — roughly 35,000 MAC-prefix-to-manufacturer mappings. It does two jobs: it fills in the vendor name on every endpoint, and it powers vendor_name and oui_prefix classification rules and their search pickers.

• First start — Taranac tries to download the registry from IEEE, and falls back to a bundled snapshot if IEEE is unreachable, so vendor lookups work even offline.
• Weekly refresh — an automatic weekly sync from IEEE keeps it current (controlled by the nac.oui_auto_update setting).
• Manual refresh — you can trigger an update from IEEE on demand. If IEEE is temporarily unavailable the request fails cleanly and the existing data is left intact.

Auto-VLAN printers. Leave the seed Printers rules in place (HP, Canon, Epson, Xerox, Brother). Any printer from those vendors classifies into Printers on first sight; point your NAC policy for the Printers group at the printer VLAN. New printers from a vendor not yet covered: add one vendor_name rule.

Corporate machines by certificate. Issue machine certificates from your internal CA and add a cert_issuer rule on Corporate Devices selecting that CA. Every domain machine that authenticates with EAP-TLS lands in Corporate Devices on its first authentication — far stronger than matching by MAC, which can be spoofed.

BYOD by certificate identity or hostname. A cert_identity_pattern of *.byod.corp.local, or a hostname_pattern like IPHONE-*, can funnel personal devices into BYOD for a restricted access profile.

Cameras and IoT segmentation. The seed Security Cameras (Hikvision, Dahua) and IoT / Sensors (Raspberry Pi, Espressif) rules give you ready-made groups to drop onto isolated segments.

Machines by where they live in the directory. Add an ldap_dn rule on Corporate Devices pointing at OU=Workstations and every machine below it classifies automatically — including machines moved into that OU later, once the next computer sync or Re-apply rules runs. Add a second rule for OU=Kiosks on a locked-down group and the two stay separate without a single MAC being typed.

Machines by a group you already maintain. If your directory already has a Lab-Machines host group, an ldap_group rule on it means the access profile follows the group: add a host to the group in the directory, and Taranac follows on the next sync. Turn on Group membership for that connection first.

Location plus type. Create a Building A group with an oui_prefix or mac_pattern rule, and keep the type-based groups too. A camera in Building A ends up in both Security Cameras and Building A — match either or both in policy. This is exactly what all-matches semantics enables.

You can create an endpoint manually by entering its MAC, an optional name and description, and the groups it should join. Manually created endpoints are static, so they are never cleaned up automatically. Manual creation assigns only the groups you choose — it does not run classification rules — so pick the groups explicitly.

Each endpoint offers one-click actions:

Reassign is a replace-set operation: the list you submit becomes the complete membership. The server works out which memberships to add and which to drop, and records the change in the audit log. All quick actions are idempotent.

The same operations are available in bulk over a selection of endpoints — bulk delete, bulk block, bulk pin, and bulk reassign.

• NAC overview — where endpoints fit in the access-control flow.
• Policy — using endpoint groups as authorisation conditions.
• Authentication — the 802.1X / MAB / EAP-TLS flows that discover endpoints.
• Captive portal — guest and BYOD registration that creates endpoints.
• PKI — the CAs referenced by cert_issuer classification rules.
• LDAP directories — computer sync and group membership, the source of ldap_dn and ldap_group matching.
• Deployment bundle & docs: github.com/TaranacLabs/taranac