Skip to content
Maran

How it works

Hosting accounts

What a hosting account is on a Maran server: a real Linux user with its own home, quota and limits, and what creating, suspending and deleting one does.

A hosting account is a system user on the server, with its own uid, its own home directory and the disk quota its plan carries. It is more than a row in a table that the panel interprets. Everything a customer owns (their sites, their files, their php-fpm pool) runs as that user.

This matters because the kernel and the filesystem enforce the boundary between two customers. The application does not have to remember to add a condition to every query. An application that forgets leaks data, and a filesystem permission never forgets.

What creating one does

The panel asks the agent, and the agent does the work on the host:

  1. Creates the system user and its home directory.
  2. Applies the plan's disk quota to it.
  3. Group-owns the home by the web server's group at mode 0750, so the server can traverse into a document root without the home being readable by every other local user.

Only then does the database row appear. The agent acts first and the row follows, so the panel never claims an account the server does not have. If the host refuses, there is no row to reconcile later.

The new account form

Administrators create an account under Accounts → New account. The form asks for:

  • Primary domain, entered without www.. The panel refuses a primary domain that starts with www..
  • Username, the account's system user name. It is filled in from the domain as you type (www.my-shop.example.com suggests myshop) until you change it yourself. It must be 3 to 30 lowercase letters, digits or underscores, and start with a letter.
  • Plan, whose disk quota, counts and CPU, memory and process limits bound the account.
  • Owner email, where the owner's invitation goes.
  • Owner language, chosen from the languages the panel ships text in (English, Russian and Armenian), each named in itself. There is nothing to type, and the server refuses any other value. It starts as your own interface language. The owner's invitation is written in it, both when the account is created and every time the invitation is resent, whatever language the administrator who sends it uses.

A panel beside the form lists what creation makes on the server. The owner sets their own password from the invitation, so the administrator never knows it. The server checks every field again, whatever the form allowed through.

Suspension is a state, not a deletion

Suspending stops the sites and the logins and leaves everything else where it is. Reactivating puts it back as it was. A billing system that suspends for non-payment and reactivates on payment needs exactly this. A panel that could only delete would turn every lapsed invoice into data loss.

Suspension also closes the panel for that account, and only for that account. Everyone who acts for it, the owner and the people the owner added, is refused at sign-in, on refresh and when switching to it, and the sessions speaking for it end. That includes a person who was invited and has not accepted yet: if they accept while the account is suspended, they still cannot sign in. Invited members of a suspended account are refused both at sign-in and on every API call made for it.

A sign-in token issued before the suspension stops working too. Every request it makes for that account is answered with "This account is suspended, so it cannot be used until it is resumed." (409), so the block does not wait for the next sign-in.

A person who owns two accounts keeps working in the other one. The suspended account leaves their account selector, and switching to it is refused with the same message. Only a person whose every account is suspended is refused at sign-in, with the same answer as a wrong password. Reactivating the account lets them back in.

The panel checks the server afterwards, both when suspending and when reactivating. It compares what each of the account's sites actually serves with the suspension page. If it cannot make that comparison for a site, because the site's virtual host file cannot be read or parsed, the request is refused and nothing is changed:

  • Suspending answers "The account was not suspended: the server could not be observed to have stopped it. Nothing has been changed; please try again."
  • Reactivating answers "The account was not reactivated: the server could not be observed to have started it again. Nothing has been changed; please try again."

The panel will not claim a state it could not see. Open the account's sites, find the one with a damaged or unreadable configuration, repair it, then repeat the request. The audit journal records no change, because none was made.

Deleting removes what the account left behind

Many panels leave orphans behind when they delete an account. Here, these go before the system user does:

  • its databases and their users,
  • its file transfer logins,
  • its jail and the jail's mount unit,
  • its queued at jobs, where at is installed,
  • a lingering session manager (systemd --user), where the host runs systemd,
  • its running processes: every process the account owns is ended, and the deletion checks that none is left,
  • its shared memory, message queues and semaphores,
  • its files left in shared temporary directories (/tmp, /var/tmp, /dev/shm), outside the home.

