startup-it-troubleshooting

What this skill does

# Startup IT Troubleshooting

Runbooks for startups and small teams where engineers double as the IT department.

## When to Use

You are the "accidental IT person." Nobody has IT in their title, but laptops freeze, Wi-Fi drops during investor demos, someone gets locked out of Google Workspace at midnight, and a new hire starts Monday with zero accounts. This skill gives you copy-paste commands to handle it all.

**Priority triage:** (1) Company-wide outages, (2) Executive/customer-facing blockers, (3) Team-wide degradations, (4) Individual workstation issues. Always ask: "How many people are affected?" and "Is revenue impacted?"

---

## SSO / Identity Lockouts

### Google Workspace via GAM

```bash
bash <(curl -s -S -L https://gam-shortn.appspot.com/gam-install)  # install GAM
gam oauth create                                                     # authorize

gam update user [email protected] password "TempPass123!" changepassword on  # reset password
gam update user [email protected] suspended off       # unsuspend locked-out user
gam user [email protected] signout                    # force sign-out all sessions
gam user [email protected] update backupcodes         # new MFA backup codes
gam user [email protected] turnoff2sv                 # disable 2SV (re-enable within 24h)
```

### Okta API

```bash
OKTA="company.okta.com"; T="your-api-token"; UID="00u1abcdef"
curl -X POST -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/lifecycle/unlock"
curl -X POST -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/lifecycle/reset_password?sendEmail=true"
curl -X POST -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/lifecycle/reset_factors"
curl -X DELETE -H "Authorization: SSWS $T" "https://$OKTA/api/v1/users/$UID/sessions"
```

**MFA recovery flow:** Verify identity via video call, generate backup codes or reset factors, have user re-enroll immediately, confirm old device is deregistered, log the incident.

---

## Network Troubleshooting

### Wi-Fi Debugging

```bash
# macOS
/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I
networksetup -setairportpower en0 off && sleep 2 && networksetup -setairportpower en0 on
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

# Linux
nmcli device wifi list && nmcli connection show --active
nmcli device disconnect wlan0 && nmcli device connect wlan0
sudo systemd-resolve --flush-caches
```

```powershell
netsh wlan show interfaces
netsh wlan disconnect; netsh wlan connect name="OfficeWiFi"
ipconfig /flushdns
netsh winsock reset  # full stack reset, reboot after
```

### DNS Issues

```bash
nslookup company.com 8.8.8.8            # test against known-good DNS
dig @1.1.1.1 company.com                # Linux/macOS detail
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 8.8.4.4  # macOS temp override
```

```powershell
$a = Get-NetAdapter | Where-Object {$_.Status -eq "Up"}
Set-DnsClientServerAddress -InterfaceIndex $a.ifIndex -ServerAddresses ("8.8.8.8","8.8.4.4")
```

### VPN Not Connecting

```bash
nc -zv vpn.company.com 443                         # test port reachability
sudo wg show                                        # WireGuard status
sudo wg-quick down wg0 && sudo wg-quick up wg0     # restart WireGuard
tailscale status && sudo tailscale up --reset       # Tailscale re-auth
```

### Slow Internet

```bash
speedtest-cli --simple        # bandwidth test (pip install speedtest-cli)
ping -c 50 8.8.8.8            # packet loss check
networkQuality -s              # macOS 12+ bufferbloat test
```

---

## Laptop Performance

### Disk Space

```bash
df -h                                    # volume overview
du -sh ~/* | sort -rh | head -15         # biggest dirs in home
docker system df                         # Docker disk usage (common culprit)
docker system prune -a --volumes         # reclaim Docker space
brew cleanup --prune=all                 # macOS Homebrew cleanup
```

```powershell
Get-PSDrive -PSProvider FileSystem | Select Name,@{N='Free(GB)';E={[math]::Round($_.Free/1GB,2)}}
Get-ChildItem C:\ -Recurse -File -EA SilentlyContinue | Sort Length -Desc | Select -First 15 FullName,@{N='MB';E={[math]::Round($_.Length/1MB,2)}}
```

