Skip to content
Maran

How it works

How it is built

The three processes on a Maran server, the contract between them, and the rules that decide what the root daemon is allowed to do.

A Maran server runs exactly three processes. The split between them is the product's main design decision, and most of the rules below follow from it.

The three processes

ProcessRuns asHolds
maran-apian unprivileged system userevery piece of business logic, and the only database connection
maran-agentrootnothing; it is stateless, with no database, and its only settings are two start-up values in /etc/maran/agent.env
PostgreSQLits own userthe panel's data, on a unix socket with no TCP listener at all

The panel never touches the system, and the agent never decides anything. The process that knows what should happen has no privileges. The process with privileges only knows how to do a fixed list of things.

The contract between them

They speak over a unix socket, and what travels is a named operation with typed, validated arguments. Four rules follow:

  • No operation runs a caller-supplied program, not even a restricted or whitelisted one. So the set of things the root process can be made to do is finite, written down and reviewable.
  • There is no shell string anywhere in the exchange. A domain is not escaped before it reaches a configuration file. It is validated as a domain (letters, digits, hyphens and dots), so there is no newline in it that could end one directive and start another of the caller's choosing.
  • The agent checks who is asking. The daemon reads the peer credentials on the socket before it considers the operation, so it knows which process is on the other end and does not rely on what it is told.
  • Every program the agent starts is bounded. Each has a deadline and an output cap. Checks and reads get 60 seconds, ordinary changes 120, service reloads 240, database statements 300, package installs 35 minutes, backups up to 12 hours. At the deadline the whole process group is killed, not just the first process. A program that prints more than 4 MiB is killed and its output discarded. A timeout reaches the panel as an ordinary SYSTEM_FAILURE result with no tool output, so a hung validator cannot block other customers' writes.

Writing a configuration file

Every privileged write follows the same order:

  1. render into a temporary file;
  2. fsync;
  3. rename it into place atomically;
  4. have the service itself validate the result with nginx -t, not with a regular expression of ours;
  5. reload;
  6. roll the file back if either the validation or the reload refuses.

One bad render cannot take down a server's other sites, because the server's own parser decides whether the render was good.

Isolation between accounts

  • An account is a real Linux user, with its own home directory and filesystem permissions.
  • Its PHP runs in its own php-fpm pool under its own uid, and file operations run as that user, never as root.
  • Tenant tables are scoped by account in the database, through query filters an automated test walks the whole model to verify.
  • A request for another account's resource answers 404, never 403, so an error never confirms that a row exists.

What is deliberately absent

There is no message broker, no sidecar and no second daemon. Background work runs on durable queues stored in PostgreSQL, and Maran's own part of the server is the three processes in the table above. Besides them, the installer sets up the services a hosting server needs and the agent manages: the web server, PHP, the database server for hosting accounts, SFTP, the firewall and the scheduler. It also installs the FTPS service, which an operator turns on themselves.

Paid modules do not change this. They are C# modules that drive operations already compiled into the open agent. The agent never loads external code, so a licence cannot add a new privileged capability.