startup-it-troubleshooting

name	startup-it-troubleshooting
description	Practical IT troubleshooting playbooks for small teams without dedicated IT staff.
license	MIT
metadata	{"author":"devops-skills","version":"2.0"}

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 <(curl -s -S -L https://gam-shortn.appspot.com/gam-install)  # install GAM
gam oauth create                                                     # authorize

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

Okta API

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

# 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

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

DNS Issues

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

$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

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

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

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

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

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

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

Battery Health

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

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

---

macOS Administration

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 "python@3.12"; 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

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

# 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

gam user [e-mail] show forwarding    # check rogue forwarding rules
gam user [e-mail] delete forwarding  # remove forwarding
gam user [e-mail] show delegates     # check email delegation
gam user [e-mail] show filters       # check mail filters

Microsoft 365

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

Email Deliverability

dig TXT company.com | grep "v=spf1"             # SPF
dig TXT google._domainkey.company.com            # DKIM
dig TXT _dmarc.company.com                       # DMARC

---

Onboarding Checklist

# 1. Google Workspace account
gam create user [e-mail] firstname "Jane" lastname "Smith" \
  password "Welcome2Company!" changepassword on org "/Engineering"
gam update group [e-mail] add member [e-mail]

# 2. 1Password
op user provision --email [e-mail] --name "Jane Smith"

# 3. Slack
curl -X POST "https://slack.com/api/admin.users.invite" \
  -H "Authorization: Bearer xoxp-your-admin-token" \
  -d "email=[e-mail]&channel_ids=C01GENERAL,C02ENGINEERING&team_id=T01YOURTEAM"

# 4. GitHub
gh api orgs/your-company/invitations -f email="[e-mail]" -f role="direct_member"
gh api orgs/your-company/teams/engineering/memberships/newhire-username -f role="member" -X PUT

# 5. VPN / Tailscale
tailscale up --authkey tskey-auth-abc123

First-Day Setup Script (macOS)

Give new hires this script. It installs Homebrew, your standard tools from a hosted Brewfile, configures Git, authenticates GitHub CLI, clones core repos, and enables FileVault.

#!/bin/bash
set -e
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
curl -sL https://internal.company.com/setup/Brewfile -o /tmp/Brewfile && brew bundle install --file=/tmp/Brewfile
read -p "Full name: " N; read -p "Email: " E
git config --global user.name "$N" && git config --global user.email "$E" && git config --global pull.rebase true
gh auth login && mkdir -p ~/src && cd ~/src && gh repo clone your-company/main-app
sudo fdesetup enable

Offboarding Checklist

Run these immediately when someone departs. Speed matters for security.

gam update user [e-mail] suspended on             # 1. block all access
gam user [e-mail] signout                         # 2. kill sessions
gam user [e-mail] transfer drive [e-mail]  # 3. transfer Drive
gam user [e-mail] add delegate [e-mail]    # 4. delegate email 30d
curl -X POST "https://slack.com/api/admin.users.remove" \
  -H "Authorization: Bearer xoxp-your-admin-token" \
  -d "user_id=U01DEPARTED&team_id=T01YOURTEAM"               # 5. remove Slack
gh api orgs/your-company/members/departed-username -X DELETE   # 6. remove GitHub
op user suspend [e-mail]                           # 7. revoke 1Password
aws iam delete-login-profile --user-name departed              # 8. revoke AWS console
aws iam list-access-keys --user-name departed                  #    then delete each key
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) Offboarded [e-mail]" >> ~/offboarding-log.txt

---

Video Conferencing

# macOS
lsof | grep "AppleCamera\|VDC"          # check what owns the camera
pkill -f zoom.us && open -a zoom.us      # restart Zoom
tccutil reset Camera                     # reset camera permissions

# Linux
pactl list short sources                 # list mics
pactl set-source-mute @DEFAULT_SOURCE@ 0 # unmute mic

Get-CimInstance Win32_SoundDevice | Select Name, Status

Quick fixes: No audio = check OS mute + correct device. No video = close other conferencing apps. Echo = use headphones. Choppy = need 3+ Mbps upload.

---

Printer / Peripheral Issues

# macOS
lpstat -p -d && cancel -a                                    # list printers, clear queue
sudo launchctl stop org.cups.cupsd && sudo launchctl start org.cups.cupsd
system_profiler SPUSBDataType            # USB devices

# Linux
sudo systemctl restart cups              # restart print system
lsusb && dmesg | tail -20               # USB diagnostics

Restart-Service Spooler -Force                              # restart print spooler
Get-PrintJob -PrinterName "OfficePrinter" | Remove-PrintJob # clear stuck jobs

---

Security Basics

Endpoint Protection

# macOS
spctl --status                           # Gatekeeper
csrutil status                           # SIP
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on

# Linux
sudo ufw enable && sudo ufw default deny incoming && sudo ufw default allow outgoing

Get-MpComputerStatus | Select AntivirusEnabled, RealTimeProtectionEnabled
Start-MpScan -ScanType QuickScan
Get-NetFirewallProfile | Select Name, Enabled

Phishing Response

gam update user [e-mail] password "$(openssl rand -base64 16)" changepassword on
gam user [e-mail] signout             # kill sessions
gam user [e-mail] turnoff2sv          # reset MFA
gam user [e-mail] show tokens         # check rogue OAuth apps
gam user [e-mail] show forwarding     # check attacker persistence

Lost / Stolen Device Protocol

1. Immediately -- Remote wipe via MDM or Find My Mac.
2. Within 15 min -- Reset password and kill sessions (SSO commands above).
3. Within 1 hour -- Rotate API keys and secrets: gh auth refresh, delete AWS access keys.
4. Within 24 hours -- Review access logs for suspicious activity.

Related Skills

• incident-management -- Structured incident handling
• runbook-creation -- Documentation standards