## 1. Project Overview & Quickstart (shellhub-io/shellhub) ## File: agent/README.md The ShellHub is a lightweight software component that runs the device and provide communication between the device and ShellHub's server. Its main role is to provide a reserve SSH server always connected to the ShellHub server, allowing SSH connections to be established to the device even when it is behind a firewall or NAT. ## Features - **Secure Communication:** The agent establishes encrypted connections between remote devices and the ShellHub server, ensuring data confidentiality and integrity during communication. - **Device Registration:** Upon installation on a new device, the agent registers it with the ShellHub server, making it accessible and manageable from the web interface. - **Authentication and Access Control:** The agent handles user authentication, allowing administrators to enforce access control based on user credentials and defined permissions. - **Session Management:** The agent manages SSH sessions initiated by users, providing secure remote access to registered devices through the ShellHub web interface. - **Heartbeat and Health Checks:** The agent sends regular heartbeat signals to the ShellHub server, indicating its status and health, facilitating device availability monitoring. # Getting Started TODO ## Configuration TODO # Compatibility The ShellHub Agent is compatible with various Linux distributions. For a list of supported operating systems and versions, please check the [compatibility documentation](). TODO: # Support If you need assistance or have questions about the ShellHub Agent, feel free to reach out to us on our [support forum](). > Please note that the ShellHub Agent is continually evolving, and some features may have changed or been added since this README was last updated. For the latest information, always refer to the official documentation and project repository. TODO --- ## File: devscripts/README.md # Devscripts This directory contains scripts which can be useful for development. They are not intented for regular use by end users. ## Requirements * Bash (although we try to avoid bashism in devscripts, things can happen) * docker-compose * HTTPie (https://httpie.org) * jq (https://stedolan.github.io/jq) ## Scripts * `add-device`: Add a test device to ShellHub (`--fake` for API-only, `--agent` for real agent container) * `get-devices`: Get devices from API * `lint-code`: Run code linter * `test-unit`: Run unit test * `gen-mock`: Generate/update mock objects for testing * `run-agent`: Runs a native agent, building if necessary, with the provided tag. * `update-go`: Updates the Go version of the project to . * `comment-scan`: Reports the comments the code style does not allow; `--diff` checks only what your branch adds, as CI does. --- ## File: gateway/README.md # Gateway The `gateway` is ShellHub's entry point. It terminates TLS and routes inbound HTTP requests and WebSocket connections to the server and the console. Routing is all it does. Authentication, the root aliases and the per-device tunnel subdomains are resolved by the API itself, which is what lets a Kubernetes deployment expose the server and the console on an Ingress with this proxy nowhere in the path. ## Architecture The binary is the proxy: it embeds [Caddy](https://caddyserver.com) as a library rather than supervising a separate process. Caddy registers its features as modules in `init()`, so what this proxy can do is the import list in `modules.go` — which is why adding a DNS provider is a line of Go here rather than a rebuild step with `xcaddy`. At startup the binary builds a Caddyfile from the environment, adapts it to Caddy's JSON configuration and loads it. Nothing is written to disk and nothing reloads it afterwards: a different configuration means a different container. ## Configuration Every setting comes from an environment variable, parsed into `GatewayConfig` in `config.go` and laid out by `Caddyfile.tmpl`. To read what an environment produces, ask the binary: ``` docker compose exec gateway /gateway config ``` ### TLS With `SHELLHUB_AUTO_SSL` enabled, Caddy obtains and renews certificates itself, answering the ACME challenge in memory. The wildcard that serves web endpoints is proven over DNS-01, using the provider named by `SHELLHUB_WEB_ENDPOINTS_DNS_PROVIDER`. `SHELLHUB_ACME_CA_SERVER` chooses which CA to ask. Leave it empty for Let's Encrypt; point it at their staging directory to rehearse without spending the real rate limit, or at a private CA. Staging certificates are signed by a root nothing trusts, so they validate the flow and never serve traffic — and switching back to production means clearing the storage first, or Caddy keeps using the account and certificates it already has. The account key and the certificates live in `/data`, which the image declares as a volume. Losing it means asking the CA for everything again, and Let's Encrypt caps how often it will answer, so a deployment that cares should mount a named volume there rather than rely on the anonymous one Docker creates. `SHELLHUB_TLS_CERT_FILE` and `SHELLHUB_TLS_KEY_FILE` serve a certificate the operator supplies instead of obtaining one, which is the only way to run HTTPS on a name no public authority will sign: an internal hostname, or a domain this deployment does not own. Both are paths inside the gateway container, so whatever holds them has to be mounted there. They are read only when `SHELLHUB_AUTO_SSL` is enabled, and they are all or nothing: setting one without the other stops the gateway from starting, checked even with automatic HTTPS off. A half-set pair is a typo in every case, and the alternative to refusing it is quietly asking a public CA for a name the operator meant to serve themselves. ### Behind a load balancer `SHELLHUB_PROXY` enables the PROXY protocol, and `SHELLHUB_PROXY_TRUSTED_IPS` names the peers allowed to use it. This list matters: a peer that may send the preamble is a peer that chooses the client's address, and that address is what the login lockout and the GeoIP rules are keyed on. The default trusts anyone, which is what the previous configuration did. ## Development `air` rebuilds the binary on change, including changes to `Caddyfile.tmpl` — the template is compiled in, so a rebuild is what applies it. ## 2. Official Technical Reference & Guides (shellhub-io/docs) ## File: docs/user-guides/devices/adding.md # Adding device In order to register a device on ShellHub, you need to install ShellHub agent onto it. The easiest way to install ShellHub agent is with our automatic one-line installation script, which works with all Linux distributions that have Docker installed and properly set up. :::tip For more information about other install methods, see [Installing Agent](/developers/agent/installing) from Developer's Guide. ::: From the Devices page, click **Add Device** button and follow instructions. After install the ShellHub agent on your device, you'll need to accept the device on the ShellHub UI in order to complete enrollment. Go to Devices -> Pending locate your device and click Accept button. --- ## File: docs/user-guides/devices/connecting.md # Connecting to a device You can establish an SSH connection to a device from the Devices page. :::tip For more information about other connection methods, see [Alternate connection method](#alternate-connection-method) section below. ::: From Devices page, choose the device you wish to connect to and click on **Connect** button. A dialog will pop up prompting you for the username and password of an existing user on the device's operating system. After providing credentials, click on Connect button. ## Alternate connection method ShellHub is compatible with any SSH client that supports a minimum of SSH version 2.0. Regardless of the connection method you choose, you need to know its SSHID address. From Devices page, choose the device you want to connect to and copy the device's SSHID address. In the next step, make sure to replace `` with the existing user on the device's operating system and `` with the SSHID copied before. ### Command line SSH Client Run the following command on your terminal: ``` ssh @ ``` ### Desktop and mobile GUI SSH Client #### PuTTY instructions Open Putty and fill in with the following information: | Field | Value | | ------------------------- | ------------------ | | Host Name (or IP address) | `@` | | Port | 22 | | Connection type | SSH | #### JuiceSSH instructions Open JuiceSSH, click on Quick Connect button and enter following address: ``` @ ``` --- ## File: docs/user-guides/devices/tagging devices.md # Tagging devices Device tags in ShellHub are a powerful feature that allows you to categorize and manage your devices more efficiently. By tagging devices, you can easily filter, search, and organize them based on specific criteria or attributes. ## Adding Tags to a Device To add tags to a device, follow these steps: 1. **Navigate to the Devices Page:** Log in to your ShellHub account and go to the "Devices" page. 2. **Edit Tags:** In the respective Actions menu, click on "Edit tags" option. 3. **Add, edit or remove Tags:** Enter the desired tags into the input field. Tags should be separated by commas or spaces. For example: `tag1, tag2, tag3`. :::warning You can use at maximum 3 tags per device. No special characters are allowed. ::: 4. **Save Changes:** Click the "Save" button to apply the tags to the device. ## Viewing Devices by Tags To view devices by tags, use the following steps: 1. **Navigate to the Devices Page:** Go to the "Devices" page in your ShellHub account. 2. **Filter by Tags:** Use the Tags menu to select the tags you want to filter. 3. **View Filtered Results:** The devices list will update to show only the devices that match the specified tags. ## Global Tag Management You can manage all tags on your namespace in a single place: 1. **Navigate to the Settings Page:** Go to the "Settings" page in your ShellHub account. 2. **Navigate to the Tags tab:** Click the "Tags" tab in the ShellHub settings. You can also go directly from [here](https://cloud.shellhub.io/settings/tags). 3. **Edit or remove Tags:** For each tag added you can edit or remove them. ## Best Practices for Tagging Devices - **Consistency:** Use a consistent tagging convention to ensure tags are uniform across all devices. - **Relevance:** Only use tags that are relevant and useful for categorizing your devices. - **Descriptiveness:** Use descriptive tags to make it clear what the tag represents. ## Example Use Cases - **Environment Tags:** Tag devices based on their environment, such as `production`, `staging`, `development`. - **Location Tags:** Tag devices based on their physical location, such as `office`, `datacenter`, `remote`. - **Role Tags:** Tag devices based on their role or purpose, such as `web-server`, `database`, `backup`. By effectively using device tags in ShellHub, you can streamline device management, improve organization, and enhance your ability to quickly locate and manage devices within your infrastructure. --- ## File: docs/user-guides/devices/tunnels.md # Using HTTP tunnels :::info This feature is only available in [ShellHub Cloud](https://shellhub.io) and [ShellHub Enterprise](https://www.shellhub.io/products/enterprise). ::: :::warning This feature is only available for **ShellHub Agent 0.18.3 or newer**. ::: ShellHub HTTP tunnels enable secure, direct access to HTTP services on devices with the ShellHub Agent, eliminating the need for SSH local port forwarding. This simplifies connectivity, allowing users to access web-based interfaces seamlessly from their browser. ## Use cases - **Web Application Access**: Expose a local web application (e.g., a dashboard or admin panel) running on a remote device to access it from anywhere. - **Remote API Access**: Expose an API running on a remote IoT device to test or interact with it from the cloud. - **Webhook Testing**: Enable external services (e.g., Stripe, GitHub, Twilio) to send webhooks to a development environment on a remote device. - **Remote Device Configuration**: Access the configuration interface of a remote network device without VPN or port forwarding. - **Viewing Logs & Monitoring**: Expose real-time logs or monitoring dashboards from a remote device. ## Create Tunnel On the device listing, click on *actions*, and access the device's details. Once there, access the menu, click on *create tunnel*. To create the tunnel, you need to specify the **host** address and the **port** where the service is running. It means you could point it to a service running on either your own machine or another machine on the device's network. You can also define a lifetime for a tunnel. A tunnel can live indefinitely, with an **Unlimited Timeout** or for a defined time. The time is reset every time the URL is accessed. After expiration, the tunnel will be inaccessible, unless recreated. If a new tunnel is created with the same **host** and **port**, the expired address will be kept. ## Using Tunnel The address for defined will be shown on the tunnel list with other information. After that, when accessing the link, you should see the application listing of the **host** and **port** defined. :::info It's worth noticing that [ShellHub Cloud](https://shellhub.io) and [ShellHub Enterprise](https://www.shellhub.io/products/enterprise) encrypts connections to the device, even if the service on it doesn't provide encryption. ::: --- ## File: docs/user-guides/firewall/create.md --- sidebar_position: 2 --- # Creating Firewall Rules From the Firewall Rules page, click **Add Rule**. You will the see the following form: --- ## File: docs/user-guides/firewall/index.md # Firewall Rules :::info This feature is only available in [ShellHub Cloud](https://shellhub.io) and [ShellHub Enterprise](https://www.shellhub.io/products/enterprise). ::: Firewall rules are security policies that control access to devices in ShellHub. They serve as a critical security mechanism for managing connections to your devices based on various parameters and conditions. Each rule can be applied globally, to specific devices using regular expressions, or via tags. [Members](../settings/namespace/members/index.md) with administrative privileges can create and manage firewall rules. Rules can be enabled or disabled at any time, providing flexibility in enforcing security policies without removing the rules entirely. Rules are enforced based on **Rule Priority** in descending order. A lower priority number indicates a higher precedence, and both positive and negative numbers can be used for fine-grained prioritization. :::tip When creating rules, consider leaving gaps between priority numbers (e.g., 10, 20, 30). ::: ## Common Use Cases Firewall rules can be applied to a wide range of security requirements. Here are some common scenarios: 1. **Corporate Network Access** - Allow connections only from company IPs: `10.0.0.*` and `172.16.*.*` 2. **Root Access Prevention** - Deny all connections to the `root` user for enhanced security 3. **Administrative Control** - Restrict admin users to specific networks: Allow `admin*` from `192.168.1.*` 4. **Development Environment** - Allow only `dev-*` users to access devices tagged with `development` 5. **Production Security** - Allow access to `prod-*` hostnames only from VPN IPs 6. **Contractor Access** - Restrict contractors to devices tagged with `contractor-accessible` --- ## File: docs/user-guides/firewall/policies.md --- sidebar_position: 1 --- # Policies Policies can **allow**, permitting connections that match the specified criteria or **deny**, blocking connections that match the specified criteria. Each policy can be configured using various parameters to create precise access control rules. ## Policy Parameters ### Source IP Controls access based on the origin IP address of the connection. You can: - Apply the rule to all IP addresses - Restrict access using regular expressions ### Username Manages access based on the authentication username of the connection. This parameter helps enforce user-level access controls across your infrastructure. ### Device Matching Determines which devices the firewall rule affects. You can configure this using three approaches: 1. **Global Application** - Applies the rule to all devices in your infrastructure 2. **Hostname Pattern** - Restricts the rule to devices whose hostnames match a specified regular expression 3. **Device Tags** - Limits the rule to devices that have tags matching the specified regular expression --- ## File: docs/user-guides/namespaces/connection-announcment.md --- sidebar_position: 2 --- # Connection Announcements Connection announcements are a custom message that are displayed every time a new SSH connection is established. --- ## File: docs/user-guides/namespaces/index.md # Namespaces Namespaces in ShellHub provide a structured and collaborative environment designed to streamline the management of devices, firewall rules, SSH keys, and more. At the core of ShellHub’s platform, namespaces promote efficient, secure, and isolated resource management, enabling teams or components to operate independently while remaining accessible for team collaboration. Each user must belong to at least one namespace, where resources are shared and organized. Within namespaces, users can become [members](../settings/namespace/members/index.md) and have roles and permissions tailored to their access needs. This enables collaborative management of devices and configurations while upholding robust security. Namespaces enhance security by enforcing firewall rules, such as blocking specific IPs, disabling root authentication, or limiting connections to predefined users. Additionally, private/public SSH keys can strengthen connection security within namespaces, adding another layer of control over access. Automation is also a key feature in namespaces. [API keys](../settings/namespace/api-keys/index.md) allow secure, programmatic access for integration and scripting. These API keys make it easier to automate tasks like device updates, firewall rule adjustments, and SSH key management, ensuring seamless operations. To help manage large device fleets, tags offer a flexible way to categorize devices within a namespace. Tags allow users to organize and retrieve devices based on specific criteria, simplifying device management by enabling quick identification, updating, or monitoring of grouped devices. --- ## File: docs/user-guides/namespaces/retrieving-your-tenant-id.md # Retrieving Your Tenant ID To connect your devices to ShellHub for remote management, you need your **Tenant ID**. This identifier links your device to your specific ShellHub namespace, ensuring secure and organized management of connected devices. ## Steps to Retrieve Your Tenant ID 1. **Log in to ShellHub** - Open [ShellHub Cloud](https://cloud.shellhub.io) in your browser or access your self-hosted ShellHub instance. - Enter your credentials to log in. 2. **Navigate to Your Namespace** - Once logged in, go to the **Namespaces** dropmenu in the left panel. - Select the namespace you wish to use for device management. :::warning If you are managing multiple namespaces, **ensure you are in the correct one**. ::: 3. **Open Settings** - In the left panel, select **Settings** under the namespace you’ve selected. - Go to **Namespace** section. 4. **Retrieve Your Tenant ID** - In the **Namespace** section, locate the **Tenant ID** field, which shows the unique Tenant ID for this namespace. - Copy the **Tenant ID** by selecting and copying its value. You’ll use this ID to configure devices and link them to this namespace. --- ## File: docs/user-guides/namespaces/switching.md --- sidebar_position: 1 --- # Switching Between Namespaces You can view your active namespace at the top of the sidebar. To switch to a different namespace, click on the dropdown menu located there, and select the desired namespace from the list. --- ## File: docs/user-guides/security/publickey-authentication.md # Using Public Key authentication Public Key authentication is a way of logging into an devices using a cryptographic key rather than a password which is the default method most SSH clients use to authenticate with remote devices, but it suffers from potential security vulnerabilities like brute-force login attempts. Using key-based authentication offers a range of benefits: * Allow multiple developers to log in as the same system user without having to share a single password between them. * Revoke a single developer's access without revoking access by other developers. * Make it easier for a single developer to log in to many accounts without needing to manage many different passwords. ## Creating a SSH key pair You can generate a new SSH key on your local machine by using the `ssh-keygen` utility from the OpenSSH suite. Run the following command in your terminal: ``` ssh-keygen -t ed25519 ``` :::caution This command may overwrite an existing key with the same name. ::: ## Add a public SSH key After you create an SSH key pair, you can upload your public key to ShellHub. :::note It’s safe to share your SSH public key to anyone because it cannot be used to re-create the private key. It can only be used to validate the user who holds the associated private key (which should never be shared). ::: From the Public Keys page, click on **Add Public Key** button and fill the form.