qb user - User Management

The qb user management functions offer a versatile and powerful set of tools to efficiently manage users on your server. With a focus on ease of use and robust functionality, these functions enable you to streamline user management, enhance security, and ensure smooth server operation.

Quick Reference

Available Commands

Create User

Create a new QuickBox user account with email verification:

qb user create -u username -p 'password' -e user@example.com

Required parameters:

To keep the password off the command line, pass it on standard input:

# Type it when it waits (hidden)
qb user create -u username --password-stdin -e user@example.com
 
# Or pipe it in from a variable
printf '%s\n' "$PASSWORD" | qb user create -u username --password-stdin -e user@example.com

What happens during user creation:

1. Username validation (no special chars, no numbers at start/end)
2. System user account is created
3. Password is encrypted using bcrypt
4. Home directory is set up (/home/username)
5. QuickBox dashboard access is configured
6. User record is added to database (level 4 - standard user)
7. Default permissions are applied
8. User can immediately log in and install applications

Delete User

Permanently delete a QuickBox user account:

qb user delete -u username

What gets removed:

• User account and home directory (/home/username)
• All installed applications for that user
• User’s dashboard access and credentials
• User’s data and configurations
• Database records for the user
• The user’s OpenVPN certificate is revoked and their client profile (.ovpn, download route) is purged, so any copy they kept stops connecting

Protection:

• Cannot delete a super admin account (level 10)
• Confirmation prompt before deletion

Show User Information

Display detailed information about a specific user:

qb user show -u username

Output includes:

• Username and user ID
• Home directory location
• Shell environment type
• Admin level (4=user, 9=admin, 10=super-admin)
• Installed applications
• Disk usage and quota
• Account status (active/banned)

Change Password

Change the password for an existing user:

qb user password -u username -p newpassword

To keep the new password off the command line, read it from standard input instead of using -p:

# Type it when it waits (hidden)
qb user password -u username --password-stdin
 
# Or pipe it in from a variable
printf '%s\n' "$NEWPASSWORD" | qb user password -u username --password-stdin

--password-stdin waits for one line that you type (it is not shown) or pipe in, and cannot be combined with -p. Passwords with a line break are rejected, with either option.

Use cases:

• User forgot their password
• Regular password rotation for security
• Compromised credentials
• Admin password resets

pyLoad Password

Set or reveal the password for a user’s pyLoad login. The password starts as the account password and can be changed here without changing the account password:

# Set it: asks twice, input hidden
qb user pyloadpasswd -u username
 
# Show it (account owner only)
qb user pyloadpasswd -u username -o reveal

Who can do what:

• Set: the account owner, any admin, and root.
• Reveal: only the account owner. An admin or root cannot reveal another user’s password.

What happens when you set it:

1. The password is checked: it cannot be empty and cannot contain a line break.
2. If pyLoad is installed, the new password is applied to pyLoad’s login first. If that fails, nothing is saved.
3. The password is saved so that Reveal and the dashboard can show it.
4. If pyLoad is running, it is restarted.

If pyLoad is not installed yet, the password is saved and pyLoad uses it when you install it. An interactive set needs a terminal. Without one, the command stops and asks you to use -o web --path.

You can also do this from the App Dashboard. Open your pyLoad row and use the API & Secrets panel.

noVNC Password

Set or reveal the dedicated password for a user’s noVNC desktop. It is separate from the account password and survives a reinstall:

# Set it: asks twice, input hidden
qb user vncpasswd -u username
 
# Show it (account owner only)
qb user vncpasswd -u username -o reveal

The options, the rules for who can set or reveal, and the -o web --path file form for scripts are the same as for qb user pyloadpasswd. The password cannot be empty or contain a line break. A password set before noVNC is installed is saved and applied at install. If the noVNC service exists, it is restarted so the new password takes effect, which ends any open desktop session.

See noVNC for the dashboard steps and the 8-character limit.

Ban User

Ban a user account, preventing login and stopping all installed services:

qb user ban -u username

What happens when a user is banned:

• Dashboard login is blocked
• All running services for the user are stopped
• SSH access is disabled
• User cannot install new applications
• If the user has an OpenVPN profile, their certificate is revoked — their existing .ovpn stops connecting immediately (enforced by the server’s certificate revocation list)

Important notes:

• This does NOT delete user data
• User’s files and configurations remain intact
• Services can be restarted by unbanning the user
• The user’s VPN membership is preserved (the certificate is revoked, not the account) so unban can reissue a fresh profile

Unban User

Restore access for a previously banned user:

qb user unban -u username

What happens when a user is unbanned:

• Dashboard login is re-enabled
• Services are started again
• SSH access is restored
• User can manage applications normally
• For OpenVPN users, a fresh client profile is issued — the certificate revoked at ban time stays permanently dead, so the user must re-download their new .ovpn bundle before reconnecting

