284 lines
8 KiB
Markdown
284 lines
8 KiB
Markdown
# Getting Support
|
|
|
|
Thank you for using **ansible-role-openssh_server**! This document explains how to get help with this OpenSSH server hardening role.
|
|
|
|
## Important Note
|
|
|
|
**This is a volunteer-run hobby project.** Maintainers contribute in their spare time. We appreciate your patience and understanding as we help where we can.
|
|
|
|
## Before Asking for Help
|
|
|
|
Please try these steps first—they often solve problems quickly:
|
|
|
|
### 1. Read the Documentation
|
|
|
|
Start with our comprehensive documentation:
|
|
|
|
- **[README.md](../README.md)**: Quick start, features, and overview
|
|
- **[docs/CONFIGURATION.md](CONFIGURATION.md)**: Complete variable reference
|
|
- **[docs/DISTRIBUTIONS.md](DISTRIBUTIONS.md)**: Supported distributions and version compatibility
|
|
- **[docs/EXAMPLES.md](EXAMPLES.md)**: Configuration examples for common scenarios
|
|
- **[docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)**: Common issues and solutions
|
|
- **[docs/CVE-TRACKING.md](CVE-TRACKING.md)**: CVE status and patch tracking
|
|
- **[docs/COMPLIANCE.md](COMPLIANCE.md)**: Compliance framework mappings
|
|
|
|
### 2. Search Existing Issues
|
|
|
|
Someone may have already encountered your problem:
|
|
|
|
1. Go to [GitHub Issues](https://github.com/welshwandering/ansible-role-openssh_server/issues)
|
|
2. Search for keywords related to your issue
|
|
3. Check both open and closed issues
|
|
4. Look for the answer in issue comments
|
|
|
|
### 3. Check Your Configuration
|
|
|
|
Many issues are configuration-related:
|
|
|
|
- Verify your Ansible version: `ansible --version` (need 2.15+)
|
|
- Check your OpenSSH version: `ssh -V`
|
|
- Confirm your distribution is supported (see [docs/DISTRIBUTIONS.md](DISTRIBUTIONS.md))
|
|
- Review your role variables for typos or incorrect values
|
|
- Test with default variables to isolate the issue
|
|
|
|
### 4. Enable Verbose Output
|
|
|
|
Get more details about what's happening:
|
|
|
|
```bash
|
|
# Run playbook with verbose output
|
|
ansible-playbook -vvv your-playbook.yml
|
|
|
|
# Validate SSH configuration
|
|
sudo sshd -t
|
|
```
|
|
|
|
## How to Get Help
|
|
|
|
### For General Questions
|
|
|
|
**GitHub Discussions** (Coming Soon)
|
|
- General questions about using the role
|
|
- "How do I...?" questions
|
|
- Configuration advice
|
|
- Best practices discussions
|
|
|
|
Until Discussions are enabled, use the question issue template:
|
|
|
|
**GitHub Issues** - Use the Question Template
|
|
1. Go to [New Issue](https://github.com/welshwandering/ansible-role-openssh_server/issues/new/choose)
|
|
2. Select "Question / Discussion"
|
|
3. Provide context about what you're trying to do
|
|
4. Include your environment details
|
|
|
|
### For Bug Reports
|
|
|
|
If you've found a bug in the role:
|
|
|
|
1. Go to [New Issue](https://github.com/welshwandering/ansible-role-openssh_server/issues/new/choose)
|
|
2. Select "Bug Report"
|
|
3. Fill out the template completely
|
|
4. Include:
|
|
- Distribution and version
|
|
- OpenSSH version
|
|
- Ansible version
|
|
- Role version (git commit or tag)
|
|
- Relevant role variables
|
|
- Error messages
|
|
- Steps to reproduce
|
|
|
|
**Please remove sensitive data** (passwords, keys, IP addresses) from examples!
|
|
|
|
### For Security Issues
|
|
|
|
**⚠️ DO NOT use GitHub Issues for security vulnerabilities!**
|
|
|
|
See [docs/SECURITY.md](SECURITY.md) for how to report security issues privately.
|
|
|
|
### For Feature Requests
|
|
|
|
Have an idea for improving the role?
|
|
|
|
1. Check if it's already requested in [GitHub Issues](https://github.com/welshwandering/ansible-role-openssh_server/issues)
|
|
2. Use the [Feature Request template](https://github.com/welshwandering/ansible-role-openssh_server/issues/new/choose)
|
|
3. Explain the use case and why it would be valuable
|
|
4. Consider contributing the feature yourself (see [CONTRIBUTING.md](CONTRIBUTING.md))
|
|
|
|
## How to Ask Good Questions
|
|
|
|
Help us help you! Good questions get faster, better answers.
|
|
|
|
### Include Key Information
|
|
|
|
Always include:
|
|
- **Distribution and version**: "Debian 12 Bookworm" or "Ubuntu 22.04 Jammy"
|
|
- **OpenSSH version**: Output of `ssh -V`
|
|
- **Ansible version**: Output of `ansible --version`
|
|
- **Role version**: Git commit hash, tag, or "latest from main"
|
|
|
|
### Provide Context
|
|
|
|
Explain:
|
|
- What you're trying to achieve
|
|
- What you expected to happen
|
|
- What actually happened
|
|
- What you've already tried
|
|
|
|
### Show Your Work
|
|
|
|
Include:
|
|
- Relevant parts of your playbook (sanitize sensitive data!)
|
|
- Role variables you've configured
|
|
- Error messages (full text, not screenshots when possible)
|
|
- Output from validation: `sudo sshd -t`
|
|
|
|
### Create a Minimal Example
|
|
|
|
Reduce your problem to the smallest example that demonstrates the issue:
|
|
|
|
```yaml
|
|
# Good: Minimal example
|
|
- hosts: test
|
|
roles:
|
|
- role: openssh_server
|
|
vars:
|
|
openssh_password_authentication: false
|
|
openssh_port: 2222
|
|
```
|
|
|
|
This is better than posting your entire 500-line playbook!
|
|
|
|
### Use Code Blocks
|
|
|
|
Format code and output properly:
|
|
|
|
````markdown
|
|
```yaml
|
|
# Your YAML here
|
|
```
|
|
|
|
```bash
|
|
# Command output here
|
|
```
|
|
````
|
|
|
|
## What NOT to Use GitHub Issues For
|
|
|
|
Please **do not** use GitHub Issues for:
|
|
|
|
### Personal Configuration Help
|
|
|
|
GitHub Issues are for bugs and features in the **role itself**, not debugging your specific infrastructure.
|
|
|
|
**Instead**:
|
|
- Review [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
|
- Check [docs/EXAMPLES.md](EXAMPLES.md)
|
|
- Post a question using the question template (keep it focused on the role)
|
|
|
|
### OpenSSH Software Issues
|
|
|
|
This role configures OpenSSH—it doesn't fix bugs in OpenSSH itself.
|
|
|
|
**Instead**:
|
|
- OpenSSH bugs: https://www.openssh.com/report.html
|
|
- OpenSSH security: https://www.openssh.com/security.html
|
|
|
|
### Distribution-Specific Package Issues
|
|
|
|
We track CVE status, but we don't fix vulnerabilities in OS packages.
|
|
|
|
**Instead**:
|
|
- Debian bugs: https://www.debian.org/Bugs/
|
|
- Ubuntu bugs: https://bugs.launchpad.net/ubuntu
|
|
- Debian security: https://security-tracker.debian.org/
|
|
- Ubuntu security: https://ubuntu.com/security
|
|
|
|
### Ansible Core Issues
|
|
|
|
Problems with Ansible itself should go to the Ansible project.
|
|
|
|
**Instead**: https://github.com/ansible/ansible/issues
|
|
|
|
## Community Support
|
|
|
|
### Help Others
|
|
|
|
If you have experience with this role:
|
|
- Answer questions in issues
|
|
- Share your configurations (sanitized!)
|
|
- Review pull requests
|
|
- Improve documentation
|
|
|
|
Your contributions help build a stronger community!
|
|
|
|
### Share Your Success
|
|
|
|
Found a great way to use this role? Let us know:
|
|
- Share in discussions (when available)
|
|
- Write a blog post and tell us about it
|
|
- Contribute an example to [examples/](../examples/)
|
|
|
|
## Commercial Support
|
|
|
|
This is an open source hobby project. **No commercial support is available.**
|
|
|
|
However, you can:
|
|
- Hire Ansible consultants who can help with your infrastructure
|
|
- Engage security consultants familiar with SSH hardening
|
|
- Use this role as-is under the MIT License
|
|
|
|
## Response Time Expectations
|
|
|
|
**This is a volunteer-run hobby project.** Please understand:
|
|
|
|
- Responses will come as maintainer time permits
|
|
- There are no guaranteed response times
|
|
- Simple questions may get quick answers
|
|
- Complex issues may take longer
|
|
- Critical security issues will be prioritized
|
|
|
|
We appreciate your patience!
|
|
|
|
## Contributing
|
|
|
|
Want to help improve this project?
|
|
|
|
- See [docs/CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute
|
|
- Review [AGENTS.md](../AGENTS.md) for development guidelines
|
|
- Check out [docs/PULL_REQUEST_TEMPLATE.md](PULL_REQUEST_TEMPLATE.md) for PR expectations
|
|
|
|
## Additional Resources
|
|
|
|
### SSH Security Resources
|
|
|
|
- **OpenSSH**: https://www.openssh.com/
|
|
- **Mozilla OpenSSH Guidelines**: https://infosec.mozilla.org/guidelines/openssh
|
|
- **NIST SP 800-52**: https://csrc.nist.gov/publications/detail/sp/800-52/rev-2/final
|
|
|
|
### Ansible Resources
|
|
|
|
- **Ansible Documentation**: https://docs.ansible.com/
|
|
- **Ansible Galaxy**: https://galaxy.ansible.com/
|
|
- **Best Practices**: https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html
|
|
|
|
### Compliance Resources
|
|
|
|
See [docs/COMPLIANCE.md](COMPLIANCE.md) for links to compliance frameworks and standards.
|
|
|
|
## Thank You
|
|
|
|
Thank you for using ansible-role-openssh_server! We're glad to have you in our community.
|
|
|
|
Remember:
|
|
- 📖 Documentation first
|
|
- 🔍 Search before asking
|
|
- 🎯 Provide details when asking
|
|
- 🤝 Help others when you can
|
|
- 💚 Be patient and kind
|
|
|
|
Happy hardening! 🔒
|
|
|
|
---
|
|
|
|
*Last updated: 2025-10-05*
|