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)**:
```bash
log_cmd "echo '$USERNAME:$PASSWORD' | chpasswd" "Setting user password"
```

**Fixed Code**:
```bash
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
```bash
id mightyuser1
getent passwd mightyuser1
```

### 2. Check User Groups
```bash
id -Gn mightyuser1
```
**Expected**: User should be in either `sftpusers` (SFTP-only) or `sshusers` (SSH+SFTP), and `litespeed` group.

### 3. Check User Home Directory
```bash
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
```bash
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
```bash
# 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
```bash
systemctl status sshd
systemctl is-active sshd
```

### 7. Check User Creation Logs
```bash
# 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
```bash
# 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
```bash
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
```bash
# 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
```bash
# 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
```bash
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
```bash
# 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)
```bash
# 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:

```bash
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.

---

## Quick Fix: Webroot Write Permissions

If users cannot create folders or files in the ROOT directory, run this standalone fix script:

```bash
# Download and run the fix script
wget https://deploy-proxy.mightybox.io/addons/add-sftp-user/raw/branch/main/fix-webroot-permissions.sh
chmod +x fix-webroot-permissions.sh
sudo ./fix-webroot-permissions.sh
```

Or manually fix:
```bash
# Ensure litespeed group exists
groupadd -f litespeed

# Set group ownership
chgrp -R litespeed /var/www/webroot/ROOT

# Add group write permissions
chmod -R g+w /var/www/webroot/ROOT

# Verify
ls -ld /var/www/webroot/ROOT
# Should show: drwxrwxr-x or drwxrwsr-x (group has write)
```

**Note**: The addon code (version 0.7+) automatically fixes this during installation or when creating new users. If you have an existing installation, either:
1. Update/reinstall the addon, OR
2. Run the fix script above

## 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.