swarmguard/agent repository overview

⁠Quick reference

• Product description:
  SwarmGuard Industrial⁠
• Maintained by:
  Inalp Solutions AG⁠
• Where to get help:
  Refer to the setup guide⁠ or email us at [email protected]⁠.
• Supported architectures:
  arm32v7, arm64, amd64, mips64, mips

⁠What is SwarmGuard

SwarmGuard redefines industrial networking by combining remote access with an overlay device network – the swarm. SwarmGuard builds secure communication links between remote users and industrial devices, as well as among devices themselves. Additionally, SwarmGuard introduces a hassle-free device onboarding and management experience that is unparalleled in the industry.

This agent container image is deployed on your industrial devices. Our user-friendly mobile app (SwarmGuard Industrial) sets up and monitors your overlay network. The agent establishes secure links directly with all onboarded peer devices.

⁠How to use this image

⁠Easy setup

This guide is here to assist you in establishing your swarm network, enabling you to link your Linux devices within a secure full-mesh overlay network. This works regardless of your devices' locations or the manner in which they are connected. It even operates if your devices are isolated from the Internet behind a NAT or firewall.

1. Sign up for SwarmGuard
   

   a. Please sign up⁠ for a SwarmGuard account.

   b. Download the SwarmGuard Industrial mobile app from either the Google Play Store⁠ or the Apple App Store⁠.

   c. Open the app and sign in with your account (email address and SMS authentication code).

2. Install Docker
   Prepare a first device for your swarm network by installing the Docker engine (if it isn't already installed). Follow these instructions for the supported platforms:

   • Raspberry Pi OS⁠
   • Ubuntu⁠
   • Debian⁠
   • CentOs⁠
   • Fedora⁠
   • RHEL⁠
   • SLES⁠
   • Other OS⁠

3. Install the SwarmGuard Agent
   You can either install a regular agent or alternatively an agent + ingress gateway (see below for more information).

   Regular Agent
   Run the following command to install a regular agent on your device:
   curl -fsSL https://swarmguard.io/install.sh | sh

   Agent + ingress gateway
   Run the following command to install an agent and make your device an ingress gateway:
   curl -fsSL https://swarmguard.io/install-gateway.sh | sh

4. Add your device to the swarm
   

   a. Start SwarmGuard by running swarm up.

   b. Use the SwarmGuard Industrial mobile application and scan the QR code issued by the swarm up command on the device. Your device is connected to your swarm now.

5. Add more devices to your swarm network
   Repeat steps 2 to 4 for additional devices.

⁠Good To Know

SwarmGuard autonomously creates a full-mesh overlay network encompassing all the registered devices, known as the swarm. Access devices within the swarm using the domain name <device-name>.swarm.

⁠Manual setup

If you intend to incorporate the SwarmGuard agent into your custom container management system, the provided docker-compose.yaml file offers guidance on embedding the container with your environment:

services:
  agent:
    image: swarmguard/agent:latest
    container_name: swarmguard-agent
    volumes:
    - agent-config:/etc/swarmguard/swarmd
    - agent-state:/var/lib/swarmguard/swarmd
    - /etc/hosts:/etc/hosts
    cap_add:
    - NET_ADMIN
    privileged: true
    network_mode: host
    restart: unless-stopped
volumes:
  agent-config:
    name: swarmguard-agent-config
  agent-state:
    name: swarmguard-agent-state

The behavior can be changed by the following environment variables:

• SG_L4GW: Set to 'builtin' to enable the built-in layer-4 gateway (Ingress Gateway).

⁠Ingress Gateway

An Ingress Gateway functions as a bridge between the public Internet and your private swarm network. By configuring one or more of your swarm devices as Ingress Gateways, provided they have a connection to the public Internet with a public IP address, you get the ability to forward designated ports to other devices within your private swarm network.

Instead of downloading and executing the install.sh script in step 4b, use the following command line instead:

curl -fsSL https://swarmguard.io/install-gateway.sh | sh

This command installs a docker-compose.yaml file that configures the SwarmGuard Agent container as a SwarmGuard Layer-4-Gateway. The Layer-4 gateway is managed remotely via your mobile application. To enable external access to a device port from the Internet, navigate to the device screen within the app and select Public Access. Subsequently, specify the desired port for opening, such as HTTPS (TCP/443). The app will display a public URL that can be used to access to the device port through one of your Ingress Gateways.

⁠Additional information

• Terms of Service⁠
• Privacy Policy⁠
• Data Mutation Form⁠