## 1. Project Overview & Quickstart (shellhub-io/LICENSE) # LICENSE Open-source repository shellhub-io/LICENSE ### Repository Details - **Repository:** [shellhub-io/LICENSE](https://github.com/shellhub-io/LICENSE) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (shellhub-io/docs) ## File: README.md # Website This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. ### Installation ``` $ yarn ``` ### Local Development ``` $ yarn start ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. ### Build ``` $ yarn build ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. ### Deployment Using SSH: ``` $ USE_SSH=true yarn deploy ``` Not using SSH: ``` $ GIT_USER= yarn deploy ``` If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. --- ## 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.