Namespace Overview

The fundamental unit of configuration in the Cordboard VSS is the namespace. A namespace is a complete, self-contained switch and dial plan: its trunks, lines and devices, translation rules, routes, voicemail, ring groups, and policies all live together in one configuration document, and every call the switch handles is processed inside exactly one namespace at a time.

You can think of a namespace as a distinct, independent switch or PBX living within the system:

• If you are a class-4/5 carrier, a namespace is a switch: it terminates your subscriber trunks, applies digit analysis and jurisdiction-aware routing, and hands traffic to your carrier interconnects.
• If you are running a hosted PBX, a namespace is one customer’s PBX: its extensions, hunt groups, voicemail boxes, and outside lines.
• If you are a reseller, each of your customers gets their own namespace under yours, and you push shared configuration down to them.

Nothing in one namespace can see or collide with another: every resource (a line, a trunk, a translation context) is named within its namespace, and device registrations are qualified by the namespace’s SIP realm — two tenants can both have an extension 1001 without conflict.

Where a namespace sits

Partition  (billing / account container)
└── Namespace  (root)
    ├── Namespace  (child)
    │   └── Namespace  (grandchild)
    └── Namespace  (child)

• A partition is the top-level container of an individual account with Cordboard, created when you are provisioned. It carries account-wide limits defined by your contract with us — a partition-wide concurrent-call cap, and allow-lists constraining which SIP realms and edge-proxy IPs your namespaces may use. You do not edit partition settings yourself, and you should contact your provider or Cordboard account representative if you need to make changes.
• Namespaces live inside the partition, arranged in a parent → child tree. A single-tenant deployment is just one root namespace; a reseller or carrier deployment grows the tree downward, one namespace per customer, sub-tenant, or subordinate switch.

Calls cross between namespaces only where a namespace linkage permits it — the parent–child edge doubles as a call-transfer boundary with its own access control, translation contexts, and caller-ID presentation policy. This is how an arbitrarily deep hierarchy still behaves as one unified network: a child hands off-net calls up to its parent (typically via a granted pstn alias), and the parent delivers DIDs down into the child.

Handoff is deny-by-default

A namespace does not accept calls from another namespace — including its own children — until its linkage explicitly allows it. If everything on-net works but off-net calls are rejected, the inbound-transfer permission on the parent side is the first thing to check.

The configuration document

Everything a namespace declares lives in a single YAML document. The document is versioned: every edit produces a new immutable version, and a version must be explicitly applied to become the running configuration — the one calls are actually processed against. Storing a version and running it are separate steps, so you can stage, validate, tag, and review changes before they take effect. The full lifecycle (versions, tags, validation, apply, rollback) is covered in the configuration management articles.

Two views of the document exist for every version:

• Your authored configuration — exactly the YAML you wrote.
• The effective configuration — your YAML after inherited configuration from your parent namespace has been merged in. This is what actually runs.

Top-level sections

The document is a set of named sections. Each is covered in its own article:

Section	What it declares
translations:	Digit analysis — match / modify / target rule chains
screening-contexts:	Per-line destination screening (toll restriction)
special-number-profiles:	Early-matched emergency/priority numbers (911)
caller-id-contexts:	Match/modify rules on presented caller-ID
feature-codes:	Star-code maps for lines
routes:	Outbound trunk selection strategies and LCR
trunks: / trunk-profiles:	SIP trunk interconnects and their shared settings
lines: / line-profiles:	Subscriber lines and their service classes
devices:	SIP endpoints, each bound to a line (see Lines)
ring-groups:	Hunt groups
voicemail-boxes: / voicemail-contexts:	Mailboxes and voicemail policy bundles
recordings:	Named audio recordings playable as call targets
namespace-profiles:	Reusable inheritance bundles offered to child namespaces
ns-linkages:	Per-peer transfer policy and child inheritance grants
stirshaken:	STIR/SHAKEN signing and verification policy
configuration:	Namespace-wide key/value settings (this article, below)

One section you will see in effective configuration but must never author yourself: received-aliases: is materialized by the system from your parent’s grants (it is how a friendly alias like pstn resolves to a real namespace). Anything you write there is discarded.

Resource authority: document vs managed

At creation time, every namespace is fixed into one of two authority modes for its subscriber-cardinal resources (lines, devices, trunks, ring groups, voicemail boxes, and linkages):