A failure in any of that aborts the deletion. The processes, the shared memory and the temporary files go last, just before the user. A temporary directory holding another owner's files is never emptied: the deletion stops and says so. If a process survives several rounds of being killed, the system user is not removed and the panel reports a system failure. Running the deletion again finishes it once the process is gone. Processes that have already exited and only await collection (zombies) are ignored. An account re-created under the same name afterwards inherits nothing: no database, no login, no password and no running process.

Plans

A plan is the package an account is created on: a name and the limits every account on it lives within. Administrators manage plans under Accounts › Plans in the panel's navigation, where a plan can be created, edited and deleted. Customers never see this page, only the limits of their own plan. When an administrator creates an account, its plan is chosen in the Plan field, which searches the server's plans as you type.

  • Disk quota is the space the account's home may use, in megabytes. The kernel enforces it.
  • Sites, databases and SFTP logins are the most of each an account may have, and each must be at least 1.
  • FTPS logins and cron entries work the same way, except that 0 is allowed and means the plan includes none.
  • PHP workers per pool is the worker budget of the account's php-fpm pool.

Some rules are worth knowing before you edit one:

  • Names are unique, and case does not count: Business and business are the same name, and the panel refuses the second.
  • A plan in use cannot be deleted. While any account is on it the deletion is refused and nothing changes; move those accounts to another plan or delete them first.
  • Editing a plan reaches the accounts already on it. A changed disk quota is pushed to every existing account.
  • A quota cannot be lowered below any account's usage. The panel measures every account on the plan first; if one is using more than the new figure, the whole edit is refused and no account is touched.
  • The count limits only gate new things. Lowering sites or databases does not remove what an account already has. It only stops the account from adding more until it is back under the limit.

Plan features

Beside its limits, a plan says which features its accounts have. On Plans → New plan and the edit form, a Features group has one checkbox per feature: Mail, DNS, Databases, Scheduled tasks (cron), File transfer (SFTP and FTPS), Backups, Websites, SSL certificates, Background tasks and PHP versions. A new plan starts with all of them ticked. Plans that existed before keep all of them, including the last four, which those plans included implicitly before they could be ticked.

  • A change reaches every account on the plan on its next request, and is audited as a plan update with the features before and after.
  • The customer's menu follows the plan. An item for a feature the plan lacks is hidden, and a section disappears when all of its items are hidden.
  • The panel refuses the request as well. A direct request for databases, scheduled tasks, file transfer, backups, websites, certificates, background tasks or a site's PHP version is answered with 403 and "This feature is not included in your plan".
  • A plan's features never restrict administrators.
  • Mail and DNS can be ticked, but they have no pages yet.

Team access: sub-users

An account owner can give other people access to part of the account under My account → Sub-users. The owner invites a person with a login name, an e-mail address and the features to grant, can change those features later, and can remove the person after a confirmation. The invitee receives a one-time link by e-mail and sets their own password, so the owner never knows it.

