Update README.md to enhance documentation structure and clarity, including detailed features, configuration instructions, and usage examples for the SSH Key Sync script. (#13)

locus313 · web-flow · commit aab4279a1796 · 2025-08-29T22:25:44.000-07:00
diff --git a/README.md b/README.md
@@ -1,83 +1,292 @@
-# SSH Key Sync Script
+# SSH Key Sync
 
-This Bash script pulls `authorized_keys` files from remote URLs and updates SSH access for multiple local users.
+[![Lint Status](https://img.shields.io/github/actions/workflow/status/locus313/ssh-key-sync/lint.yml?style=flat-square&label=lint)](https://github.com/locus313/ssh-key-sync/actions)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+[![Shell](https://img.shields.io/badge/Shell-Bash-green?style=flat-square&logo=gnu-bash)](https://www.gnu.org/software/bash/)
+[![Version](https://img.shields.io/badge/Version-0.1.0-orange?style=flat-square)](https://github.com/locus313/ssh-key-sync/releases)
 
-## 🔧 Features
+⭐ If you like this project, star it on GitHub — it helps a lot!
 
-- Pull-based (ideal for cron or systemd timer)
-- Supports multiple users
-- Works with:
-  - ✅ Public URLs (method: `raw`)
-  - ✅ Private GitHub repositories via GitHub API (method: `api`, requires token)
-  - ✅ GitHub user public keys (method: `ghuser`)
-- Safe: Only updates keys if they’ve changed
-- Logs activity per user
-- Retries failed fetch operations up to 3 times with a delay
-- **Self-update**: Automatically updates the script to the latest version from the GitHub repository
+[Features](#features) • [Getting Started](#getting-started) • [Configuration](#configuration) • [Usage](#usage) • [Examples](#examples) • [Automation](#automation)
 
-## ⚙️ Configuration
+A robust Bash script for automating SSH `authorized_keys` synchronization across multiple users from various sources. Perfect for managing SSH access in development environments, CI/CD pipelines, and production systems.
 
-User configuration is stored in a separate `users.conf` file in the same directory as the script.  
-Edit `users.conf` to define users and their key sources.  
-Each entry uses the format:  
-`["username"]="method:url"`
+## Features
 
-- **raw:** Fetches directly from a public URL.
-- **api:** Fetches from a private GitHub repo using the GitHub API (requires `GITHUB_TOKEN` environment variable).
-- **ghuser:** Fetches public keys from a GitHub user's profile (provide the GitHub username after the colon).
+- **Multiple Key Sources**: Fetch SSH keys from public URLs, private GitHub repositories, or GitHub user profiles
+- **Retry Logic**: Built-in retry mechanism with configurable delays for handling network failures
+- **Safe Updates**: Only modifies `authorized_keys` when remote content has actually changed
+- **Comprehensive Logging**: Detailed timestamped logs for monitoring and debugging
+- **Self-Updating**: Automatically update to the latest version from the GitHub repository
+- **Configuration-Driven**: External configuration file for easy management
+- **Error Handling**: Robust error handling with graceful fallbacks
+- **Multi-User Support**: Manage SSH keys for multiple system users simultaneously
 
-You can also set your GitHub token in the config file using `CONF_GITHUB_TOKEN`.  
-If `GITHUB_TOKEN` is not set in the environment, the script will use `CONF_GITHUB_TOKEN` from `users.conf`.
+## Getting Started
+
+### Prerequisites
+
+- Bash 4.0 or later
+- `curl` for HTTP requests
+- `getent` for user information (typically available on Linux systems)
+- GitHub token (only required for private repository access)
+
+### Quick Start
+
+1. **Download the script**:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/locus313/ssh-key-sync/main/sync-ssh-keys.sh -o sync-ssh-keys.sh
+   chmod +x sync-ssh-keys.sh
+   ```
+
+2. **Download the configuration template**:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/locus313/ssh-key-sync/main/users.conf -o users.conf
+   ```
+
+3. **Configure your users** by editing `users.conf`:
+   ```bash
+   nano users.conf
+   ```
+
+4. **Run the script**:
+   ```bash
+   ./sync-ssh-keys.sh
+   ```
+
+## Configuration
+
+Configuration is managed through the `users.conf` file, which defines users and their SSH key sources.
+
+### Configuration Format
 
-**Example `users.conf`:**
 ```bash
+# Optional: GitHub token for private repository access
 CONF_GITHUB_TOKEN="your_github_token_here"
 
+# User key mapping
+declare -A USER_KEYS=(
+  ["username"]="method:target"
+)
+```
+
+### Supported Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `raw` | Fetch from public URL | `raw:https://example.com/keys.txt` |
+| `api` | Fetch from private GitHub repo via API | `api:https://api.github.com/repos/org/repo/contents/keys/user.keys?ref=main` |
+| `ghuser` | Fetch public keys from GitHub user | `ghuser:username` |
+
+### Example Configuration
+
+```bash
+#!/bin/bash
+
+# GitHub token for API access (optional)
+CONF_GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# User key definitions
 declare -A USER_KEYS=(
+  # Fetch from public URL
   ["ubuntu"]="raw:https://example.com/ssh-keys/ubuntu.authorized_keys"
+  
+  # Fetch from private GitHub repository
   ["devuser"]="api:https://api.github.com/repos/yourorg/ssh-keys/contents/keys/devuser.authorized_keys?ref=main"
+  
+  # Fetch public keys from GitHub user
   ["alice"]="ghuser:alice-github-username"
+  ["bob"]="ghuser:bob-github-username"
 )
 ```
 
 ## Usage
 
-1. Edit the `users.conf` file to define users and their key URLs or GitHub usernames.
-2. If using the `api` method, either export your GitHub token:
+### Command Line Options
+
+```bash
+./sync-ssh-keys.sh [OPTIONS]
+
+OPTIONS:
+  --self-update    Update the script to the latest version from GitHub
+  --help, -h       Show help message
+  --version, -v    Show version information
+```
+
+### Environment Variables
+
+- `GITHUB_TOKEN`: GitHub personal access token (overrides `CONF_GITHUB_TOKEN`)
+
+### Basic Usage
+
+```bash
+# Run synchronization
+./sync-ssh-keys.sh
+
+# Update script to latest version
+./sync-ssh-keys.sh --self-update
+
+# Show help
+./sync-ssh-keys.sh --help
+```
+
+## Examples
+
+### Adding New Users
+
+1. **Add a user with GitHub public keys**:
    ```bash
-   export GITHUB_TOKEN=your_token_here
+   # Edit users.conf
+   ["newuser"]="ghuser:github-username"
    ```
-   or set `CONF_GITHUB_TOKEN` in `users.conf`.
-3. Make sure the script is executable:
+
+2. **Add a user with keys from a private repository**:
    ```bash
-   chmod +x sync-ssh-keys.sh
+   ["secureuser"]="api:https://api.github.com/repos/company/ssh-keys/contents/users/secureuser.keys?ref=main"
    ```
-4. Add to root's crontab:
-   ```cron
-   */15 * * * * /usr/local/bin/sync-ssh-keys.sh >> /var/log/ssh-key-sync.log 2>&1
+
+3. **Add a user with keys from a public URL**:
+   ```bash
+   ["webuser"]="raw:https://company.com/keys/webuser.authorized_keys"
    ```
-5. To update the script to the latest version, run:
+
+### GitHub Token Setup
+
+For private repositories, you need a GitHub personal access token:
+
+1. Go to GitHub Settings → Developer settings → Personal access tokens
+2. Generate a new token with `repo` scope
+3. Add it to your configuration:
    ```bash
-   ./sync-ssh-keys.sh --self-update
+   CONF_GITHUB_TOKEN="your_token_here"
    ```
 
-## Implementation Notes
+### Multiple Key Sources
 
-- The script sources `users.conf` for configuration.
-- Uses a helper function `fetch_key_file` to fetch keys using the appropriate method.
-- Includes a retry mechanism for failed fetch operations (3 attempts with a 2-second delay).
-- Only updates a user's `authorized_keys` if the remote file has changed.
-- Logs all actions with timestamps.
-- The `--self-update` option fetches the latest version of the script from the GitHub repository and replaces the current version.
+You can configure users with different key sources:
 
-## Examples
+```bash
+declare -A USER_KEYS=(
+  ["prod-user"]="api:https://api.github.com/repos/company/prod-keys/contents/prod-user.keys?ref=main"
+  ["dev-user"]="ghuser:dev-github-username"
+  ["external-user"]="raw:https://partner.com/keys/external-user.keys"
+)
+```
 
-### Adding a New User
-1. Add the user to `users.conf`:
-   ```bash
-   ["newuser"]="ghuser:newuser-github-username"
+## Automation
+
+### Cron Setup
+
+Add to root's crontab for automated synchronization:
+
+```bash
+# Edit crontab
+sudo crontab -e
+
+# Add entry (sync every 15 minutes)
+*/15 * * * * /path/to/sync-ssh-keys.sh >> /var/log/ssh-key-sync.log 2>&1
+```
+
+### Systemd Timer
+
+Create a systemd service and timer:
+
+1. **Create service file** `/etc/systemd/system/ssh-key-sync.service`:
+   ```ini
+   [Unit]
+   Description=SSH Key Synchronization
+   Wants=ssh-key-sync.timer
+
+   [Service]
+   Type=oneshot
+   ExecStart=/path/to/sync-ssh-keys.sh
+   User=root
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+2. **Create timer file** `/etc/systemd/system/ssh-key-sync.timer`:
+   ```ini
+   [Unit]
+   Description=Run SSH Key Sync every 15 minutes
+   Requires=ssh-key-sync.service
+
+   [Timer]
+   OnCalendar=*:0/15
+   Persistent=true
+
+   [Install]
+   WantedBy=timers.target
    ```
-2. Run the script to sync keys:
+
+3. **Enable and start**:
    ```bash
-   ./sync-ssh-keys.sh
+   sudo systemctl daemon-reload
+   sudo systemctl enable ssh-key-sync.timer
+   sudo systemctl start ssh-key-sync.timer
    ```
+
+### CI/CD Integration
+
+Use in CI/CD pipelines for automated SSH access management:
+
+```yaml
+# GitHub Actions example
+- name: Sync SSH Keys
+  run: |
+    curl -fsSL https://raw.githubusercontent.com/locus313/ssh-key-sync/main/sync-ssh-keys.sh | bash -s
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Permission denied errors**:
+```bash
+# Ensure script is executable
+chmod +x sync-ssh-keys.sh
+
+# Run with appropriate privileges
+sudo ./sync-ssh-keys.sh
+```
+
+**GitHub API rate limits**:
+- Use authenticated requests with a GitHub token
+- Consider reducing sync frequency
+
+**Network timeouts**:
+- Script includes automatic retry logic (3 attempts by default)
+- Check network connectivity and firewall settings
+
+### Logging
+
+The script provides detailed logging with timestamps:
+
+```
+2025-08-29 12:00:00: Starting SSH key synchronization (version 0.1.0)
+2025-08-29 12:00:01: Fetching key file for user 'ubuntu' from https://example.com/keys.txt (method: raw)
+2025-08-29 12:00:02: Successfully processed user 'ubuntu'
+2025-08-29 12:00:02: Synchronization complete. Processed: 1, Failed: 0
+```
+
+## Security Considerations
+
+- Store GitHub tokens securely and rotate them regularly
+- Use least-privilege access for GitHub tokens (only `repo` scope if needed)
+- Monitor logs for failed authentication attempts
+- Validate SSH key sources before adding them to configuration
+- Consider using private repositories for sensitive key storage
+
+## FAQ
+
+**Q: Can I use this script with GitLab or other Git providers?**
+A: Currently, the script supports GitHub's API. For other providers, use the `raw` method with direct URLs to key files.
+
+**Q: What happens if a user doesn't exist on the system?**
+A: The script will log a warning and skip that user, continuing with the next user in the configuration.
+
+**Q: How often should I run the synchronization?**
+A: This depends on your security requirements. Common intervals are 15 minutes for development environments and 1 hour for production systems.
