Redirected from 
README
¶
Centralized SSH for Linux devices and servers behind NAT and firewalls.
Website · Documentation · ShellHub Cloud · Discussions
ShellHub is an SSH gateway that ties every login to a person on your team. A small agent on each
device dials out to the ShellHub server, and you reach the device through the server with ssh,
scp, sftp or the browser. The device needs no public IP or inbound port, whether it is a
server, a cloud instance or an embedded Linux device in the field.
Quickstart
ShellHub Cloud. Create a free account at cloud.shellhub.io. The console walks you through your first device.
Self-hosted. You need Docker with Compose, and ports 80 and 22 free on the host:
git clone -b v0.27.0 https://github.com/shellhub-io/shellhub.git
cd shellhub
make start
Open http://<your-server>/setup to create the admin account and its namespace, the group that
holds your devices and the people who can reach them. The
deployment guide covers HTTPS and production
settings.
Add a device. Run the installer on the device:
curl -sSf http://<your-server>/install.sh | sh
The agent prints a pairing code. Enter it in the console to pair the device, then open a shell from the console or from any SSH client:
ssh <user>@<namespace>.<device>@<your-server>
To enroll many devices without pairing each one, create a provisioning key under Add Device → Fleet and pass it to the installer.
Features
- Standard SSH. OpenSSH, PuTTY,
scp,sftpand port forwarding work unchanged. - Web terminal. Open a shell on any device from the console.
- SSH Identities. Every SSH login belongs to a person on your team, not to a key copied into
authorized_keys, and it works with the plainsshclient, with no wrapper to install. Remove someone from the team and their access ends on every device at once. - Access Policies. Default-deny rules for who reaches which devices and as which Linux user, managed in one place. A policy can also require a fresh sign-in before each session.
- Sessions. ShellHub logs every connection with the user, the source IP and the device.
- Tags. Group devices and filter by tag.
- Platforms. Packages for Yocto, Buildroot, FreeBSD and Snap.
Editions
| Edition | Runs on | Adds |
|---|---|---|
| Community | Your servers | This repository, Apache 2.0 |
| Cloud | Ours, shared | MFA, server-side recording, web endpoints, more namespaces, free to start |
| Enterprise | Ours, dedicated to you | MFA, server-side recording, web endpoints, more namespaces, SAML SSO |
See editions for the full comparison.
Contributing
Read CONTRIBUTING.md for the development setup and how to send a change. Ask questions and share ideas in Discussions; report bugs in Issues. Security reports go through SECURITY.md.
License
O.S. Systems develops ShellHub and releases it under the Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
agent
module
|
|
|
api
module
|
|
|
cli
module
|
|
|
connector
module
|
|
|
gateway
module
|
|
|
openapi
module
|
|
|
pkg
|
|
|
api/requests
Package requests defines structures to represent requests' bodies from API.
|
Package requests defines structures to represent requests' bodies from API. |
|
api/scope
Package scope makes the namespace an operation is bounded to a first-class value.
|
Package scope makes the namespace an operation is bounded to a first-class value. |
|
connectivity
Package connectivity reports a server's reachability as transitions rather than as attempts, so a component that retries for as long as it is offline logs when it loses the server and when it gets it back instead of once per retry.
|
Package connectivity reports a server's reachability as transitions rather than as attempts, so a component that retries for as long as it is offline logs when it loses the server and when it gets it back instead of once per retry. |
|
devicekey
Package devicekey reads the key pair a device enrols with: the agent's SSH host key, whose public half the device record stores as PEM.
|
Package devicekey reads the key pair a device enrols with: the agent's SSH host key, whose public half the device record stores as PEM. |
|
geoip
Package geoip helps in geolocation operations.
|
Package geoip helps in geolocation operations. |
|
pairingcode
Package pairingcode generates and validates short, human-readable codes — the kind a person reads off one screen and types on another (device pairing, invitation links).
|
Package pairingcode generates and validates short, human-readable codes — the kind a person reads off one screen and types on another (device pairing, invitation links). |
|
revdial
Package revdial implements a Dialer and Listener which work together to turn an accepted connection (for instance, a Hijacked HTTP request) into a Dialer which can then create net.Conns connecting back to the original dialer, which then gets a net.Listener accepting those conns.
|
Package revdial implements a Dialer and Listener which work together to turn an accepted connection (for instance, a Hijacked HTTP request) into a Dialer which can then create net.Conns connecting back to the original dialer, which then gets a net.Listener accepting those conns. |
|
testimage
Package testimage gives a test that builds a ShellHub Dockerfile the build arguments the Dockerfile declares without defaults: the versions pinned in versions.env at the repository root, the same file the compose wrapper and CI pass to their builds.
|
Package testimage gives a test that builds a ShellHub Dockerfile the build arguments the Dockerfile declares without defaults: the versions pinned in versions.env at the repository root, the same file the compose wrapper and CI pass to their builds. |
|
testport
Package testport publishes test containers on host ports below the kernel's ephemeral range, so that rootless Docker under pasta, which forwards only non-ephemeral ports, can reach them.
|
Package testport publishes test containers on host ports below the kernel's ephemeral range, so that rootless Docker under pasta, which forwards only non-ephemeral ports, can reach them. |
|
testrun
Package testrun owns the Docker objects a test process creates on a shared daemon.
|
Package testrun owns the Docker objects a test process creates on a shared daemon. |
|
webendpoints
Package webendpoints provides helpers for composing web-endpoint hostnames.
|
Package webendpoints provides helpers for composing web-endpoint hostnames. |
|
wsconnadapter/wsconnadaptertest
Package wsconnadaptertest connects a wsconnadapter.Adapter to a WebSocket peer over an in-memory pipe, so a test can drive the adapter's keep-alive inside a testing/synctest bubble without a socket or the real clock.
|
Package wsconnadaptertest connects a wsconnadapter.Adapter to a WebSocket peer over an in-memory pipe, so a test can drive the adapter's keep-alive inside a testing/synctest bubble without a socket or the real clock. |
|
api/openapi
module
|
|
|
server
module
|
|
|
ssh
module
|
|
|
tests
module
|