From 28a3e394d80c6ecdd51d201ad9ad96f700e47720 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 23 Nov 2025 04:25:56 +0000
Subject: [PATCH] Fix talkkonnect permission issues and add setup documentation

The installation script had a critical bug where it created the config
directory in the script runner's home directory instead of the target
user's home directory. This caused "permission denied" errors when the
systemd service tried to run as the target user.

Changes:
- Fixed CONFIG_DIR to use $TARGET_HOME instead of $HOME
- Updated config path replacements to use $TARGET_HOME
- Added ownership change after config creation when running as different user
- Created fix_talkkonnect_permissions.sh script to repair existing installations
- Added comprehensive TALKKONNECT_SETUP.md with troubleshooting guide

This fixes the "open /home/user/.config/talkkonnect/talkkonnect.xml: permission denied" error.
---
 TALKKONNECT_SETUP.md            | 290 ++++++++++++++++++++++++++++++++
 fix_talkkonnect_permissions.sh  | 123 ++++++++++++++
 talkkonnect_complete_install.sh |  10 +-
 3 files changed, 421 insertions(+), 2 deletions(-)
 create mode 100644 TALKKONNECT_SETUP.md
 create mode 100755 fix_talkkonnect_permissions.sh

diff --git a/TALKKONNECT_SETUP.md b/TALKKONNECT_SETUP.md
new file mode 100644
index 0000000..dc0889f
--- /dev/null
+++ b/TALKKONNECT_SETUP.md
@@ -0,0 +1,290 @@
+# TalkKonnect Mumble Client Setup Guide
+
+This guide will help you set up TalkKonnect as a headless Mumble client on your kiosk.
+
+## The Permission Issue (FIXED)
+
+The original installation script had a bug where it created the configuration directory in the script runner's home directory instead of the target user's home directory. This caused a "permission denied" error when the service tried to run.
+
+**The fix has been applied to `talkkonnect_complete_install.sh`**
+
+## Quick Fix for Existing Installations
+
+If you already ran the installation and got the permission error, run this:
+
+```bash
+sudo ./fix_talkkonnect_permissions.sh
+```
+
+This will:
+- Move the config to the correct user's home directory
+- Fix all file permissions and ownership
+- Verify your systemd service configuration
+
+## Fresh Installation
+
+For a new installation, simply run:
+
+```bash
+./talkkonnect_complete_install.sh
+```
+
+When prompted, enter the username that should run talkkonnect (e.g., `user` or `kiosk`).
+
+The script will now:
+1. Install all dependencies
+2. Build talkkonnect with the correct Opus library fixes
+3. **Create the config in the TARGET user's home directory** (FIXED)
+4. **Set proper ownership and permissions** (FIXED)
+5. Set up the systemd service to run as the target user
+
+## Configuration
+
+After installation, edit the configuration file:
+
+```bash
+# If you're the target user:
+nano ~/.config/talkkonnect/talkkonnect.xml
+
+# If talkkonnect runs as a different user (e.g., 'user'):
+sudo nano /home/user/.config/talkkonnect/talkkonnect.xml
+```
+
+### Required Settings
+
+Update these fields in the XML:
+
+```xml
+<serverandport>your.mumble.server:64738</serverandport>
+<username>your_username</username>
+<password>your_password</password>
+<channel>Root</channel>
+```
+
+### Self-Signed Certificates
+
+If your Mumble server uses a self-signed certificate, set:
+
+```xml
+<insecure>true</insecure>
+```
+
+### Voice Activation vs PTT
+
+**Voice Activation (Default):**
+```xml
+<voiceactivity enabled="true">
+  <settings threshold="0.3" holdtimems="1000" holdtimeoutms="2000"/>
+</voiceactivity>
+<ptt enabled="false"/>
+```
+
+**Push-to-Talk with USB Keyboard:**
+```xml
+<voiceactivity enabled="false"/>
+<ptt enabled="true">
+  <usbkeyboard enabled="true" device="/dev/input/event0" keycode="KEY_F13"/>
+</ptt>
+```
+
+To find your USB keyboard device:
+```bash
+sudo evtest
+```
+
+## Testing
+
+### Manual Test
+
+Before enabling the service, test manually:
+
+```bash
+# If running as yourself:
+/usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml
+
+# If running as a different user (e.g., 'user'):
+sudo -u user /usr/local/bin/talkkonnect -config /home/user/.config/talkkonnect/talkkonnect.xml
+```
+
+You should see:
+- Connection to Mumble server
+- Join the specified channel
+- No permission errors
+
+### Common Errors
+
+**"permission denied" on config file:**
+- Run `./fix_talkkonnect_permissions.sh`
+- OR manually: `sudo chown -R user:user /home/user/.config/talkkonnect`
+
+**"unable to unmute" errors:**
+- This is usually non-fatal; audio may still work
+- Check: `amixer scontrols`
+
+**Connection refused:**
+- Check your `<serverandport>` setting
+- Verify firewall allows outbound connections on port 64738
+
+**Certificate errors:**
+- Set `<insecure>true</insecure>` for self-signed certs
+
+## Systemd Service (if available)
+
+If your system uses systemd:
+
+```bash
+# Enable and start
+sudo systemctl enable talkkonnect
+sudo systemctl start talkkonnect
+
+# Check status
+sudo systemctl status talkkonnect
+
+# View logs
+journalctl -u talkkonnect -f
+```
+
+## Docker/Non-Systemd Environments
+
+If you're running in Docker or without systemd, run talkkonnect directly:
+
+```bash
+# Create a simple start script
+cat > ~/start-talkkonnect.sh << 'EOF'
+#!/bin/bash
+/usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml
+EOF
+
+chmod +x ~/start-talkkonnect.sh
+
+# Run it
+./start-talkkonnect.sh
+```
+
+Or run in the background:
+
+```bash
+nohup /usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml > ~/talkkonnect.log 2>&1 &
+```
+
+## Audio Configuration
+
+### ALSA (Direct)
+Best for single-application use:
+```xml
+<input>
+  <settings enabled="true" device="hw:0,0" samplerate="48000" channels="1"/>
+</input>
+<output>
+  <settings enabled="true" device="hw:0,0" samplerate="48000" channels="1"/>
+</output>
+```
+
+### PulseAudio/PipeWire
+Best for multi-application use:
+```xml
+<input>
+  <settings enabled="true" device="default" samplerate="48000" channels="1"/>
+</input>
+<output>
+  <settings enabled="true" device="default" samplerate="48000" channels="1"/>
+</output>
+```
+
+List available devices:
+```bash
+aplay -L        # List output devices
+arecord -L      # List input devices
+```
+
+## Programmatic Channel Switching
+
+TalkKonnect can join a specific channel on connect by setting:
+
+```xml
+<channel>Your/Channel/Path</channel>
+```
+
+Use `/` to separate nested channels:
+- `Root` - joins root channel
+- `General` - joins General channel
+- `General/Support` - joins Support subchannel under General
+
+To switch channels at runtime, TalkKonnect has an API you can enable:
+
+```xml
+<api enabled="true">
+  <listenport>8011</listenport>
+</api>
+```
+
+Then use HTTP requests to control it:
+```bash
+# Switch channel
+curl http://localhost:8011/api/channel?channel=General/Support
+```
+
+## Troubleshooting
+
+### View Logs
+
+```bash
+# Config file log
+cat ~/.config/talkkonnect/talkkonnect.log
+
+# Systemd logs (if applicable)
+journalctl -u talkkonnect -f
+
+# Manual run (shows errors directly)
+/usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml
+```
+
+### Common Issues
+
+1. **No audio input/output:**
+   - Check `aplay -l` and `arecord -l`
+   - Verify user is in `audio` group: `groups`
+   - Test audio: `speaker-test` or `arecord -d 5 test.wav && aplay test.wav`
+
+2. **Can't access /dev/input devices (for PTT):**
+   - Verify user is in `input` group: `groups`
+   - May need to log out and back in after adding to group
+
+3. **Connection drops frequently:**
+   - Check network stability
+   - Increase keepalive timeouts in config
+   - Check server logs
+
+4. **Permissions errors:**
+   - Run `./fix_talkkonnect_permissions.sh`
+   - Verify config directory ownership: `ls -la ~/.config/talkkonnect`
+
+## Files and Locations
+
+- **Binary:** `/usr/local/bin/talkkonnect`
+- **Config:** `~/.config/talkkonnect/talkkonnect.xml`
+- **Logs:** `~/.config/talkkonnect/talkkonnect.log`
+- **Service:** `/etc/systemd/system/talkkonnect.service` (if using systemd)
+- **Source:** `~/talkkonnect`
+
+## Security Notes
+
+- Config file contains your Mumble password in plain text
+- Protect it: `chmod 600 ~/.config/talkkonnect/talkkonnect.xml`
+- Consider using certificate-based authentication instead of passwords
+- For production, use proper systemd hardening options
+
+## Next Steps
+
+1. ✅ Fix permissions (if needed): `./fix_talkkonnect_permissions.sh`
+2. ✅ Edit config: `nano ~/.config/talkkonnect/talkkonnect.xml`
+3. ✅ Test manually first
+4. ✅ Enable systemd service (if applicable)
+5. ✅ Configure audio ducking for multi-app environments (optional)
+6. ✅ Set up API for programmatic control (optional)
+
+## References
+
+- [TalkKonnect GitHub](https://github.com/talkkonnect/talkkonnect)
+- [Mumble Protocol](https://www.mumble.info/documentation/)
+- Config file path: `~/.config/talkkonnect/talkkonnect.xml`
diff --git a/fix_talkkonnect_permissions.sh b/fix_talkkonnect_permissions.sh
new file mode 100755
index 0000000..e8571db
--- /dev/null
+++ b/fix_talkkonnect_permissions.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# ======================================================================
+# File: fix_talkkonnect_permissions.sh
+# Purpose: Fix talkkonnect config permissions for the correct user
+# ======================================================================
+set -e
+
+echo "======================================================================="
+echo "TalkKonnect Permission Fix Script"
+echo "======================================================================="
+echo ""
+
+# Prompt for target user
+read -p "Which user should talkkonnect run as? [user]: " TARGET_USER
+TARGET_USER=${TARGET_USER:-user}
+
+# Verify the target user exists
+if ! id "$TARGET_USER" &>/dev/null; then
+    echo "[!] Error: User '$TARGET_USER' does not exist"
+    exit 1
+fi
+
+TARGET_HOME=$(eval echo ~"$TARGET_USER")
+CONFIG_DIR="$TARGET_HOME/.config/talkkonnect"
+
+echo "[+] Target user: $TARGET_USER"
+echo "[+] Home directory: $TARGET_HOME"
+echo "[+] Config directory: $CONFIG_DIR"
+echo ""
+
+# Check if config file exists in wrong location
+WRONG_LOCATIONS=(
+    "/root/.config/talkkonnect"
+    "$HOME/.config/talkkonnect"
+)
+
+FOUND_CONFIG=""
+for LOC in "${WRONG_LOCATIONS[@]}"; do
+    if [ -f "$LOC/talkkonnect.xml" ] && [ "$LOC" != "$CONFIG_DIR" ]; then
+        echo "[+] Found existing config at: $LOC"
+        FOUND_CONFIG="$LOC"
+        break
+    fi
+done
+
+if [ -n "$FOUND_CONFIG" ]; then
+    echo "[+] Moving config from $FOUND_CONFIG to $CONFIG_DIR"
+    mkdir -p "$CONFIG_DIR"
+    cp -r "$FOUND_CONFIG/"* "$CONFIG_DIR/"
+
+    # Update paths in the config file
+    sed -i "s|$FOUND_CONFIG|$CONFIG_DIR|g" "$CONFIG_DIR/talkkonnect.xml"
+    sed -i "s|/home/user/|$TARGET_HOME/|g" "$CONFIG_DIR/talkkonnect.xml"
+    sed -i "s|/root/|$TARGET_HOME/|g" "$CONFIG_DIR/talkkonnect.xml"
+
+    echo "[+] Config moved and paths updated"
+else
+    echo "[*] No existing config found in wrong locations"
+
+    if [ ! -f "$CONFIG_DIR/talkkonnect.xml" ]; then
+        echo "[!] Error: No config file found at $CONFIG_DIR/talkkonnect.xml"
+        echo "[!] Please run the installation script first"
+        exit 1
+    fi
+fi
+
+# Set proper ownership
+echo "[+] Setting ownership to $TARGET_USER..."
+chown -R "$TARGET_USER:$TARGET_USER" "$CONFIG_DIR"
+
+# Set proper permissions
+chmod 755 "$CONFIG_DIR"
+chmod 644 "$CONFIG_DIR/talkkonnect.xml"
+
+if [ -f "$CONFIG_DIR/enable-ducking.sh" ]; then
+    chmod 755 "$CONFIG_DIR/enable-ducking.sh"
+fi
+
+echo "[+] Permissions fixed!"
+echo ""
+
+# Show the result
+echo "Current permissions:"
+ls -la "$CONFIG_DIR"
+echo ""
+
+# Check systemd service if it exists
+if [ -f /etc/systemd/system/talkkonnect.service ]; then
+    echo "[+] Checking systemd service configuration..."
+    SERVICE_USER=$(grep "^User=" /etc/systemd/system/talkkonnect.service | cut -d= -f2)
+    SERVICE_CONFIG=$(grep "^ExecStart=" /etc/systemd/system/talkkonnect.service | grep -o '\-config [^ ]*' | cut -d' ' -f2)
+
+    echo "    Service runs as: $SERVICE_USER"
+    echo "    Config path: $SERVICE_CONFIG"
+
+    if [ "$SERVICE_USER" != "$TARGET_USER" ]; then
+        echo ""
+        echo "[!] WARNING: Service is configured to run as '$SERVICE_USER' but you selected '$TARGET_USER'"
+        echo "[!] Update /etc/systemd/system/talkkonnect.service to use the correct user"
+    fi
+
+    if [ "$SERVICE_CONFIG" != "$CONFIG_DIR/talkkonnect.xml" ]; then
+        echo ""
+        echo "[!] WARNING: Service config path doesn't match!"
+        echo "[!] Update /etc/systemd/system/talkkonnect.service to use: $CONFIG_DIR/talkkonnect.xml"
+    fi
+fi
+
+echo ""
+echo "======================================================================="
+echo "✓ Permission fix complete!"
+echo "======================================================================="
+echo ""
+echo "Next steps:"
+echo "  1. Edit your config file:"
+echo "     nano $CONFIG_DIR/talkkonnect.xml"
+echo ""
+echo "  2. Test manually as $TARGET_USER:"
+echo "     sudo -u $TARGET_USER /usr/local/bin/talkkonnect -config $CONFIG_DIR/talkkonnect.xml"
+echo ""
+echo "  3. If systemd is available, restart the service:"
+echo "     sudo systemctl restart talkkonnect"
+echo ""
diff --git a/talkkonnect_complete_install.sh b/talkkonnect_complete_install.sh
index 28b93dc..10c1cac 100644
--- a/talkkonnect_complete_install.sh
+++ b/talkkonnect_complete_install.sh
@@ -434,7 +434,7 @@ echo "======================================================================="
 echo "[+] CREATING CONFIGURATION"
 echo "======================================================================="
 
-CONFIG_DIR="$HOME/.config/talkkonnect"
+CONFIG_DIR="$TARGET_HOME/.config/talkkonnect"
 mkdir -p "$CONFIG_DIR"
 
 cat > "$CONFIG_DIR/talkkonnect.xml" << 'EOFXML'
@@ -523,7 +523,13 @@ cat > "$CONFIG_DIR/talkkonnect.xml" << 'EOFXML'
 EOFXML
 
 # Update the log path to use actual username
-sed -i "s|/home/user/|$HOME/|g" "$CONFIG_DIR/talkkonnect.xml"
+sed -i "s|/home/user/|$TARGET_HOME/|g" "$CONFIG_DIR/talkkonnect.xml"
+
+# Set proper ownership if running as a different user
+if [ "$TARGET_USER" != "$USER" ]; then
+    sudo chown -R "$TARGET_USER:$TARGET_USER" "$CONFIG_DIR"
+    echo "[+] Set ownership of config directory to $TARGET_USER"
+fi
 
 echo "[+] Created configuration file: $CONFIG_DIR/talkkonnect.xml"