From 6edc235129945fd729571dde10f73bf42f15d6b9 Mon Sep 17 00:00:00 2001 From: Arpad Krejczinger Date: Wed, 6 Aug 2025 17:24:49 +0200 Subject: [PATCH] Remove old documentation files after reorganization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean up root directory by removing documentation files that were moved to docs/ folder in previous commit. πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- network-security.md | 488 -------------------------------------------- services.md | 223 -------------------- system-setup.md | 158 -------------- troubleshooting.md | 312 ---------------------------- 4 files changed, 1181 deletions(-) delete mode 100644 network-security.md delete mode 100644 services.md delete mode 100644 system-setup.md delete mode 100644 troubleshooting.md diff --git a/network-security.md b/network-security.md deleted file mode 100644 index 958952d..0000000 --- a/network-security.md +++ /dev/null @@ -1,488 +0,0 @@ -# Network & Security Configuration - -Complete guide for securing and networking your homelab. - -## SSH Security Setup - -### Initial Configuration -```bash -# Generate SSH key pair -ssh-keygen -t ed25519 -C "homelab-key" -f ~/.ssh/homelab_ed25519 - -# Copy public key to target -ssh-copy-id -i ~/.ssh/homelab_ed25519.pub user@target -``` - -### SSH Hardening - -**Status:** βœ… **Complete** - Port changed to 2222 - -Edit `/etc/ssh/sshd_config`: -``` -# Disable root login -PermitRootLogin no - -# Use key-based authentication only -PasswordAuthentication no -PubkeyAuthentication yes - -# Change default port (CRITICAL - currently still on 22) -Port 2222 - -# Restrict users -AllowUsers hoborg - -# Security settings -Protocol 2 -X11Forwarding no -AllowTcpForwarding no -ClientAliveInterval 300 -ClientAliveCountMax 2 -MaxAuthTries 3 -MaxStartups 2 -``` - -**Completed:** -1. βœ… Changed SSH port from 22 to 2222 -2. βœ… Updated router port forwarding rules -3. βœ… External access via ak-homelab.duckdns.org:2222 working - -Restart SSH: `sudo systemctl restart sshd` - -### Mosh Alternative (Investigation Needed) - -**Issue:** SSH can be unreliable on WiFi connections with packet loss. - -**Mosh Benefits:** -- Maintains connection during network switches (ethernet ↔ WiFi) -- Handles poor WiFi connections better -- Local echo for responsive typing -- Roaming support (IP changes don't break connection) - -**Installation:** -```bash -# Server side -sudo pacman -S mosh - -# Client side -mosh user@server -``` - -**Requirements:** -- UDP ports 60000-61000 open on router -- SSH still needed for initial authentication - -**Status:** βœ… **Local use working** ❌ **External blocked by ISP** - -**Key Findings:** -- **Local mosh**: Works perfectly (`mosh localhost`, `mosh 192.168.0.100`) -- **External mosh**: Blocked by ISP UDP port filtering on ports 60000-61000 -- **SSH still needed**: Mosh uses SSH for initial authentication, then switches to UDP - -**ISP UDP Blocking Issue:** -- Most ISPs block UDP ports 60000-61000 for "security" -- SSH works fine (TCP port 2222) but mosh fails (UDP 60000-61000) -- Router port forwarding is correct, but ISP drops UDP packets - -**Current Recommendation:** -- Use mosh for local/internal network connections -- Stick with SSH for external connections until VPN is set up -- VPN tunnel can bypass ISP UDP blocking - -### SSH Client Configuration -Create `~/.ssh/config`: -``` -Host homelab - HostName ak-homelab.duckdns.org - User hoborg - Port 2222 - IdentityFile ~/.ssh/homelab_ed25519 - ServerAliveInterval 60 -``` - -**Usage:** -```bash -# Connect via SSH -ssh homelab - -# Connect via Mosh (uses SSH config automatically) -mosh homelab -``` - -## Dynamic DNS with DuckDNS - -### Account Setup -1. Create account at duckdns.org -2. Create subdomain: `ak-homelab.duckdns.org` -3. Get token from dashboard - -### Automatic IP Updates -Update script at `~/.local/scripts/duckdns.py` (Python implementation) - -Cron job for automatic updates: -```bash -# Update every 5 minutes -*/5 * * * * /home/hoborg/.local/scripts/duckdns.py >/dev/null 2>&1 -``` - -### Current Setup (Router-based) - -**Status:** βœ… **Migrated from script to router DynDNS** - -**Changes made:** -- βœ… Disabled cron job script (`*/5 * * * *` entry removed) -- βœ… Enabled router Dynamic DNS for ak-homelab.duckdns.org -- ⏳ **Testing pending** - Cannot force public IP change to verify - -**Router DynDNS Benefits:** -- Immediate updates on IP change (vs 5-minute delay) -- Works when server is down -- Lower resource usage - -**Limitations:** -- Likely IPv4-only (Sagemcom router limitation) -- Less control over update process - -### Testing -```bash -# Check current IP -curl -s https://ipinfo.io/ip - -# Verify DNS resolution -nslookup ak-homelab.duckdns.org - -# Check IPv6 (likely not updated by router) -nslookup -type=AAAA ak-homelab.duckdns.org -``` - -**Testing will occur naturally when ISP changes public IP address.** - -## VPN Setup with WireGuard - -### What is WireGuard? -WireGuard is a modern, lightweight VPN protocol that creates secure tunnels between devices. It encrypts all network traffic and routes it through a VPN server, making your internet connection private and secure. - -**Key benefits:** -- **Privacy**: Hides your IP address and encrypts traffic -- **Security**: Protects against man-in-the-middle attacks on public WiFi -- **Access**: Bypass geo-restrictions and enables remote homelab access -- **Performance**: Much faster than OpenVPN with lower battery drain -- **Simplicity**: Easy to configure compared to other VPN protocols - -**When you need VPN:** -- Accessing homelab remotely over internet -- Working from public WiFi frequently -- Need to bypass ISP restrictions -- Running public-facing services - -**Costs:** WireGuard itself is free. Self-hosted VPN costs $5-20/month for VPS hosting. - -**Use cases:** -- Access homelab services remotely (SSH, web interfaces, file shares) -- Secure connection on public WiFi -- Bypass ISP restrictions or geo-blocks - -**Performance:** Much faster and lighter than OpenVPN, better battery life on mobile devices. - -### Server Configuration -Install WireGuard: `pacman -S wireguard-tools` - -Generate keys: -```bash -wg genkey | tee server_private.key | wg pubkey > server_public.key -``` - -Server config `/etc/wireguard/wg0.conf`: -```ini -[Interface] -PrivateKey = -Address = 10.0.0.1/24 -ListenPort = 51820 -PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE -PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE - -[Peer] -PublicKey = -AllowedIPs = 10.0.0.2/32 -``` - -### Client Configuration -Generate client keys: -```bash -wg genkey | tee client_private.key | wg pubkey > client_public.key -``` - -Client config: -```ini -[Interface] -PrivateKey = -Address = 10.0.0.2/24 -DNS = 1.1.1.1 - -[Peer] -PublicKey = -Endpoint = ak-homelab.duckdns.org:51820 -AllowedIPs = 0.0.0.0/0 -PersistentKeepalive = 25 -``` - -### Enable VPN -```bash -sudo systemctl enable wg-quick@wg0 -sudo systemctl start wg-quick@wg0 -``` - -## Firewall Configuration - -### UFW (Uncomplicated Firewall) - -**What it does:** Controls what network traffic is allowed in/out of your server. - -**Key functions:** -- **Default deny**: Blocks all incoming connections by default -- **Port control**: Open only specific ports you need (SSH, HTTP, etc.) -- **Rate limiting**: Prevent brute force attacks -- **Application profiles**: Pre-configured rules for common services - -**Why needed:** Without firewall, all services are exposed to network attacks. - -### UFW Setup -```bash -# Install and enable UFW -pacman -S ufw -sudo ufw enable - -# Default policies -sudo ufw default deny incoming -sudo ufw default allow outgoing - -# SSH access -sudo ufw allow 2222/tcp - -# WireGuard -sudo ufw allow 51820/udp - -# HTTP/HTTPS for services -sudo ufw allow 80/tcp -sudo ufw allow 443/tcp -``` - -### Advanced Rules -```bash -# Rate limiting for SSH -sudo ufw limit 2222/tcp - -# Allow from specific networks -sudo ufw allow from 192.168.1.0/24 to any port 22 - -# Log denied connections -sudo ufw logging on -``` - -## Network Security Best Practices - -### Port Management -- **Change default ports**: SSH (2222), WireGuard (51820) -- **Close unused ports**: Regular port scans with nmap -- **Port forwarding**: Only forward necessary ports - -### Access Control -- **VPN-first approach**: Access services through VPN tunnel -- **IP whitelisting**: Restrict access to known IPs when possible -- **Rate limiting**: Prevent brute force attacks - -### Monitoring -- **Log analysis**: Monitor `/var/log/auth.log` for SSH attempts -- **Network monitoring**: Use netstat/ss to check listening ports -- **Intrusion detection**: Use fail2ban for automated blocking - -## fail2ban - Intrusion Prevention - -### What is fail2ban? - -**What it does:** Automatically blocks IP addresses that show malicious behavior. - -**Key functions:** -- **Log monitoring**: Watches system logs for suspicious activity -- **Pattern detection**: Identifies failed login attempts, scanning, etc. -- **Automatic blocking**: Temporarily bans offending IP addresses -- **Customizable rules**: Configure what triggers a ban and for how long - -**Common protections:** -- SSH brute force attempts -- Web server attacks (404 scanning, etc.) -- Email server abuse -- Custom application attacks - -**Example:** After 5 failed SSH login attempts in 10 minutes, ban IP for 1 hour. - -**Why important:** Reduces server load and prevents automated attacks from succeeding through persistence. - -### fail2ban Installation & Setup - -```bash -# Install fail2ban -sudo pacman -S fail2ban - -# Enable and start service -sudo systemctl enable fail2ban -sudo systemctl start fail2ban - -# Create local configuration -sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local -``` - -### Basic SSH Protection Configuration - -Edit `/etc/fail2ban/jail.local`: -```ini -[sshd] -enabled = true -port = 2222 -filter = sshd -logpath = /var/log/auth.log -maxretry = 5 -bantime = 3600 -findtime = 600 -``` - -**Configuration explained:** -- `maxretry = 5`: Ban after 5 failed attempts -- `bantime = 3600`: Ban for 1 hour (3600 seconds) -- `findtime = 600`: 5 attempts within 10 minutes triggers ban -- `port = 2222`: Monitor custom SSH port - -### Restart and Monitor - -```bash -# Restart fail2ban to apply changes -sudo systemctl restart fail2ban - -# Check status -sudo fail2ban-client status -sudo fail2ban-client status sshd - -# View banned IPs -sudo fail2ban-client get sshd banned -``` - -## Router Configuration - -### Port Forwarding -Forward these ports to your homelab server: -- SSH: External port β†’ Internal 2222 -- WireGuard: 51820 β†’ 51820 -- Web services: 80/443 β†’ 80/443 (if needed) - -### Security Settings -- **Disable WPS**: Turn off WiFi Protected Setup -- **Strong WiFi password**: WPA3 with complex passphrase -- **Guest network**: Separate network for guests -- **Firmware updates**: Keep router firmware current - -## Network Planning - -### Dual Network Interface Issue (Critical) - -**Problem:** Server has both ethernet and WiFi interfaces. When switching between connections, IP address changes from ethernet (192.168.0.22) to different WiFi IP, breaking SSH connections and port forwards. - -**Limitation:** Most routers don't allow DHCP reservation of same IP for multiple MAC addresses. - -**Solutions:** - -**Option 1: Static IP Configuration (Recommended)** -Configure both interfaces with same static IP: -```bash -# Check interface names -ip link show - -# Configure ethernet interface -sudo systemctl edit --full systemd-networkd -# Create /etc/systemd/network/20-ethernet.network -[Match] -Name=enp* - -[Network] -DHCP=no -Address=192.168.0.100/24 -Gateway=192.168.0.1 -DNS=192.168.0.1 - -# Create /etc/systemd/network/25-wifi.network -[Match] -Name=wlp* - -[Network] -DHCP=no -Address=192.168.0.100/24 -Gateway=192.168.0.1 -DNS=192.168.0.1 -``` - -**Option 2: Hostname-based Access** -Use local hostname resolution instead of IP: -```bash -# Access via hostname (works for both interfaces) -ssh hoborg@ak-homelab.local -# or configure local DNS/mDNS -``` - -**Option 3: Bridge Networking** -Create bridge combining both interfaces for automatic failover: -```bash -# Advanced: Bridge both interfaces -ip link add name br0 type bridge -ip link set enp3s0 master br0 -ip link set wlp2s0 master br0 -``` - -**Current Setup:** -- Router: 192.168.0.1 -- Ethernet: 192.168.0.100 (static IP achieved) -- WiFi: Static IP needed (same .100) -- External: ak-homelab.duckdns.org βœ… -- SSH: Port 2222 βœ… - -**Network Interface Identification:** -- **enp3s0f0**: First ethernet port (98:fa:9b:f1:06:d5) -- **enp4s0**: Second ethernet port (98:fa:9b:f1:06:d4) ← **Use this one** -- **wlp1s0**: WiFi interface (0c:dd:24:e6:0f:87) - -**Issue Solved:** Dual ethernet ports caused MAC address confusion when cable was moved between ports. Stick to enp4s0 consistently. - -### IP Address Scheme -- **Router**: 192.168.0.1 -- **Homelab server**: 192.168.0.100 (target static IP) -- **Current ethernet**: 192.168.0.22 (can migrate to .100) -- **DHCP range**: 192.168.0.10-99 (excluding static IPs) -- **VPN subnet**: 10.0.0.0/24 - -### DNS Configuration -- **Primary DNS**: Router (192.168.1.1) -- **Secondary DNS**: 1.1.1.1, 8.8.8.8 -- **Local domain**: homelab.local -- **Dynamic DNS**: ak-homelab.duckdns.org - -### Service Architecture -``` -Internet β†’ Router β†’ Homelab Server - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ SSH (2222) β”‚ - β”‚ WireGuard VPN (51820) β”‚ - β”‚ Web Services (80/443) β”‚ - β”‚ Monitoring & Logging β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -## Backup and Recovery - -### Configuration Backups -- **SSH keys**: Store securely, separate from server -- **WireGuard configs**: Document peer configurations -- **Firewall rules**: Export UFW rules with `ufw status numbered` - -### Network Documentation -- **IP mappings**: Document static assignments -- **Port forwards**: List all forwarded ports and purposes -- **Access credentials**: Secure storage of passwords/keys \ No newline at end of file diff --git a/services.md b/services.md deleted file mode 100644 index 6292440..0000000 --- a/services.md +++ /dev/null @@ -1,223 +0,0 @@ -# Services & Applications - -Planning and configuration for self-hosted services and applications. - -## Git Repository Hosting - -### Service Options -- **Gitea**: Lightweight, Go-based, minimal resource usage βœ… *Recommended* -- **Forgejo**: Gitea fork, community-driven development -- **GitLab CE**: Feature-rich but more resource intensive -- **Gogs**: Simple, lightweight alternative - -### Gitea Installation -```bash -# Create gitea user -sudo useradd -r -s /bin/false -d /var/lib/gitea gitea - -# Download and install -wget https://dl.gitea.io/gitea/latest/gitea-linux-amd64 -sudo mv gitea-linux-amd64 /usr/local/bin/gitea -sudo chmod +x /usr/local/bin/gitea - -# Create directories -sudo mkdir -p /var/lib/gitea/{custom,data,log} -sudo chown -R gitea:gitea /var/lib/gitea/ -sudo chmod -R 750 /var/lib/gitea/ -``` - -### Configuration -- **Database**: SQLite for simplicity, PostgreSQL for production -- **Port**: 3000 (internal), reverse proxy for HTTPS -- **SSH**: Port 2222 for git operations -- **Features**: Web interface, issue tracking, organizations - -## Cloud Storage Solutions - -### Service Options -- **Copyparty**: Quite new self-hosted file storage solution, must investigate! -- **Nextcloud**: Full-featured, extensive app ecosystem βœ… *Recommended* -- **ownCloud**: Original project, stable and mature -- **Seafile**: Performance-focused file sync -- **Syncthing**: Decentralized sync (no server needed) - -### Nextcloud Installation -```bash -# Via snap (recommended) -sudo snap install nextcloud - -# Or via Docker -docker run -d \ - --name nextcloud \ - -p 8080:80 \ - -v nextcloud_data:/var/www/html \ - nextcloud -``` -Personal notes: Not a fan of snap, isn't there an AUR package? -Go with docker otherwise - -### Features -- File synchronization across devices -- Video files, game installers -> high prio -- Self-hosted git mirrors of favorite FOSS projects -> medium prio -- Calendar and contacts (CalDAV/CardDAV) -> low prio -- Document editing (OnlyOffice/Collabora) -> low prio -- Photo management and sharing -> low prio -- Mobile apps available? - -## Media Management - -### Jellyfin Media Server -```bash -# Install via AUR -yay -S jellyfin-server jellyfin-web - -# Enable service -sudo systemctl enable jellyfin -sudo systemctl start jellyfin -``` - -Configuration: -- **Port**: 8096 (web interface) -- **Media paths**: `/data/movies`, `/data/tv`, `/data/music` -- **Transcoding**: Hardware acceleration if available - -### Photo Management -- **PhotoPrism**: AI-powered photo management -- **Immich**: Modern photo backup solution -- **LibrePhotos**: Privacy-focused alternative - -## Monitoring & Logging - -### System Monitoring -```bash -# Prometheus + Grafana stack -docker-compose up -d prometheus grafana node-exporter -``` - -### Log Management -- **Centralized logging**: rsyslog or journald -- **Log rotation**: logrotate configuration -- **Analysis**: grep, awk, or ELK stack for advanced needs - -### Health Checks -- **Uptime monitoring**: Simple HTTP checks -- **Service status**: systemd service monitoring -- **Disk space**: Automated alerts for low space - -## Containerization Strategy - -### Docker Setup -```bash -# Install Docker -pacman -S docker docker-compose -sudo systemctl enable docker - -# Add user to docker group -sudo usermod -aG docker hoborg -``` - -### Container Management -- **Orchestration**: Docker Compose for multi-service apps -- **Storage**: Named volumes for persistent data -- **Networking**: Custom networks for service isolation -- **Updates**: Watchtower for automated updates - -## Reverse Proxy Configuration - -### Nginx Setup -```bash -# Install nginx -pacman -S nginx certbot certbot-nginx - -# Basic configuration -server { - server_name ak-homelab.duckdns.org; - - location /gitea/ { - proxy_pass http://localhost:3000/; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } - - location /nextcloud/ { - proxy_pass http://localhost:8080/; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} -``` - -### SSL Certificates -```bash -# Let's Encrypt via certbot -sudo certbot --nginx -d ak-homelab.duckdns.org -``` - -## Backup Strategy - -### Configuration Backups -- **Service configs**: Docker volumes, /etc configs -- **Database dumps**: Regular automated backups -- **Storage**: External drive or cloud backup - -### Automated Backups -```bash -#!/bin/bash -# backup-services.sh -DATE=$(date +%Y%m%d) - -# Backup Gitea -tar -czf /backup/gitea-$DATE.tar.gz /var/lib/gitea/ - -# Backup Nextcloud data -rsync -av /var/snap/nextcloud/common/nextcloud/data/ /backup/nextcloud-$DATE/ - -# Database backup -sudo -u postgres pg_dump gitea > /backup/gitea-db-$DATE.sql -``` - -## Resource Planning - -### Hardware Requirements -- **RAM**: 4GB minimum, 8GB recommended -- **Storage**: - - System: 50GB SSD - - Data: 1TB+ HDD for media/files -- **Network**: Gigabit Ethernet preferred - -### Service Resource Usage -| Service | RAM | CPU | Storage | Port | -|---------|-----|-----|---------|------| -| Gitea | 200MB | Low | 5GB+ | 3000 | -| Nextcloud | 512MB | Medium | 10GB+ | 8080 | -| Jellyfin | 1GB | High* | Media | 8096 | -| Monitoring | 500MB | Low | 2GB | 3000/9090 | - -*High during transcoding - -## Security Considerations - -### Service Hardening -- **Regular updates**: Automated security patches -- **Access control**: VPN-only access when possible -- **Authentication**: Strong passwords, 2FA where available -- **Network isolation**: Separate VLANs or containers - -### Data Protection -- **Encryption**: Full disk encryption (LUKS) -- **Backups**: Encrypted offsite backups -- **Access logs**: Monitor service access patterns -- **Fail2ban**: Automatic IP blocking for repeated failures - -## Future Expansion - -### Additional Services to Consider -- **Home Assistant**: ABSOLUTELY NOT -- **Bitwarden/Vaultwarden**: Password management - - How is this better than keepassxc + filesync? -- **Pi-hole**: Network-wide ad blocking -- **Wireguard UI**: Web interface for VPN management -- **Bookstack**: Documentation wiki - - What is this for? How does it compare to Logseq? -- **FreshRSS**: RSS feed aggregator diff --git a/system-setup.md b/system-setup.md deleted file mode 100644 index e17ffe7..0000000 --- a/system-setup.md +++ /dev/null @@ -1,158 +0,0 @@ -# System Setup Guide - -Complete guide for Arch Linux installation and system configuration. - -## Initial Installation - -### Pre-installation -1. Boot from Arch ISO -2. Verify boot mode: `ls /sys/firmware/efi/efivars` -3. Connect to internet: `iwctl` for WiFi -4. Update system clock: `timedatectl set-ntp true` - -### Disk Preparation -1. List disks: `fdisk -l` -2. Partition the disk: `cfdisk /dev/sdX` - - EFI partition: 512M, type EFI System - - Root partition: remaining space, type Linux filesystem -3. Format partitions: - ```bash - mkfs.fat -F32 /dev/sdX1 # EFI - mkfs.ext4 /dev/sdX2 # Root - ``` -4. Mount filesystems: - ```bash - mount /dev/sdX2 /mnt - mkdir /mnt/boot - mount /dev/sdX1 /mnt/boot - ``` -Current partition setup is a quite fragmented leftover from my dual-booting days. Later we should wipe the leftover -Windows drive for extra storage, but first we should confirm there's no essential files there -(unlikely since it wasn't booted for months, mostly using other windows PC) - -### System Installation -1. Install base packages: `pacstrap /mnt base linux linux-firmware` -2. Generate fstab: `genfstab -U /mnt >> /mnt/etc/fstab` -3. Chroot: `arch-chroot /mnt` -4. Set timezone: `ln -sf /usr/share/zoneinfo/Europe/Budapest /etc/localtime` -5. Generate hardware clock: `hwclock --systohc` -6. Configure locale: - - Edit `/etc/locale.gen`, uncomment `en_US.UTF-8 UTF-8` - - Run: `locale-gen` - - Create `/etc/locale.conf`: `LANG=en_US.UTF-8` -7. Set hostname: `echo "homelab" > /etc/hostname` -8. Configure hosts file -9. Set root password: `passwd` -10. Install bootloader: `pacman -S grub efibootmgr` -11. Install GRUB: `grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=GRUB` -12. Generate config: `grub-mkconfig -o /boot/grub/grub.cfg` - -## Post-Installation Setup - -### User Management -```bash -# Create user -useradd -m -G wheel -s /bin/bash hoborg -passwd hoborg - -# Configure sudo -pacman -S sudo -visudo # Uncomment %wheel ALL=(ALL) ALL -``` - -### Essential Packages -```bash -pacman -S git base-devel openssh networkmanager -systemctl enable NetworkManager -systemctl enable sshd -``` - -### AUR Access -```bash -# Install yay AUR helper -git clone https://aur.archlinux.org/yay.git -cd yay -makepkg -si -``` - -## Desktop Environment - -### XFCE Installation -```bash -pacman -S xfce4 xfce4-goodies lightdm lightdm-gtk-greeter -systemctl enable lightdm -``` - -### Themes and Appearance -- **Window Manager Theme**: Matcha-dark-aliz -- **Icons**: Papirus-Maia -- **Fonts**: - - System: Install Nerd Fonts (`ttf-iosevkaterm-nerd ttf-jetbrains-mono-nerd`) - - TTY: ter-124b (12x24 bold) - -## Development Environment - -### Dotfiles Management -```bash -# Install yadm -pacman -S yadm - -# Clone dotfiles -yadm clone git@gitlab.com:akrejczinger/dotfiles.git -``` - -### Shell Configuration -- **Shell**: zsh with antidote plugin manager -- **Terminal**: wezterm with Catppuccin theme -- **Multiplexer**: tmux with catppuccin theme and temperature monitoring -- **Editor**: neovim with lazy.nvim plugin manager - -### Key Configurations -- **Keyboard Layout**: Colemak (US variant in X11) -- **TTY Layout**: Colemak with caps lock β†’ backspace via systemd service -- **Font Fallbacks**: Noto fonts for Unicode support - -## TTY Configuration - -### Font and Layout -```bash -# Configure /etc/vconsole.conf -KEYMAP=colemak -FONT=ter-124b -FONT_MAP=8859-1 -``` - -### Caps Lock Fix -Caps lock mapped to backspace via systemd service: -```bash -# /etc/systemd/system/caps-backspace.service -sudo setkeycodes 3a 14 # Map caps scancode to backspace keycode -``` - -### Color Scheme -TTY colors configured in `.zshrc` for better readability. - -## System Maintenance - -### Package Management -- Regular updates: `yay -Syu` -- Orphaned packages: `yay -Yc` -- Cache cleanup: `yay -Sc` - -### Backup Strategy -- Dotfiles: yadm + git repository -- System configs: Document in this guide -- User data: External backup solution - -## Hardware-Specific Notes - -### ThinkPad Optimizations -- **Temperature Monitoring**: Available via `sensors` command -- **Battery Management**: TLP for power optimization -- **Trackpad**: libinput with natural scrolling -- **Function Keys**: Media keys work out of box - -### Network Configuration -- **WiFi**: NetworkManager with GUI applet -- **Ethernet**: Automatic DHCP -- **Bluetooth**: bluez with pulseaudio integration diff --git a/troubleshooting.md b/troubleshooting.md deleted file mode 100644 index 6a3f4ac..0000000 --- a/troubleshooting.md +++ /dev/null @@ -1,312 +0,0 @@ -# Bluetooth keeps disconnecting - reconnecting - -Solution: Change config in /etc/bluetooth/main.conf -`ControllerMode = bredr` -Then `sudo systemctl restart bluetooth` - -UPDATE: It's still not fixed :( -Trying `yay -S pipewire wireplumber` -TODO test it again - -# Touchpad scroll direction (libinput) - -To change touchpad scroll direction on Arch Linux using libinput driver: - -## Investigation steps: -1. Check which driver is used: `pacman -Q | grep -E "(synaptics|libinput)"` -2. Verify libinput config exists: `ls /usr/share/X11/xorg.conf.d/ | grep libinput` - -## Solution for libinput: -Create `/etc/X11/xorg.conf.d/30-touchpad.conf`: - -``` -Section "InputClass" - Identifier "touchpad" - Driver "libinput" - MatchIsTouchpad "on" - Option "NaturalScrolling" "true" - Option "Tapping" "on" - Option "TappingDrag" "on" - Option "DisableWhileTyping" "on" -EndSection -``` - -Set `NaturalScrolling` to: -- `"true"` for macOS-style (natural) scrolling -- `"false"` for traditional scrolling - -Restart X11 (log out/in) or reboot to apply changes. - -## Alternative: Synaptics driver (legacy) - -If using the older synaptics driver instead of libinput: - -### Investigation steps: -1. Check for synaptics: `pacman -Q xf86-input-synaptics` -2. Look for config: `ls /usr/share/X11/xorg.conf.d/ | grep synaptics` - -### Solution: -Create `/etc/X11/xorg.conf.d/70-synaptics.conf`: - -``` -Section "InputClass" - Identifier "touchpad" - Driver "synaptics" - MatchIsTouchpad "on" - MatchDevicePath "/dev/input/event*" - Option "VertScrollDelta" "-111" - Option "HorizScrollDelta" "-111" - Option "TapButton1" "1" - Option "TapButton2" "3" - Option "TapButton3" "2" - Option "PalmDetect" "1" - Option "SHMConfig" "on" -EndSection -``` - -Synaptics scroll direction options: -- `VertScrollDelta` and `HorizScrollDelta`: - - Positive values (e.g., `"111"`) for traditional scrolling - - Negative values (e.g., `"-111"`) for natural/reversed scrolling - -**Note:** libinput is the modern standard. Consider switching from synaptics to libinput for better support and features. - -# Theme switching issues - -## Cross-application theme synchronization - -**Issue:** Need to synchronize theme (light/dark) across tmux, nvim, and other terminal applications. - -**Solution:** File-based theme management system using `~/.vim_theme`: - -### Setup: - -1. **Create theme switcher script** (`~/.config/tmux/themeswitch.sh`): -```bash -#!/bin/bash -if [ -f ~/.vim_theme ] && [ "$(cat ~/.vim_theme)" = "light" ]; then - tmux set -g @catppuccin_flavor "latte" -else - tmux set -g @catppuccin_flavor "mocha" -fi -``` - -2. **Add to tmux config** (`~/.config/tmux/tmux.conf`): -```bash -# Dynamic theme switching based on ~/.vim_theme file -run 'bash ~/.config/tmux/themeswitch.sh' -``` - -3. **Add to shell config** (`~/.zshrc`): -```bash -# Export THEME environment variable for nvim and other apps -if [ -f ~/.vim_theme ]; then - export THEME=$(cat ~/.vim_theme) -else - export THEME="dark" # default -fi -``` - -### Usage: -```bash -# Switch to light theme -echo "light" > ~/.vim_theme - -# Switch to dark theme -echo "dark" > ~/.vim_theme -``` - -### Benefits: -- βœ… **Single source of truth:** `~/.vim_theme` file controls all applications -- βœ… **Automatic propagation:** New terminals inherit theme via shell config -- βœ… **No environment variable issues:** File-based approach avoids tmux env var propagation problems -- βœ… **Cross-application support:** nvim reads `$THEME`, tmux uses catppuccin flavors - -### Limitations: -- **Tmux live reload:** Changes require tmux config reload or session restart -- **Workaround:** Use tmux-resurrect to quickly restore sessions after restart - -## Legacy: Tmux and terminal not updating after theme switch - -**Issue:** After running the theme switcher script, tmux sessions and existing terminals don't reflect the new theme until restarted. - -**Temporary workaround:** -- Restart tmux sessions: `tmux kill-server && tmux` -- Open new terminal windows - -**Status:** βœ… **Solved** - Use file-based theme management system above - -## Tmux window names showing hostname instead of command - -**Issue:** Tmux windows show "homelab" (hostname) for inactive tabs but correct command names for active tabs. - -**Root cause:** Catppuccin tmux theme with `@catppuccin_window_tabs_enabled on` uses different text formatting for active vs inactive windows. - -**Solution:** Disable catppuccin window tabs: -``` -set -g @catppuccin_window_tabs_enabled off -``` - -**Alternative:** Configure explicit window text for both states: -``` -set -g @catppuccin_window_default_text "#W" -set -g @catppuccin_window_current_text "#W" -``` - -Also ensure automatic renaming is enabled: -``` -setw -g automatic-rename on -setw -g allow-rename on -``` - -# Font and Unicode Display Issues - -## Missing emoji and unicode symbols - -**Issue:** Emojis show as boxes or missing characters, unicode symbols don't display properly. - -**Solution:** Install comprehensive unicode font packages: -```bash -sudo pacman -S noto-fonts-emoji noto-fonts-extra -fc-cache -f -``` - -## Nerd Font icons not displaying - -**Issue:** Developer icons (programming languages, git symbols, file types) show as blank spaces or boxes. - -**Root cause:** Terminal emulator not configured to use Nerd Font as primary font. - -**Solution:** -1. Install Nerd Fonts: -```bash -sudo pacman -S ttf-iosevkaterm-nerd ttf-jetbrains-mono-nerd -fc-cache -f -``` - -2. Configure terminal to use Nerd Font as primary font -3. For wezterm, ensure config includes: -```lua -config.font = wezterm.font_with_fallback { - 'IosevkaTerm Nerd Font', - 'JetBrainsMono Nerd Font Mono', - 'Noto Color Emoji' -} -``` - -**Testing:** Use printf with direct codepoints: -```bash -printf "Icons: \\ue702 \\uf121 \\uf015 \\uf07b\\n" -``` - -## Ancient/exotic script support - -**Comprehensive coverage achieved with:** -- `noto-fonts` (base unicode) -- `noto-fonts-cjk` (Chinese/Japanese/Korean) -- `noto-fonts-emoji` (color emoji) -- `noto-fonts-extra` (additional scripts) - -Successfully displays: Egyptian hieroglyphs, Cuneiform, Nordic runes, Hungarian rovΓ‘s, Arabic, Chinese, Japanese, Korean, Thai, Hindi, Hebrew, Greek, Tamil. - -# Cannot tile windows by drag and dropping - -Keyboard workaround: Go to Settings > Window Manager > Keyboard, set up tiling shortcuts (set to Super+arrow keys) - -# Additional Known Issues (TODO Items) - -## Tmux battery indicator missing until config reload - -**Issue:** Battery indicator doesn't appear in tmux status line immediately after starting tmux. - -**Temporary workaround:** Reload tmux config with `Prefix + r` or restart tmux session. - -**Status:** Investigation needed - -## TTY fallbacks needed - -**Issue:** When not in X11/graphical mode, nvim and tmux need proper fallback configurations. - -**Status:** Completed - -**Solutions implemented:** -- βœ… **nvim:** TTY detection and color scheme fallback configured -- βœ… **Font:** Selected ter-124b (12x24 bold) for good readability -- βœ… **Keyboard:** Colemak layout with caps lock remapped to backspace -- βœ… **Caps lock fix:** Uses systemd service with `setkeycodes 3a 14` - -**Configuration files:** -- `/etc/systemd/system/caps-backspace.service` - Permanent caps lock remapping -- TTY font testing script: `~/.local/scripts/test-fonts.sh` - -## TTY Caps Lock Not Working as Backspace - -**Issue:** With colemak keymap loaded, caps lock acts like Control instead of backspace in TTY. - -**Root cause:** Colemak keymap maps caps lock to Control, which conflicts with tmux navigation keys. - -**Solution:** Use `setkeycodes` to remap at scancode level: -```bash -sudo setkeycodes 3a 14 # Map caps lock scancode to backspace keycode -``` - -**Permanent fix:** Systemd service created at `/etc/systemd/system/caps-backspace.service` - -## Laptop sleeps when lid is closed - -Solution: - -sudo nvim /etc/systemd/logind.conf - -Uncomment and change these lines: - -``` -HandleLidSwitch=ignore -HandleLidSwitchExternalPower=ignore -HandleLidSwitchDocked=ignore -``` - -Then restart service: -`sudo systemctl restart systemd-logind` - -## IP addresses keep changing - -Due to 3 interfaces: -* Wifi -* Ethernet left port (ThinkPad adapter) - Wired Connection 1 -* Ethernet right port (regular ethernet cable) - Wired Connection 2 - -### Proposed solution - -* Stick with wired2 - -● Configure static IP for "Wired connection 2" (enp4s0): - - * Set static IP to 192.168.0.100 - sudo nmcli connection modify "Wired connection 2" \ - ipv4.method manual \ - ipv4.addresses 192.168.0.100/24 \ - ipv4.gateway 192.168.0.1 \ - ipv4.dns 192.168.0.1 - - * Apply the changes - sudo nmcli connection up "Wired connection 2" - - Then configure WiFi with the same static IP: - - * First connect to your WiFi if not already - sudo nmcli connection up "Telekom-4b28df-2.4GHz" - - * Set same static IP for WiFi - sudo nmcli connection modify "Telekom-4b28df-2.4GHz" \ - ipv4.method manual \ - ipv4.addresses 192.168.0.100/24 \ - ipv4.gateway 192.168.0.1 \ - ipv4.dns 192.168.0.1 - - Verify the configuration: - nmcli connection show "Wired connection 2" | grep ipv4 - ip addr show enp4s0 - - This way both your ethernet (enp4s0) and WiFi will use 192.168.0.100, solving your dual interface IP issue. - Ready to run these commands?