Portal reference¶

How the Claugine portal works, how it is run, and what comes next. Addresses, host names, ports and accounts of the running installation are left out.

1. Overview¶

The portal is the single tool for day 0/1/2 operations of the OpenNebula cloud: customers register and order tenants, staff approve them, and the portal keeps the authoritative record of organizations, tenants, resources, connectivity and addresses. Tasks will also be callable through an API.

Platform endpoints currently run in read-only mode: the portal reads OpenNebula, flags every difference with its own records and does not provision yet. The move from the old management system was a one-time transition (section 15); every next installation of claugine starts fresh. Execution mode, in which the portal itself provisions, is switched on per platform only after the provisioning engine is built and all tests pass.

Principles: the database is the desired state; OpenNebula is the actual state; nothing is ever deleted from the database (rows are versioned or blocked), except requests that never became tenants and organizations without any history.

2. Architecture and hosting¶

App VMs (Ubuntu 26.04): Apache 2.4 with mod_wsgi (daemon mode, user www-data), Django 5.2 on Python in /opt/claugine-portal/venv, MySQL 8.4. One app VM per site; see The portal on two sites.
Public names: the portal and a second name for a new version under test (super admins only), both resolving to both sites. On each site VyOS forwards the site's public load-balancer address to the LB VM; HAProxy on the LB VM ends TLS (Let's Encrypt) and sends portal requests (443; 80 redirects) to the right app VM on its own site or over the link between the sites. The app VMs take HTTPS from HAProxy only, and answer the role checks on their internal address.
OpenNebula front ends are published through the same HAProxy, each site its own, with TLS on HAProxy: FireEdge, the gRPC API and the XML-RPC API from anywhere; OneGate and OneFlow only from the site's delegated subnet.
Other web sites (such as this documentation) can be published through the same HAProxy by name (install-lb.sh --web <names>=<address>:<port>); HAProxy ends TLS and passes X-Forwarded-For and X-Forwarded-Proto, and shows a "not available" page while the site does not answer.
Paths: code /opt/claugine-portal/app; configuration /etc/claugine-portal/portal.env (root-owned, never in code); /var/lib/claugine-portal holds only the file-mail fallback.
Everything is in the database: users (with their photos), organizations, tenants, the infrastructure, templates, tasks, logs and every secret (passwords, ssh keys, BGP passwords, the old system's ssh key — encrypted with FIELD_ENCRYPTION_KEY). The portal is restored from a database backup, the distribution and portal.env: the encryption key cannot live in the database it protects, so keep a copy of portal.env (or at least FIELD_ENCRYPTION_KEY) apart from the database backups. Without it the stored secrets cannot be read.
Restore: an appliance backup (Settings → Portal appliance) holds everything: the database, portal.env, the portal distribution and restore.sh. Each backup is a folder claugine-portal-YYYYmmdd-HHMM: database.sql.gz, portal.env.zip (protected by the archive password, AES-256), claugine-portal-dist.tgz and restore.sh. Copy the folder to a freshly installed Ubuntu 26.04 VM and run sudo bash restore.sh --site-url https://… in it: it installs the portal and everything it needs from the distribution in the backup, asks for the archive password, puts portal.env in place, loads the database, migrates and starts Apache. Database dumps made before each deployment are in /var/backups/claugine-portal.
Django apps: accounts (users, roles, invitations, 2FA, audit log, dashboard), tenants (organizations, tenants, orders, quota and connectivity records, address assignments, naming), inventory (inventory revisions and index, capacity, platform endpoints), adoption (old-system imports, OpenNebula collection, drift), content (news, announcements, service status).
Background job: systemd timer claugine-collect.timer reads OpenNebula every 15 minutes (read-only).

The portal on two sites¶

VMs: on each site an app VM and an LB VM. One site with an app VM and an LB VM works the same way; there are never more than two app VMs.
Roles (/etc/claugine-portal/node.env on each app VM, never replicated): active serves every user and runs the timers (collection, health, the old system, history, backups); standby serves nothing and its database follows the active one; new is a new portal version under test (only super admins sign in; mail stays in files; the platforms, routers and iLOs are read only from there); maintenance serves nothing. HAProxy asks each app VM GET /active, /standby, /maintenance, /new (200 for its role) and sends the portal name to the active one and the test name to the new one; when there is none it shows a maintenance page.
Database: MySQL GTID replication from the active to the standby (a dedicated replication user, TLS, the standby is super_read_only). Users and grants are each VM's own (outside the binary log).
HA agent (claugine-ha, root, on the internal address, authenticated with a token from portal.env): runs the operations on both VMs. Settings → Publishing shows both nodes (role, version, replication, running tasks) and the buttons: Switch over (the standby becomes active; about a minute of maintenance; refused while tasks run or when the versions differ), Publish the new version (the standby takes a copy of the database and becomes new; install the new version there), Make the new version active (the new node takes a final copy, migrates and becomes active; the old one takes the new version and becomes its standby), Back to standby, Maintenance on/off. Nothing switches by itself. By hand: sudo claugine-manage-root ha_agent status | op <operation> | replicate <address> | role <role>.
Install: app VMs with deploy/install.sh … --site <site> --server-id <n> --addr <app address> --peer-site <other site> --peer-addr <other app address> --lb-addrs <LB addresses> --mail-name <mail host name> (the second VM first gets the same portal.env, copied VM to VM, then --role standby and ha_agent replicate <active address>). A standby never migrates. LB VMs with deploy/install-lb.sh --apps … --peer-lb … --public-name <portal name> --test-name <test name> --one-name <front-end name> --one-addr <front-end address> --local-nets <delegated subnet> --letsencrypt-email …: the Let's Encrypt check may reach either LB; a token not found on one is served by the other (allowed from the other LB only).

3. Users and roles¶

Staff¶

Role	What it does
Super admin	Everything: users, settings, platform endpoints, audit log. Opens every page; approves in the roles assigned to them (Users → Roles), or in a role nobody active holds.
Resource manager	Approves tenants (names them, places them on a cluster, confirms resources), manages organizations and the sales rep directory, platforms and capacity, address registry.
Support engineer	Approves corporate tenants when that switch is on, inventory, platforms, address registry, L2 VLANs, news.
Key account manager (KAM)	Looks after cloud organizations together with the sales rep; sees their organizations and tenants.
Sales manager (sales rep)	Owns organizations. While sales approval is off, reps are directory entries (name, email, phone) without login; the resource manager records contracts and balance confirmations on their behalf.

Administration → Users has two tabs. Platform users: email, name, 2FA, state and a column per role (super admin, resource manager, support engineer, sales manager, key account manager). Tenant users: organization, email, name, 2FA, state, tenants and the roles org admin (everything in the organization), tenant admin (only the tenants given) and read only (sees every tenant of the organization, changes nothing); organization admins have the same tab in their portal (Organization → Users). States: active (the invitation was accepted, sign-in works), blocked (accepted, sign-in locked), invited (sent, not accepted), inactive (not invited). Actions: Invite (platform users get their roles with the invitation — no role before it), Block/Unblock, Archive (instead of deleting: no sign-in, kept forever; Show archived lists them) and Edit roles in the details. Every staff role always keeps at least one active person; with a single active person the super admin holds all roles. A person holding several roles approves once for all of them.

Customers¶

Role	Scope
Organization admin	Manages users of the organization, orders tenants, full access to every tenant of the organization.
Tenant admin	Manages one tenant and can invite tenant users to it.
Tenant user	Works in one tenant.

One email is either staff or a customer, never both. For adopted tenants the users come from the sales team's check sheet: the first person of a tenant is its tenant admin, the first person of an organization its organization admin. Each tenant is also associated with one OpenNebula user — the admin of its group — imported at every collection.

4. Organizations¶

The legal entity, identified by IIN/BIN (checked with the Kazakhstan check digit). It has no object in OpenNebula.
Type: cloud (external client) or corp (internal client of the group). An organization is corporate when its admin registers with an email domain from the corporate list (Settings), or when staff invite it as corporate; staff can also change the type. Only corporate organizations may order corporate tenants and the corporate network.
Invitations: the super admin, resource managers, support engineers and sales reps can invite a person to register a new organization (Organizations → Invite an organization), choosing its type and sales rep (a sales rep invites for themselves). The person fills in the registration form with the email locked; no confirmation email is needed.
Short name: 3–14 lowercase latin letters and digits, starting with a letter; generated from the legal name, editable by staff until a tenant group uses it.
The sales rep and the key account manager are set on a cloud organization and apply to all its tenants; reassigning moves all its tenants.
A corporate organization has no sales rep and no KAM, only a resource manager and a support engineer. Each corporate tenant can have its own resource manager and support engineer; otherwise the organization's apply, and with none assigned anybody with the role approves. When data is imported, corporate organizations without a support engineer get the default one (an import setting, not shown in the interface).
Support engineers and super admins can also be users of corporate tenants (tenant admin or tenant user), added on the tenant page.
Registering with an IIN/BIN that already exists never creates a second organization: it becomes a join request to the organization admins; staff are informed.
An organization can be deleted only while it has no tenants, users, join requests or invitations.
Organization area (left menu for customers): Dashboard — tenants approved, deployed and waiting, resources of the quotas in force (vCPU, RAM, GPU, storage), VMs running/total from the last collection, users, join requests, open invitations and the latest events; Tenants — the tenants and ordering; Users (org admins) — users and their roles, join requests, invitations; Keys — the ssh public keys of the tenants the person manages (add several at once, pasted or as .pub files, to several tenants; assign them to the igw) and the organization's default ssh key; Logs (org admins) — every operation on the organization, its tenants and its users, filterable by tenant. Tenant users see the dashboard and tenants they belong to.

5. Tenants¶

Cloud → Tenants has two tabs: Tenants (approved tenants; columns status, stage, tenant, organization, type, approval, platform, created; filters by status, stage and type; Show archived) and Requests (waiting, rejected or cancelled requests). Actions of a tenant: resources, stage, status, review date, history, move; the type of a tenant cannot be changed. All activity is seen in Logs and Tasks — the same pages in the super admin's and the organization's portal.

A tenant is a project with its own resources, network and cost center (contract number and date, balance confirmations are per tenant).

Attribute	Values
Type	`cloud` — external clients; `corp` — internal clients of the group (only corporate organizations may order it).
Stage	`poc` or `client`. A new tenant starts as poc, reviewed a month after it was created (the sales rep may extend a POC up to 3 months). Changed by the super admin, resource manager, support engineer or the organization's sales rep.
Connections	corp tenants: internet, corporate network or L2; cloud tenants: internet or L2. Internet and the corporate network are never in one tenant; L2 goes with either, and alone only in a cloud tenant.
Approval	pending → approved, or rejected / cancelled.
Status	ok, paused, suspended, saved, archived (see lifecycle).
Dates	created, last modification, review date (the end of a POC or of the current status), contract end.
Origin	registered in the portal, adopted from the old system, test tenant.

6. Tenant ID (OpenNebula group name)¶

A tenant is one OpenNebula group, and the group name is the tenant ID shown everywhere in the portal. Tenants created by the portal are named _t_<org>_<tenant>, e.g. _t_acme_gpulab; the _t_ prefix marks a tenant group, and other _<x>_ prefixes are reserved for other kinds of groups such as roles. Tenants of the old system keep their groups tenant-<name>. The limit in OpenNebula is 32 characters: organization short name 3–14, tenant name 4–14, both lowercase latin letters and digits starting with a letter, so _t_ + 14 + _ + 14 = 32 at most and the separators are unambiguous.

The customer enters only the tenant name when ordering (there is no separate project title); the portal shows the full ID with the prefix. The tenant name is unique within its organization.
The ID is fixed at the resource manager's approval (the manager may still correct the short name while approving); the portal refuses an ID used by another tenant or by an existing OpenNebula group. A rejected or cancelled request frees it.
OpenNebula groups cannot be renamed, so a tenant ID never changes afterwards, and the organization short name is locked once any of its tenant IDs exists. Old tenant-* groups are never renamed.

7. Customer registration¶

The person enters email, password, profile (name, mobile, city, photo), organization legal name, IIN/BIN type and number, and consents to personal-data processing.
A confirmation link is emailed (valid 48 hours). Confirming creates the organization only, with the person as its admin — no tenant is created. The organization is corporate if the email domain is in the corporate list, otherwise cloud.
Users invited by staff register through the invitation link instead and skip the confirmation.
If the IIN/BIN is known, a join request goes to the organization admins instead.
The admin then orders tenants from My organization → Order a tenant.

8. Ordering a tenant¶

Field	Rule
Tenant name	4–14 characters; the tenant ID is built from it (see naming).
Type	Cloud; corp is offered only to corporate organizations.
Resources	vCPU, RAM GB, storage GB — defaults 4 / 16 / 100.
Connections	At least one of `inet` (internet), `corpnet` (corporate network — corporate organizations only) and `l2` (external L2-over-L3 channel). Any combination is allowed: inet and corpnet can coexist, and L2 can be added to either or ordered alone. Support assigns the L2 VLAN number. In the connectivity record, routed connections are stored space-separated (`inet`, `corpnet`, `corpnet inet`), `none` when only L2.
Internet	Bandwidth 10–1000 Mbps in steps of 1 (default 100); main public prefix; optional additional prefixes.
Corporate network	Corporate organizations only. A list of prefixes.
Prefix lengths	/31, /29, /28, /27, /26. The customer chooses sizes; the portal assigns the addresses.

A pending order can be cancelled by the organization admin or a resource manager; rejected and cancelled requests can be deleted. Cancelling or rejecting releases reserved prefixes and the group name.

9. Approvals¶

Type	Always	Also, when the switch is on
cloud	Resource manager	The organization's sales rep (Settings → sales rep approval)
corp	Resource manager	A support engineer (Settings → support engineer approval)

When a resource manager or support engineer is assigned to the tenant (or its organization) and can sign in, only that person — or the super admin — approves; otherwise anybody with the role.
An extra approval is skipped while nobody can give it: no sales rep on the organization or none in the directory; no support engineer defined.
Settings shows one table: resource manager, sales rep and support engineer, each required or not, and who approves today. Without resource manager approval (or a resource manager who can sign in) the super admin approves — naming, placing and confirming resources; without sales rep or support engineer approval (or anybody in that role who can sign in) that step is skipped.
The resource manager's approval names the tenant, picks the platform and shared cluster, may adjust resources, may choose the internet pool, and reserves the prefixes. When the last approval arrives the tenant becomes approved and its first quota and connectivity records are written.

10. Network model and addresses¶

Summary; the full description is on the Network page.

A shared front end is a shared platform; a secondary zone belongs to the front end of its primary (a secondary zone at a second site still makes one front end).
Shared front ends are completely separate: no exchange (IX) network and no host may be used by two of them.
Public and corporate subnets are always bound to an IX network (bgp.subnets of the site network), and each IX network serves exactly one shared front end. A tenant's prefixes come only from the IX networks of the platform it is placed on (cloud-ix for internet, corpnet-ix for the corporate network). portal-ix belongs to the portal platform and is never used for tenants.
Allocation takes the first free aligned block, largest blocks first, skipping everything in the address registry, in the latest old-system import and in OpenNebula group metadata. For a /31 main prefix the second address goes to the internet gateway.
The service networks of the inventory that lie inside a public pool of a shared platform (for example cloud-services, the first /29 of each cloud-ix pool) run on the management clusters. They are recorded in the registry as platform services automatically after every inventory change and are never given to tenants.
The address registry lists delegated subnets and every assignment (main, additional, corporate, reserved); support can record reservations, e.g. a /32 for the portal VM.
Each routed connection has its own exchange network and tenant EGW leg: the internet EGW shapes bandwidth and passes only the tenant's public addresses (main public network /31 minimum, one address is the tenant's default gateway); the corporate EGW connects to the corporate network the same way. See the network reference design in the claugine docs (docs/network).
L2 (L2-over-L3 channel s2s-NNNN, two provider-controlled legs bridging a client-site VLAN into a tenant VXLAN network): VLAN numbers are entered by support; tenants bind a VNet (shown as "name (id)") to an L2 VLAN without approval, which reconfigures the VyOS VMs (with provisioning).

