Configure and bootstrap


  • The node must be installed and able to access the Internet.
  • You need administrator-level command-line access to the node (for example, via SSH or a local console).
  • You must have an access token and device key (received from Cisco) that the node can use to access the Great Bear control plane.
  • The node must be able to access the Internet on TCP port 443.

  • If creating sites with multiple nodes, each hostname must be unique.
  • If creating sites with multiple nodes, the nodes must be able to reach each other via the default route.
    • You can check this with the following steps -
      • Run the command ip route get | grep -oP 'src \K\S+' on each node and make note of the IP address
      • Use the ping command to test connectivity between each of the nodes using the addresses found

If you need help with setting up the Raspberry Pi, see Assembling a Raspberry Pi.


  1. If you haven’t already done it, write the Ubuntu Server image to an SD card with the Raspberry Pi Imager, then boot the SD card in the Raspberry Pi.

  2. Login to the Raspberry using ubuntu as the username and the password. The system will ask you to create a new password.

    Note: The keyboard layout is ‘QWERTY’ by default.

  3. If the Raspberry connects to the Internet using a wired Ethernet connection, retrieve its IP address (for example, run ip a show dev eth0) so that you can ssh from another device to your RPi (ssh ubuntu@<raspberry-ip-address>).

    • Otherwise, see this tutorial for instructions to connect to Wi-Fi.
  4. Change the hostname from ‘ubuntu’ to a unique name.

    Run sudo nano /etc/hostname, change the name and save your changes.

    Note: Changing the hostname takes effect only after rebooting the Raspberry Pi in the next step.

  5. Upgrade the operating system of the Raspberry Pi:

    1. Run the following commands. Make sure that you accept the upgrade of the kernel. sudo apt update; sudo apt upgrade
    2. Install the extra-raspi package: sudo apt-get install linux-modules-extra-raspi
    3. Reboot the system: sudo reboot
  6. You will need to get your Hardware Identifier to onboard your node on the Great Bear dashboard. By default, the Hardware Identifier of the node is the MAC address of the first network interface. In order to find it, you can run the command ip a.

    Ifconfig command To use a different identifier, set the HARDWARE_ID environmental variable, for example: export HARDWARE_ID="xx:xx:xx:xx:xx:xx"

    Note: The HARDWARE_ID must be:

    • Unique within Great Bear, as this ID also identifies the node on the dashboard.
    • Between 8 and 128 characters long.
    • Include only ASCII letters (A-Za-z), numbers (0-9), and the :-_ characters.

    Using the MAC address, the serial number of the CPU, or a similar Universally Unique Identifier (UUID) is a convenient way to make sure the ID has not already been used within Great Bear.

  7. Bootstrap the node for Great Bear. Run the following command:

    curl | \
    TOKEN=<access-token> DEVICE_KEY=<device-key> sh

    Note: You can bootstrap the node with an agent showing more verbose logs by adding the LOG_LEVEL=DEBUG option.

  8. That’s it! Next you can Start using your node.


In case you encounter problems, see our Troubleshooting guide.

Powered down nodes or disconnected nodes

If you power off the node, or it loses the Internet connection, the Great Bear dashboard will show that the node is offline. If you power on the node, or the network connection is restored, it becomes online again.