Designs and promotion

An organisation’s design is its configuration as one document. Try a change in a sandbox, review what it would change in your organisation, apply it all at once, and go back to the version before if you need to.

What a design holds

• Settings
• Filter rules
• Access rules
• Alerts
• Impersonation protection
• TLS agreements
• Journal rules
• Retention policies
• Branding
• Custom roles
• Allowed and blocked senders
• Sign-in with an identity provider
• Directory sync

A design never holds people, mailboxes, mail, keys, legal holds or secrets.

Sign-in with an identity provider and directory sync travel without their secrets: the identity provider’s client secret and the directory’s bind password stay where they were set. Before applying a design that brings either to an organisation for the first time, set that organisation’s own secret on its Sign-in or Directory sync page; until then the apply is refused and says which. A design that changes either keeps the secret already there.

A custom role in a design can’t gain the right to search mail for a discovery case. That right is given only by its own approval, so a design that would add it is refused and names the role.

A part an organisation has never changed is left out, and applying the design leaves the target’s own. For example, a sandbox’s default alerts tell the sandbox’s made-up administrator; they don’t follow the design into production.

Names between organisations

A design names domains: a rule about boss@try.example.com.test in a sandbox is about boss@example.com in production. Between a sandbox and the organisation it was made for, the names are found for you. For a design from anywhere else, say which of your domains stands for each of its own. It can’t be applied until every domain it names has a name here.

Reviewing and applying

Reviewing a design shows what it would change, part by part and rule by rule, for example:

Settings: passwords.min_length changed from 14 to 16
Filter rules: "Boss" added

Applying writes every change at once, or none of them:

• If anything the review read has changed since, the apply is refused. Review it again.
• Each part is checked as an edit made there would be. A setting below the installation’s floors is refused and named. So are access rules that would lock every administrator out of the console.

A design can’t be used to get round an approval. When an organisation requires a second administrator for changing the access rules or custom roles, or for loosening an approval or a second step, a design that makes one of those changes waits for that approval too, just as the change would if made directly.

A second administrator’s approval

To have every apply and every rollback approved by a second administrator, require it:

vsx admin org approvals apply-design required

An apply then waits, with the reason you give, until another administrator approves it. The design is kept exactly as it was reviewed. When it’s approved, it is applied only if nothing has changed since the review; otherwise it’s refused, to be reviewed again. Nobody can approve their own. See Approvals.

The watch window

For 30 minutes after an apply, the organisation is watched. Five measures are compared with the same minutes of the same weekday a week before:

• mail bounced or delayed, out of all mail sent;
• messages refused at the door;
• the share of arriving mail quarantined;
• sign-ins refused by the access rules;
• wrong passwords, counted every ten minutes. A design that moves sign-in to another identity provider or directory shows here first.

A measure breaches the window when it reaches three times the week before’s rate and at least ten of what it counts, so a quiet hour does not trip it. A breach raises the design-watch alert, naming the design version, the measure and both numbers, with the command that rolls the design back. The design history shows, for each apply, whether its window is running, passed, breached, or was rolled back.

Pre-production and production

A sandbox is made up; pre-production is real. It is an organisation of its own on the server that takes mail from the internet for a test subdomain, such as staging.example.com, and sends real mail from it, so a design is proved against real senders and receivers before it reaches production. The operator flags it, naming the production organisation and, for each production domain, the name it has in pre-production; a domain under it, such as staging.example.com, is found without being named:

versealx-server admin tenant 4 pre-production --of 1
versealx-server admin tenant 4 pre-production --of 1 --name example.com=preprod.example.net
versealx-server admin tenant 4 pre-production none

Names map between the environments both ways, so a rule naming ada@example.com in production reads as ada@staging.example.com in pre-production and ada@example.com.test in a sandbox.

Environments, on the Organisation page, shows production, pre-production and the sandboxes side by side: each one’s design version, its last change, and the drift between them, such as “production has 2 changes made directly, not through promotion”. Promote here shows the difference in words and applies it as any design is applied, with the approval and the watch window:

vsx admin design environments
vsx admin design promote --from 4 --what-if
vsx admin design promote --from 4

Changing production only by promotion

An organisation’s administrators can make production change only by promotion. Then a direct change to anything a design holds is refused, saying to make it in pre-production and promote it: settings, filter rules, access rules, alerts, impersonation protection, TLS agreements, journal rules and retention policies. A design is applied only exactly as pre-production holds it now, or a sandbox when there is no pre-production. A rollback is still allowed. Each refusal is in the audit log.

vsx admin design promotion-only on

In an emergency, a break-glass account can still change production directly. Its sign-in alerts every administrator, and each change it makes is audited. Turning promotion-only off also takes a break-glass account, or the operator, so it is not a way around itself.

Pre-production on another installation

Pre-production can also be a separate installation of Nixt Server, a staging server of its own. Its design reaches production as a signed bundle:

1. On the staging installation, an administrator exports the design signed with that installation’s published key:

   vsx admin design export --signed --file design-bundle.json

   The bundle names the installation, the organisation and the environment it came from. It carries a sequence number that rises with every bundle, and whether the design passed its watch window there. It never carries a secret: a secret is named and left for production to fill in.

2. On production, the operator registers the staging installation once. --key takes the staging installation’s published keys as JSON, and --fingerprint picks the one to trust. Its domains are named where they differ:

   versealx-server admin design staging add staging-eu --issuer https://staging.example.com --key "$(cat staging-keys.json)" --fingerprint <hex> --name staging.example.com=example.com
   versealx-server admin design staging list

3. An administrator takes the bundle, after seeing what it would change:

   vsx admin design import design-bundle.json --what-if
   vsx admin design import design-bundle.json

   --what-if checks the bundle exactly as taking it would, and shows what it would change, but takes nothing: the same bundle can be checked again, and then taken. It is refused when its signature does not verify against a registered installation’s key, when any byte of it changed, or when its sequence is not higher than the last one taken from that installation, so an old bundle can’t be replayed. A bundle that passes becomes a proposed promotion. It goes through the same review, second approval, watch window and rollback as a local one. Changing production only by promotion accepts it, and so does requiring a watched design, when the bundle says it passed its watch window on staging.

Environments shows each registered staging installation as a source, with the last bundle taken from it. Registering, removing, exporting and taking a bundle are each in the audit log.

Versions and going back

Every apply is a new version of the design, recorded with who, when and what changed. The first apply also keeps the design as it was before it as version 1, so it can be undone. Going back to any earlier version makes a new version; the history is never rewritten.

Who may

Applying and going back are lines in the audit log.

In the console

On the Organisation page:

• Promote, beside each sandbox, reviews what was tried in it as a change here.
• The Design card downloads this organisation’s design, reviews one pasted in, and applies what you reviewed.
• Design history lists every version, with Go back to this beside each earlier one.
• On the Environments card, Export a signed bundle saves this installation’s design as a bundle for production. On production, See what it would change checks a bundle you paste or choose as a file and lists its changes without taking it; Apply these changes then takes it and applies what you reviewed. A bundle taken but not applied, for example because its apply was refused, stays listed there with Review, Apply again and Discard; discarding it keeps its number used, so the same bundle is never taken again.

On the command line

versealx-server admin sandbox promote 12
versealx-server admin design export --sandbox 12 > design.json
versealx-server admin design apply design.json --what-if
versealx-server admin design apply design.json
versealx-server admin design history
versealx-server admin design rollback --to 1

design diff is the same as apply --what-if. For a design from an organisation that is not your sandbox, name its domains: --name staging.example.com=example.com, once for each.

Over the API