11. Resource records and metadata¶

Storage quota has three parts: VMs + images (one quota), files (the first 1 GB is free) and backups (0 by default). Customers order all three; the super admin and resource managers can change the resources of an approved tenant on its page (Edit resources) — every change is a new version.
Quota records per tenant, site and cluster (quota code): vCPU, RAM, GPU (fixed slices), storage (one number for VM disks, images and files; tenant admins split it on the tenant page without approval — by default above 100 GB 20 GB for images and 1 GB for files, VM disks the rest), backups. Append-only versions with an effective date; a change is a new version, a removal is a version marked removed.
Connectivity per tenant and site: connection type, gateway type, bandwidth, prefix lengths, L2 VLANs and VNets — also append-only.
Platform defaults when empty: files 1 GB, backups 0. Full field list and the group format: Data model.
The OpenNebula group template holds an emergency copy of the current state in the quota.md format, plus the sales rep email and group info. Pending and archived tenants exist only in the database.

Imported tenants¶

Tenants of the old system keep its names: group tenant-<name>, objects tenant_<name>-egw_<site>, tenant_<name>-igw_<site>, tenant_<name>-main_<site>; the portal addresses them that way. They are not deployed; their resources (group, users, quotas, networks, VMs) are not touched. The old system's database is the true list: an imported tenant it no longer has is deleted at the next refresh (logged).

