Restricted Shell Policy
QuickBox Pro sandboxes standard (non-admin) users into a restricted shell built on lshell. It intercepts every command a limited user types and checks it against a whitelist before running it — so a seedbox user can manage their own torrents and files without being able to roam the server, chain commands, or escape to an interactive shell.
The Restricted Shell editor lives in the dashboard at Settings → Security → Restricted Shell and is the recommended way to tune that policy. It exposes the safe, user-facing fields of the lshell configuration as guarded form inputs, previews every change before it lands, and stores your edits in the shared database so they survive qb update — where a hand-edited /etc/lshell.conf would be overwritten.
The Restricted Shell editor follows the standard Security Settings gates: admin.settings.read to view the policy, admin.settings.update to apply a change (or user level 9+). Writes are CSRF-protected. Navigate to Settings → Security → Restricted Shell from the sidebar.
This page edits the shared restricted-shell policy — the command whitelist and hardening applied to every limited-shell user. To choose which shell level a specific user gets (sudo, full, or limited), use User Management → User Admin in the dashboard or qb user shell on the CLI.
What the editor does
Edits the safe fields
Ten user-facing policy fields — allowed and forbidden commands, over-SSH commands, SCP/SFTP, warnings, process cap, the shell banner, and aliases — are editable as guarded form inputs
Locks the security fields
The log paths, path confinement, and no-exec backstop are always rendered from the shipped base and cannot be edited — changing them would break confinement or the Fail2Ban jails
Previews before applying
A Preview action shows the current vs proposed policy and which fields changed, so nothing is written until you have seen the diff
Applies safely
The new config is round-trip parsed exactly as lshell reads it before it ever replaces the live file — a config that fails validation is never applied, so a bad edit can't lock every limited user out
Editable fields
These ten [default] fields are exposed as form inputs. Each input carries the same guard rails the server enforces on save, so the UI hints match what will actually be accepted.
| Field | What it controls | Guard rails |
|---|---|---|
Allowed commands | The command whitelist a limited user may run interactively | May never include a shell or shell-escape editor ( sh, bash, dash, zsh, ksh, csh, tcsh, vi, vim) |
Forbidden patterns | Tokens blocked anywhere in user input — command chaining, piping, redirection, subshells | Must be non-empty and must retain every required token: ; & | ` > < $( ${ sudo ./ |
Over-SSH commands | Commands allowed via non-interactive SSH (e.g. ssh user@host rsync ...) | Must be a subset of the effective Allowed list |
Warning counter | Forbidden-command warnings before the session is terminated | 1–10 |
Strict mode | When on, every forbidden token counts as a warning and is logged in the shape the Fail2Ban filter recognizes | On / off |
SCP | Allow file transfer via SCP | On / off |
SFTP | Allow the SFTP subsystem | On / off |
Max processes | Per-user process/thread cap (RLIMIT_NPROC) that stops a fork bomb on a shared box | 0 (disabled) or 100–10000 |
Intro banner | The welcome text shown when a limited user logs in | Free text |
Aliases | Command aliases applied in the restricted shell (e.g. ll → ls -l) | Key/value pairs |
Adding a command to Allowed gives every limited-shell user on the box that command. Keep the list tight — the default whitelist covers the torrent, file-management, and transfer tools a seedbox user needs and nothing more. The editor refuses to add any interactive shell or a text editor with a known shell-escape (like vi/vim), because those would let a user break out of confinement.
Locked fields
These fields are always rendered from the shipped base config and are rejected if you try to send them as an edit. They are locked on purpose:
| Locked field | Why it is locked |
|---|---|
logpath, loglevel, logfilename | The Fail2Ban shell-confinement filters match against these exact log paths and levels. Changing them would silently break brute-force detection on the restricted shell |
path, home_path, env_path, allowed_cmd_path | These confine a user to their own home directory and control which system directories are searched for command binaries — the core of the sandbox |
path_noexec_strict | The no-exec backstop that stops a user executing arbitrary binaries. lshell fails closed at login if its supporting library is missing |
history_file | The per-user command-history location, pinned to the user's home tree |
The locked fields are not editable from the dashboard, the API, or a hand-edited config that the dashboard re-applies. They are what keeps a limited user inside their home directory and what keeps the Fail2Ban shell jails working. If a locked field is ever sent as an override, the server rejects the whole request rather than silently accept it.
Preview, then apply
Editing the policy is a two-step, no-surprises flow:
- Edit the fields you want to change. Each input validates against its guard rails as you type.
- Preview — the editor shows the current policy alongside the proposed one and lists exactly which fields changed. Nothing is written yet.
- Apply — the new configuration is validated the way lshell itself parses it, then atomically swapped in. If validation fails, the live config is left untouched and the errors are shown.
Applying a new policy does not disturb users who are currently logged in — their session keeps the previous policy until they next log in. The change takes effect for each limited user on their next login.
Per-field revert to base
Every editable field can be reverted to the value QuickBox ships. The editor compares your saved policy against the pristine base, so you can drop a single override without resetting everything else. When you edit a value back to exactly the shipped base, that override is dropped automatically — it becomes a true “no override” rather than an override that happens to match.
Clearing all overrides resets the policy entirely to the shipped base.
Your edits survive qb update
The editor stores your changes as an override document in the shared database, not as a hand-edit of /etc/lshell.conf. That distinction matters:
/etc/lshell.confis a derived file — QuickBox rebuilds it from the shipped base plus your overrides.- On every
qb update, the pristine base config is re-copied over/etc/lshell.conf. A hand-edit made directly to that file would be lost. - Because your dashboard edits live in the database, the update pipeline re-applies them automatically after re-copying the base, so an edited policy persists across updates.
You can hand-edit /etc/lshell.conf on the server, but those edits are overwritten on the next qb update unless they are captured as dashboard overrides. For any change you want to keep, use the Restricted Shell editor (or the API) so it is stored durably and re-applied on update.
When to use the editor
Symptoms
- A tool your users legitimately need (e.g. an added transfer or media utility) is being blocked in the limited shell
- You want to tighten the whitelist and remove a command limited users no longer need
- Fork bombs or runaway process counts are affecting a shared box and you want to lower the per-user process cap
- You want a custom welcome banner for your seedbox users
- You changed the policy directly on disk and it keeps reverting after an update
What to do
- Open Settings → Security → Restricted Shell
- Edit the Allowed, Forbidden, or hardening fields as needed
- Click Preview and confirm only the fields you intended changed
- Apply — the change is validated and swapped in atomically
- Move any on-disk hand-edits into the editor so they survive qb update
Best practices
Do
- Keep the Allowed whitelist as small as your users actually need — every command you add is granted to all limited-shell users.
- Use Preview before every Apply and confirm only the fields you meant to change are listed.
- Store policy changes through the editor (or the API) so they survive
qb update. - Leave Strict mode on so forbidden commands are logged in the shape the Fail2Ban shell jails recognize.
- Keep a sensible Max processes cap on shared boxes to contain fork bombs.
- Revert a single field to base with per-field revert instead of resetting the whole policy when you only need to undo one change.
Don't
- Don't add an interactive shell (
bash,sh,zsh) or a shell-escape editor (vi,vim) to Allowed — the editor rejects these because they break confinement. - Don't remove required tokens from the Forbidden list — chaining, piping, redirection, and
sudomust stay blocked. - Don't hand-edit
/etc/lshell.conffor changes you want to keep — they are overwritten on the next update. - Don't try to change the log paths or path confinement — they are locked to protect the sandbox and the Fail2Ban jails.
- Don't set Over-SSH commands that are not also in the Allowed list — the editor requires Over-SSH to be a subset.
FAQ
qb user shell -o sudo|full|limited./etc/lshell.conf is left untouched and the editor shows the validation errors. A broken config would lock out every limited-shell user, so nothing that fails validation is ever written.qb update, the pristine base config is re-copied and then your overrides are re-applied automatically, so an edited policy persists. A change made by hand-editing /etc/lshell.conf directly would be overwritten on the next update.qb user shell -o sudo|full|limited -u <username>, and you can hand-edit /etc/lshell.conf on the server — but hand-edits are overwritten on the next qb update unless they are captured as dashboard overrides. For durable policy changes, use the editor.Related pages
The parent page — username policies, IP bans, the firewall viewer, geo-lock, geo-block, and Fail2Ban
Shell levels (sudo / full / limited), how to assign them, and where the restricted shell logs
Assign a user's shell level and manage accounts from the dashboard
Brute-force protection, including the two shell-confinement jails that watch the restricted-shell logs
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.