Promote User

Promote a standard user to admin level:

qb user promote -u username

Admin privileges include:

• Access to admin dashboard
• Ability to manage all users
• System-level configuration
• View server statistics
• Install system-wide applications

Demote User

Demote an admin user back to standard user level:

qb user demote -u username

What changes:

• Admin dashboard access is removed
• Cannot manage other users
• Can only manage their own applications
• System configuration access is revoked

User Quota

Set disk quota limits for a user:

# Set quota with size (TB, GB, or MB)
qb user quota -u username -o 2TB
qb user quota -u username -o 500GB
qb user quota -u username -o 10240MB
 
# View user's disk usage
qb user show -u username

Supported units:

• TB - Terabytes (e.g., 2TB, 5TB)
• GB - Gigabytes (e.g., 500GB, 1000GB)
• MB - Megabytes (e.g., 10240MB, 5000MB)

Important notes:

• Do NOT use decimals in disk space values (e.g., use 500GB not 0.5TB)
• The quota system must be installed first: qb install quota
• Filesystem must support quotas (enabled on mount point)
• Quotas are enforced by the quota package

How it works:

1. Quota size is stored in the database for the user
2. The setquota command applies the limit to the filesystem
3. Cron job periodically enforces quotas: qb user quota -o cron
4. Use qb user show -u username to view current disk usage

Shell Environment

Set the shell environment and access level for a user:

qb user shell -u username -o [sudo|full|limited]

Shell Environment Options

Shell levels

Each option maps to a shell level stored on the user account. The level controls both the login shell and whether the user is in the sudo group:

New users created with qb user create always start at level 3 (limited). Promotion and demotion move the level as a side effect:

• qb user promote -u <username> — sets the user to admin (level 9) and shell level 2 (full bash, no sudo).
• qb user demote -u <username> — returns the user to standard (level 4) and shell level 3 (limited, back into lshell).

The limited (lshell) shell

Level 3 users run inside lshell , a restricted shell that intercepts every command and checks it against a whitelist before running it. A limited user is confined to their own home directory, cannot chain or pipe commands, cannot use sudo, and cannot escape to an interactive shell. This is what lets you hand a standard seedbox user shell access safely.

The command whitelist and hardening (allowed commands, forbidden patterns, over-SSH access, warnings, process cap, banner) are a single shared policy. Edit it from the dashboard at Settings → Security → Restricted Shell — those edits are stored durably and survive qb update. See that page for the full field reference and guard rails.

Common Workflows

Creating a New User

Standard user creation workflow:

# 1. Create the user
qb user create -u john -p 'SecurePass123!' -e john@example.com
 
# 2. Set shell environment (optional, defaults to limited shell)
qb user shell -u john -o limited
 
# 3. Set disk quota (optional, requires quota to be installed)
qb user quota -u john -o 2TB
 
# 4. User can now log in and install applications

Dealing with Problem Users

Temporary suspension:

# Ban user (keeps data, stops services)
qb user ban -u problemuser
 
# After issue is resolved, unban
qb user unban -u problemuser

Permanent removal:**

# Backup user data first (if needed)
tar -czf /root/backups/problemuser-$(date +%Y%m%d).tar.gz /home/problemuser
 
# Delete user and all data
qb user delete -u problemuser

Password Reset

Resetting a forgotten password:

# As admin, reset the user's password
qb user password -u username -p 'NewTemporaryPass123'
 
# Instruct user to change password after first login

Additional Features

Rclone Management

Manage rclone configuration and operations for a specific user:

# Remove rclone lock file (if stuck)
qb user rclone -u username -o remove_lock
 
# Trigger rclone upload manually
qb user rclone -u username -o upload
 
# View rclone upload logs
qb user rclone -u username -o logs

Available options:

• remove_lock - Remove stale lock file if rclone upload is stuck
• upload - Manually trigger rclone upload process
• logs - Display rclone upload logs for troubleshooting

Use cases:

• Rclone upload process is stuck or frozen
• Force an immediate upload to cloud storage
• Debug cloud storage sync issues
• Monitor upload progress and errors

Troubleshooting

User Cannot Log In

# Check user information
qb user show -u username
 
# If banned, unban them
qb user unban -u username
 
# Reset password
qb user password -u username -p 'NewPassword123'
 
# Fix user home directory permissions
qb fix home -u username

User’s Applications Not Starting

# Check user's services
systemctl --user -M username@ status
 
# Fix user home permissions
qb fix home -u username
 
# Check if user has any installed software
qb user show -u username

Quota Not Working

# Install quota system (must be done first)
qb install quota
 
# Set user quota (size in TB/GB/MB, no decimals)
qb user quota -u username -o 2TB
 
# View user's disk usage
qb user show -u username
 
# Force quota enforcement for all users (cron mode)
qb user quota -o cron

Security Best Practices

Related Commands

Need Help?