Redeploy egw / cgw / L2 gateways: the old gateway is recorded (networks, addresses, size) and removed, a new one is made from the platform's image and the portal's templates on the same networks and addresses. L2 channels the portal knows are made again. The old system's L2 gateways of an imported VLAN are found by their names (tenant_s2s-<vlan>-src_<tenant>_<site> on the management platform, tenant_s2s-<vlan>-dst_<tenant>_<site> on the tenant's platform), recorded and removed, and the portal makes the channel on the same tenant network.
igw: upload the old igw's configuration (show configuration commands). It is checked against the old VM's networks and addresses: interfaces the VM does not have, files of the old VM (openvpn, certificates on disk) or addresses that are not the NIC's make it not transferable. Transferable: Create the new igw removes the old one and makes a VyOS igw on the same networks and addresses (eth0, eth1, … stay) with that configuration on its first boot, given to the old owner. Not transferable: the igw is marked imported, not adopted and stays as it is, to be done with the tenant's staff.

12. Tenant lifecycle¶

Status	Portal account	VMs	Network	Data
ok	active	running	working	kept
paused	blocked	running	blocked	kept
suspended	blocked	powered off	blocked	kept
saved	deleted	deleted	—	one full backup of every VM is kept
archived	deleted	deleted	—	nothing on the platform

