Kasm Workspaces 1.17.0 Admin Password Reset Guide

Problem

Forgotten admin password for Kasm Workspaces 1.17.0 with console access available.

Initial Troubleshooting Attempts

Method 1: Database Password Reset (Official Method)

We started with the official Kasm Workspaces account recovery method:

sudo docker exec -it kasm_db psql -U kasmapp -d kasm

update users set
    pw_hash = 'fe519184b60a4ef9b93664a831502578499554338fd4500926996ca78fc7f522',
    salt = '83d0947a-bf55-4bec-893b-63aed487a05e',
    secret=NULL, set_two_factor=False, locked=False,
    disabled=False, failed_pw_attempts = 0 where username ='[email protected]';

DELETE FROM webauthn_credentials WHERE user_id IN ( 
    SELECT user_id FROM users WHERE username = '[email protected]' 
);

Method 2: Database Initialization with Seed File

Attempted to reinitialize the database using Kasm’s built-in utilities:

cd /opt/kasm/current/
sudo bin/utils/db_init --initialize --seed-file /opt/kasm/admin_reset.yaml --accept-warning

Root Cause Discovery

Issue 1: API Server Crashes

When checking the API logs, we discovered the server was crashing on startup:

sudo docker logs kasm_api --tail 20

AttributeError: 'NoneType' object has no attribute 'lower'

Issue 2: Missing Configuration File

Investigation revealed the API configuration file was missing:

ls -la /opt/kasm/current/conf/app/api.app.config.yaml
# Result: No such file or directory

Solution Steps

Step 1: Locate and Copy Missing Configuration

Found the configuration file in the installation directory:

sudo find /opt/kasm -name "*api*config*" -type f
# Found: /opt/kasm/1.17.0/conf/app/api/api.app.config.yaml

# Copy to correct location
sudo cp /opt/kasm/1.17.0/conf/app/api/api.app.config.yaml /opt/kasm/current/conf/app/

Step 2: Fix Incomplete Logging Configuration

Even with the config file in place, the API was still crashing. Investigation revealed incomplete logger configurations:

# Check the problematic section
sed -n '270,280p' /opt/kasm/current/conf/app/api.app.config.yaml

Fix: Add missing logging levels:

# Backup the config
sudo cp /opt/kasm/current/conf/app/api.app.config.yaml /opt/kasm/current/conf/app/api.app.config.yaml.backup

# Add missing level configurations
sudo sed -i '/client_api_server:/a\        level: DEBUG' /opt/kasm/current/conf/app/api.app.config.yaml
sudo sed -i '/admin_api_server:/a\        level: DEBUG' /opt/kasm/current/conf/app/api.app.config.yaml  
sudo sed -i '/subscription_api_server:/a\        level: DEBUG' /opt/kasm/current/conf/app/api.app.config.yaml

Step 3: Restart Services

sudo /opt/kasm/bin/stop
sudo /opt/kasm/bin/start

Step 4: Verify and Login

Check that the API starts without errors:

sudo docker logs kasm_api --tail 10

Key Lessons Learned

1. The official password reset method works – but only if the API server is functioning properly
2. Missing configuration files can prevent the entire system from starting
3. Incomplete YAML configurations can cause cryptic errors – always check for missing required fields
4. Symlink issues – configuration files may exist in the installation directory but not be properly linked to the current directory

Troubleshooting Commands Reference

Check Database User Status

sudo docker exec -it kasm_db psql -U kasmapp -d kasm -c "SELECT username, disabled, locked, failed_pw_attempts FROM users WHERE username = '[email protected]';"

Check API Server Logs

sudo docker logs kasm_api --tail 20

Check All Container Status

sudo docker ps --format "table {{.Names}}\t{{.Status}}"

Verify Configuration Files

find /opt/kasm -name "*config*" -type f | grep api

Prevention Tips

1. Regular backups of the /opt/kasm/current/conf/ directory
2. Document any configuration changes made to the system
3. Test admin access regularly to avoid lockout situations
4. Monitor container logs for early detection of configuration issues

Alternative Methods (if the above doesn’t work)

If the configuration file approach doesn’t resolve the issue, consider:

1. Complete reinstallation while preserving data volumes
2. Database seed file recreation with proper YAML format
3. Manual user creation directly in the database with proper encryption

This guide was tested on Kasm Workspaces 1.17.0 running on Ubuntu with Docker deployment.