Skip to content

Commit 32add2f

Browse files
committed
docs: Add server configuration manual and manpages
Create comprehensive documentation for bssh-server and bssh-keygen: Man Pages: - docs/man/bssh-server.8 - System administration manual for bssh-server - docs/man/bssh-keygen.1 - User manual for SSH key generation tool Documentation: - docs/README.md - Documentation index and quick links - docs/quick-start.md - Getting started guide - docs/container-deployment.md - Docker and Kubernetes deployment guide - docs/security.md - Security best practices and hardening checklist - docs/audit-logging.md - Audit logging setup and SIEM integration All documentation includes: - Complete configuration reference - CLI options and examples - Best practices and security considerations - Integration examples (OTEL, Logstash, ELK, Grafana) - Troubleshooting guides Closes #144
1 parent 4147b29 commit 32add2f

7 files changed

Lines changed: 2495 additions & 0 deletions

File tree

docs/README.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# bssh Documentation
2+
3+
Welcome to the bssh documentation. This documentation covers both the bssh client and bssh-server.
4+
5+
## Quick Links
6+
7+
- **[Quick Start Guide](./quick-start.md)** - Get bssh-server running in minutes
8+
- **[Server Configuration](./architecture/server-configuration.md)** - Complete configuration reference
9+
- **[Security Guide](./security.md)** - Security best practices
10+
- **[Container Deployment](./container-deployment.md)** - Docker and Kubernetes deployment
11+
12+
## Documentation Index
13+
14+
### Getting Started
15+
16+
| Document | Description |
17+
|----------|-------------|
18+
| [Quick Start](./quick-start.md) | Installation and first run guide |
19+
| [Container Deployment](./container-deployment.md) | Docker and Kubernetes deployment |
20+
21+
### Server Administration
22+
23+
| Document | Description |
24+
|----------|-------------|
25+
| [Server Configuration](./architecture/server-configuration.md) | Complete configuration reference |
26+
| [Security Guide](./security.md) | Security best practices and hardening |
27+
| [Audit Logging](./audit-logging.md) | Audit logging setup and integration |
28+
29+
### Client Documentation
30+
31+
| Document | Description |
32+
|----------|-------------|
33+
| [CLI Interface](./architecture/cli-interface.md) | Command-line interface documentation |
34+
| [Interactive Mode](./architecture/interactive-mode.md) | TUI and interactive shell mode |
35+
| [SSH Jump Hosts](./architecture/ssh-jump-hosts.md) | ProxyJump and jump host support |
36+
| [Port Forwarding](./architecture/ssh-port-forwarding.md) | Local, remote, and dynamic forwarding |
37+
38+
### Migration Guides
39+
40+
| Document | Description |
41+
|----------|-------------|
42+
| [pdsh Migration](./pdsh-migration.md) | Migrating from pdsh to bssh |
43+
| [pdsh Examples](./pdsh-examples.md) | pdsh-style command examples |
44+
| [pdsh Options](./pdsh-options.md) | pdsh option compatibility |
45+
46+
### Architecture
47+
48+
| Document | Description |
49+
|----------|-------------|
50+
| [Architecture Overview](./architecture/README.md) | System architecture overview |
51+
| [SSH Client](./architecture/ssh-client.md) | SSH client implementation |
52+
| [SSH Config Parser](./architecture/ssh-config-parser.md) | SSH config file parsing |
53+
| [Executor](./architecture/executor.md) | Parallel execution engine |
54+
| [TUI](./architecture/tui.md) | Terminal user interface |
55+
| [Exit Codes](./architecture/exit-code-strategy.md) | Exit code handling |
56+
57+
### Man Pages
58+
59+
Man pages are located in [docs/man/](./man/):
60+
61+
| Man Page | Section | Description |
62+
|----------|---------|-------------|
63+
| [bssh(1)](./man/bssh.1) | 1 | bssh client manual |
64+
| [bssh-server(8)](./man/bssh-server.8) | 8 | bssh-server administration manual |
65+
| [bssh-keygen(1)](./man/bssh-keygen.1) | 1 | SSH key generation tool manual |
66+
67+
### Shell Integration
68+
69+
| Document | Description |
70+
|----------|-------------|
71+
| [Shell Config](./shell-config/README.md) | Shell integration and completion |
72+
73+
## Installation
74+
75+
### From Binary
76+
77+
```bash
78+
# Download and install binaries
79+
curl -LO https://github.com/lablup/bssh/releases/latest/download/bssh-linux-amd64.tar.gz
80+
tar xzf bssh-linux-amd64.tar.gz
81+
sudo mv bssh bssh-server bssh-keygen /usr/local/bin/
82+
```
83+
84+
### From Source
85+
86+
```bash
87+
git clone https://github.com/lablup/bssh.git
88+
cd bssh
89+
cargo build --release
90+
sudo cp target/release/bssh /usr/local/bin/
91+
sudo cp target/release/bssh-server /usr/local/bin/
92+
sudo cp target/release/bssh-keygen /usr/local/bin/
93+
```
94+
95+
### Man Page Installation
96+
97+
```bash
98+
sudo install -Dm644 docs/man/bssh.1 /usr/share/man/man1/bssh.1
99+
sudo install -Dm644 docs/man/bssh-keygen.1 /usr/share/man/man1/bssh-keygen.1
100+
sudo install -Dm644 docs/man/bssh-server.8 /usr/share/man/man8/bssh-server.8
101+
sudo mandb
102+
```
103+
104+
## Components
105+
106+
### bssh (Client)
107+
108+
A high-performance SSH client that can be used as a drop-in replacement for OpenSSH while also providing parallel execution capabilities for cluster management.
109+
110+
```bash
111+
# Single host (SSH compatibility)
112+
bssh user@host
113+
114+
# Multiple hosts
115+
bssh -H host1,host2,host3 'uptime'
116+
117+
# Using clusters
118+
bssh -C mycluster 'hostname'
119+
```
120+
121+
### bssh-server
122+
123+
A lightweight SSH server designed for container environments with built-in audit logging, file transfer filtering, and comprehensive security controls.
124+
125+
```bash
126+
# Generate configuration
127+
bssh-server gen-config -o /etc/bssh/server.yaml
128+
129+
# Generate host key
130+
bssh-server gen-host-key -t ed25519 -o /etc/bssh/ssh_host_ed25519_key
131+
132+
# Start server
133+
bssh-server -c /etc/bssh/server.yaml
134+
```
135+
136+
### bssh-keygen
137+
138+
SSH key generation tool compatible with OpenSSH key formats.
139+
140+
```bash
141+
# Generate Ed25519 key (recommended)
142+
bssh-keygen
143+
144+
# Generate RSA key
145+
bssh-keygen -t rsa -b 4096
146+
147+
# Generate with custom comment
148+
bssh-keygen -C "user@hostname"
149+
```
150+
151+
## Support
152+
153+
- **Issues**: [GitHub Issues](https://github.com/lablup/bssh/issues)
154+
- **Repository**: [GitHub](https://github.com/lablup/bssh)
155+
156+
## License
157+
158+
Apache License 2.0

0 commit comments

Comments
 (0)