diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..6e120d0 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +# EditorConfig helps maintain consistent coding styles +root = true + +[*] +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 + +[*.md] +# Keep Markdown tidy; code blocks remain untouched by trim rule exceptions +trim_trailing_whitespace = true diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..21e3a61 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# Require review from maintainers for key areas +* @iplaycomputer + +# Optional: expand with more granular ownership as project grows +# /kb/ @iplaycomputer +# /labs/ @iplaycomputer +# /tickets/ @iplaycomputer +# /scenarios/ @iplaycomputer diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 62165da..5d10491 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,24 +1,52 @@ -## Summary +## Summary + Briefly describe what this PR adds or changes. ## Linked Artifacts (relative paths) + - Ticket(s): /tickets/[file].md - KB: /kb/[file].md - Lab: /labs/[file].md (optional) - Scenario: /scenarios/[file].md (optional) ## Checklists + - Content - [ ] Uses the correct template (copied from 000.*-template.md) - [ ] Clear, reproducible steps and plain language - [ ] Relative links resolve inside the repo + - [ ] Avoid duplication across modules (KB = productized steps; Lab = full commands + Verification; Scenario = flow/success, links only) + - [ ] Deep link to sections where applicable (KB → #resolution-steps, Lab → #verification) - Metadata - [ ] Owner set; Last Reviewed and Next Review Due (KB/Lab) - [ ] Escalation Path filled (Ticket) - [ ] Metrics block added if useful (see docs/METRICS.md) - Quality - [ ] Verification steps included (expected outputs / pass-fail) - - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria + - [ ] Anchors exist and resolve (KB “Resolution Steps”, Lab “Verification”) + - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria + +### Labs (if included) + +- [ ] Dedicated “Verification” section with expected outputs +- [ ] Images pinned if using containers; HTTP services include a simple healthcheck when applicable +- [ ] Assets stored under `labs//assets/` + +### KBs (if included) + +- [ ] Brief (1–2 lines) verification; link to related Lab for full commands + +### Scenarios (if included) + +- [ ] Uses deep links to KB “Resolution Steps” and Lab “Verification” (no step duplication) ## Notes + Add screenshots, logs, or context as needed. + +## How to Verify (for reviewers) + +- Click Related KB/Lab links and confirm they jump to the correct anchors. +- If a Lab changed, run the Verification steps and confirm expected outputs. +- Check that no personal IPs or credentials are included; use `` placeholders. + diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a1a3fa1..1239640 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,16 +1,18 @@ -# Copilot Instructions for DeskForge-Simulator +# Copilot Instructions for DeskForge-Simulator This repo simulates real helpdesk workflows using Markdown contributions. Agents should prioritize clarity, reproducibility, and alignment with the troubleshooting standards in `CONTRIBUTING.md`. ## Big Picture + - Four modules map to real workflows: - Tickets (`/tickets/`): user-reported issues - Knowledge Base (`/kb/`): solution docs derived from tickets - Labs (`/labs/`): hands-on practice exercises - - Scenarios (`/scenarios/`): end-to-end flows linking ticket → KB → lab + - Scenarios (`/scenarios/`): end-to-end flows linking ticket → KB → lab - Use templates in each folder (`000.*-template.md`). ## Key Files + - `CONTRIBUTING.md`: Primary standards, workflows, and references (CompTIA A+ model, escalation, templates). - `docs/lamp-osticket-setup.md`: Optional local osTicket setup to test tickets/KBs. - `docs/ROLES.md`: Lightweight tiers, escalation cues, and ownership metadata. @@ -18,7 +20,8 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - `README.md`: Project overview and contribution on-ramp. ## Authoring Patterns -- Follow CompTIA A+ 6-step model: Identify → Theory → Test → Plan/Implement → Verify → Document. + +- Follow CompTIA A+ 6-step model: Identify → Theory → Test → Plan/Implement → Verify → Document. - Keep language plain and steps reproducible. Include environment details (OS/version), verification, and escalation path. - Link artifacts with relative paths (e.g., `/tickets/printer-failure.md` in KB/Lab/Scenario). - Use checklists for Tier 1/2/3 completion; mark what you actually did. @@ -28,22 +31,27 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - Scenarios should express flow and success criteria, linking to KB "Resolution Steps" and Lab "Verification" sections (use deep links like `/kb/foo.md#resolution-steps` and `/labs/bar.md#verification`). ## Workflows + - Propose in Discussions: draft tickets/KBs/labs in appropriate categories. - Land changes via PRs adding Markdown under `/tickets`, `/kb`, `/labs`, `/scenarios`. - Labs should be verifiable on a Linux VM or container; osTicket is optional. ## Examples from Repo + - Templates: `kb/000.kb-template.md`, `labs/000.lab-template.md`, `tickets/000.ticket-template.md`, `scenarios/000.scenario-template.md`. - osTicket URLs referenced use `http:///osticket/` and `.../scp` for staff; replace `` locally and do not share it publicly. ## Conventions + - Filenames: use kebab-case, concise, and descriptive (e.g., `printer-spooler-restart.md`). - Metadata blocks: include Category, Environment, Owner, Reviewed dates when applicable. - References: cite external docs in a final section; prefer vendor support links. ## What NOT to do -- Don’t invent infrastructure or public endpoints; this repo is markdown-only. -- Don’t add personal IPs or credentials. + +- Don’t invent infrastructure or public endpoints; this repo is markdown-only. +- Don’t add personal IPs or credentials. --- Clarifications welcome: if any folder structure or template changes, update this file to match. + diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 0000000..32cbb04 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,19 @@ +name: markdownlint + +on: + pull_request: + push: + branches: [ main ] + +jobs: + lint: + name: lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v16 + with: + globs: | + **/*.md diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..a3fbcab --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,14 @@ +{ + // Inherit rules from .markdownlint.jsonc and set default globs + "config": { + // Extend the base markdownlint rules from repo root + "extends": ".markdownlint.jsonc" + }, + "globs": ["**/*.md"], + "ignores": [ + "**/node_modules/**", + ".git/**", + // Loosen restrictions only for repo meta/docs under .github (e.g., PR template) + ".github/**/*.md" + ] +} diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index d77d23e..8ca733c 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -1 +1,16 @@ -{\n "MD029": {\n "style": "ordered"\n }\n} \ No newline at end of file +{ + // Allow long lines in code blocks and tables + "MD013": false, + // Allow consecutive headings in templates/checklists + "MD025": false, + // Allow inline HTML when needed (README badges) + "MD033": false, + // Allow trailing spaces (soft line breaks) to preserve authoring style + "MD009": false, + // Allow non-heading first lines (some files are not articles) + "MD041": false, + // Temporarily disable strict fragment validation to reduce false positives on deep-links + "MD051": false, + // Prefer incrementing ordered lists (1/2/3) to avoid renumbering churn + "MD029": { "style": "ordered" } +} \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..c44d7a7 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "DavidAnson.vscode-markdownlint", + "EditorConfig.EditorConfig" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..cd9b925 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,9 @@ +{ + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + "files.eol": "\n", + "[markdown]": { + "editor.formatOnSave": true, + "markdownlint.fix.onSave": true + } +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43c8ab2..42a25e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,16 +7,19 @@ This guide provides **guidelines** (not strict rules) for contributing to DeskFo **Note**: Setting up a local osTicket instance is **optional** but recommended to learn how ticketing systems work in real-world IT jobs (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md)). You can contribute by writing Markdown files directly or sharing real-world tech support issues, KB drafts, or labs via GitHub Discussions. ## What You’ll Need + - A GitHub account to submit contributions (sign up at [github.com](https://github.com)). - A text editor for writing Markdown files in `/tickets/`, `/kb/`, and `/labs/` (we provide templates!). - + - **Optional**: A local osTicket setup to test tickets and KB articles (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) for installing osTicket v1.18.1 in a VirtualBox VM with Ubuntu 24.04 Desktop; client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - + - For labs: A lightweight Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container) to test troubleshooting steps, which can be the same VM as osTicket or a separate one. - Curiosity and a willingness to learn—no IT expertise required! ## Contribution Workflow + To keep contributions organized, use the following channels: + - **GitHub Discussions ([https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions))**: - **Tickets**: Share real-world tech support issues, fictional scenarios, or training exercises in the `Tickets` category. Convert these into Markdown files for `/tickets/`. - **Knowledge Base**: Share KB drafts or solution ideas in the `Knowledge Base` category. Convert these into Markdown files for `/kb/`. @@ -31,7 +34,9 @@ To keep contributions organized, use the following channels: This keeps Discussions for collaboration and learning, Issues for project fixes, and the repo clean with structured contributions. ## What This Guide Does + This guide will help you: + - Write tickets, KB articles, and labs in Markdown for the DeskForge-Simulator repo. - Share tickets, KB drafts, or labs via GitHub Discussions or test them in a local osTicket instance. - Test labs in a Linux VM or sandbox environment without needing osTicket. @@ -39,6 +44,7 @@ This guide will help you: - Use community resources to ask questions and get help. ## Table of Contents + 1. [Code of Conduct](#code-of-conduct) 2. [I Have a Question!](#i-have-a-question) 3. [Troubleshooting Philosophy](#troubleshooting-philosophy) @@ -52,21 +58,26 @@ This guide will help you: 7. [Roadmap Note](#roadmap-note) ## Code of Conduct + We want DeskForge-Simulator to be a welcoming, respectful, and professional community. By contributing, you agree to follow the **DeskForge Code of Conduct**, which emphasizes: + - Respectful communication. - Collaboration and inclusivity. - Professional behavior. If you encounter unacceptable behavior, report it via GitHub issues or by contacting the maintainers directly. -## I Have a Question! +## I Have a Question + Don’t file a GitHub issue for general questions—you’ll get faster answers in the `Scenarios & General` category of [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). Other resources: + - **[r/helpdesk on Reddit](https://reddit.com/r/helpdesk)**: Share and learn from real-world troubleshooting stories. - **[Spiceworks Community](https://community.spiceworks.com/)**: Connect with IT pros for tips and best practices. - **[Microsoft TechNet Forums](https://docs.microsoft.com/en-us/answers/products/)**: Get help with OS, networking, or enterprise issues. - **[Stack Overflow](https://stackoverflow.com/)**: Ask programming or script-related questions. ## Troubleshooting Philosophy + DeskForge-Simulator follows industry-standard helpdesk practices to ensure contributions are clear, professional, and useful. When writing tickets, KB articles, or labs, align with these principles: | Principle | Description | Reference | @@ -80,12 +91,14 @@ DeskForge-Simulator follows industry-standard helpdesk practices to ensure contr | **Knowledge management** | Turn solved tickets into KB articles or labs to prevent repeat issues. | Blokdyk, 2020; Art of Service, 2021 | ### References + - *Help Desk: A Complete Guide – 2020 Edition* (Gerardus Blokdyk, ISBN 978-1867309383) - *CompTIA A+ Complete Practice Tests, 4th Edition* (Audrey O’Shea, 2025, Print ISBN 978-1394330331; eText ISBN 978-1394330348) - *IT Service Desk: A Complete Guide, 2021 Edition* (The Art of Service, ISBN 978-1867437223) - [Atlassian: What Is ITIL? Best Practices for ITSM](https://www.atlassian.com/itsm) ## What Should I Know Before I Get Started? + DeskForge-Simulator mimics a real IT helpdesk, allowing you to contribute tickets, KB articles, and labs in Markdown. Testing tickets and KB articles in a local osTicket instance is optional but recommended to understand how ticketing systems work in real-world IT jobs. Here’s what you need to know: - **GitHub Basics**: If you’re new to GitHub, check out [Contributing to a Project on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) to learn about forking, branching, committing, and pull requests. @@ -98,6 +111,7 @@ DeskForge-Simulator mimics a real IT helpdesk, allowing you to contribute ticket - **Learning by Doing**: The best way to learn is to write tickets, test solutions, and get feedback. Start small and improve with each contribution! ## DeskForge Modules + DeskForge-Simulator is built around four modules that mirror real helpdesk workflows: | Module | Path | Purpose | @@ -110,13 +124,16 @@ DeskForge-Simulator is built around four modules that mirror real helpdesk workf Folder guides for quick navigation: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Labs](labs/README.md) · [Scenarios](scenarios/README.md) Roles (to avoid duplication): + - Labs are the canonical source of exact commands and environment setup. Always put full commands in Labs and include a small "Verification" section. - KBs contain productized resolution steps with 1–2 verification lines (max). Link to the Lab for full commands. - Scenarios define the flow and success criteria; they should link to specific sections in the KB (Resolution Steps) and Lab (Verification) rather than restating steps. ### How Modules Work Together + Contributions flow like this: **Ticket → Resolution → KB → Lab → Scenario**. -- **Tickets**: Share a ticket in GitHub Discussions (`Tickets` category) or write a Markdown file in `/tickets/` describing a problem (e.g., “Printer not working”). + +- **Tickets**: Share a ticket in GitHub Discussions (`Tickets` category) or write a Markdown file in `/tickets/` describing a problem (e.g., “Printer not working”). Optionally, test it in your local osTicket instance’s client portal (`http:///osticket/`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. @@ -126,9 +143,11 @@ Optionally, test it in your local osTicket instance’s client portal (`http://< - **Scenarios**: Combine tickets, KB articles, and labs into a complete workflow in `/scenarios/`. ## How Can I Contribute? + You can contribute by writing tickets, KB articles, or labs in Markdown, sharing them via GitHub Discussions, or testing tickets/KB articles in a local osTicket instance. Below are the details for each. ### Submitting Tickets + Tickets represent user-reported problems (real, training, or fictional). You can share them in GitHub Discussions, write them directly in Markdown for `/tickets/`, or test them in a local osTicket instance for realism. - **Option 1: GitHub Discussions**: Post a ticket in the `Tickets` category at [https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) with details of a real-world tech support issue (e.g., “My laptop won’t connect to Wi-Fi”). Convert the details into the Markdown template and save in `/tickets/`. @@ -147,12 +166,14 @@ Template: copy `/tickets/000.ticket-template.md` to `/tickets/.md` a Folder guide: see [tickets/README.md](tickets/README.md) **Tips**: + - Use GitHub Discussions (`Tickets` category) to share real-world tech support issues you’ve encountered. - Test tickets in your local osTicket instance (if set up) to simulate a real helpdesk. - Follow the CompTIA A+ six-step model (see “Troubleshooting Philosophy”). - Submit your ticket as a pull request in the `/tickets/` folder. ### Creating KB Articles + KB articles document solutions from solved tickets. Share them in GitHub Discussions (`Knowledge Base` category) or write them in Markdown for `/kb/`. Optionally, test them in your local osTicket instance’s admin/staff panel. Template: copy `/kb/000.kb-template.md` to `/kb/.md` and complete the fields. @@ -160,6 +181,7 @@ Template: copy `/kb/000.kb-template.md` to `/kb/.md` and complete th Folder guide: see [kb/README.md](kb/README.md) **Tips**: + - Share KB drafts in GitHub Discussions (`Knowledge Base` category) for feedback. - Use your local osTicket admin/staff panel (e.g., `http:///osticket/scp`) to draft KB articles, if set up. Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - Ensure steps are clear, reproducible, and tested. @@ -167,12 +189,14 @@ Folder guide: see [kb/README.md](kb/README.md) - Submit as a pull request in the `/kb/` folder. ### Creating Labs + Labs are standalone troubleshooting exercises in `/labs/`, tested in a Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container), not requiring osTicket. Share them in GitHub Discussions (`Labs` category) or write them in Markdown. **Testing Labs**: Use a local Linux VM or sandbox to simulate issues (e.g., stop a service with `sudo systemctl stop `). Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up a VM, or use a Docker container for simplicity. Template: copy `/labs/000.lab-template.md` to `/labs/.md` and follow the structure. **Tips**: + - Share lab ideas in GitHub Discussions (`Labs` category) for feedback. - Test labs in a Linux VM or Docker container, not osTicket. - Include a dedicated "Verification" section with specific commands/outputs (Labs are the source of truth for commands). @@ -181,13 +205,16 @@ Template: copy `/labs/000.lab-template.md` to `/labs/.md` and follow Folder guide: see [labs/README.md](labs/README.md) ### Creating Scenarios + Scenarios stitch together one or more tickets, a KB article, and an optional lab into an end-to-end learning flow. Use them to show how a real incident moves from report → resolution → documentation → practice. -**When to create a scenario** +#### When to create a scenario + - You have at least one ticket and a corresponding KB article; a lab is recommended but optional. - You want a guided narrative that learners can follow front-to-back. -**How to author** +#### How to author + - Start from the template at `/scenarios/000.scenario-template.md`. - Create a new file under `/scenarios/`, e.g. `/scenarios/printer-outage-end-to-end.md`. - Fill in: @@ -196,17 +223,41 @@ Scenarios stitch together one or more tickets, a KB article, and an optional lab - Related Lab: link if you have one, e.g. `/labs/restart-print-spooler.md`. - Overview, Flow (Ticket → KB → Lab), Success Criteria. -**Submission** +#### Submission + - Open a PR with the new scenario file in `/scenarios/`. - In your PR description, briefly summarize the learning goals and link the related ticket/KB/lab. Folder guide: see [scenarios/README.md](scenarios/README.md) -**Tips** +### Tips + - Keep links relative so they work in GitHub and downstream clones. - Be explicit about pass/fail checks so learners can self-verify. - Prefer deep links to existing sections instead of rewriting steps, e.g.: `/kb/...#resolution-steps` and `/labs/...#verification`. +## Local Lint (Optional) + +Before you commit, you can run the Markdown linter locally to catch spacing/format issues early: + +- Windows PowerShell: + +```powershell +npx -y markdownlint-cli2 +``` + +Optional Git hook (runs locally, does not affect CI): + +1. Create a file at `.git/hooks/pre-commit` with the following and make sure it’s executable in your Git environment: + +```bash +#!/usr/bin/env bash +set -euo pipefail +npx -y markdownlint-cli2 +``` + +1. Save. The hook will block commits that fail linting. You can always run the linter manually if you prefer. ## Roadmap Note + Public ticket submissions are not yet enabled. If a central osTicket instance is launched, it will likely allow public users to submit tickets via the client portal only, with the admin/staff panel restricted to maintainers. diff --git a/README.md b/README.md index cfbdc6d..a58e337 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