ok → paused (2 weeks) → suspended (1 month) → saved; back to ok from paused or suspended. The review date is the end of the current status. Statuses change by hand only (super admin, resource manager: Status on the tenant); the one exception is saved → archived, done by the nightly round a month after saving. The status change only changes the record for now; the platform follows with the provisioning engine.

Nothing is deleted: deleting a tenant or an organization archives it, and an organization can be unarchived. Every change of a tenant's resources is a new record; replaced versions are kept for the tenant history period (Settings, 2 years). A tenant's History opens the Logs on it, archived tenants included; an organization's History shows its tenants and users too.

Notices to the organization admins: the end of a production contract 3 months, 1 month and 2 weeks before, then every day of the last week; the end of a POC every week, then every day of the last week. While email to clients is off, notices are only logged (tenant_notice, held).

13. Infrastructure¶

Lists work the same everywhere (as in FireEdge): a page shows 5, 10, 25 or 50 rows (the choice is remembered), a filter box searches the rows, the add button is at the top right, the actions of a row (edit, test, delete, …) are buttons on its right, and selecting a row shows its details under the list. Types are coloured labels with one colour per type everywhere (corp blue, cloud/client teal, poc violet, …); states are a dot and a word (green: active/approved, amber: planned/pending, red: retired/failed).
The Infrastructure menu: Sites (and endpoints outside the inventory), Server profiles, Templates, Secrets, Keys, then one item per site with tabs Platforms, Clusters, IP subnets (delegated subnets and their assignments), Hosts, Storage, Networks. All infrastructure data are portal records edited only in the portal (list, details of the selected item, add and edit in dialogs); a record can be deleted while nothing refers to it.
Site code: a number, required for a new site and fixed once set; it is part of the AS numbers of the site's networks (4 2xx xxx xxx is the private AS range).
Management hosts and ports (site settings): addresses or host groups (e.g. 192.0.2.4, 192.0.2.0/28) allowed to manage the site's systems, and the ports for VyOS management ssh and for ssh and RDP to the management hosts. Every provider VyOS router (egw, cgw, L2 gateways, route reflectors — not the tenant's igw) has eth0 on the site's cloud-vyos network in VRF MGMT; ssh listens only there, on the VyOS management port, and only the management hosts reach it. The other interfaces follow (egw: eth1 exchange, eth2 main network; cgw: eth1 exchange, eth2… corporate networks; L2: eth1 s2s, eth2 bridged). Ports: hosts, VMs and the rest use the standard ssh port 22, the portal VM too; only the jump hosts, reachable from outside, use non-standard ports for ssh and RDP; VyOS network functions use their own management port in VRF MGMT. The portal connects to every address of a site directly; the site's jump host is tried only when the direct connection fails.
Networks tab: type, interface, VLAN, MTU, subnet, gateway, ranges (an exchange network gets ext-gws .0/30 and rrs .240/30, a VXLAN network rrs .240/30 by default) and BGP: local AS, delegated subnets, then the peer groups rrs (addresses only), igw and egw (exchange networks: remote AS), each with hosts generated from a range and editable, and a password set from Secrets. Management interfaces of VyOS routers (VRF MGMT) get their addresses from the ranges automatically.
Site settings: time zone, up to 4 NTP servers, up to 3 DNS servers for normal operation and up to 2 green-field DNS servers used when deploying from scratch while only the claugine appliance is up.
Platforms tab: type, state (active when its OpenNebula secret is defined in Secrets), front-end mode (single, local, primary, secondary → its primary), the front-end address as a link to FireEdge (http://<vip>:2616/fireedge/sunstone), operations mode; Edit, Switch to full mode/Switch to read-only (operations: execution or read-only; only a deployed platform can be switched to full mode; logged), + Image, Import tenant data: on/off and Test; details show front end, XML-RPC endpoint, secret, service images, datastores and networks. Shared platforms have a public FireEdge URL: where tenants open OpenNebula (e.g. https://one.example.com), shown on the tenant page and as the icon in the first column of the tenant lists; it can be changed on a deployed platform too, and a secondary zone without its own uses its primary's. Service images (purpose, type, name, id, status): three rows are mandatory — vyos image VyOS Router 2026.03 (egw, igw, cgw; only the name can be changed), one-router template Service Virtual Router (the native igw; only the name) and its image (named as the template); other rows are free. Id and status are read from the platform by the health check. L2 channels follow from the clusters, nothing is chosen: a shared platform with a dedicated edge cluster (its hosts carry the egw and the L2 bridges; one per platform, only on shared platforms) bridges a VLAN with one VyOS VM there, as the edge cluster is on the same EVPN fabric as the tenants. Without one, the src gateway lives on the site's management platform and the dst gateway on the tenant's shared cluster, with a VXLAN tunnel between them. Import tenant data: when on, the collector (every 15 minutes) reads the platform's tenant groups with their users, quotas and templates, the VMs, hosts, address ranges and datastore usage into the portal (Dashboard, tenant usage, comparison with the old system); it only reads. Off: the platform is not read (its health is still checked). On a deployed platform the front-end mode and its primary are fixed.
Platform health: every platform is checked on the period set in Settings → Platform health (default 30 minutes; a timer runs every 5 minutes and checks the platforms that are due): the OpenNebula endpoint answers (its version is recorded) and, on shared platforms, the service images exist and are ready or used. The Platforms tab shows the result and the problems; Test checks at once.
Hosts tab: IPMI address as a link (Redfish, always https; the IPMI https port of each host, default 443) and the iLO type. IPMI settings reads every iLO of the site through Redfish (HPE iLO 6 and 7) and compares it with the site: the same IPMI user (a credential), NTP and DNS servers of the site and its time zone; Apply to checked writes NTP, DNS and the time zone to the chosen iLOs (some iLO network changes need an iLO reset; the iLO messages are shown). The iLO type found is written to the host file.
Disk sizes: the boot disks of server profiles are in GB (10⁹ bytes), as hardware vendors give them — the only place with GB; volumes and everything else are in GiB (2³⁰ bytes).
Reading the hardware of a host asks its IPMI first (Redfish on the iLO): chassis, CPU, sockets and cores, RAM, GPUs, the boot volume (the NS204i boot controller) and the network cards with their PCI slots, models, ports and speeds. The names of the components come from there. The Linux names of the ports are predicted from the slots as systemd gives them: ens<slot>f<function>np<port> (slot 1 → ens1f0np0, ens1f1np1; OCP slot 22 → ens22f0np0; a card in PCI domain 1 → enP1s2f0np0; a one-port card has no f0: ens3np0). The OS is then read over ssh (port 22) for what only it knows: the boot device and its volumes, and the aliases the ports carry (nic-data1 = ens1f0np0). Hosts in no cluster may not answer over ssh: that is no error.
Server profiles: Check reads every host of a profile and compares (cards are paired by PCI slot; the aliases of the hosts with the profile's); it also takes the component names from the IPMIs (the name most hosts give). Port aliases: a server has 2 or 4 ports — two fabrics: bond0 = nic-data1 + nic-data2 (data: VMs, host to host, MTU 9100) and bond1 = nic-storage1 + nic-storage2 (storage, MTU 9000); one fabric: bond0 = nic-data1 + nic-data2 carries both (e.g. gi2 until its second card comes). The profile assigns each alias a port of its cards. Verify: a profile can be edited until it is verified (its aliases assigned, its hosts checked and the same); then only its volumes can change, and the aliases while no active host of a cluster uses it. FC HBAs are not used yet.
States: items of a platform that is not installed are planned; installed items are active; removing an active host or cluster marks it retired until it is taken down, removing a planned one deletes it. A new cluster on an installed platform sets the platform to updated. Only active hosts give capacity and only active shared clusters of an active shared platform can be ordered.
Inventory files were the source once: manage.py load_inventory loaded the last revision into the records (the installer runs it with --once). Nothing reads the files any more and there is no file view, upload or export; the stored revisions are kept until their removal is confirmed. A new import/export format comes later.
Capacity (in the details of a cluster) compares hardware (hosts × server profile) with current quota records: vCPU as an overcommit ratio, RAM, GPUs (PCI passthrough, never overcommitted).

Secrets¶

Infrastructure → Secrets keeps every secret of the infrastructure, by type, encrypted with FIELD_ENCRYPTION_KEY. Lists show whether a value is kept, never the value; the super admin can show the values of a secret (logged). Each row counts its contributors (what uses the secret: platforms, hosts, sites, BGP peer groups, settings, the portal itself); used by N · show contributors opens the list. In edit dialogs a kept value is shown as set (●●●●●●●●), never its content; focusing the field shows the real value (logged). Copy next to a kept value in the details copies it to the clipboard without showing it (logged). Contributors refer to a secret by its id, so a secret can be renamed at any time; every reference to a secret (or to another object) is chosen from a list of the existing ones. The old system's ssh key is chosen in Settings → Old management system; the portal's own key on tenant routers is made on first use.

Users — name (unique), status, user name, password and/or ssh private key (one of them is required), purpose, the public key calculated from the private key. Platform super admins, IPMI users, jump hosts, the portal's own service user and the old system's key.
BGP — one per exchange network of a site, named <site>.<network>, type ix or evpn: the passwords of the route reflectors (rrs), of the internal peers (igw: tenant gateways, KVM hosts) and, for ix, of the external peers (egw). All required.
OpenNebula — one per front end (e.g. cloud.one): the OS user oneadmin (password of at least 30 characters and an ssh private key), the database (default onedb, user onedbuser, password of at least 30 characters) and the OpenNebula super admin oneadmin (uid 0; password of at least 15 characters).
Keys — public ssh keys of users (type, key, comment). A key cannot be changed after adding.

Status: new (added, not used), used, replaced (its contributors were moved to another secret, but a system may still accept it; it cannot be given to new contributors), archived (not used, kept for the record; Show archived). Replace points every contributor to another secret of the same type and starts a check (Tasks): the new secret is accepted and the old one refused — OpenNebula over XML-RPC, super admins and jump hosts over ssh, IPMI over Redfish; BGP and the rest are confirmed by hand. When every check passes the old secret is archived; otherwise Check systems runs the check again. Archive takes only a secret nothing uses. The portal does not change secrets on the systems: change them there first, then replace them here.

Templates¶

Infrastructure → Templates holds the sources of the configurations of network functions, taken from the running services: egw (internet edge: BGP to the internet exchange route reflectors, martians filtered, bandwidth limit), igw (tenant gateway: EXT main network, INT private networks with SNAT, PUB extra public networks, ssh key login), cgw (corporate edge), L2 channel tenant and external sides (bridge + VXLAN over the s2s network), the route reflectors of the internet, corporate and VXLAN/EVPN exchanges, and FRR of the KVM hosts. Templates leave out what the first boot of the VyOS image already sets from the OpenNebula context (addresses, MTU and IPv6 options of the NICs, default route, host name, time zone, login user and key, ssh basics, system options, syslog); only descriptions are in double quotes and only passwords in single quotes. The deployment passes the rendered configuration as the one-time init script ONE_TIME_INIT_SCRIPT_BASE64, which vyos-postconfig-bootup.script runs once on the first boot (commit and save; a failed command is reported by its line number). Templates use Django template syntax; addresses, names, ASNs, peer ranges and users come from the inventory and the tenant, secrets from Secrets. A preview renders a template for a tenant or for a site and route reflector, with secrets masked as «secret:…» and values decided at deployment as «…»; the super admin can show it with secrets (audited). The tenant page links the configurations of its egw, igw, cgw and L2 sides. Reset restores the built-in version.

Tenant deployment¶

Tenants are deployed on platforms switched to execution mode (site → Platforms → Mode and image); on a read-only platform the approval says so and the tenant page shows why it was not deployed. The order offers a tenant name (tenant1, tenant2, … free in the organization), the igw administrator (<tenant>-igw-admin), the organization's default ssh public key (set on Organization → Tenants) and a generated OpenNebula admin password. Password login to the igw over ssh is disabled: the ssh key is required; the igw user also gets a console password (offered by default, same password rules, shown on the tenant page) for the VM console. The igw ssh port is random, 50000–59999, chosen with the order.

Passwords (portal users, tenants' OpenNebula admins and routers, secrets of the infrastructure) follow the password policy in Settings: by default at least 10 characters with 2 small letters, 2 capital letters, a figure and a special symbol; special symbols only from the allowed list (default - _ . + = ^ ~). Symbols that break passwords where they are used are never allowed: ? @, quotes, the space, \ ` $ ; & | < > ( ) * ! # : / % { } [ ] ,. A password may not contain a part (4 characters or more, 6 for figures) of the personal data of the person, the tenant or the organization: names, email, phone, IIN/BIN. The last 5 passwords may not be used again. The rules are shown under every new-password field and checked while typing. The tenant's admins can show the tenant's OpenNebula admin password (logged) and change it — OpenNebula is changed too.

When the last approval arrives the deployment starts in the background; the tenant page shows each step (pending, running, ok, failed) while it runs. The super admin can preview a deployment (nothing is written) or run it again. Before creating anything the main prefix is checked against every address range in OpenNebula; collection records those ranges and the address allocation skips them.

The tenant page has a Log of every operation on the tenant — order, approvals, prefixes, each deployment step, password views and changes — for staff and the tenant's admins.

Group _t_<org>_<tenant> on the primary zone of the federation, with the template copy (TENANT, QUOTA_\<SITE>, QUOTA_\<SITE>_\<QC>) and the FireEdge views.
Admin <org>-<tenant>-admin in the group, admin of the group.
Quota as in lib/claugine_quota: the tenant's cluster gets VMS and CPU twice the running limits, MEMORY twice RUNNING_MEMORY, SYSTEM_DISK_SIZE, PCI_DEV = GPUs; the other clusters -1; datastores: SYSTEM_DISK_SIZE is the VM part of the storage and the IMAGE datastore of the cluster the images part, the FILE datastore the files part (the split of the one storage number), BACKUP.
ACLs as in lib/claugine_acl without role groups (as on the live platforms): the group admin holds the super admin rights, the group the user rights, in the platform's zone; encoded to the hex form of one.acl.addrule (checked against the rules of the live platforms).
Main public network <group>-main_<site>: VXLAN/EVPN, MTU 1500; the lowest address is the egw and the gateway, the next one the igw; DNS of the platform's services network.
egw <group>-egw_<site>: provider's VM in group oneadmin, 2 vCPU / 4 GB, NIC 0 a free address of the exchange network (cloud-ix), NIC 1 the egw address; user and key of the platform's super admin (from Secrets).
igw <group>-igw_<site>: the tenant's VM (owned by its admin), 1 vCPU / 2 GB, NIC 0 the igw address with the egw as gateway.

Both routers come from the platform's network function image (default VyOS Router 2026.03, set per platform) and are only created with their interfaces: the VyOS context sets addresses, user, key and time zone on the first boot; nothing else is configured yet. Every step is idempotent: an object that exists by name is reused, so a failed run can be repeated. The tenant page shows the steps and the created resources: group, admin, main network, egw, igw, quota and ACLs.

Deleting a tenant: when the deletion is requested, every resource of the tenant on its platform is listed and attached to the request — VMs including the egw, igw, cgw and L2 gateways, backup jobs, virtual routers, templates, images and backups, security groups, VM groups, networks with the main one, ACL rules of the group and its users, the users and the group (a resource is the tenant's when its group is the tenant's or its owner is a tenant user). After approval exactly the listed resources are deleted; before the users and the group go, and again at the end, the platform is checked: if anything of the tenant is left (for example a backup made after the request) the deletion stops and lists it, and a new run lists everything again. Org admins and tenant admins request it on the tenant page (typing the tenant name to confirm); a resource manager of the tenant (or the super admin when the RM approval is off) approves it there or in Approval requests → Deletions. Resource managers and the super admin can also delete a tenant at once (tenant page or the Delete button in the tenant list). The deletion removes everything of the tenant in OpenNebula — its VMs and the provider's egw/cgw/L2 VMs (terminate, then wait), virtual routers, templates, images, security groups, VM groups, networks, the ACL rules of the group and its users, users whose primary group is the tenant's (others only leave the group) and the group — then releases its prefixes, removes L2 channels, closes its quota records, removes memberships and marks it deleted; the record and its log stay. On a read-only platform or for a tenant never deployed only the portal part runs. A failed run can be repeated: what is already gone is skipped. Every object gets its own status on the request (deleted, gone, left the group, failed) and a line in the tenant's log. What would be deleted shows the plan without writing.

Configuration check (tenant page, staff and the tenant's admins): the portal logs in to the egw/cgw as the platform's super admin on the exchange network (on the VyOS management port; the portal's address is in their allowed sources) and to the igw as its service user claugine, reads show configuration commands and compares it with the configuration built from the templates: lines missing on the router, and lines the router has under the paths the template manages that the template does not give. Quotes are ignored; secrets are masked in the stored result.

SSH keys of a tenant (tenant page → SSH keys, and Organization → Keys): tenant admins add several public keys at once and assign them to the igw; the igw is created with the first assigned key and its configuration lists every assigned key. The igw always needs one assigned key (ssh is key-only). For a running igw the page shows the commands that make it match the assigned keys.

Networks of a tenant (tenant page → Connectivity): tenant admins ask to add a public subnet (/24–/32), a corporate network (corporate organizations only) or an L2 channel; to delete an additional public network, a corporate network (not the last one) or an L2 channel; or to replace the main public network. A support engineer of the tenant (or the super admin) approves in Approval requests or on the tenant page; the change is then made at once on a deployed tenant whose platform is in execution mode, step by step, with each step on the request (Connectivity → Changes, with Retry after a failure) and in the log:

Public network, add: the subnet is assigned from the delegated pool; a network with it is created in the tenant; the igw gets a NIC on it; the igw configuration gets the interface, the PUB group and zone; the egw gets the subnet in its CLIENT group and a static route to it via the igw.
Public network, delete: the route and CLIENT entry leave the egw, the interface and PUB entries leave the igw, the NICs of all VMs on the network are detached, the network is deleted and the subnet returned.
Main network, replace: a new main subnet is reserved at approval; the egw and igw are removed, NICs of other VMs on the old main network detached, the old network deleted and its subnet returned; then a deployment creates the new main network, egw and igw with the same settings (bandwidth, igw user, keys, ssh port and allowed networks, console password).
Corporate network, add: a network in the tenant, a NIC on the cgw and the cgw configuration (interface, CLIENT group and zone); a tenant without a cgw gets one from a deployment. Delete: the cgw configuration, NICs of all VMs detached, the network deleted, the subnet returned.
L2 channel: the approver gives the VLAN number (it is the VXLAN VNI too when free). On the site's management platform (it must be in execution mode) the VLAN network s2s_<vlan>_<org>-<tenant> (802.1Q, one ethernet address, no IP) and the src gateway are created; on the tenant's platform the tenant network gets an ethernet-only address range and the dst gateway is attached through it; both gateways bridge their NIC and a VXLAN tunnel that runs inside WireGuard over cloud-s2s (link-local inner addresses). The WireGuard keys of both ends and a random pre-shared key (the tunnel's password) are made each time the gateways are made and go only into their first-boot configuration: the portal keeps them nowhere, not in Secrets either. A gateway left from an earlier run is removed and made again with the other, so both always share the new keys. Delete removes both gateways, the VLAN network and the address range.

Router configurations are changed over ssh from the templates: the portal reads the running configuration and the interfaces, sets what the new configuration has and the router lacks, deletes only what the old configuration had and the new one does not (first-boot settings and manual additions stay), commits and saves in one session (a failed commit is discarded) and reads the configuration again to verify. Endpoints of a site other than the portal's (Settings → Network access) are reached through that site's jump host (Sites → site settings: host, ssh port and the account whose key logs in).

Tenant secrets and igw configurations (tenant page → Access; tenant admins, organization admins and the super admin; every look at a secret or a configuration is logged): the OpenNebula link (the platform's public FireEdge URL, also the icon in the first column of the tenant lists), the OpenNebula admin's password — Set a new password (OpenNebula changes too) or Keep the current password (checked by logging in to OpenNebula with it, read only) — and the igw login (address, ssh port, user, password; the portal keeps them and does not change the igw). igw configurations (VyOS igw): keep the running configuration (show configuration commands), edit a saved one (saved as a new one, linked to the one it came from), apply one. Over ssh: the portal keeps the running configuration ("before applying …"), sets what the chosen one has and the igw lacks and deletes what it does not have — never the hw-id lines nor the account the portal logs in with — and commits with commit-confirm <minutes> without saving; Confirm on the page runs confirm and save, otherwise the igw goes back to its previous configuration by itself. The timeout is asked in seconds (default 60) and rounded up to whole minutes, as VyOS counts them. By making the igw again: the takeover's igw steps — the configuration is checked against the igw's NICs, the igw is removed and made again from the platform's VyOS image on the same networks and addresses with the configuration on its first boot. Rolling back = applying the configuration kept before. Login: the portal's service account on an igw it made, else the tenant's igw login (password, through sshpass). Not tried on a real router yet.

Changing resources: the tenant's admins ask for other resources on the tenant's pool (vCPU and RAM, or GPU bunches on a GPU pool; storage with its VM-disk / images split; files; backups). A resource manager (or the super admin when the RM approval is off) approves it in Approval requests → Resource changes or on the tenant page, and can change vCPU, RAM, GPUs, storage and backups in the approval dialog first (what was asked is kept and the change is logged); the approval writes a new quota record version and, for a deployed tenant on an execution platform, sets the quota in OpenNebula at once. One change at a time can wait for approval; the tenant's admins can cancel it. The Edit button is on the Resources table; a waiting change is shown as a row under the current resources. The storage split is set with a slider or a number.

15. Transition from the old system¶

Until the old system is switched off, its tenants are refreshed every day at 08:00 (Asia/Almaty) by adopt_old_system --apply --group (read-only on the old database; systemd timer claugine-oldsync).

The transition from the old management system happens once, for the installation that replaced it; every next installation of claugine starts fresh, so the portal has no menu for it. It is a management command:

sudo claugine-manage adopt_old_system                  # dry run: read the old database, show the differences
sudo claugine-manage adopt_old_system --apply --group  # record it, group tenants into organizations
sudo claugine-manage adopt_old_system --csv export.csv --apply
sudo claugine-manage adopt_old_system --checksheet sheet.csv

Old database: an SQLite file on the old system's server, reached over SSH; the target, the file and the ssh key (with the server's host keys) are in the database (Administration → Settings → Old management system; the key is kept in Secrets). It is opened read-only (mode=ro and query_only); nothing is installed or written there. Rows with state delete are skipped. Adopted tenants keep their groups tenant-<name>.
Grouping creates organizations by the legal name the old system kept (a valid IIN/BIN inside the name becomes the organization's). Afterwards a resource manager can move a tenant to another organization (by IIN/BIN) or merge organizations from the organization and tenant pages.
Check sheet: IIN/BIN, stage, sales rep and KAM (cloud) or resource manager (corporate), and tenant users — the first person of a tenant is its tenant admin, the first of an organization its organization admin; mobile numbers become international (+…). Support engineers and super admins listed for corporate tenants become their users.
The OpenNebula group admin of each tenant is linked at every collection.

16. Settings, languages and content¶

Settings (super admin): sales rep approval, support engineer approval, password policy, lists and history (task, log and tenant history periods), platform health, network access, the old system, corporate email domains (subdomains match) that make a newly registered organization corporate, and the portal appliance.
Portal appliance: everything the portal VM needs, so nothing is set by hand on its OS. Public URL (links in emails; its host is accepted at once). Mail: internal — the VM's postfix (loopback only) relays through an SMTP server with its account and signs with DKIM (OpenDKIM); direct — the VM's postfix delivers to the recipients' mail servers itself under the node's mail name and signs with DKIM; external — the portal sends to an SMTP server itself; mail that cannot be sent is kept in files and logged (mail_failed). The relay settings already on the VM are taken over once. Backups: each backup is a folder with the database (database.sql.gz), portal.env.zip (the key to the stored secrets, in a zip protected by the archive password, AES-256), the portal distribution and restore.sh; folders 750, files 640, owned like the backup folder itself (give that folder the owner the backups should have); to a local folder or to a remote host by rsync over ssh (host, port, a user secret with an ssh key, folder); from the start time (00:45) every period (6 hours), kept for N days (10); Back up now. A root timer (claugine-appliance, every 5 minutes) applies the mail settings and makes the backups that are due. Restore on a freshly installed Ubuntu 26.04: copy one backup folder there and run sudo bash restore.sh --site-url https://… in it (Settings shows the commands with the newest backup's name and the public URL filled in); restore.sh --backup <folder> takes a folder elsewhere. The sender address may carry a name: Claugine Cloud <portal@…>.
Languages: English, Russian, Kazakh — switch in the top bar; texts live in locale/ru and locale/kk and are compiled on install.
Content: news, announcements and incident banners with an optional end time, and public service status with 30-day uptime on the main page.

17. Email¶

Set in Settings → Mail and backups. Direct delivery (now): the portal sends to the app VM's Postfix (loopback only), which signs with DKIM (OpenDKIM; domain, selector and key in Settings) and delivers to the recipients' mail servers itself, from the site's public address under the node's mail name (MAIL_NAME in node.env; its A and PTR records must match). DNS for the sender domain: an SPF record listing the sites' mail addresses, DKIM (<selector>._domainkey.<domain>) and DMARC. Internal relay (through an SMTP server with an account) and external (the portal sends to an SMTP server itself) remain possible. Only the active node sends; the others keep mail in files. Email to clients is off for now (Settings).

18. Security and data¶

Secrets are never in code: Django key, database password, encryption key and source settings are in portal.env; platform passwords are encrypted in the database.
Staff use mandatory TOTP with replay protection; customers may enable it.
Every significant action is written to the audit log (who, what, object, details).
Photos are served only to users allowed to see the person.

19. Operations¶

Deploy: the package is unpacked into the source folder, synced to the app folder and installed with sudo bash deploy/install.sh --site-url https://<portal name> (node settings are kept in node.env, see two sites). The installer is idempotent: packages, venv, MySQL, portal.env (keeps existing values), migrations, the one-time inventory load, static files, translations, Apache, certificate, collector timer.
Management commands (sudo claugine-manage …): bootstrap_superadmin (one-time super admin link), collect_platforms (collect now), load_inventory (the one-time load of the inventory files into the records; reindex_inventory is its old name), adopt_old_system (one-time transition), plus standard Django commands.
Logs: Apache logs under /var/log/apache2, mail in /var/log/mail.log, installer output in /tmp/install.log.
Backups: Settings → Portal appliance (encrypted archives on a schedule, see above); the installer's deployments also leave a database dump in /var/backups/claugine-portal.

20. Roadmap¶

Provisioning engine: desired vs actual state, reconciler, procedures, collectors; test tenants; execution mode per platform.
Customer ordering of changes to existing tenants (resources, connectivity, L2 binding) and the task API.
Renaming adopted groups to the new naming convention.
Automatic lifecycle transitions and personal-data deletion on request.
Dedicated clusters.
Production platform endpoints and database backups.