Merge pull request #42 from outis1one/claude/mumble-kiosk-setup-01RUgNotdEkjq4KfNRBeqDyK

Fix talkkonnect permission issues and add setup documentation
2025-11-22 23:27:55 -05:00
parent cd5a52de63 28a3e394d8
commit bce7c540e5
3 changed files with 421 additions and 2 deletions
@@ -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`
@@ -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 ""
@@ -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"