Last commit @@ -16,101 +16,104 @@

-# DeskForge-Simulator +# DeskForge-Simulator -**DeskForge-Simulator** is an open-source project that recreates the experience of working on a real IT helpdesk — but in a safe, collaborative learning environment. +**DeskForge-Simulator** is an open-source project that recreates the experience of working on a real IT helpdesk — but in a safe, collaborative learning environment. -It’s designed for **beginners exploring IT support** as well as **experienced contributors who want to practice professional workflows**. By contributing, you’ll gain hands-on experience with the same skills used in real service desk roles: +It’s designed for **beginners exploring IT support** as well as **experienced contributors who want to practice professional workflows**. By contributing, you’ll gain hands-on experience with the same skills used in real service desk roles: -- 🎫 **Submitting and triaging tickets** — learn to capture user issues, categorize problems, and document troubleshooting steps. -- 📚 **Writing and refining knowledge base (KB) articles** — transform solved tickets into reusable documentation that helps prevent repeat issues. -- 🧪 **Building troubleshooting labs** — create interactive exercises that let others practice resolving common IT incidents. -- 🌐 **Practicing escalation paths and IT workflows** — follow industry-standard processes like the CompTIA A+ six-step troubleshooting model and learn when to escalate issues. +- 🎫 **Submitting and triaging tickets** — learn to capture user issues, categorize problems, and document troubleshooting steps. +- 📚 **Writing and refining knowledge base (KB) articles** — transform solved tickets into reusable documentation that helps prevent repeat issues. +- 🧪 **Building troubleshooting labs** — create interactive exercises that let others practice resolving common IT incidents. +- 🌐 **Practicing escalation paths and IT workflows** — follow industry-standard processes like the CompTIA A+ six-step troubleshooting model and learn when to escalate issues. -💡 Think of it as a **helpdesk-in-a-repo**: instead of just reading about IT support, you actively practice it — using tickets, KBs, and labs that mirror real-world scenarios. +💡 Think of it as a **helpdesk-in-a-repo**: instead of just reading about IT support, you actively practice it — using tickets, KBs, and labs that mirror real-world scenarios. -Whether you’re completely new to IT, sharpening your troubleshooting skills, or mentoring others, DeskForge-Simulator gives you a structured, low-stakes environment to learn, contribute, and grow. +Whether you’re completely new to IT, sharpening your troubleshooting skills, or mentoring others, DeskForge-Simulator gives you a structured, low-stakes environment to learn, contribute, and grow. -⭐ If you find **DeskForge-Simulator** useful, please give this project a **star** on GitHub — it helps the community grow and keeps the project alive! +⭐ If you find **DeskForge-Simulator** useful, please give this project a **star** on GitHub — it helps the community grow and keeps the project alive! -## 🔰 Quick Start: Contribute in 5 Minutes +## 🔰 Quick Start: Contribute in 5 Minutes + +1. **Fork** this repository and clone it to your machine. -1. **Fork** this repository and clone it to your machine. ```bash git clone https://github.com//DeskForge-Simulator.git cd DeskForge-Simulator ``` -2. **Create a ticket** using the template in `/tickets/`. - Save it as a new Markdown file, e.g.: - ``` +2. **Create a ticket** using the template in `/tickets/`. + Save it as a new Markdown file, e.g.: + + ```text /tickets/printer-issue.md ``` -3. **Commit and push** your changes. +3. **Commit and push** your changes. + ```bash git add tickets/printer-issue.md git commit -m "Add sample printer ticket" git push origin main ``` -4. **Open a Pull Request** to share your contribution! 🎉 -👉 That’s it — you’ve added your first simulated helpdesk ticket. -Check out `CONTRIBUTING.md` if you want to go deeper (KB articles, labs, scenarios). +4. **Open a Pull Request** to share your contribution! 🎉 -### **Note on Real Troubleshooting**: +👉 That’s it — you’ve added your first simulated helpdesk ticket. +Check out `CONTRIBUTING.md` if you want to go deeper (KB articles, labs, scenarios). -You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. -*This community will treat them as learning scenarios.* +### **Note on Real Troubleshooting** -However: -- This project is for **education only** — responses are not official IT support. This means no guarantees of fixes and we are not responsible for people's devices. -- Please **do not share sensitive information** (personal IPs, passwords, or private configs). -- Use advice at your own discretion. +You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. +*This community will treat them as learning scenarios.* -Think of it as a safe space to learn troubleshooting together, not a replacement for your workplace or vendor IT support. +However: -## 🚀 Documentation & osTicket +- This project is for **education only** — responses are not official IT support. This means no guarantees of fixes and we are not responsible for people's devices. +- Please **do not share sensitive information** (personal IPs, passwords, or private configs). +- Use advice at your own discretion. -- Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up an optional **local osTicket instance** on Ubuntu 24.04 (for realism). -- Or start contributing right away using **GitHub Discussions** and Markdown files in `/tickets/`, `/kb/`, and `/labs/`. -- See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for templates and workflow details. - - For end-to-end flows, see the `/scenarios/` folder and use the template at `/scenarios/000.scenario-template.md`. - - Browse available labs in the [Labs Catalog](labs/README.md). - - Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) +Think of it as a safe space to learn troubleshooting together, not a replacement for your workplace or vendor IT support. -## ❤️ Community & Contributions +## 🚀 Documentation & osTicket -DeskForge-Simulator is **community-driven**. We welcome: +- Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up an optional **local osTicket instance** on Ubuntu 24.04 (for realism). +- Or start contributing right away using **GitHub Discussions** and Markdown files in `/tickets/`, `/kb/`, and `/labs/`. +- See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for templates and workflow details. +- For end-to-end flows, see the `/scenarios/` folder and use the template at `/scenarios/000.scenario-template.md`. +- Browse available labs in the [Labs Catalog](labs/README.md). +- Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) -- 🐞 Bug reports and fixes -- ✨ New tickets, KB articles, and labs -- 📖 Documentation improvements -- 💡 Ideas for scenarios or learning modules +## ❤️ Community & Contributions -Check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide and join the conversation in [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). +DeskForge-Simulator is **community-driven**. We welcome: +- 🐞 Bug reports and fixes +- ✨ New tickets, KB articles, and labs +- 📖 Documentation improvements +- 💡 Ideas for scenarios or learning modules -## 📫 Questions & Support +Check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide and join the conversation in [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). -Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) to: -- Post tickets (simulated issues) -- Draft KB articles -- Share lab walkthroughs -- Ask general IT or project-related questions +## 📫 Questions & Support +Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) to: -## 🤝 Found a Bug? Missing a Feature? +- Post tickets (simulated issues) +- Draft KB articles +- Share lab walkthroughs +- Ask general IT or project-related questions -- File issues here: [DeskForge-Simulator Issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues) -- Open a pull request if you’ve already got a fix or draft -- See [CONTRIBUTING.md](CONTRIBUTING.md) for coding/writing standards +## 🤝 Found a Bug? Missing a Feature? +- File issues here: [DeskForge-Simulator Issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues) +- Open a pull request if you’ve already got a fix or draft +- See [CONTRIBUTING.md](CONTRIBUTING.md) for coding/writing standards -## ✅ Requirements +## ✅ Requirements -- GitHub account (to contribute) -- Text editor (for Markdown tickets, KBs, labs) -- Optional: - - Ubuntu 24.04 VM (via VirtualBox or Docker) - - osTicket v1.18.1 (local deployment) for testing tickets & KB workflows +- GitHub account (to contribute) +- Text editor (for Markdown tickets, KBs, labs) +- Optional: + - Ubuntu 24.04 VM (via VirtualBox or Docker) + - osTicket v1.18.1 (local deployment) for testing tickets & KB workflows diff --git a/docs/METRICS.md b/docs/METRICS.md index ef9d78c..659cf3a 100644 --- a/docs/METRICS.md +++ b/docs/METRICS.md @@ -1,8 +1,9 @@ -# Helpdesk Metrics (Lightweight) +# Helpdesk Metrics (Lightweight) Use simple, repeatable fields so contributors can track quality without heavy tooling. Add these to Tickets and KBs when helpful. ## Ticket Metrics + - Reported: YYYY-MM-DD - Resolved: YYYY-MM-DD (or TBD) - MTTR (mins): (Resolved - Reported) @@ -10,35 +11,40 @@ Use simple, repeatable fields so contributors can track quality without heavy to - Affected Users: 1 | few | many Example block for tickets: + ```markdown -**Metrics:** -- Reported: 2025-09-26 -- Resolved: 2025-09-26 -- MTTR (mins): 12 -- Recurrence: No -- Affected Users: 1 +## Metrics: +- Reported: 2025-09-26 +- Resolved: 2025-09-26 +- MTTR (mins): 12 +- Recurrence: No +- Affected Users: 1 ``` ## KB Metrics + - Verification Date: YYYY-MM-DD - Verified By: @handle - Validated Against: OS/App version(s) - Recurrence Notes: When to apply or retire Example block for KBs: + ```markdown -**Metrics / Verification:** -- Verification Date: 2025-09-26 -- Verified By: @your-handle -- Validated Against: Windows 11 23H2, HP LaserJet Pro -- Recurrence Notes: Common after major Windows updates +## Metrics / Verification: +- Verification Date: 2025-09-26 +- Verified By: @your-handle +- Validated Against: Windows 11 23H2, HP LaserJet Pro +- Recurrence Notes: Common after major Windows updates ``` ## When To Track + - New incident patterns emerge (multiple similar tickets) - Longer-than-expected MTTR - Playbooks or KBs need periodic review windows ## Keep It Practical -- No dashboards required—just fill fields in Markdown. + +- No dashboards required—just fill fields in Markdown. - Prefer consistency over precision. diff --git a/docs/ROLES.md b/docs/ROLES.md index a53b370..ebdde50 100644 --- a/docs/ROLES.md +++ b/docs/ROLES.md @@ -1,8 +1,9 @@ -# Roles and Escalation +# Roles and Escalation Keep contributions simple and consistent. Use these lightweight roles and tiers to signal ownership and when to escalate. ## Project Roles + - Contributor: Anyone adding or improving tickets, KBs, labs, or scenarios. - Reviewer: Anyone giving peer feedback in Discussions or PRs. - Maintainer: Approves PRs, curates templates, and organizes Discussions categories. @@ -10,38 +11,42 @@ Keep contributions simple and consistent. Use these lightweight roles and tiers Tip: In KBs and Labs, use metadata fields like Owner, Last Reviewed, Next Review Due to show stewardship. ## Support Tiers (Scope and Actions) + - Tier 1 (Frontline) - Scope: Single-user issues, basic checks, standard fixes. - Typical actions: Verify problem, collect environment, reproduce, apply known fixes. - - Timebox: 10–20 minutes before escalating. + - Timebox: 10–20 minutes before escalating. - Tier 2 (Specialist) - Scope: Drivers, services, complex app configs, small network issues. - Typical actions: Logs review, driver/config changes, targeted scripts. -- Tier 3 (Deep) +- Tier 3 (Deep) - Scope: OS-level faults, hardware failures, infrastructure dependencies. - Typical actions: Advanced diagnostics, vendor docs, replacement decisions. ## Escalation Signals + - Safety or data risk detected. - Permissions or tooling required beyond your access. - Timebox exceeded with no progress. - Systemic/recurring incident (affects multiple users). ## How To Mark Tiers in Tickets + Include this block (edit as you go): ```markdown -**Escalation Path:** -- [x] Tier 1 complete (basic troubleshooting done) -- [ ] Escalated to Tier 2 (e.g., driver or service-level change) -- [ ] Escalated to Tier 3 (e.g., OS/hardware/vendor) +## Escalation Path: +- [x] Tier 1 complete (basic troubleshooting done) +- [ ] Escalated to Tier 2 (e.g., driver or service-level change) +- [ ] Escalated to Tier 3 (e.g., OS/hardware/vendor) ``` ## KB/Lab Ownership Example + Add to the metadata block: ```markdown -**Owner:** @your-handle -**Last Reviewed:** 2025-09-26 -**Next Review Due:** 2026-03-26 +**Owner:** @your-handle +**Last Reviewed:** 2025-09-26 +**Next Review Due:** 2026-03-26 ``` diff --git a/docs/lamp-osticket-setup.md b/docs/lamp-osticket-setup.md index 05cbfd5..e255e47 100644 --- a/docs/lamp-osticket-setup.md +++ b/docs/lamp-osticket-setup.md @@ -5,19 +5,24 @@ This guide explains how to set up **osTicket v1.18.1**, a free helpdesk ticketin **Warning**: This setup is for testing or development. Do **not** use it in production without adding HTTPS (SSL), a firewall, and other security measures (see “What to Do Next” section). ## What You’ll Need + - A computer with **Oracle VirtualBox** installed (download from [virtualbox.org](https://www.virtualbox.org)). - The **Ubuntu 24.04 Desktop ISO** file (get it from [ubuntu.com](https://ubuntu.com)). - A basic understanding of how to use a computer terminal (we’ll explain commands clearly!). - About 1–2 hours to follow along. ## Using Placeholders + This guide uses placeholders for sensitive information: + - Replace `YOUR_DB_PASSWORD` with a strong password (e.g., generate one with `openssl rand -base64 12` in the terminal). - Replace `` with your VM’s IP address (find it by running `ip addr show` in the terminal and looking for the IP under `inet`, usually starting with `192.168.`). - Replace `osticket-server.localdomain` with your VM’s hostname or IP if needed. ## What This Guide Does + This guide will help you: + - Create a virtual machine (VM) in VirtualBox. - Install Ubuntu 24.04 Desktop on the VM. - Set up a web server, database, and PHP (the “LAMP stack”). @@ -25,6 +30,7 @@ This guide will help you: - Check that everything works. ## Table of Contents + 1. [Set Up Your Virtual Machine](#set-up-your-virtual-machine) 2. [Install Ubuntu](#install-ubuntu) 3. [Set Up the Web Server and Database](#set-up-the-web-server-and-database) @@ -38,6 +44,7 @@ This guide will help you: 11. [What to Do Next](#what-to-do-next) ## Set Up Your Virtual Machine + 1. Open VirtualBox and click **New** to create a virtual machine. 2. Name it (e.g., “osTicket-VM”). 3. Choose **Linux** as the type and **Ubuntu (64-bit)** as the version. @@ -50,87 +57,118 @@ This guide will help you: 5. Select the Ubuntu 24.04 Desktop ISO file when prompted and start the VM. ## Install Ubuntu + 1. The VM will boot from the Ubuntu ISO. Follow the on-screen steps to install Ubuntu 24.04 Desktop. 2. Choose a hostname (e.g., `osticket-server`) and a domain (e.g., `localdomain`) during setup. 3. Complete the installation and log in to the Ubuntu desktop. ## Set Up the Web Server and Database + 1. Open the **Terminal** (search for it in Ubuntu’s menu or press `Ctrl + Alt + T`). 2. Update your system and install Apache (web server), MySQL (database), PHP, and required tools: + ```bash sudo apt update sudo apt install -y apache2 mysql-server php libapache2-mod-php php-mysql php-imap php-intl php-gd php-xml php-cli php-mbstring unzip curl sudo systemctl enable --now apache2 mysql ``` - - **What this does**: Updates your system, installs the web server, database, and PHP, then starts them. -3. Check that Apache and MySQL are running: + +- **What this does**: Updates your system, installs the web server, database, and PHP, then starts them. + +1. Check that Apache and MySQL are running: + ```bash systemctl status apache2 systemctl status mysql ``` - - **What to look for**: You should see “active (running)” for both. Press `Ctrl + C` to exit each status check. -4. Confirm PHP is installed (version should be 7.2 or higher): + +- **What to look for**: You should see “active (running)” for both. Press `Ctrl + C` to exit each status check. + +1. Confirm PHP is installed (version should be 7.2 or higher): + ```bash php -v ``` ## Set Up the Database + 1. **Secure MySQL**: - Run this command to make MySQL safer: + ```bash sudo mysql_secure_installation ``` - - Follow the prompts: - - Keep the default `auth_socket` for local root access (just press Enter). - - Remove anonymous users (say “Yes”). - - Disallow remote root login (say “Yes”). - - Drop the test database (say “Yes”). - - Reload privileges (say “Yes”). -2. **Create a database and user for osTicket**: + +- Follow the prompts: + - Keep the default `auth_socket` for local root access (just press Enter). + - Remove anonymous users (say “Yes”). + - Disallow remote root login (say “Yes”). + - Drop the test database (say “Yes”). + - Reload privileges (say “Yes”). + +1. **Create a database and user for osTicket**: - Log in to MySQL: + ```bash sudo mysql ``` - - Run these commands (replace `YOUR_DB_PASSWORD` with a strong password, e.g., generate one with `openssl rand -base64 12`): + +- Run these commands (replace `YOUR_DB_PASSWORD` with a strong password, e.g., generate one with `openssl rand -base64 12`): + ```sql CREATE DATABASE IF NOT EXISTS osticket; CREATE USER 'osticketuser'@'localhost' IDENTIFIED BY 'YOUR_DB_PASSWORD'; GRANT ALL PRIVILEGES ON osticket.* TO 'osticketuser'@'localhost'; FLUSH PRIVILEGES; ``` - - Exit MySQL: + +- Exit MySQL: + ```sql EXIT; ``` -3. Verify MySQL version and authentication plugin: + +1. Verify MySQL version and authentication plugin: + ```sql SELECT VERSION(); ``` - - **What to look for**: You should see MySQL 8.x and `caching_sha2_password` as the default plugin. + +- **What to look for**: You should see MySQL 8.x and `caching_sha2_password` as the default plugin. ## Install osTicket Files + 1. Download osTicket v1.18.1 from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). Save the ZIP file to your VM (e.g., in `/tmp`). 2. If the ZIP file doesn’t work (e.g., corrupt), download it again. 3. Extract the ZIP and copy the `upload/` folder contents to the web server’s directory: + ```bash sudo cp -r /tmp/upload/* /var/www/html/osticket/ ``` - - **Note**: If you unzipped the file and the `upload` folder is intact (not extracted), use this instead: + +- **Note**: If you unzipped the file and the `upload` folder is intact (not extracted), use this instead: + ```bash sudo mv /tmp/upload /var/www/html/osticket ``` -4. Set the correct ownership so the web server can access the files: + +1. Set the correct ownership so the web server can access the files: + ```bash sudo chown -R www-data:www-data /var/www/html/osticket ``` ## Configure the Web Server + 1. Create a configuration file for osTicket at `/etc/apache2/sites-available/osticket.conf`: - Use a text editor like `nano`: + ```bash sudo nano /etc/apache2/sites-available/osticket.conf ``` - - Add this content (replace `osticket-server.localdomain` with your VM’s hostname or IP): + +- Add this content (replace `osticket-server.localdomain` with your VM’s hostname or IP): + ```apache ServerName osticket-server.localdomain @@ -144,21 +182,28 @@ sudo nano /etc/apache2/sites-available/osticket.conf CustomLog ${APACHE_LOG_DIR}/osticket_access.log combined ``` - - Save and exit (`Ctrl + O`, Enter, `Ctrl + X`). -2. Enable the site and URL rewriting: + +- Save and exit (`Ctrl + O`, Enter, `Ctrl + X`). + +1. Enable the site and URL rewriting: + ```bash sudo a2ensite osticket.conf sudo a2enmod rewrite sudo systemctl daemon-reload sudo systemctl reload apache2 ``` -3. Check that the configuration is correct: + +1. Check that the configuration is correct: + ```bash sudo apache2ctl configtest ``` - - **What to look for**: It should say `Syntax OK`. If not, check for typos in `osticket.conf`. + +- **What to look for**: It should say `Syntax OK`. If not, check for typos in `osticket.conf`. ## Run the osTicket Web Installer + 1. Open a web browser on the VM (or your host computer) and go to `http:///osticket/setup/` (replace `` with your VM’s IP address, found via `ip addr show` in the terminal). 2. You should see the osTicket setup page. If not, check that Apache is running (`systemctl status apache2`). 3. Fill in the database details: @@ -168,82 +213,110 @@ sudo apache2ctl configtest - **Password**: (the secure password you set earlier) 4. Follow the setup wizard to complete installation. 5. Note: The installer may say the APCu extension is optional. You can install it later if needed: + ```bash sudo apt install php-apcu ``` ## Secure Your Setup + 1. During installation, osTicket copies a sample config to `ost-config.php`. 2. Remove the setup folder to prevent unauthorized access: + ```bash sudo rm -rf /var/www/html/osticket/setup/ ``` -3. Lock down the config file so only the web server can read it: + +1. Lock down the config file so only the web server can read it: + ```bash sudo chmod 0444 /var/www/html/osticket/include/ost-config.php sudo chown root:www-data /var/www/html/osticket/include/ost-config.php ``` -4. Double-check file permissions: + +1. Double-check file permissions: + ```bash ls -l /var/www/html/osticket/include/ost-config.php ``` - - It should show `-r--r--r-- root www-data`. + +- It should show `-r--r--r-- root www-data`. ## Check That It Works + 1. Open `http:///osticket/` in your browser. You should see the osTicket client portal. 2. Log in to the staff panel (usually at `http:///osticket/scp`) with the admin credentials you set during installation. 3. Check that the database tables were created: - Log in to MySQL: + ```bash sudo mysql -u osticketuser -p ``` - - Enter your `YOUR_DB_PASSWORD`. - - Run: + +- Enter your `YOUR_DB_PASSWORD`. +- Run: + ```sql USE osticket; SHOW TABLES; ``` - - You should see a list of tables (e.g., `ost_ticket`, `ost_user`). -4. Check for insecure files in the web directory (this should return nothing): + +- You should see a list of tables (e.g., `ost_ticket`, `ost_user`). + +1. Check for insecure files in the web directory (this should return nothing): + ```bash sudo find /var/www/html/osticket -type f -perm -o=w -ls sudo find /var/www/html/osticket -type d -perm -o=w -ls ``` ## Troubleshooting Common Issues + - **Corrupt ZIP file**: If the osTicket ZIP doesn’t extract, it might have downloaded incorrectly. Re-download from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). - **MySQL shows `->` prompt**: This means you didn’t finish a command. Type `;` to complete it or `\c` to cancel. - **ERROR 1064 in MySQL**: This happens if you press Enter too soon or use wrong syntax. Check your command and verify MySQL version: + ```sql SELECT VERSION(); ``` + - **ERROR 1410 (GRANT)**: This means the user doesn’t exist or you’re not logged in as root. Use `sudo mysql` to log in as root. ## What to Do Next + **Important**: This setup is for testing only. For production, you must add security measures like HTTPS and a firewall to protect your osTicket instance. - Set up an email account for osTicket to send notifications (use a custom domain and a service like Gmail to avoid spam issues). - Add HTTPS for security using Let’s Encrypt: + ```bash sudo apt install certbot python3-certbot-apache sudo certbot --apache ``` + - Set up a firewall to allow web traffic: + ```bash sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` + - Install `fail2ban` to protect against brute-force attacks: + ```bash sudo apt install fail2ban ``` + - Back up your web files and database regularly: + ```bash sudo tar -czf /backup/osticket_backup_$(date +%F).tar.gz /var/www/html/osticket/ mysqldump -u osticketuser -p osticket > /backup/osticket_db_$(date +%F).sql ``` + - Keep your system updated: + ```bash sudo apt update && sudo apt upgrade ``` diff --git a/kb/000.kb-template.md b/kb/000.kb-template.md index b3dede5..3d056ae 100644 --- a/kb/000.kb-template.md +++ b/kb/000.kb-template.md @@ -1,28 +1,32 @@ # KB: [Short Title] -**Related Ticket(s):** /tickets/[filename].md -**Category:** Hardware | Software | Network | Account | Other -**Environment:** [OS, system, or software version, e.g., "Windows 10, HP LaserJet Pro"] +**Related Ticket(s):** /tickets/[filename].md +**Category:** Hardware | Software | Network | Account | Other +**Environment:** [OS, system, or software version, e.g., "Windows 10, HP LaserJet Pro"] -**Owner:** [Your name or team] -**Last Reviewed:** [YYYY-MM-DD] -**Next Review Due:** [YYYY-MM-DD] +**Owner:** [Your name or team] +**Last Reviewed:** [YYYY-MM-DD] +**Next Review Due:** [YYYY-MM-DD] ## Resolution Steps -1. [Step 1, e.g., "Open Services.msc and locate Print Spooler"] -2. [Step 2, e.g., "Restart the service"] -3. Verification: [Confirm the outcome, e.g., "Print a test page to ensure success"] + +1. [Step 1, e.g., "Open Services.msc and locate Print Spooler"] +2. [Step 2, e.g., "Restart the service"] +3. Verification: [Confirm the outcome, e.g., "Print a test page to ensure success"] ## Troubleshooting Notes -- [Escalation guidance, e.g., "If restarting fails, check driver compatibility"] -- [Known limitations, e.g., "Solution may not work for network printers"] -- [Logs or outputs, e.g., "Check /var/log/syslog for errors"] + +- [Escalation guidance, e.g., "If restarting fails, check driver compatibility"] +- [Known limitations, e.g., "Solution may not work for network printers"] +- [Logs or outputs, e.g., "Check /var/log/syslog for errors"] ## Linked Incidents -- /tickets/[incident1].md -- /tickets/[incident2].md + +- /tickets/[incident1].md +- /tickets/[incident2].md ## Metrics / References -- Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] -- Recurrence: [Yes/No, e.g., "No"] + +- Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] +- Recurrence: [Yes/No, e.g., "No"] - External reference: [e.g., "HP Printer Manual, https://support.hp.com"] diff --git a/kb/README.md b/kb/README.md index 68233e4..acb2f08 100644 --- a/kb/README.md +++ b/kb/README.md @@ -1,4 +1,4 @@ -# Knowledge Base Index +# Knowledge Base Index Reusable solution docs derived from tickets and verified in labs. @@ -9,6 +9,7 @@ Reusable solution docs derived from tickets and verified in labs. - Cite vendor docs in a References section. Conventions: + - Filename in kebab-case (e.g., `printer-spooler-restart.md`). - Include a short metadata block (category, environment, owner). - Link back to the originating ticket and any validating lab. diff --git a/kb/account-lockout-reset.md b/kb/account-lockout-reset.md index 92cc6b4..5295194 100644 --- a/kb/account-lockout-reset.md +++ b/kb/account-lockout-reset.md @@ -1,32 +1,36 @@ -# KB: Account lockout reset and verification +# KB: Account lockout reset and verification -**Related Ticket(s):** /tickets/account-locked-out.md -**Related Lab(s):** /labs/htpasswd-auth-reset.md -**Related Scenario:** /scenarios/account-lockout-reset.md -**Category:** Account +**Related Ticket(s):** /tickets/account-locked-out.md +**Related Lab(s):** /labs/htpasswd-auth-reset.md +**Related Scenario:** /scenarios/account-lockout-reset.md +**Category:** Account **Environment:** Windows workstation joined to Active Directory; VPN/Email access -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps -1. Verify identity per policy (secondary info, manager approval if required). -2. In AD Users and Computers: check account state; unlock if locked. -3. If password expired/unknown, reset to a temporary value; require change at next logon. -4. Instruct the user to sign in on a wired network if possible; wait for policy replication if applicable. + +1. Verify identity per policy (secondary info, manager approval if required). +2. In AD Users and Computers: check account state; unlock if locked. +3. If password expired/unknown, reset to a temporary value; require change at next logon. +4. Instruct the user to sign in on a wired network if possible; wait for policy replication if applicable. 5. Verification: user confirms workstation login; for lab parity, Basic Auth to `/secure` returns HTTP 200. ## Troubleshooting Notes -- If repeated lockouts occur, look for stale credentials on other devices (mobile email, mapped services, scheduled tasks). -- Confirm MFA/SSPR state and recent policy changes. -- Check domain controller replication or account lockout policy thresholds. + +- If repeated lockouts occur, look for stale credentials on other devices (mobile email, mapped services, scheduled tasks). +- Confirm MFA/SSPR state and recent policy changes. +- Check domain controller replication or account lockout policy thresholds. - Logs: Security Event Log (user lockout), DC lockout status. ## Linked Incidents + - /tickets/account-locked-out.md ## Metrics / References -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Account lockout troubleshooting) diff --git a/kb/outlook-reconnect-after-update.md b/kb/outlook-reconnect-after-update.md index c22f939..6754c93 100644 --- a/kb/outlook-reconnect-after-update.md +++ b/kb/outlook-reconnect-after-update.md @@ -1,32 +1,36 @@ -# KB: Resolve Outlook disconnect / password prompts +# KB: Resolve Outlook disconnect / password prompts -**Related Ticket(s):** /tickets/outlook-disconnected-password-prompts.md -**Related Lab(s):** /labs/mailhog-connectivity.md -**Related Scenario:** /scenarios/outlook-reconnect-after-update.md -**Category:** Software +**Related Ticket(s):** /tickets/outlook-disconnected-password-prompts.md +**Related Lab(s):** /labs/mailhog-connectivity.md +**Related Scenario:** /scenarios/outlook-reconnect-after-update.md +**Category:** Software **Environment:** Windows 10/11; Outlook (Microsoft 365); VPN (if remote) -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps -1. Validate user credentials on another system (SSO/portal) to rule out auth failure. -2. Check VPN/Network connectivity (if remote): ensure stable connection. -3. Toggle Cached Exchange Mode (disable → enable) and restart Outlook. -4. Clear Windows Credential Manager entries for Office/Outlook; restart Outlook. -5. If needed, create a new Outlook profile (Control Panel → Mail → Profiles). -6. Verification: Outlook shows Connected; send/receive works. In lab, MailHog captures a test message at http://localhost:8025/. + +1. Validate user credentials on another system (SSO/portal) to rule out auth failure. +2. Check VPN/Network connectivity (if remote): ensure stable connection. +3. Toggle Cached Exchange Mode (disable → enable) and restart Outlook. +4. Clear Windows Credential Manager entries for Office/Outlook; restart Outlook. +5. If needed, create a new Outlook profile (Control Panel → Mail → Profiles). +6. Verification: Outlook shows Connected; send/receive works. In lab, MailHog captures a test message at . ## Troubleshooting Notes -- After updates, Autodiscover or token cache can cause loops; clearing credentials/profile often resolves. -- If organization-wide, check Exchange/identity provider status and service health. -- Logs: Windows Event Viewer → Application (Outlook), Office logs. + +- After updates, Autodiscover or token cache can cause loops; clearing credentials/profile often resolves. +- If organization-wide, check Exchange/identity provider status and service health. +- Logs: Windows Event Viewer → Application (Outlook), Office logs. ## Linked Incidents + - /tickets/outlook-disconnected-password-prompts.md ## Metrics / References -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Outlook connectivity, Autodiscover) diff --git a/kb/printer-queue-clearing.md b/kb/printer-queue-clearing.md index 78f2eef..c8e08a2 100644 --- a/kb/printer-queue-clearing.md +++ b/kb/printer-queue-clearing.md @@ -1,31 +1,35 @@ -# KB: Clear stuck print queue (client/server) +# KB: Clear stuck print queue (client/server) -**Related Ticket(s):** /tickets/cannot-print-to-shared-printer.md -**Related Lab(s):** /labs/print-queue-stuck.md -**Related Scenario:** /scenarios/printer-queue-clearing.md -**Category:** Hardware +**Related Ticket(s):** /tickets/cannot-print-to-shared-printer.md +**Related Lab(s):** /labs/print-queue-stuck.md +**Related Scenario:** /scenarios/printer-queue-clearing.md +**Category:** Hardware **Environment:** Windows clients; server-hosted printer (e.g., HP LaserJet series) -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps -1. Confirm scope: multiple users affected implies server-side issue. -2. On server: open Print Management; check the queue; cancel the oldest/large stuck job. -3. Restart the Print Spooler service (Services.msc or `net stop spooler` / `net start spooler`). -4. On a client: clear local queue if needed and print a test page. + +1. Confirm scope: multiple users affected implies server-side issue. +2. On server: open Print Management; check the queue; cancel the oldest/large stuck job. +3. Restart the Print Spooler service (Services.msc or `net stop spooler` / `net start spooler`). +4. On a client: clear local queue if needed and print a test page. 5. Verification: new test job prints; in lab, remaining job is processed and queue shows steady state. ## Troubleshooting Notes -- Ensure correct driver model on server (Type 3/4) and clients. -- Watch for mis-sized PDFs or offline ports. + +- Ensure correct driver model on server (Type 3/4) and clients. +- Watch for mis-sized PDFs or offline ports. - If department-wide and persistent, check network path to printer, SNMP status, or firmware. ## Linked Incidents + - /tickets/cannot-print-to-shared-printer.md ## Metrics / References -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Print Management); Vendor printer admin guide diff --git a/kb/workstation-performance-triage.md b/kb/workstation-performance-triage.md index d43ba09..2c97985 100644 --- a/kb/workstation-performance-triage.md +++ b/kb/workstation-performance-triage.md @@ -1,31 +1,35 @@ -# KB: Workstation performance triage (CPU/Disk/Network) +# KB: Workstation performance triage (CPU/Disk/Network) -**Related Ticket(s):** /tickets/computer-running-slow-lagging.md -**Related Lab(s):** /labs/resource-spike-triage.md -**Related Scenario:** /scenarios/workstation-performance-triage.md -**Category:** Hardware +**Related Ticket(s):** /tickets/computer-running-slow-lagging.md +**Related Lab(s):** /labs/resource-spike-triage.md +**Related Scenario:** /scenarios/workstation-performance-triage.md +**Category:** Hardware **Environment:** Windows 10/11; corporate network -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps -1. Differentiate network vs local: ping internal resource vs external site. -2. Check Task Manager for CPU/RAM/Disk spikes; identify culprit process. -3. Remediate: stop runaway task; reschedule AV scans/OneDrive sync; check Windows Update. -4. Disk health: check SMART, consider SSD upgrade if HDD and recurring. + +1. Differentiate network vs local: ping internal resource vs external site. +2. Check Task Manager for CPU/RAM/Disk spikes; identify culprit process. +3. Remediate: stop runaway task; reschedule AV scans/OneDrive sync; check Windows Update. +4. Disk health: check SMART, consider SSD upgrade if HDD and recurring. 5. Verification: CPU/Disk usage normalizes; common actions (open browser/drive) are fast; in lab, top shows normal usage. ## Troubleshooting Notes -- If only company site is slow, escalate to web/app owners. -- Confirm no VPN tunnel conflicts or DNS issues. + +- If only company site is slow, escalate to web/app owners. +- Confirm no VPN tunnel conflicts or DNS issues. - Capture before/after metrics if possible for MTTR. ## Linked Incidents + - /tickets/computer-running-slow-lagging.md ## Metrics / References -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Performance troubleshooting), vendor AV scheduling docs diff --git a/labs/000.lab-template.md b/labs/000.lab-template.md index b6d3257..c2a9581 100644 --- a/labs/000.lab-template.md +++ b/labs/000.lab-template.md @@ -1,39 +1,49 @@ -# Lab: [Short Title] +# Lab: [Short Title] -**Related KB:** /kb/[filename].md -**Category:** Hardware | Software | Network | Account | Other -**Environment:** [OS, system, or software version, e.g., "Ubuntu 24.04"] +**Related KB:** /kb/[filename].md +**Category:** Hardware | Software | Network | Account | Other +**Environment:** [OS, system, or software version, e.g., "Ubuntu 24.04"] -**Owner:** [Your name or team] -**Last Reviewed:** [YYYY-MM-DD] -**Next Review Due:** [YYYY-MM-DD] +**Owner:** [Your name or team] +**Last Reviewed:** [YYYY-MM-DD] +**Next Review Due:** [YYYY-MM-DD] ## Objectives + - [Skill or goal, e.g., "Learn to diagnose and fix a failed print service"] ## Prerequisites -- [Setup, e.g., "Ubuntu 24.04 VM with CUPS installed"] -- [Credentials, e.g., "User with sudo access"] + +- [Setup, e.g., "Ubuntu 24.04 VM with CUPS installed"] +- [Credentials, e.g., "User with sudo access"] ## Steps -1. [Instruction, e.g., "Simulate a failure: sudo systemctl stop "] -2. [Instruction, e.g., "Check service status: sudo systemctl status "] + +1. [Instruction, e.g., "Simulate a failure: sudo systemctl stop "] +2. [Instruction, e.g., "Check service status: sudo systemctl status "] 3. [Command, e.g.,] - `sudo systemctl restart ` + + ```bash + sudo systemctl restart + ``` ## Verification -- [Expected outcome, e.g., "Run lpstat -p; confirm printer is enabled"] -- [Pass condition, e.g., "Test page prints successfully"] -- [Fail condition, e.g., "Error: ‘printer not found’"] + +- [Expected outcome, e.g., "Run lpstat -p; confirm printer is enabled"] +- [Pass condition, e.g., "Test page prints successfully"] +- [Fail condition, e.g., "Error: ‘printer not found’"] ## Escalation Context -- [If lab fails, e.g., "Check /var/log//error_log and escalate to Tier 2 if driver issues persist. See ROLES.md"] + +- [If lab fails, e.g., "Check /var/log//error_log and escalate to Tier 2 if driver issues persist. See ROLES.md"] ## Metrics / Feedback -- Estimated time to complete: [e.g., "15 minutes"] -- Common errors: [e.g., "‘ not found’ ( not installed)"] -- Links: [/tickets/[incident].md or /scenarios/[scenario].md] + +- Estimated time to complete: [e.g., "15 minutes"] +- Common errors: [e.g., "‘ not found’ ( not installed)"] +- Links: [/tickets/[incident].md or /scenarios/[scenario].md] ## Cleanup -- [Reset steps, e.g., "Restart service: sudo systemctl start "] + +- [Reset steps, e.g., "Restart service: sudo systemctl start "] - [Ensure readiness, e.g., "Verify service status with systemctl status "] diff --git a/labs/README.md b/labs/README.md index 1941965..2744b81 100644 --- a/labs/README.md +++ b/labs/README.md @@ -1,8 +1,9 @@ -# Labs Catalog +# Labs Catalog Hands-on troubleshooting exercises. Use these to practice skills and validate KBs. ## Start here + - Beginner: [Nginx fails to start (config error)](./nginx-startup-fail.md) - Account: [Basic auth reset verification](./htpasswd-auth-reset.md) - Email: [Mail connectivity sanity with MailHog](./mailhog-connectivity.md) @@ -10,9 +11,11 @@ Hands-on troubleshooting exercises. Use these to practice skills and validate KB - Performance: [Resource spike triage (CPU/Disk)](./resource-spike-triage.md) ## Templates + - [Lab template](./000.lab-template.md) ## Conventions + - Keep each lab self-contained under `labs//assets` (configs, docker compose, sample files). - Include commands for both PowerShell and Bash when they differ. - At the top of each lab, link any related tickets, KBs, or scenarios. diff --git a/labs/htpasswd-auth-reset.md b/labs/htpasswd-auth-reset.md index bb6d871..98deee9 100644 --- a/labs/htpasswd-auth-reset.md +++ b/labs/htpasswd-auth-reset.md @@ -1,55 +1,69 @@ -# Lab: Basic auth reset verification (htpasswd + Nginx) +# Lab: Basic auth reset verification (htpasswd + Nginx) Simulate a credential reset and prove the fix with a protected endpoint. -**Related Ticket:** /tickets/account-locked-out.md -**Related KB:** /kb/account-lockout-reset.md -**Related Scenario:** /scenarios/account-lockout-reset.md -**Category:** Account +**Related Ticket:** /tickets/account-locked-out.md +**Related KB:** /kb/account-lockout-reset.md +**Related Scenario:** /scenarios/account-lockout-reset.md +**Category:** Account **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives + - Protect a page with HTTP Basic Auth - Reset the password and verify access ## Prerequisites + - Docker running - PowerShell or Bash ## Steps + 1) Start stack (from repo root) - - PowerShell - ```powershell - docker compose -f .\labs\htpasswd-auth-reset\assets\compose.yaml up -d - ``` - - Bash - ```bash - docker compose -f ./labs/htpasswd-auth-reset/assets/compose.yaml up -d - ``` + - PowerShell + + ```powershell + docker compose -f .\labs\htpasswd-auth-reset\assets\compose.yaml up -d + ``` + + - Bash + + ```bash + docker compose -f ./labs/htpasswd-auth-reset/assets/compose.yaml up -d + ``` + 2) Try accessing (expect auth required) + ```powershell Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = ("Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("user:wrong"))) } | Select-Object -ExpandProperty StatusCode # Expect 401/403 ``` + 3) Reset password + ```powershell docker exec htpasswd sh -lc "htpasswd -b /auth/.htpasswd user newpass" ``` + 4) Verify access succeeds + ```powershell $pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode # Expect 200 ``` - ## Verification - ```powershell - $pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); - Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode - # Expect: 200 - ``` +## Verification + +```powershell +$pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); +Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode +# Expect: 200 +``` ## Cleanup + ```powershell docker compose -f .\labs\htpasswd-auth-reset\assets\compose.yaml down -v ``` diff --git a/labs/mailhog-connectivity.md b/labs/mailhog-connectivity.md index 1077a3b..56fc1cd 100644 --- a/labs/mailhog-connectivity.md +++ b/labs/mailhog-connectivity.md @@ -1,57 +1,72 @@ -# Lab: Mail connectivity sanity with MailHog +# Lab: Mail connectivity sanity with MailHog Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. -**Related Ticket:** /tickets/outlook-disconnected-password-prompts.md -**Related KB:** /kb/outlook-reconnect-after-update.md -**Related Scenario:** /scenarios/outlook-reconnect-after-update.md -**Category:** Software +**Related Ticket:** /tickets/outlook-disconnected-password-prompts.md +**Related KB:** /kb/outlook-reconnect-after-update.md +**Related Scenario:** /scenarios/outlook-reconnect-after-update.md +**Category:** Software **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives + - Stand up a local SMTP sink and web UI - Simulate disconnect by stopping service / changing port - Verify send/receive via test message ## Prerequisites + - Docker running - PowerShell or Bash ## Steps + 1) Start MailHog (from repo root) - - PowerShell - ```powershell - docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml up -d - ``` - - Bash - ```bash - docker compose -f ./labs/mailhog-connectivity/assets/compose.yaml up -d - ``` + - PowerShell + + ```powershell + docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml up -d + ``` + + - Bash + + ```bash + docker compose -f ./labs/mailhog-connectivity/assets/compose.yaml up -d + ``` + 2) Check status + ```powershell docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml ps - # UI at http://localhost:8025 + # UI at ``` + 3) Send a test message + ```powershell docker exec mailhog bash -lc "echo -e 'HELO test\nMAIL FROM:\nRCPT TO:\nDATA\nSubject: hello\n\nmailhog test\n.\nQUIT' | nc 127.0.0.1 1025" ``` + 4) Simulate disconnect and recover + ```powershell docker stop mailhog # expect UI down; restart docker start mailhog ``` + 5) Verify in UI - - Browse http://localhost:8025 and confirm the message is present. + - Browse and confirm the message is present. - ## Verification - ```powershell +## Verification + +```powershell Invoke-WebRequest http://localhost:8025 -UseBasicParsing | Select-Object -ExpandProperty StatusCode # Expect: 200 (and message visible in UI) - ``` +``` ## Cleanup + ```powershell docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml down -v ``` diff --git a/labs/nginx-startup-fail.md b/labs/nginx-startup-fail.md index 4994965..acdec8c 100644 --- a/labs/nginx-startup-fail.md +++ b/labs/nginx-startup-fail.md @@ -1,54 +1,70 @@ -# Lab: Nginx fails to start (config error) +# Lab: Nginx fails to start (config error) Make a broken web server boot again by fixing a one-word typo. -**Related KB:** /kb/nginx-config-basics.md (optional) -**Category:** Software +**Related KB:** /kb/nginx-config-basics.md (optional) +**Category:** Software **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) -**Owner:** -**Last Reviewed:** -**Next Review Due:** +## Owner + +## Last Reviewed + +## Next Review Due ## Why this matters (30 seconds) -This is what real-life looks like: “my web page won’t load” and the container keeps restarting. Your job is to read the logs, spot the typo, make a tiny change, and prove the fix. + +This is what real-life looks like: “my web page won’t load” and the container keeps restarting. Your job is to read the logs, spot the typo, make a tiny change, and prove the fix. ## Objectives + - Diagnose a containerized Nginx startup failure - Fix a simple configuration error and verify success -Time: ~10–15 min • Difficulty: Beginner +Time: ~10–15 min • Difficulty: Beginner ## Prerequisites (quick preflight) + - Docker is installed and running - PowerShell - ```powershell + + ```powershell docker --version docker compose version ``` + - Bash - ```bash + + ```bash docker --version docker compose version ``` ## Steps + 1) Start the broken stack (from repo root) + - PowerShell + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml up -d ``` + - Bash + ```bash docker compose -f ./labs/nginx-startup-fail/assets/compose.yaml up -d ``` 2) Observe the failure - Status + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml ps ``` - - Logs (look for “unknown directive” or “invalid”) + + - Logs (look for “unknown directive” or “invalid”) + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml logs nginx ``` @@ -60,47 +76,58 @@ Time: ~10–15 min • Difficulty: Beginner 4) Fix and retry - Change `roooot` to `root` in nginx.conf - Recreate the container + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml up -d --force-recreate ``` ## Verification (success criteria) -- Browse http://localhost:8080 and see “Nginx is up” + +- Browse and see “Nginx is up” - Container health should go to `healthy` once the page is served - Or use a CLI check: - Check health status quickly + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml ps # Expect: State shows "running (healthy)" ``` + - PowerShell + ```powershell Invoke-WebRequest http://localhost:8080 -UseBasicParsing | Select-Object -ExpandProperty StatusCode # Expect: 200 ``` + - Bash + ```bash curl -s -o /dev/null -w "%{http_code}" http://localhost:8080 # Expect: 200 ``` -## Hints (if you’re stuck) -- Re-run logs and read the first error: it usually tells you exactly what Nginx didn’t understand. -- If the fix doesn’t apply, make sure you recreated the container with `--force-recreate`. +## Hints (if you’re stuck) + +- Re-run logs and read the first error: it usually tells you exactly what Nginx didn’t understand. +- If the fix doesn’t apply, make sure you recreated the container with `--force-recreate`. - If port 8080 is busy, edit `compose.yaml` and change `8080:80` to another free port (e.g., `8081:80`). - On Windows, if you see file permission issues, temporarily remove `:ro` from the volume lines to test. ## Metrics / Feedback + - Estimated time: 10 minutes - Common pitfalls: wrong compose path; forgetting `--force-recreate` after config changes -- Optional next step: write a KB titled “Nginx: fix startup syntax errors” linking this lab +- Optional next step: write a KB titled “Nginx: fix startup syntax errors” linking this lab ## Bonus challenges (optional) + - Inspect the health status with `docker compose ps` and experiment with failing/healthy states - Explain in one sentence why pinning `nginx:1.27-alpine` improves reproducibility - Change the published port and update your verification command ## Cleanup + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml down -v ``` diff --git a/labs/print-queue-stuck.md b/labs/print-queue-stuck.md index 797c865..8ea4382 100644 --- a/labs/print-queue-stuck.md +++ b/labs/print-queue-stuck.md @@ -1,33 +1,41 @@ -# Lab: Print queue stuck (department-wide) +# Lab: Print queue stuck (department-wide) Reproduce a stuck print queue and practice clearing jobs and restarting the "spooler" safely. -**Related Ticket:** /tickets/cannot-print-to-shared-printer.md -**Related KB:** /kb/printer-queue-clearing.md -**Related Scenario:** /scenarios/printer-queue-clearing.md -**Category:** Hardware +**Related Ticket:** /tickets/cannot-print-to-shared-printer.md +**Related KB:** /kb/printer-queue-clearing.md +**Related Scenario:** /scenarios/printer-queue-clearing.md +**Category:** Hardware **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives + - Simulate a department-wide stuck print queue - Clear the queue and restart the service - Verify a new job processes ## Prerequisites (preflight) + - Docker running - PowerShell or Bash ## Steps + 1) Start the simulated print service (from repo root) - - PowerShell - ```powershell - docker compose -f .\labs\print-queue-stuck\assets\compose.yaml up -d - ``` - - Bash - ```bash - docker compose -f ./labs/print-queue-stuck/assets/compose.yaml up -d - ``` + - PowerShell + + ```powershell + docker compose -f .\labs\print-queue-stuck\assets\compose.yaml up -d + ``` + + - Bash + + ```bash + docker compose -f ./labs/print-queue-stuck/assets/compose.yaml up -d + ``` + 2) Submit a job and simulate a stuck queue + ```powershell # submit two jobs docker exec print-queue echo "report-a.pdf" >> /queue/jobs.txt @@ -35,30 +43,38 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo # simulate stuck consumer docker stop print-queue-consumer ``` + 3) Diagnose + ```powershell docker exec print-queue cat /queue/jobs.txt docker compose -f .\labs\print-queue-stuck\assets\compose.yaml ps ``` + 4) Fix + ```powershell # clear the oldest bad job and restart consumer docker exec print-queue sed -i '1d' /queue/jobs.txt docker start print-queue-consumer ``` + 5) Verify + ```powershell # remaining job should be processed (file moved to processed.txt) docker exec print-queue cat /queue/processed.txt ``` - ## Verification - ```powershell +## Verification + +```powershell docker exec print-queue cat /queue/processed.txt # Expect: remaining job name present; queue stable - ``` +``` ## Cleanup + ```powershell docker compose -f .\labs\print-queue-stuck\assets\compose.yaml down -v ``` diff --git a/labs/resource-spike-triage.md b/labs/resource-spike-triage.md index 89b4ecb..ed60a61 100644 --- a/labs/resource-spike-triage.md +++ b/labs/resource-spike-triage.md @@ -1,53 +1,65 @@ -# Lab: Resource spike triage (CPU/Disk) +# Lab: Resource spike triage (CPU/Disk) Practice identifying and resolving resource spikes that cause slowness. -**Related Ticket:** /tickets/computer-running-slow-lagging.md -**Related KB:** /kb/workstation-performance-triage.md -**Related Scenario:** /scenarios/workstation-performance-triage.md -**Category:** Hardware +**Related Ticket:** /tickets/computer-running-slow-lagging.md +**Related KB:** /kb/workstation-performance-triage.md +**Related Scenario:** /scenarios/workstation-performance-triage.md +**Category:** Hardware **Environment:** Linux VM or Docker container ## Objectives + - Trigger a CPU or disk spike - Identify the culprit - Resolve and verify performance returns to normal ## Prerequisites + - Linux shell (VM or WSL2) or Docker ## Steps + 1) Create a CPU spike (Linux VM) + ```bash sudo apt-get update && sudo apt-get install -y stress-ng stress-ng --cpu 2 --timeout 60s & top -b -n 1 | head -n 20 ``` + 2) Or create a CPU spike (Docker) + ```bash docker run --rm -d --name cpu-spike alpine:3.20 sh -c "apk add --no-cache stress-ng && stress-ng --cpu 2 --timeout 60s" docker top cpu-spike ``` + 3) Resolve + ```bash # VM: kill the process if still running pkill -f stress-ng || true # Docker: stop container docker stop cpu-spike || true ``` + 4) Verify + ```bash top -b -n 1 | head -n 20 # Expect CPU usage back to normal ``` - ## Verification - ```bash +## Verification + +```bash top -b -n 1 | head -n 20 # Expect: CPU/Disk normalized; no stress-ng running - ``` +``` ## Cleanup + ```bash pkill -f stress-ng 2>/dev/null || true docker rm -f cpu-spike 2>/dev/null || true diff --git a/scenarios/000.scenario-template.md b/scenarios/000.scenario-template.md index 28f64e2..ca70a04 100644 --- a/scenarios/000.scenario-template.md +++ b/scenarios/000.scenario-template.md @@ -1,4 +1,4 @@ -# Scenario: [Short Title] +# Scenario: [Short Title] Link tickets, KB, and labs to form an end-to-end workflow. @@ -7,18 +7,22 @@ Link tickets, KB, and labs to form an end-to-end workflow. - Related Lab: /labs/[lab].md ## Overview + Briefly describe the user story and desired outcome. ## Flow + 1) Ticket summary and context 2) Resolution path (KB reference) 3) Practice in lab ## Success Criteria -- [ ] Ticket resolved (what “resolved” means here) + +- [ ] Ticket resolved (what “resolved” means here) - [ ] KB validated (up-to-date and accurate) - [ ] Lab passes verification steps ## Notes + - Assumptions and constraints - Follow-ups or improvements diff --git a/scenarios/README.md b/scenarios/README.md index fb778fb..fb472d2 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -1,8 +1,9 @@ -# Scenarios Index +# Scenarios Index -End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the story and define success criteria. +End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the story and define success criteria. - Template: [000.scenario-template.md](./000.scenario-template.md) + - Good scenarios include: - A realistic ticket with symptoms and constraints - A KB solution path with alternatives @@ -10,5 +11,6 @@ End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the stor - Clear acceptance/success criteria Conventions: + - Name scenarios clearly (e.g., `printer-spooler-end-to-end.md`). - Link artifacts with relative paths; avoid external private endpoints. diff --git a/scenarios/account-lockout-reset.md b/scenarios/account-lockout-reset.md index d294760..f549c34 100644 --- a/scenarios/account-lockout-reset.md +++ b/scenarios/account-lockout-reset.md @@ -1,14 +1,16 @@ -# Scenario: Account lockout and password reset +# Scenario: Account lockout and password reset - Related Ticket: /tickets/account-locked-out.md -- Related KB: /kb/account-lockout-reset.md -- Related Lab: /labs/htpasswd-auth-reset.md +- Related KB: /kb/account-lockout-reset.md#resolution-steps +- Related Lab: /labs/htpasswd-auth-reset.md#verification ## Flow + 1. User reports lockout; verify identity and account status. 2. Reset password; instruct user to retry on wired login. 3. In lab, reset htpasswd password and verify 200 OK with Basic Auth header. ## Success Criteria + - Access restored in lab (HTTP 200) and, in real workflow, user confirms workstation login. - Ticket updated with steps, and (when created) KB drafted referencing the lab. diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index 4a8a87b..f3fbe8c 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -1,14 +1,16 @@ -# Scenario: Outlook reconnect after update +# Scenario: Outlook reconnect after update - Related Ticket: /tickets/outlook-disconnected-password-prompts.md -- Related KB: /kb/outlook-reconnect-after-update.md -- Related Lab: /labs/mailhog-connectivity.md +- Related KB: /kb/outlook-reconnect-after-update.md#resolution-steps +- Related Lab: /labs/mailhog-connectivity.md#verification ## Flow + 1. Validate credentials on another system; check VPN if remote. 2. Confirm connectivity; recreate profile or clear cached credentials as needed. 3. In lab, use MailHog to verify SMTP is reachable and a test message is captured. ## Success Criteria + - MailHog shows the test message; service reachable. - Ticket notes profile/cache actions; KB drafted with steps. diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index ed97ec3..57d846c 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -1,14 +1,16 @@ -# Scenario: Department-wide printer outage (queue clearing) +# Scenario: Department-wide printer outage (queue clearing) - Related Ticket: /tickets/cannot-print-to-shared-printer.md -- Related KB: /kb/printer-queue-clearing.md -- Related Lab: /labs/print-queue-stuck.md +- Related KB: /kb/printer-queue-clearing.md#resolution-steps +- Related Lab: /labs/print-queue-stuck.md#verification ## Flow + 1. Confirm scope (multiple users); check server queue/state. 2. Clear stuck job(s); restart the service. 3. In lab, simulate stuck queue; clear oldest job; restart consumer. ## Success Criteria + - Queue shows processed jobs and accepts new test job. - Ticket documents scope, remediation, and server-side action; KB drafted. diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index 3105810..36d28ee 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -1,14 +1,16 @@ -# Scenario: Workstation performance triage +# Scenario: Workstation performance triage - Related Ticket: /tickets/computer-running-slow-lagging.md -- Related KB: /kb/workstation-performance-triage.md -- Related Lab: /labs/resource-spike-triage.md +- Related KB: /kb/workstation-performance-triage.md#resolution-steps +- Related Lab: /labs/resource-spike-triage.md#verification ## Flow + 1. Compare internal vs external latency; check local resource usage. 2. Identify culprit (scan/update/runaway process); apply remediation. 3. In lab, trigger and stop a synthetic load; verify usage returns to normal. ## Success Criteria + - CPU/Disk usage normalizes; simple command completes fast. - Ticket lists root cause and remediation; KB drafted. diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index 8864eb3..362d512 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -1,22 +1,33 @@ -# Ticket: [Short Title] +# Ticket: [Short Title] -**Category:** Hardware | Software | Network | Account | Other -**Priority:** Low | Medium | High | Critical -**Impact:** Single user | Department | Organization-wide -**Urgency:** Low (no workflow impact) | Medium (work slowed) | High (work blocked) +**Category:** Hardware | Software | Network | Account | Other +**Priority:** Low | Medium | High | Critical +**Impact:** Single user | Department | Organization-wide +**Urgency:** Low (no workflow impact) | Medium (work slowed) | High (work blocked) -**Problem:** [One-line description of the issue] -**Symptoms:** [What the user sees or experiences] -**Environment:** [OS, system, or software version] +## Problem -**Troubleshooting Steps Taken:** -- [ ] [Step 1, e.g., "Checked printer connection"] -- [ ] [Step 2, e.g., "Restarted Print Spooler service"] +[One-line description of the issue] -**Resolution:** -[Steps to resolve, or "TBD" if unknown] +## Symptoms -**Escalation Path:** -- [ ] Tier 1 complete (basic troubleshooting done) -- [ ] Escalated to Tier 2 (e.g., for driver issues) -- [ ] Escalated to Tier 3 (e.g., for hardware replacement) +[What the user sees or experiences] + +## Environment + +[OS, system, or software version] + +## Troubleshooting Steps Taken + +- [ ] [Step 1, e.g., "Checked printer connection"] +- [ ] [Step 2, e.g., "Restarted Print Spooler service"] + +## Resolution + +[Steps to resolve, or "TBD" if unknown] + +## Escalation Path + +- [ ] Tier 1 complete (basic troubleshooting done) +- [ ] Escalated to Tier 2 (e.g., for driver issues) +- [ ] Escalated to Tier 3 (e.g., for hardware replacement) diff --git a/tickets/README.md b/tickets/README.md index e9492ec..1082139 100644 --- a/tickets/README.md +++ b/tickets/README.md @@ -1,20 +1,23 @@ -# Tickets Index +# Tickets Index User-reported issues. Start here when simulating a helpdesk intake. - Template: [000.ticket-template.md](./000.ticket-template.md) + - How to write good tickets: - Be specific about symptoms, environment, and what changed. - Include simple reproduction steps if known. - Avoid credentials or personal IPs. Conventions: + - Use kebab-case filenames (e.g., `printer-wont-print.md`). - Link related KBs/labs/scenarios with relative paths. - Follow the CompTIA A+ 6-step model in your troubleshooting notes. Examples: -- [Account locked out – cannot log in](./account-locked-out.md) + +- [Account locked out – cannot log in](./account-locked-out.md) - [Cannot print to shared Finance printer](./cannot-print-to-shared-printer.md) - [Outlook disconnected and password prompts](./outlook-disconnected-password-prompts.md) - [Computer is running extremely slow / lagging](./computer-running-slow-lagging.md) diff --git a/tickets/account-locked-out.md b/tickets/account-locked-out.md index 9f6fe54..3eca812 100644 --- a/tickets/account-locked-out.md +++ b/tickets/account-locked-out.md @@ -1,32 +1,35 @@ -# Ticket: Account locked out – cannot log in +# Ticket: Account locked out – cannot log in -**Category:** Account -**Priority:** High -**Impact:** Single user +**Category:** Account +**Priority:** High +**Impact:** Single user **Urgency:** High (work blocked) -**Ticket ID:** HLP-20250928-001 -**Status:** New -**Requester:** Jane Doe (ID: JDoe) -**Department:** Sales -**Contact:** Ext: 4122, Cell: (555) 555-4122 +**Ticket ID:** HLP-20250928-001 +**Status:** New +**Requester:** Jane Doe (ID: JDoe) +**Department:** Sales +**Contact:** Ext: 4122, Cell: (555) 555-4122 **System/Component:** Active Directory, Email/VPN Access -**Problem:** User reports account is locked and cannot access desktop, email, or files after vacation. -**Symptoms:** Login attempts fail; account lockout message. +**Problem:** User reports account is locked and cannot access desktop, email, or files after vacation. +**Symptoms:** Login attempts fail; account lockout message. **Environment:** Windows desktop joined to AD; remote services (email/VPN) affected. -**Troubleshooting Steps Taken:** -- [ ] Verified user identity via secondary info (DOB, employee ID) -- [ ] Checked AD status for JDoe -- [ ] If locked, unlocked account -- [ ] If password expired, initiated reset or guided through SSPR +## Troubleshooting Steps Taken + +- [ ] Verified user identity via secondary info (DOB, employee ID) +- [ ] Checked AD status for JDoe +- [ ] If locked, unlocked account +- [ ] If password expired, initiated reset or guided through SSPR - [ ] Instructed user to restart and attempt login on wired network -**Resolution:** +## Resolution + [TBD] -**Escalation Path:** -- [ ] Tier 1 complete (basic checks and unlock/reset) -- [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) +## Escalation Path + +- [ ] Tier 1 complete (basic checks and unlock/reset) +- [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) - [ ] Escalated to Tier 3 (directory service problems) diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 1631e7c..8f3710f 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -1,32 +1,35 @@ -# Ticket: Cannot print to shared Finance printer +# Ticket: Cannot print to shared Finance printer -**Category:** Hardware -**Priority:** Medium -**Impact:** Department +**Category:** Hardware +**Priority:** Medium +**Impact:** Department **Urgency:** Medium (work slowed) -**Ticket ID:** HLP-20250928-002 -**Status:** New -**Requester:** Michael Smith (ID: MSmith) -**Department:** Finance -**Contact:** Ext: 3015 +**Ticket ID:** HLP-20250928-002 +**Status:** New +**Requester:** Michael Smith (ID: MSmith) +**Department:** Finance +**Contact:** Ext: 3015 **System/Component:** Shared Network Printer (HP LaserJet 5500), Print Server -**Problem:** Department cannot print to shared printer FINANCE-5500. -**Symptoms:** Print jobs stuck as Error/Spooling; device shows Ready with flashing status light. +**Problem:** Department cannot print to shared printer FINANCE-5500. +**Symptoms:** Print jobs stuck as Error/Spooling; device shows Ready with flashing status light. **Environment:** Windows clients printing via central print server. -**Troubleshooting Steps Taken:** -- [ ] Confirmed print server is running and reachable -- [ ] Remotely checked client printer driver/port -- [ ] Cleared local print queue; attempted test page -- [ ] Checked server print queue for large/stuck jobs +## Troubleshooting Steps Taken + +- [ ] Confirmed print server is running and reachable +- [ ] Remotely checked client printer driver/port +- [ ] Cleared local print queue; attempted test page +- [ ] Checked server print queue for large/stuck jobs - [ ] If department-wide, escalated to Tier 2 (Server Team) -**Resolution:** +## Resolution + [TBD] -**Escalation Path:** -- [ ] Tier 1 complete (client/queue verification) -- [ ] Escalated to Tier 2 (server-side queue/driver) +## Escalation Path + +- [ ] Tier 1 complete (client/queue verification) +- [ ] Escalated to Tier 2 (server-side queue/driver) - [ ] Escalated to Tier 3 (hardware/network issue) diff --git a/tickets/computer-running-slow-lagging.md b/tickets/computer-running-slow-lagging.md index 1d06fe8..93fa0b4 100644 --- a/tickets/computer-running-slow-lagging.md +++ b/tickets/computer-running-slow-lagging.md @@ -1,32 +1,35 @@ -# Ticket: Computer is running extremely slow / lagging +# Ticket: Computer is running extremely slow / lagging -**Category:** Hardware -**Priority:** Medium -**Impact:** Single user +**Category:** Hardware +**Priority:** Medium +**Impact:** Single user **Urgency:** Medium -**Ticket ID:** HLP-20250928-004 -**Status:** New -**Requester:** David Patel (ID: DPatel) -**Department:** Operations -**Contact:** Ext: 5098 +**Ticket ID:** HLP-20250928-004 +**Status:** New +**Requester:** David Patel (ID: DPatel) +**Department:** Operations +**Contact:** Ext: 5098 **System/Component:** Endpoint PC (Windows 10), Network Connectivity -**Problem:** Computer performance is very slow for common tasks (Chrome, shared drive), despite restarts. -**Symptoms:** Long app launch times; constant disk activity; internal company site loads slowly while YouTube is fine. +**Problem:** Computer performance is very slow for common tasks (Chrome, shared drive), despite restarts. +**Symptoms:** Long app launch times; constant disk activity; internal company site loads slowly while YouTube is fine. **Environment:** Windows 10 desktop; corporate network. -**Troubleshooting Steps Taken:** -- [ ] Compared internal vs external network latency (ping tests) -- [ ] Checked Task Manager CPU/RAM/Disk usage and processes -- [ ] Ran malware scan or checked for runaway updates -- [ ] Assessed disk health (HDD fragmentation/SMART) +## Troubleshooting Steps Taken + +- [ ] Compared internal vs external network latency (ping tests) +- [ ] Checked Task Manager CPU/RAM/Disk usage and processes +- [ ] Ran malware scan or checked for runaway updates +- [ ] Assessed disk health (HDD fragmentation/SMART) - [ ] Isolated network cause; escalate website performance to Web/DevOps if isolated -**Resolution:** +## Resolution + [TBD] -**Escalation Path:** -- [ ] Tier 1 complete (resource & basic network checks) -- [ ] Escalated to Tier 2 (network/server) +## Escalation Path + +- [ ] Tier 1 complete (resource & basic network checks) +- [ ] Escalated to Tier 2 (network/server) - [ ] Escalated to Tier 3 (hardware upgrade/policy) diff --git a/tickets/outlook-disconnected-password-prompts.md b/tickets/outlook-disconnected-password-prompts.md index 66e8da5..c05d2be 100644 --- a/tickets/outlook-disconnected-password-prompts.md +++ b/tickets/outlook-disconnected-password-prompts.md @@ -1,32 +1,35 @@ -# Ticket: Outlook disconnected and repeatedly prompting for password +# Ticket: Outlook disconnected and repeatedly prompting for password -**Category:** Software -**Priority:** Medium -**Impact:** Single user +**Category:** Software +**Priority:** Medium +**Impact:** Single user **Urgency:** Medium -**Ticket ID:** HLP-20250928-003 -**Status:** New -**Requester:** Sarah Chen (ID: SChen) -**Department:** Marketing -**Contact:** Ext: 2005 +**Ticket ID:** HLP-20250928-003 +**Status:** New +**Requester:** Sarah Chen (ID: SChen) +**Department:** Marketing +**Contact:** Ext: 2005 **System/Component:** Microsoft Outlook (Cached Mode), Exchange Server -**Problem:** Outlook disconnects and repeatedly prompts for password after a company security update. -**Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. +**Problem:** Outlook disconnects and repeatedly prompts for password after a company security update. +**Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. **Environment:** Laptop (potentially remote); VPN in use when offsite. -**Troubleshooting Steps Taken:** -- [ ] Verified credentials work on another system (e.g., internal portal) -- [ ] Checked Outlook status bar connectivity -- [ ] Verified VPN connection if remote -- [ ] Toggled Cached Exchange Mode +## Troubleshooting Steps Taken + +- [ ] Verified credentials work on another system (e.g., internal portal) +- [ ] Checked Outlook status bar connectivity +- [ ] Verified VPN connection if remote +- [ ] Toggled Cached Exchange Mode - [ ] Created a new Outlook profile or cleared Credential Manager entries -**Resolution:** +## Resolution + [TBD] -**Escalation Path:** -- [ ] Tier 1 complete (profile/credentials checks) -- [ ] Escalated to Tier 2 (Exchange/Autodiscover) +## Escalation Path + +- [ ] Tier 1 complete (profile/credentials checks) +- [ ] Escalated to Tier 2 (Exchange/Autodiscover) - [ ] Escalated to Tier 3 (SAML/MFA/identity provider)