• document — the resources are authored directly in the YAML sections above. The right choice for most: the whole dial plan is one reviewable, versionable document.
• managed — the resource sections are rejected in YAML and are instead managed individually through dedicated REST endpoints. Built for very high line-count namespaces (tens of thousands of subscribers) where a single document is impractical.

The mode is chosen when the namespace is created and is immutable for its lifetime. In both modes, the non-resource sections (translations, profiles, policies, configuration:) remain YAML-authored.

Selecting a mode

The hard limit for a document-mode namespace is 10M of YAML configuration. The recommended rule of thumb is 10,000 lines and trunks max in a single document-mode namespace. Though you may be able to add more, if you expect to cross this threshold, you should use managed mode.

Additionally, if you primarily intend to provision new lines, trunks, or tenant namespaces programmatically, managed mode is likely a better fit, as it has distinct REST endpoints for each resource type, instead of relying on YAML patches against the main document.

Finally, Document mode also includes changes to lines, subscribers, and trunks in the version controlled history, meaning that these subscribers may be added or removed if you restore a historical version that predates their creation. If this is undesirable for your use case, you should use managed mode.

Inheritance, conceptually

A parent namespace can push configuration down to its children. The intent is the reseller/carrier workflow: define your standard line profiles, translation contexts, screening rules, and voicemail policies once, and have every customer namespace receive them automatically — while each child stays free to add its own configuration on top.

The shape of the model:

• Only reusable, template-like sections are inheritable: translation contexts, screening contexts, line profiles, trunk profiles, voicemail contexts, caller-ID contexts, feature-code maps, special-number profiles, and namespace profiles themselves.
• Concrete resources are never inherited. A parent’s lines, devices, trunks, ring groups, voicemail boxes, routes, recordings — and its STIR/SHAKEN policy and configuration: map — never appear in a child. A child’s subscribers and interconnects are always its own.
• The parent chooses what each child receives by attaching a namespace profile (a named bundle of section selections plus granted aliases) to the child’s linkage. What a parent authors reaches a child only through such a grant; what a parent itself inherited flows on to its children automatically.
• The child’s own definitions win. Inherited sections merge underneath the child’s document; where names collide, the child’s definition replaces the inherited one, key by key.
• Aliases are granted, not built-in. Friendly names like pstn (and self, the parent itself) only exist in a child because the parent granted them. A pstn route target in a namespace that was never granted the alias simply fails.
• Parents can also impose limits a child cannot override from its own YAML: a concurrent-call cap, and allow-lists restricting which sip-realm and edge-proxy values the child may configure.

The exact mechanics are covered in Namespace Profiles (what is selected and how the merge is processed) and Namespace Linkages (the transfer permission model and the inheritance grant).

The configuration: map

The top-level configuration: key is a flat map of namespace-wide settings. All values are strings, so quote them:

configuration:
  sip-realm: "acme.example.net"
  edge-proxy: "198.51.100.10"
  max-concurrent-calls: "200"
  cleanup-mailboxes: "true"

The configuration: map is never inherited — every namespace declares its own, and sip-realm / edge-proxy are required in any namespace that declares resources.

sip-realm (required)

The namespace’s SIP domain. Devices register against it — a device’s address-of-record is device-name@sip-realm — and it is the domain your endpoints must be provisioned with. Because registrations are qualified by realm, your extension numbering never collides with another tenant’s.

Your provider may constrain which realms you can use (your partition’s allowed-realm list permits each listed realm and its subdomains); a value outside the allowed set is rejected at validation time.

Changing sip-realm re-provisions every device

Registration identities and Digest credentials are both bound to the realm (the stored credential is a hash of user:realm:password). Applying a config with a new realm tears down every existing device entry and recreates it under the new realm in a locked-out state: all registrations drop, and every device credential must be re-minted and pushed to the endpoints before they can register again. Treat a realm change as a full device re-deployment, not a rename.

DNS

It’s not strictly required to even configure DNS for the sip-realm, but it’s highly recommended to configure the A and SRV records for this realm to point towards the configured edge-proxy. This enables SIP clients to register devices using the standard username@sip-realm format without having to configure an outbound proxy.

sharing sip realms