### Memory Pressure and Runaway Processes

```bash
# macOS
memory_pressure
top -o rsize -l 1 -n 10 -stats pid,command,rsize
pkill -f "Google Chrome Helper"

# Linux
free -h && ps aux --sort=-%mem | head -11
sudo dmesg | grep -i "oom\|out of memory"
```

```powershell
Get-Process | Sort WorkingSet64 -Desc | Select -First 10 Name,@{N='MB';E={[math]::Round($_.WorkingSet64/1MB,2)}}
Stop-Process -Name "Teams" -Force
```

### Battery Health

```bash
system_profiler SPPowerDataType | grep -E "Cycle Count|Condition"  # macOS
upower -i /org/freedesktop/UPower/devices/battery_BAT0             # Linux
```

```powershell
powercfg /batteryreport /output "$env:USERPROFILE\Desktop\battery.html"
```

---

## macOS Administration

```bash
profiles status -type enrollment          # MDM enrollment check
sudo systemsetup -setremotelogin on       # enable SSH for remote admin

# Homebrew fleet setup — standard Brewfile
cat > Brewfile <<'EOF'
brew "git"; brew "node"; brew "[email protected]"; brew "awscli"; brew "jq"; brew "gh"
cask "google-chrome"; cask "slack"; cask "1password"; cask "visual-studio-code"; cask "docker"; cask "zoom"
EOF
brew bundle install --file=Brewfile
brew bundle dump --file=~/Brewfile --force  # export current setup

# FileVault
sudo fdesetup status && sudo fdesetup enable  # store recovery key in 1Password

# Updates
softwareupdate -l && sudo softwareupdate -ia --restart
```

---

## Windows Administration

```powershell
gpresult /r; gpupdate /force             # check and refresh Group Policy

# Windows Update
Install-Module PSWindowsUpdate -Force -Scope CurrentUser
Install-WindowsUpdate -AcceptAll -AutoReboot
# If stuck: reset update components
Stop-Service wuauserv,cryptSvc,bits,msiserver -Force
Remove-Item "C:\Windows\SoftwareDistribution" -Recurse -Force
Start-Service wuauserv,cryptSvc,bits,msiserver

# BitLocker
manage-bde -status C:
Enable-BitLocker -MountPoint "C:" -EncryptionMethod XtsAes256 -UsedSpaceOnly -TpmProtector

# Remote Desktop
Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -Name "fDenyTSConnections" -Value 0
Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
```

---

## Linux Desktop

```bash
# Ubuntu — fix broken packages
sudo apt --fix-broken install && sudo dpkg --configure -a && sudo apt update && sudo apt upgrade -y

# Fedora — fix broken packages
sudo dnf check && sudo dnf distro-sync && sudo dnf update -y

# Service failures
systemctl --failed
journalctl -p err -b

# Drivers
sudo ubuntu-drivers autoinstall                    # Ubuntu proprietary drivers
lspci | grep -i vga && sudo lshw -C display        # GPU info
sudo dmesg | grep -i firmware                       # missing firmware

# Display issues
xrandr --auto                                       # reset to auto-detect
xrandr --output HDMI-1 --mode 1920x1080 --rate 60  # force resolution
echo $XDG_SESSION_TYPE                              # Wayland vs X11 check
```

---

## Email / Calendar Issues

### Google Workspace

```bash
gam user [email protected] show forwarding    # check rogue forwarding rules
gam user [email protected] delete forwarding  # remove forwarding
gam user [email protected] show delegates     # check email delegation
gam user [email protected] show filters       # check mail filters
```

### Microsoft 365

```powershell
Install-Module ExchangeOnlineManagement -Force -Scope CurrentUser
Connect-ExchangeOnline -UserPrincipalName [email protected]
Get-MessageTrace -SenderAddress [email protected] -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date)
Get-MailboxStatistics -Identity [email protected] | Select DisplayName,TotalItemSize
```

### Email Deliverability

```bash
dig TXT company.com | grep "v=spf1"             # SPF
dig TXT google._domainkey.company.com            # D