> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TenantOS

> Sell dedicated servers from TenantOS server pools and VPS from TenantOS plans.

![Two ways to sell a TenantOS server](https://mintcdn.com/dezerx/7zoDaZC5lwbwCGMK/public/services/tenantos/top.webp?fit=max\&auto=format\&n=7zoDaZC5lwbwCGMK\&q=85\&s=f0b3159984de22fcb9076b6937972f17)

The TenantOS module sells servers you run in TenantOS. A dedicated product hands the customer a free server from a pool, a VPS product creates a new virtual server from a TenantOS plan. Each customer gets their own TenantOS account and the server moves into it. The module ships switched off.

| Server type | On a paid order | What the customer gets |
| - | - | - |
| Dedicated server from a pool | Takes one free server that has every pool tag. Two orders never get the same server | Power, console, reinstall and rescue, reverse DNS, statistics, plus boot device, BMC reset and their own IPMI login when you allow them |
| VPS from a TenantOS plan | Creates a new VPS from the plan in the customer's account | Power, console, reinstall and rescue, reverse DNS, statistics, backups and snapshots |

Both also get one click login to the TenantOS panel, SSH keys for reinstalls and the server activity log.

## Requirements

* A TenantOS panel your Spartan server can reach over HTTPS. Plain HTTP only works for private IP addresses.
* An admin or reseller API key, created in TenantOS under My Account, API Keys, ideally restricted to your Spartan server's IP.
* An end user role in TenantOS for your customers. Every product needs one.
* For dedicated servers: free servers owned by the API account, tagged for the pool (For Rent by default). A disk wipe profile is strongly recommended.
* For VPS: at least one VPS plan, created in TenantOS under Virtualization.

## Connect Spartan

**1. Enable the module**

Open Admin, Integrations, Modules, Services and switch TenantOS on. Then open its settings at `/admin/tenantos/settings`.

**2. Enter the URL and API key**

Enter the TenantOS URL and paste the API key. The key is stored encrypted. Leave the key field empty later to keep the saved key. Changing the address, or turning off certificate checks, asks for the key again, because the saved key is only sent to the address it was saved for.

**3. Save and test**

Press Save settings, then Test connection. The test pings TenantOS and reads the API account and the TenantOS version. It never changes anything. The Connection card on the right shows the result.

![The Connection tab of the TenantOS settings](https://mintcdn.com/dezerx/7zoDaZC5lwbwCGMK/public/services/tenantos/connection.webp?fit=max\&auto=format\&n=7zoDaZC5lwbwCGMK\&q=85\&s=76663e5065ff71a7abc2111624c5ea97)

The settings page has seven tabs. Save settings saves every tab at once, not just the one you have open. The Server pools card lists each TenantOS product, with the number of free servers for dedicated ones.

### Connection

| Setting | Default | What it does |
| - | - | - |
| TenantOS URL | Empty | Your panel address, for example `https://panel.example.com` |
| API key | Empty | An admin or reseller key, stored encrypted |
| Verify the TLS certificate | On | Turn off only for a private test panel with a self signed certificate |
| Request timeout | 30 seconds | 5 to 120 |

### Customer access

| Setting | Default | What it does |
| - | - | - |
| Panel URL shown to customers | Empty | Used for panel login links when customers reach TenantOS on another domain than the API URL |
| Run customer actions as the customer's TenantOS account | On | Recommended. TenantOS then checks ownership and the role permissions itself, and logs the customer's IP |
| Allow one click login to TenantOS | On | Turns on Open control panel for customers |
| Log staff into the API account from the service tab | Off | Off opens the server page in TenantOS and staff log in themselves |
| Console proxy domain | Empty | Rewrites console links to your own noVNC reverse proxy, so the TenantOS domain stays hidden |

### Ordering

| Setting | Default | What it does |
| - | - | - |
| Pause automatic provisioning | Off | Paid orders wait as failed services until you retry them |
| Never assign servers with these tags | Internal | Comma separated. Products can add more |
| Include external provider servers | On | OVH and other providers that set their own password. Spartan reads the credentials from TenantOS after the install and shows them on the Access tab |
| Send the customer email address to TenantOS | Off | With an email, the customer can reset the panel password through TenantOS, even when panel login is off for the product |
| Skip servers with a running installation or job | On | Busy servers are never handed out |
| Skip servers that are powered on | Off | |
| Skip servers with an unknown power status | Off | |
| Username format | `dx{user_id}` | Placeholders `{user_id}`, `{first_name}`, `{last_name}` and `{random}`. A suffix is added when the name is taken |
| Account description | `DezerX customer #{user_id}` | Only staff see it in TenantOS. Same placeholders |
| VPS override format | Dotted paths | How resource overrides are sent when a VPS is created. Keep dotted unless TenantOS support tells you otherwise |

### Suspension

| Setting | Default | What it does |
| - | - | - |
| Power on suspension | Power off | Or leave it running |
| Switch port on suspension | No change | Disable the port. A server without a manageable switch port is powered off instead |
| Power on unsuspension | Power on | Or no change |
| Switch port on unsuspension | No change | Enable the port |

### Termination

| Setting | Default | What it does |
| - | - | - |
| Power when a dedicated server is freed | Power off | Skipped when the product runs a wipe profile |
| Delete VPS on the hypervisor when the service ends | On | Off leaves the VPS in TenantOS, moved back to your account |
| Reset reverse DNS when a server is freed | On | |
| Reset reverse DNS when a server is assigned | Off | |
| Reset to the default PTR template instead of empty | On | |
| Remove extra IPv4 addresses | Off | The primary address stays |
| Remove IPv6 addresses and subnets | Off | Keep one IPv6 assignment can keep one of them |
| Hostname after termination | Empty | For example `free{service_id}.example.com` |
| Delete the customer TenantOS account when it has no servers left | Off | |

### Tags

Tags Spartan adds to or removes from a server, comma separated. They move a server between your pool and a customer.

| Setting | Default |
| - | - |
| Add after provisioning | Assigned to client |
| Remove after provisioning | For Rent |
| Add after suspension | Suspended |
| Remove after unsuspension | Suspended |
| Add after termination | For Rent |
| Remove after termination | Assigned to client, Suspended |

### Automation

| Setting | Default | What it does |
| - | - | - |
| Never suspend, unsuspend or free servers with these tags automatically | Empty | The skip tags, see [Hourly sync and skip tags](#hourly-sync-and-skip-tags) |
| Sync hostnames and IP addresses from TenantOS every hour | On | |
| Check bandwidth limits every hour | Off | Uses the limit and action of each product |
| Tell admins when a server reaches its bandwidth limit | On | Only works while the hourly bandwidth check is on |

## Set up a product

Create a product, open the Module tab and pick TenantOS. The lists on this tab load live from TenantOS, so save the connection first. Refresh options reloads them.

![Server type, role, pool and OS fields on the Module tab](https://mintcdn.com/dezerx/7zoDaZC5lwbwCGMK/public/services/tenantos/product.webp?fit=max\&auto=format\&n=7zoDaZC5lwbwCGMK\&q=85\&s=9aa36cd3e7a5eaf0a876ffc7c711fe97)

**1. Server type and role**

Pick the Server type: Dedicated server from a pool, or Virtual server from a TenantOS VPS plan. The form reloads with the fields for that type. Then pick the Customer account role, the TenantOS role of the account Spartan creates for the customer. Admin and template roles are never offered, and a reseller role gets a warning because customers could create sub users.

**2. Dedicated: the pool**

A server qualifies only when it has every Pool tags entry (For Rent by default). Only these server IDs narrows the pool further, and Never use servers with these tags adds to the global exclusions. Without pool tags and without server IDs, orders are refused. The help text shows how many free servers match right now. IPMI login privilege is Operator (console and power) or User (read only), never Administrator. Upgrades and downgrades either waits for an admin to move the customer, or changes billing only and tells admins.

**3. VPS: the plan**

Pick the VPS plan. Resource overrides take one dotted plan path per line, the same paths as the TenantOS WHMCS module, for example `cores=4`, `memory=8192` or `disks.disk0.disk_size=80`. Apply configurable option changes to the running VPS is off by default. When on, paid option and plan changes set CPU cores, sockets, CPU units, memory and the first disk on the VPS. Disks only grow. Server name pattern sets the name shown in TenantOS.

**4. Operating system**

Pick the Default operating system, or Do not install an OS. Tick Let the customer choose the OS at checkout to show an OS picker, and use the Offer boxes to limit the list. Ticking none offers all of them, and reinstalls follow the same list. Disk layout, Scripts after the install (TenantOS script IDs), Power action when an install starts and Configure all IPv4 or IPv6 addresses in the OS fine tune the install.

**5. Wipe profile**

Dedicated products have Profile to run when the service ends. Pick a disk wipe profile here. It starts once the server is taken back from the customer.

**6. Hostname and network**

Use the hostname the customer enters at checkout is on by default. Otherwise the Hostname pattern applies, with `{service_id}`, `{user_id}` and `{random}`. Extra IPv4 addresses (0 to 256) and IPv6 subnet size (a prefix length such as 64) are assigned after the server, optionally from given subnet IDs. Run network automation after IP assignments lets TenantOS update switch VLANs.

**7. Bandwidth**

Monthly bandwidth limit in GB, 0 for unlimited. Bandwidth counted is total, incoming, outgoing or the 95th percentile of the last 30 days (then the limit is read as Mbit/s). Bandwidth period is the last 30 days or the calendar month. When the limit is reached, Spartan only shows it to the customer, tells admins, or suspends the service and tells admins. Actions only run while Check bandwidth limits every hour is on.

**8. Customer features**

Untick anything the customer should not be able to do. See the table below.

> [!WARNING]
>
> Set Profile to run when the service ends to a wipe profile. Without one, and without a default OS, a freed dedicated server goes back to the pool with the previous customer's data on its disks.

| Customer feature | Default | Server type |
| - | - | - |
| Power on, off, reset and power cycle | On | Both |
| Pick the next boot device (PXE, disk, BIOS) | Off | Dedicated |
| Reset the BMC | Off | Dedicated |
| Remote console | On | Both |
| Reinstall the operating system | On | Both |
| Boot the rescue system | On | Both |
| Cancel a running installation | On | Both |
| Edit reverse DNS | On | Both |
| Bandwidth, CPU, memory and disk graphs | On | Both |
| Hardware details | On | Both |
| Server activity log | On | Both |
| One click login to the TenantOS panel | On | Both |
| Reset the TenantOS panel password | On | Both |
| Manage SSH keys used for installs | On | Both |
| Create their own IPMI login | Off | Dedicated |
| Backups | On | VPS |
| Snapshots | On | VPS |

Configurable options can change the order per customer. Map an option to the OS profile id, disk layout id, VPS plan id, extra IPv4 addresses, IPv6 subnet size, monthly bandwidth, a VPS resource (cores, sockets, memory, CPU units, first disk size, IPv4 on the first interface, maximum backups or snapshots), or Dedicated pool: server must have this tag, which adds a pool tag per order. An option named `vps.cores` or any other `vps.` path overrides that resource too. Customers cannot change these options after purchase.

## What happens and when

| Spartan event | Dedicated server | VPS |
| - | - | - |
| Paid order | Reserves one free server for this order only, moves it into the customer's TenantOS account and sets the hostname and tags | Creates the VPS from the plan in the customer's account. A marker on the server stops a retry from creating a second one |
| Right after | Assigns the extra IP addresses and installs the chosen OS with a random root password, which the customer finds on the Access tab | Same |
| Suspend | Suspends the server for the customer's account, powers it off (or what the Suspension tab says), adds the Suspended tag and disables their IPMI login | Same, without IPMI |
| Unsuspend or renewal paid | Lifts the suspension, powers it on and enables their IPMI login again. A renewal only unsuspends a service an admin did not suspend | Same |
| Upgrade or downgrade | Hardware never changes by itself. Spartan waits for an admin, or changes billing only, as the product says, and tells admins | Moves the VPS to the plan of the new product, and applies the overrides when the product allows it |
| Terminate | Removes the customer's IPMI login, resets reverse DNS, removes extra IPs if set, powers it off or starts the wipe profile, and returns it to your account tagged For Rent | Deletes the VPS on the hypervisor |

With no free server in the pool, checkout tells the customer the server is sold out. The stock is checked per configuration, so a tag option counts its own pool.

Spartan never touches a server that TenantOS shows in another account than the customer's. Suspend and terminate leave it alone, and unsuspend is refused. Every problem becomes an urgent service note and a notification for every super admin.

## The TenantOS tab for staff

The TenantOS tab on the admin service page shows the server, its hardware, IP addresses, the customer's TenantOS account and traffic.

![The TenantOS tab on a service](https://mintcdn.com/dezerx/7zoDaZC5lwbwCGMK/public/services/tenantos/admin.webp?fit=max\&auto=format\&n=7zoDaZC5lwbwCGMK\&q=85\&s=9b8d0c33d4abbfd1e1d1026b7cfe414d)

* Sync from TenantOS reads the hostname, IP addresses and OS again.
* Open in TenantOS opens the server page. With Log staff into the API account from the service tab on, it logs you in.
* Power sends on, off, reset or power cycle.
* Reinstall or Boot rescue with a profile, disk layout, hostname and an optional root password. The password is shown once and saved on the customer's Access tab.
* Assign extra IPs gives the product's extra addresses, for example after the step failed on the order.
* Check bandwidth reads the usage now. Tick Apply the product action when over the limit to also run the product's action. Pause bandwidth actions stops automatic bandwidth actions until the next renewal.
* Unlink asks you to type UNLINK. Tick Take back and unlink to free the server first, like a termination. Without it, the server stays as it is in TenantOS.
* An unlinked service can be linked to a server by its ID, optionally with a TenantOS user ID. Show server pool lists your dedicated servers, marks each one Free or Not free and says why. A TenantOS account Spartan did not create needs the box This TenantOS user was not created by DezerX, and then panel login and panel password reset stay off. The API account and admin accounts are never linked.

Change owner on the admin service page moves the server into the new owner's TenantOS account, removes the old customer's IPMI login and forgets the stored passwords.

## The customer side

Customers manage the server from the Server group on their service page.

![The Server tabs in the client area](https://mintcdn.com/dezerx/7zoDaZC5lwbwCGMK/public/services/tenantos/client.webp?fit=max\&auto=format\&n=7zoDaZC5lwbwCGMK\&q=85\&s=a9e3d8ef79339549c79b369309ef79fa)

| Tab | Use |
| - | - |
| Overview | Power status, hostname, IP address, OS, hardware and traffic, with the power buttons and Open control panel. Boot device and BMC reset on dedicated servers when allowed |
| Console | Opens the remote console in a new tab. It only works from the customer's current IP address |
| Reinstall | A new OS from the allowed list, or the rescue system. A running installation can be cancelled |
| Network | IP addresses and reverse DNS |
| Statistics | Bandwidth, CPU, memory and disk graphs |
| Backups | VPS only |
| Snapshots | VPS only |
| IPMI | Dedicated only. The customer creates their own BMC login, with the privilege set on the product |
| Access | Open control panel, a new panel password, the stored root and rescue passwords, and SSH keys for reinstalls. Service owner only |
| Activity | The server activity log |

Tabs only show for features the product allows, and only open while the service is active and linked. Each tab is also a permission for service members, and Power actions is a permission of its own.

With Run customer actions as the customer's TenantOS account on, server actions run as the customer's own TenantOS account, so TenantOS still applies its ownership checks and role permissions.

## Hourly sync and skip tags

`tenantos:sync` runs every hour for active and suspended services. It:

* copies the hostname, IP addresses and OS from TenantOS, while Sync hostnames and IP addresses from TenantOS every hour is on,
* finishes installs, and reads the provider credentials for external servers,
* alerts admins when a server is missing, is now in another account, or the service owner changed outside Spartan's change owner,
* checks bandwidth limits on active services, while Check bandwidth limits every hour is on.

Run it by hand for one service with `php artisan tenantos:sync --service=123`. Add `--no-bandwidth` to skip the bandwidth check.

![The Automation tab](https://mintcdn.com/dezerx/7zoDaZC5lwbwCGMK/public/services/tenantos/automation.webp?fit=max\&auto=format\&n=7zoDaZC5lwbwCGMK\&q=85\&s=10646298bff81be082b734547201157a)

Servers with a tag from Never suspend, unsuspend or free servers with these tags automatically are skipped by automatic suspend, unsuspend and terminate. Spartan only changes the service on its own side and alerts admins, so you can handle these servers by hand. Actions staff start on the service page still run.

## Troubleshooting

* **The API key was rejected.** The key is wrong or deleted, or its IP restriction does not include your Spartan server.
* **No free server matches this product right now.** Add a server with the pool tags in TenantOS. It must be in your API account, not suspended, not busy and without an excluded tag. Show server pool on the service's TenantOS tab tells you why each server is not free. Then retry the order.
* **Orders are refused for a dedicated product.** It has no pool tags and no server IDs. Set one of them.
* **No customer role to pick.** TenantOS has no assignable end user role. Create one there.
* **Some lists could not be loaded from TenantOS.** The product form shows this when plans, profiles or tags fail to load. Test the connection, then press Refresh options.
* **Suspension finished with problems.** The power provider does not support the power action, or the server has no manageable switch port. The service note says which.
* **Upgrade not applied.** Dedicated hardware never changes by itself. Move the customer to a matching server, then mark the invoice as processed.
* **The console does not open.** The link is bound to the customer's IP. Behind Cloudflare Spartan reads the real IP, behind another proxy make sure the real IP reaches Spartan.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.