The system will not stop two namespaces which are both permitted to use the same sip-realm from sharing it. This can be desirable if, for example, you would like to shard customers across multiple namespaces while maintaining a unified customer facing presentation. It can create issues however: if two namespaces share the same realm, you may get a conflict error when attempting to create a peer on a namespace.

edge-proxy (required)

The anycast IP address assigned to this namespace by your provider. This is the single IP you point everything at — your carriers send inbound calls to it, your devices register to it, and your outbound calls are sourced from it, from every region. Set it exactly as assigned; like sip-realm, the value is validated against your partition’s allow-list.

The value does double duty inside the switch:

• It is the address the switch dials out through for every leg your namespace originates.
• It scopes your trunk IP authentication: a trunk peer is identified by the pair (source IP, your edge-proxy IP). That is what lets two different tenants receive traffic from the same carrier source IP — each owns the pair with their own edge IP. It also means traffic from your authorized IPs must arrive at your assigned edge IP; the same packets aimed at another tenant’s IP are rejected.

You do not need multiple IPs for redundancy

The single edge proxy IP is automatically spanned across every physical node in every region in our datacenters using IP anycasting technology. A single IP will survive not only hardware but entire region failures. If you’re used to deploying several signalling IPs for redundancy, you need not worry about this with the Cordboard VSS.

IP auth boundary and sharing

Two tenants who are not permitted to configure trunks can safely share an edge proxy IP. Registrations are scoped based on the configured sip-realm, so a devices-only namespace can share without issues. If, however, a namespace will be configuring it’s own trunks, especially it’s own outbound trunks, it must use it’s own edge-proxy. Not only will the switch prevent it, but it would allow toll fraud.

max-concurrent-calls (optional)

The namespace’s concurrent-call cap, as a non-negative integer. Absent or "0" means unlimited. When the cap is reached, further calls receive the all-circuits-busy treatment (fast busy; SIP 503, Q.850 cause 34).

Three things to know:

• The count covers your whole subtree. A call active in any descendant namespace counts against this namespace’s cap, so a reseller cap of "500" bounds the sum of all its customers’ traffic, not just calls the reseller namespace handles directly.
• Your parent may impose its own cap on you through its linkage grant. The enforced cap is the minimum of your own value and the parent-imposed one — you can restrict yourself further, but you cannot raise what your parent set.
• The partition-wide cap applies on top. It is enforced across every namespace in your (or your provider’s) account, independently of any per-namespace values. If you’re experiencing call rejections that don’t match you’re configuration, contact your provider or Cordboard account representative.

Per-trunk, per-line, and per-profile caps are separate, resource-level settings covered on the trunk and line profile pages.

cleanup-mailboxes (optional, default "true")

Controls what happens to a voicemail box’s stored state — messages, greetings, and PIN — when the box is removed from the configuration and the new version is applied:

• "true" (the default): the box’s storage is permanently deleted at apply time.
• "false": the storage is left behind as an orphan box — invisible to callers, but recoverable through the voicemail administration API, which can list orphans, read or delete their messages, rehome one into an active box (the recovery path for a renamed box), or purge them.

The default deletes messages

With cleanup-mailboxes at its default, removing a mailbox from your YAML — including renaming it, which is a remove-plus-add — destroys its stored messages and greetings on apply. If you rename boxes or want an undo window, set cleanup-mailboxes: "false" and purge orphans on your own schedule.

Note the scope: this flag only governs config-removed boxes. Re-applying a configuration that still contains a box never touches its messages, PIN, or greetings.

A minimal namespace

Putting it together — the smallest useful shape of a namespace document:

configuration:
  sip-realm: "acme.example.net"
  edge-proxy: "198.51.100.10"

translations:
  from-lines:
    "100":
      match:
        - ast-pattern: "_1XXX"
      target:
        resource-type: line
        resource-id: "!dialedNum"
        not-found-treatment: vacant-code
    "900":
      match:
        - always: true
      target:
        resource-type: treatment
        resource-id: cannot-complete-as-dialed

line-profiles:
  standard:
    inbound-translation-context: from-lines

devices:
  alice-desk: "1001"

lines:
  "1001":
    line-profile: standard
    devices: [alice-desk]

From here, the translation contexts article covers how calls route, and the lines and trunks articles cover the resources they route between.