Resending an invitation and offering a place to an existing login are not in 1.0.0-beta.4. They arrive with the next release.

  • Grantable features are Mail, DNS, Databases, Cron, File transfer, Backups, Websites, SSL certificates, Background tasks and PHP versions, and a feature must also be in the account's plan. A member holding none of them reaches none of those areas. Switching a site's PHP version needs PHP versions in addition to Websites.
  • Changes apply on the person's next request. Removal takes effect at once everywhere. The panel checks on every request that the person still belongs to the account, so a removed person's existing sign-in stops working immediately instead of at its expiry.
  • Action needed after upgrading: re-grant Websites, SSL certificates, Background tasks and PHP versions. People who were invited before this was gated keep the features they were given but do not receive these four, so until the owner grants them under Sub-users → Change features those members lose access to the sites, certificates, tasks and PHP settings they could reach before.
  • Only the owner manages the team. Members and administrators are refused.
  • A pending invitation can be resent. For a person who has not accepted yet, Resend invitation in the list sends a new e-mail to the address already stored on that login, never to one typed in the request. The earlier link stops working at once, so only one link is live. Once the person has accepted, there is nothing to resend and the panel answers SubUserNotPending (409). Resending counts against the sending limit below and is audited as Sub-user invitation resent.
  • A login that already exists can be offered a place. Under Add an existing login, enter the login name or e-mail address and the features to offer. The person is not added yet: they get an e-mail with no link in it, and an invitation card appears on their My account page the next time they sign in, where they Accept or Decline. They join with exactly the features offered, and only if they accept. An offer stays open for 14 days, shows in your list as Offer sent, and Cancel offer withdraws it. It can only go to an active customer login that is not already on the team, and only while your account is active. As with an invitation, the panel gives the same answer whether or not that login exists, and the outcome is recorded for the administrator in the audit journal. Accepting is refused with MembershipOfferAccountSuspended (409) while the account is suspended, and an offer that is gone, expired or already answered is MembershipOfferNotFound (404). Offers count towards the team limit below, and an administrator viewing as the person cannot accept or decline for them.
  • The panel does not say whether a login name or address was already taken. An invitation request always gets the same answer (accepted, with the name and address you typed), whether or not the name or address already belongs to a login on this server. If it was free, the person appears in the list as Invited and receives the e-mail. If it was taken, nothing is created and nothing is mailed. An invitation never adds an existing login to your account; use an offer for that. The refusal is recorded for the administrator in the audit journal.
  • There is a limit on the team. One account may hold 25 sub-users, invited or active, unless the administrator sets another number (SubUsers__MaxPerAccount, 1 to 1000). Past it, the panel answers with the code SubUserLimitReached until you remove someone.
  • Sending invitations has its own rate limit, per account and separate from accepting one: 20 invitations an hour by default (RateLimiting__InvitationSendMaxRequests and RateLimiting__InvitationSendWindowSeconds). Further requests are answered with 429 and a Retry-After header.
  • Inviting, changing features and removing are each written to the audit journal.
  • The list shows each person's state: Active, Invited or Offer sent. It cannot show a suspension, because nobody can sign in to a suspended account to read the list. No invitation can be issued while the account is suspended, so reactivate it first.

More than one account per login

One login can own several accounts. A customer with two or more picks the active one from the account selector in the header, as described in finding your way around the panel. Sign-in starts on the oldest account, every switch is audited as Switched active account, and switching to an account the login does not belong to is refused as not found.

Viewing as an account

An administrator can open View as this account on an account's page. The panel then shows the customer panel as that account's login, with a banner on every page: "You are viewing as the account name and its login". A Back button returns to the administrator's own session, on the account's page. Viewing ends by itself after 15 minutes.

  • Viewing is read-only apart from a short allow-list. Everything the customer can read, you can read. Anything that changes something is refused unless it is on the list of safe changes, and an action nobody classified is refused by default. The safe changes are pinning and unpinning a page and ending the view. Each of these is refused, because each would leave something behind that outlives the 15 minutes: creating an SFTP or FTP login, a database or a cron entry; running a cron job; creating or deleting a site, a certificate or a backup; changing the password, two-factor settings, sessions or sub-users; switching accounts; and starting a second view. A refused action answers 403 with the code HostViewAsNotAllowed. To make such a change, end the view and do it as the administrator.
  • Audited both ways. Starting and stopping are recorded as Started viewing as an account and Stopped viewing as an account, with the administrator as the actor. Actions taken while viewing record the administrator as the impersonator.
  • The customer can see it. The view appears on their sessions screen.
  • Viewing as a reseller, and a reseller viewing its own accounts (not in 1.0.0-beta.4; arrives with the next release). An administrator will be able to view as a reseller from the reseller's page, and a reseller as the owner of one of its own accounts, never of another reseller's. Each is a single step: a view cannot start another view.
  • The audit screen shows who was viewing (from the next release; 1.0.0-beta.4 does not show it). An entry written while an administrator viewed the panel as a customer prints "via" and the administrator's name under the actor, on the audit list and in the dashboard's recent activity, and the audit search also finds the administrator's name.

