add-sftp-user/TROUBLESHOOTING.md

SFTP/SSH Account Troubleshooting Guide

Critical Bug Fixed

Password Setting Bug (CRITICAL)

Location: add-sftp.sh line 150
Issue: The password was being set using single quotes which prevented variable expansion when passed through log_cmd function (which uses eval).

Original Code (BROKEN):

log_cmd "echo '$USERNAME:$PASSWORD' | chpasswd" "Setting user password"

Fixed Code:

CHPASSWD_OUTPUT=$(printf '%s:%s\n' "$USERNAME" "$PASSWORD" | chpasswd 2>&1)
CHPASSWD_STATUS=$?
if [ $CHPASSWD_STATUS -eq 0 ]; then
    log_success "Password set for user $USERNAME"
else
    log_error "Failed to set password for user $USERNAME"
    exit 1
fi

Impact: This bug would cause passwords to NOT be set properly, resulting in login failures even if the account was created successfully.

---

Server Diagnostic Commands

Run these commands on your server as root to diagnose the issue with user mightyuser1:

1. Check if User Exists

id mightyuser1
getent passwd mightyuser1

2. Check User Groups

id -Gn mightyuser1

Expected: User should be in either sftpusers (SFTP-only) or sshusers (SSH+SFTP), and litespeed group.

3. Check User Home Directory

getent passwd mightyuser1 | cut -d: -f6
ls -ld /home/sftpusers/mightyuser1
stat /home/sftpusers/mightyuser1

Expected:

• Home directory should exist at /home/sftpusers/mightyuser1
• Ownership should be root:root
• Permissions should be 755 or 751

4. Check Password Status

grep "^mightyuser1:" /etc/shadow | cut -d: -f2

Expected: Should show a hashed password (long string starting with $). If it shows *, !, or is empty, the password is NOT set.

5. Check SSH Configuration

# Check if password authentication is enabled
grep -E "^PasswordAuthentication" /etc/ssh/sshd_config

# Check Match Group configuration
grep -A 5 "Match Group sftpusers" /etc/ssh/sshd_config
grep -A 5 "Match Group sshusers" /etc/ssh/sshd_config

# Check addon config file
cat /etc/ssh/sshd_config.d/99-sftp-addon.conf 2>/dev/null

# Test SSH config syntax
sshd -t

6. Check SSH Service Status

systemctl status sshd
systemctl is-active sshd

7. Check User Creation Logs

# Find the most recent user creation log
ls -t /opt/add-sftp-user-addon/logs/user_creation-*.log | head -1 | xargs cat

# Check error logs
tail -20 /opt/add-sftp-user-addon/logs/errors.log

# Check main log
tail -50 /opt/add-sftp-user-addon/logs/script_output.log

8. Check Directory Structure

# Check if data directory exists and has correct permissions
ls -ld /home/sftpusers/mightyuser1/data
ls -ld /home/sftpusers/mightyuser1/data/ROOT

# Check if ROOT is mounted
mountpoint /home/sftpusers/mightyuser1/data/ROOT
mount | grep "mightyuser1"

9. Check User Shell

getent passwd mightyuser1 | cut -d: -f7

Expected:

• /sbin/nologin for SFTP-only users (should be in sftpusers group)
• /bin/bash for SSH+SFTP users (should be in sshusers group)

---

Quick Fixes (Run as Root)

Fix 1: Reset Password

# Replace NEW_PASSWORD with the actual password
echo "mightyuser1:NEW_PASSWORD" | chpasswd

# Verify password was set
grep "^mightyuser1:" /etc/shadow | cut -d: -f2

Fix 2: Fix Group Membership

# For SFTP-only access:
usermod -aG sftpusers,litespeed mightyuser1
usermod -s /sbin/nologin mightyuser1

# For SSH+SFTP access:
usermod -aG sshusers,litespeed mightyuser1
usermod -s /bin/bash mightyuser1

# Verify
id -Gn mightyuser1

Fix 3: Fix Home Directory Permissions

chown root:root /home/sftpusers/mightyuser1
chmod 755 /home/sftpusers/mightyuser1
chown mightyuser1:mightyuser1 /home/sftpusers/mightyuser1/data
chmod 775 /home/sftpusers/mightyuser1/data

Fix 4: Remount ROOT Directory

# Unmount if already mounted
umount /home/sftpusers/mightyuser1/data/ROOT 2>/dev/null

# Remount
mount --bind /var/www/webroot/ROOT /home/sftpusers/mightyuser1/data/ROOT

# Verify
mountpoint /home/sftpusers/mightyuser1/data/ROOT

Fix 5: Enable Password Authentication (if disabled)

# Check current setting
grep "^PasswordAuthentication" /etc/ssh/sshd_config

# Enable if disabled
sed -i 's/^PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config

# Restart SSH service
systemctl restart sshd

---

Code Analysis

Algorithm Review

The account creation process follows these phases:

1. Pre-flight Checks: Validates environment and required directories exist
2. System Preparation: Configures SSH/SFTP service and ensures password auth is enabled
3. Username Validation: Validates username format (3-32 chars, alphanumeric + underscore)
4. User Existence Check: Prevents duplicate users
5. Group Setup: Creates sftpusers and sshusers groups if needed
6. Directory Setup: Creates /home/sftpusers with proper permissions
7. User Creation: Creates user with appropriate shell (/bin/bash for SSH, /sbin/nologin for SFTP-only)
8. Password Setting: FIXED - Now uses printf to properly set password
9. Chroot Setup: Sets up chroot jail structure with proper ownership
10. Bind Mount: Creates bind mount for webroot access
11. Group Assignment: Adds user to appropriate groups (sftpusers or sshusers + litespeed)

Potential Issues Identified

1. FIXED: Password setting bug (single quotes preventing variable expansion)
2. Configuration Duplication: Both manifest.jps and system_prep.sh configure SSH, which could cause conflicts
3. Password Special Characters: The fix uses printf which handles special characters better than echo
4. SSH Config File Location: The code creates config in /etc/ssh/sshd_config.d/99-sftp-addon.conf but also modifies main /etc/ssh/sshd_config - ensure Include directive exists

Recommendations

1. Deploy the fix - The password setting bug is critical and must be fixed
2. Test password reset - For existing users created with the bug, reset their passwords
3. Verify SSH config - Ensure /etc/ssh/sshd_config includes Include /etc/ssh/sshd_config.d/*.conf
4. Check logs - Review user creation logs to see if password setting failed silently

---

Using the Diagnostic Script

A comprehensive diagnostic script check-sftp-user.sh has been created. Upload it to your server and run:

chmod +x check-sftp-user.sh
./check-sftp-user.sh mightyuser1

This script will check all aspects of the user account and provide detailed diagnostics.

---

Common Issues and Solutions

Issue: "Permission denied" when logging in

Causes:

1. Password not set (most likely due to the bug)
2. User in wrong group
3. Password authentication disabled in SSH config
4. Home directory permissions incorrect

Solution: Run diagnostic commands above, then apply appropriate fixes.

Issue: User can connect but cannot access files

Causes:

1. User not in litespeed group
2. ROOT directory not mounted
3. Data directory permissions incorrect

Solution: Check group membership and mount status, fix as needed.

Issue: SSH works but SFTP doesn't (or vice versa)

Causes:

1. User in wrong group (sftpusers vs sshusers)
2. Shell mismatch (/sbin/nologin vs /bin/bash)
3. SSH config Match Group rules incorrect

Solution: Verify group membership and shell match the desired access type.