Architecture

Understanding how Simuzo's components work together to provide secure hosting isolation.

Overview

Simuzo leverages Linux kernel features and containerization to provide resource management and user isolation:

cGroups v2 — Resource management (CPU, memory, IO, processes)
SimuzoFS — Filesystem isolation (Jailed per-user filesystem)

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Simuzo Architecture                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐         ┌──────────────┐         ┌───────────┐ │
│  │  Webuzo/     │         │   Simuzo     │         │  Apache   │ │
│  │  Plesk/cPanel│◄──────►│   Admin API   │◄──────► │  (Ports)  │ │
│  └──────────────┘         └──────────────┘         └───────────┘ │
│          │                        │                        │      │
│          ▼                        ▼                        ▼      │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │                    Simuzo Core                               │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │ │
│  │  │ User Mgmt   │  │ cGroup Mgr  │  │  CLI Interface      │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘   │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │ │
│  │  │ Stats Coll  │  │ Audit Trail │  │  Task Manager       │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘   │ │
│  └──────────────────────────────────────────────────────────────┘ │
│          │                        │                        │      │
│          ▼                        ▼                        ▼      │
│  ┌──────────────┐         ┌──────────────┐         ┌───────────┐  │
│  │ simuzofs-cmd │         │  cgroup.sh   │         │    PAM    │  │
│  │ (Jail Cmd)   │         │ (cGroup Mgr) │         │  Module   │  │
│  └──────────────┘         └──────────────┘         └───────────┘  │
│          │                        │                        │      │
└──────────┼────────────────────────┼────────────────────────┼──────┘
           │                        │                        │
           ▼                        ▼                        ▼
    ┌──────────────┐         ┌──────────────┐         ┌───────────┐
    │  /var/simuzo │         │ /sys/fs/     │         │  /etc/    │
    │     /fs/     │         │  cgroup/     │         │  pam.d/   │
    │  (Jail Root) │         │   simuzo/    │         │           │
    └──────────────┘         └──────────────┘         └───────────┘

Core Components

Core

The main application handles all web requests and business logic:

Component	File	Purpose
Admin Panel	`admin.php`	Server administration interface
End User Panel	`enduser.php`	User self-service interface
CLI Interface	`cli.php`	Command-line operations
Universal Loader	`universal.php`	Main entry point

SimuzoFS (Filesystem Isolation)

SimuzoFS provides jail isolation by isolating each user's filesystem view.

Components

Component	Purpose
simuzofs-ld.so	LD_PRELOAD for path restrictions
pam_simuzofs.so	PAM authentication module
simuzofs-cmd	Execute commands inside jail
simuzofs-init	Initialize jail environment

Jail Filesystem Structure

/var/simuzo/fs/
├── user1/
│   ├── root/
│   │   └── simuzofs/       # Persistent Volume (Physical Source)
│   │       ├── etc/
│   │       │   ├── passwd  # User-specific filtered passwd
│   │       │   └── group   # User-specific filtered group
│   │       └── var/log/    # User-specific logs
│   ├── etc/                # Bind-mounted (rbind) from skeleton
│   ├── usr/                # Bind-mounted (rbind) from skeleton
│   ├── home/               # Bind-mounted from host
│   └── tmp/                # Bind-mounted from host
├── user2/
│   └── ...
└── simuzofs/               # Global Skeleton Template

How SimuzoFS Works

User logs in via PAM module (pam_simuzofs.so)
PAM sets up environment for jail access
simuzofs-ld.so intercepts file operations via LD_PRELOAD
File access is restricted to user's jail directory
simuzofs-cmd executes commands within the jail context

cGroups v2 (Resource Limits)

Simuzo uses Linux cgroups v2 for resource management and throttling.

cGroup Hierarchy

/sys/fs/cgroup/simuzo/
├── user1-1000/
│   ├── cpu.max
│   ├── memory.max
│   ├── memory.high
│   ├── io.max
│   ├── pids.max
│   └── ...
└── user2-1001/
    └── ...

/sys/fs/cgroup/simuzo-db/
├── user1-1000/
│   └── (database-specific limits)
└── user2-1001/
    └── ...

Resource Controllers

Controller	File	Limits
CPU	`cpu.max`	CPU percentage quota
Memory	`memory.max`, `memory.high`	RAM allocation and throttling threshold
IO	`io.max`	Read/write bandwidth and IOPS
PIDs	`pids.max`	Maximum process count

Entry Processes (EP) Limits

Entry processes limit concurrent connections/processes for each user.

Components

Component	Purpose
simuzo-procmon	Monitor process counts per user
simuzo-load	Privilege escalation helper

How EP Limits Work

simuzo-procmon runs as a daemon monitoring process events via Netlink.
It identifies new user processes and automatically moves them to their assigned cgroups.
Counts active processes per user via UID mapping to enforce Entry Processes (EP) limits.
Writes real-time statistics to /run/simuzo/ep_stats.json.
If a user exceeds their limit, new processes are terminated to prevent resource exhaustion.

MySQL Governor

MySQL Governor monitors and throttles database resource usage per user.

Components

simuzo-mysql-governor — Systemd service for monitoring
Database Map — User-to-database mappings at /var/run/simuzo/dbmap
performance_schema — MySQL tables for query monitoring

Throttling Mechanism

Governor reads active MySQL threads from performance_schema
Maps MySQL users to system users via dbmap
Applies throttling based on user's resource plan
Slow queries exceeding limits are terminated

Data Flow

User Login

User ──► (Apache - PHP FPM) / Exim ──► Simuzo Core
                                              │
                                              ▼
            SSH / SU ──►            PAM Check
                                              │
                                              ▼
                                    pam_simuzofs.so ──► /etc/pam.d/simuzo
                                              │
                                              ▼
                                    Set UID/GID ──► Grant Jail Access
                                              │
                                              ▼
                                    simuzofs-ld.so ──► LD_PRELOAD
                                              │
                                              ▼
                                    Restricted FS Access ──► /var/simuzo/fs/{user}/

Resource Limit Enforcement

User Process ──► cgroups ──► Limits Applied
     │                 │
     │                 ├─► CPU throttle (%)
     │                 ├─► Memory limit (bytes)
     │                 ├─► IO throttle (bytes/sec, IOPS)
     │                 └─► Process count limit
     │
     └─► simuzofs-ld.so ──► Filesystem restriction

Panel Integration Details

Simuzo integrates with hosting panels to provide unified management.

Supported Panels

Panel	Status
Webuzo	Supported
cPanel	Supported
DirectAdmin	Supported
Plesk	Supported
Interworx	Supported

Integration Points

User Management — Create/delete users via panel API
Resource Limits — Apply cGroup limits based on panel plans
Jail Setup — Initialize user jail on account creation
Stats Collection — Aggregate resource usage per user

Key Paths

Path	Purpose
`/usr/local/simuzo/`	Installation directory
`/var/simuzo/`	Runtime data directory
`/var/simuzo/fs/`	Jail filesystem root
`/sys/fs/cgroups/simuzo`	cGroup hierarchy mount
`/sys/fs/cgroups/simuzo-db`	Database cGroup hierarchy mount
`/var/simuzo/users/`	Per-user configuration
`/var/simuzo/logs/`	Log files
`/run/simuzo/`	Runtime files (stats, PID files)
`/run/simuzo/stats.json`	Live statistics
`/run/simuzo/ep_stats.json`	Entry process stats
`/run/simuzo/dbmap`	MySQL user mappings

Next Steps

Requirements — Check system requirements
Server Installation — Install Simuzo