Runtime limits

Beside the disk quota and the counts, a plan carries three ceilings on what each account on it may use at once. Each is either a figure or No limit:

  • CPU (% of one core): a share of one core. 50 is half a core, 200 is two whole cores.
  • Memory (MB): the most memory the account's processes may hold together.
  • Processes: the most processes and threads the account may run at once.

The agent writes them onto the account's systemd slice, user-<uid>.slice. It does so when the account is created, when a plan's ceilings change (for every account on it), and when an account moves to a plan with other ceilings. A new account always gets all three, "No limit" included, so an account that reuses an old uid never inherits its predecessor's ceilings. If the server refuses them, the account is not created.

A lowered ceiling is applied immediately. CPU is throttled, the next process past the cap is refused, and memory above a lowered cap is reclaimed from the account, which can end the account's own processes. Plans that existed before this feature are "No limit" on all three.

In the provisioning API a ceiling is {"kind": "limited" | "unlimited", "maximum": n}. A missing ceiling, a limited zero and an unlimited ceiling with a figure are refused with 400.

What the slice covers, and what it does not:

  • Covered: the account's SSH and SFTP sessions and everything started under them.
  • Not covered: PHP workers. Each PHP version runs one php-fpm master as a system service, and every pool's workers belong to it, not to the account's slice. A busy PHP site is bounded only by PHP workers per pool.
  • Not covered: cron jobs on the Debian family. Debian's cron PAM stack registers no session, so a job runs in the cron service's cgroup. On the RHEL family cron jobs land in the user's slice, according to the distribution's shipped PAM files; this has not been verified on a host yet.

Running a scheduled task now

A cron entry can be started by hand from Scheduled tasks → Run now, to check that it works without waiting for its schedule. It runs as the account's own user, inside the account's resource slice, so the plan's CPU, memory and process limits apply, with the crontab's environment. It is stopped after two minutes, and stopped without keeping its output if it prints more than 64 KiB on one stream. When a run reaches the output limit, the server stops the job's own unit and waits for confirmation before it reports the run as stopped. If the stop cannot be confirmed, the run is not reported as stopped, because the job may still be running until the server's own runtime ceiling ends it. The request is answered with CronRunNotStopped (500) instead, which says the job may still be running and that you should check it before running it again. The result shows how the run ended, its exit code, how long it took and both output streams.

Run history keeps the last twenty runs started this way for each entry, searchable in their output and filterable by outcome. Runs that cron starts on the schedule are not in it; the last one is still under Last run. A disabled entry can be run by hand; a suspended account's entries cannot.

What a customer sees

A customer signs in to their own account and sees nothing that belongs to the server. The menu has nine sections: System status, Sites and domains, DNS, Mail, Databases, Files and access, Backups, Activity (background tasks) and My account (profile, two-step verification and sessions). A section with more than one page opens as a submenu.

  • Pages that are not built yet are shown, disabled. They are greyed out, marked "Coming soon" and cannot be opened, so you can see the shape of the panel before every page exists.
  • A feature the plan does not include is hidden. The menu follows the plan's features (see Plan features above), and an item for a feature the plan lacks is not offered.
  • At a plan limit, the create action is replaced by the reason. When an account holds as many sites, databases, SFTP logins, FTPS logins or cron entries as its plan allows, the screen says so instead of offering another, using the same counts as the account's Resources card. The panel refuses the create on its own as well. The menu and the screens are only advice, and the server enforces the limit.
  • On a phone, the bottom bar holds Home, Sites, Mail and Account, with More opening the full menu. Mail is disabled until mail hosting lands.

One limitation worth knowing

An account created before 1.0.0-beta.1 does not have the group ownership on its home that lets the web server reach a document root, and there is no repair command. chgrp www-data /home/<account> fixes one by hand, nginx instead of www-data on the RHEL family.

Every action above is written to the audit journal, which is append-only.