qb user - User Management

User Management System

Create, manage, and control user accounts on your QuickBox server

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

Command	Description
`qb user create -u username -p password -e email`	Create a new user account
`qb user delete -u username`	Delete a user account
`qb user password -u username -p newpass`	Change user password
`qb user ban -u username`	Ban a user (disable services, block login)
`qb user unban -u username`	Unban a user (re-enable services)
`qb user promote -u username`	Promote user to admin level (level 9)
`qb user demote -u username`	Demote user to standard level (level 4)
`qb user quota -u username -o [SIZE]`	Set user disk quota (e.g., 2TB, 500GB)
`qb user shell -u username -o [sudo\|full\|limited]`	Set shell environment
`qb user show -u username`	Display detailed user information
`qb user rclone -u username -o [option]`	Manage user’s rclone configuration

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:

-u, --username - Username (no special characters, cannot start/end with numbers)
-p, --password - User password (will be encrypted)
-e, --email - Email address for notifications

What happens during user creation:

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

Username Requirements

Usernames must be alphanumeric only. They cannot contain special characters (!@#$%^&*()_+) and cannot start or end with numbers. Valid examples: john, alice, bob123, user001

Password Security

Use strong passwords with a mix of uppercase, lowercase, numbers, and special characters. Consider using a password manager to generate and store secure credentials. Passwords are encrypted using industry-standard bcrypt hashing.

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

Protection:

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

Permanent Deletion

This action permanently deletes the user’s home directory and all associated data. There is no undo. Make sure to backup any important data before deleting a user.

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

Use cases:

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

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

Important notes:

This does NOT delete user data
User’s files and configurations remain intact
Services can be restarted by unbanning the user

When to Ban vs Remove

Use ban for temporary restrictions (e.g., policy violations, unpaid subscription). Use remove for permanent account deletion.

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

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

Security Consideration

Admin users have full access to your server. Only promote trusted users. Admins can view/modify other users’ data and system configurations.

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:

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

Viewing Disk Usage

The qb user show command displays the user’s current disk usage (excludes rclone mounts). This helps you monitor quota compliance without checking the quota system directly.

Shell Environment

Set the shell environment and access level for a user:


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

Shell Environment Options

🔓 sudo

Complete admin privileges

• Full sudo access
• Can modify system files
• Install system packages
• Manage services

🔒 full

Full access, no sudo

• Access entire filesystem
• Cannot use sudo
• Cannot access root directories
• Good for power users

🔐 limited

Jailed environment

• Restricted to home directory
• Cannot access other users
• Very limited shell commands
• Most secure option

Critical Warning: Bash Requirement

Changing the shell environment to anything other than /bin/bash may lead to unintended behavior when using qb (QuickBox). The QuickBox CLI has been specifically designed and optimized for the Bash shell environment.

Recommendation: Stick with the /bin/bash environment when using QuickBox. If you must use a different shell, consult that shell’s documentation for compatibility adjustments.

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

Rclone Configuration

Users must have rclone installed and configured before using these commands. See the rclone documentation for setup instructions.

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

Do

Use strong, unique passwords for each user
Regularly audit user accounts (qb user list)
Remove unused accounts promptly
Use limited shell for untrusted users
Document admin user promotions
Set disk quotas to prevent abuse

Don't

Share user credentials between people
Give sudo access to untrusted users
Use weak/default passwords
Leave banned users indefinitely
Promote users without consideration
Remove users without backing up data

Fix Command

Fix user permission issues and home directories

Manage Command

Advanced system management (API keys, database, etc.)

Clean Command

Clean user logs and temporary files

Generate Logs

Generate system logs for troubleshooting

Need Help?

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support

Feature Previews

Community Configs

Active Discussions

Join Discord Server

Additional Resources

Getting Started

Complete installation guide

CLI Reference

All available commands

Troubleshooting

Common issues and solutions

qb user - User Management

Quick Reference

Available Commands

Create User

Delete User

Show User Information

Change Password

Ban User

Unban User

Promote User

Demote User

User Quota

Shell Environment

Shell Environment Options

🔓 sudo

🔒 full

🔐 limited

Common Workflows

Creating a New User

Dealing with Problem Users

Permanent removal:**

Password Reset

Additional Features

Rclone Management

Troubleshooting

User Cannot Log In

User’s Applications Not Starting

Quota Not Working

Security Best Practices

Do

Don't

Related Commands

Need Help?

Join the Community

Additional Resources