Skip to content

FAQ.md

Latest commit

 

History

History
338 lines (217 loc) · 8.45 KB

FAQ.md

File metadata and controls

338 lines (217 loc) · 8.45 KB
Raw

Frequently Asked Questions (FAQ)

General Questions

What is Server Utilities?

Server Utilities is a collection of production-grade tools for DevOps, SRE, and infrastructure teams. Each utility is independently versioned and can be used standalone.

Who should use these tools?

  • DevOps Engineers managing server infrastructure
  • SRE teams monitoring production systems
  • Security teams auditing server configurations
  • Compliance teams requiring inventory and version tracking
  • System Administrators managing multiple servers

Is it production-ready?

Yes! These tools are battle-tested in production environments. Each utility has comprehensive test coverage and follows security best practices.

Installation

How do I install the utilities?

Via Homebrew (recommended for macOS/Linux):

brew tap minademian/server-utilities
brew install server-audit

From source:

git clone https://github.com/minademian/server-utilities.git
cd server-utilities
make install

Which operating systems are supported?

  • Primary Support: Ubuntu 20.04+, RHEL 8+, macOS 11+
  • Tested On: Debian 10+, CentOS 8+, Amazon Linux 2
  • Shell: Bash 4.0+ or Zsh 5.0+

Do I need root access?

No! These tools are designed to work without root access. They use SSH to connect to remote servers and run read-only operations by default.

Configuration

How do I configure SSH access?

Create an SSH config file (~/.ssh/config) with your server details:

Host production-*
  User serviceaccount
  IdentityFile ~/.ssh/id_ed25519_servers
  StrictHostKeyChecking yes

Then reference servers in your server list file.

What's the difference between dry-run and production mode?

  • Dry-run mode (--dry-run): Uses test data, no actual SSH connections, safe for testing
  • Production mode (--production): Conservative settings, rate limiting, safe for production use
  • Normal mode: Balanced settings for regular use

Can I customize the checkers?

Yes! The architecture is pluggable. See the development guide for details on creating custom checkers.

Usage

How do I audit Java versions across my servers?

./server-audit --check java -s production_servers.txt

Can I check multiple things at once?

Yes! Use comma-separated values:

./server-audit --check java,tomcat,apache -s servers.txt

How do I save results to a file?

Use CSV output and redirect:

./server-audit --check java --csv > results.csv

What if I need to use a specific SSH key?

Use the -k flag:

./server-audit --check java -k ~/.ssh/production_key -s servers.txt

Troubleshooting

I'm getting "Permission denied (publickey)"

This means SSH key authentication is failing:

  1. Verify your SSH key is added to the target server
  2. Check your SSH config file
  3. Test SSH manually: ssh user@server
  4. Use the -k flag to specify the correct key

The tool is very slow

For large server fleets:

  1. Use production mode: --production (includes rate limiting)
  2. Adjust concurrency: -c 10 (default is 5)
  3. Check network latency to servers
  4. Consider using a jump/bastion host closer to targets

I'm getting timeout errors

  1. Increase timeout: -t 60 (default is 30 seconds)
  2. Check network connectivity to servers
  3. Verify servers are online and accessible
  4. Check if firewalls are blocking SSH

ShellCheck is showing errors

Run ShellCheck locally:

make lint

Fix any issues and ensure all scripts pass ShellCheck before committing.

Security

Is it safe to use in production?

Yes! Security features include:

  • SSH-only connections (no passwords)
  • Read-only operations by default
  • No root access required
  • Input validation and sanitization
  • Secure error handling
  • Rate limiting to prevent overwhelming servers

What data is collected?

Only the information you request:

  • Binary versions (e.g., Java version)
  • Installation paths
  • Running processes (only what's needed)

No sensitive data, credentials, or application data is collected.

How should I handle the output?

  • Store results securely (may contain server names and paths)
  • Use encryption for results containing sensitive information
  • Follow your organization's data retention policies
  • Consider using --csv with secure storage

Can I audit this tool's security?

Absolutely! The code is open source. Please:

  • Review the code on GitHub
  • Run your own security scans
  • Report vulnerabilities privately (see SECURITY.md)

Contributing

How can I contribute?

See our Contributing Guide for detailed information. Quick start:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Submit a pull request

I found a bug, what should I do?

  1. Check if it's already reported in Issues
  2. Gather debug information: DEBUG=1 ./server-audit ...
  3. Open a new issue using the bug report template
  4. Include steps to reproduce

Can I request a new feature?

Yes! Open a feature request or start a discussion.

How do I add a new checker?

See the development guide for step-by-step instructions.

Distribution

How do I publish to Homebrew?

For maintainers:

  1. Create a tap repository
  2. Write a Formula (see Homebrew docs)
  3. Test locally: brew install --build-from-source ./Formula/utility.rb
  4. Submit to your tap

How do I publish to Maven Central?

For Java utilities:

  1. Set up Sonatype account
  2. Configure GPG signing
  3. Update pom.xml with distribution management
  4. Run mvn deploy

See the Maven publish guide for details.

Performance

How many servers can I audit at once?

Tested with:

  • 100 servers: Excellent performance
  • 500 servers: Good performance with -c 10
  • 1000+ servers: Use production mode and increase timeout

How can I improve performance?

  1. Increase concurrency: -c 20
  2. Use a bastion/jump host close to targets
  3. Optimize network connectivity
  4. Run from a location close to target servers

Does it use a lot of bandwidth?

No. Each check is lightweight:

  • Java check: ~1-2 KB per server
  • Tomcat check: ~5-10 KB per server
  • Total for typical audit: < 100 KB for 10 servers

Comparison

How does this compare to Ansible?

  • Server Utilities: Lightweight, read-only auditing, no agent required
  • Ansible: Full configuration management, can make changes, requires setup

Use Server Utilities for quick audits and monitoring. Use Ansible for configuration management.

How does this compare to commercial tools?

Advantages:

  • Open source and free
  • Lightweight and fast
  • No agents or daemons
  • Easy to customize
  • Security-first design

When to use commercial tools:

  • Need enterprise support and SLA
  • Require advanced analytics/AI
  • Want a GUI/dashboard
  • Need compliance reporting features

Updates

How do I update to the latest version?

Via Homebrew:

brew update
brew upgrade server-audit

From source:

git pull
make install

How often are updates released?

  • Patch releases: Monthly or as needed for bugs
  • Minor releases: Quarterly with new features
  • Major releases: Annually with breaking changes

How do I know when updates are available?

  • Watch the repository on GitHub
  • Subscribe to releases
  • Check with: brew outdated (if using Homebrew)

Support

Where can I get help?

  1. Check this FAQ
  2. Read the documentation
  3. Search existing issues
  4. Ask in Discussions
  5. Open a new issue

Is commercial support available?

Yes! Contact us for:

  • Priority support and SLA
  • Custom feature development
  • Training and consultation
  • Enterprise licensing

How do I report a security vulnerability?

Do not open a public issue. Follow our Security Policy to report privately.

Still have questions?

Ask in GitHub Discussions or open an issue!