Install a node in VirtualBox

You can create virtual Great Bear nodes in VirtualBox. For testing purposes, you can even run nodes on your laptop. To prepare a virtual machine in VirtualBox to use as a Great Bear node, complete the following steps.

Prerequisites

  • Make sure that your system supports VirtualBox. At the time of writing the systems we have validated are Apple Mac x86 and Windows x86.
  • You have downloaded and installed VirtualBox.
  • You have downloaded the ISO installation image of Ubuntu Server 22.04
  • If creating sites with multiple nodes, each hostname must be unique.
  • The node must be installed and able to access the Great Bear control plane on the network level.

  • The node must be able to access the Internet on TCP port 443.

  • 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.
  • 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 1.1.1.1 | 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

Create a new VM

  1. Open VirtualBox and create a new virtual machine. The virtual machine must have at least:
    • 2 GB of memory
    • 8 GB of virtual hard disk
  2. Configure network access for the virtual machine. The virtual machine must have Internet access to be able to access the Great Bear control plane. (NAT or bridged access is recommended.)
  3. Launch the virtual machine and install the operating system.

Bootstrap the node

  1. Open a terminal on the node.

  2. (Optional) By default, the Hardware Identifier of the node is the MAC address of the first network interface. You can also type ifconfig or ip a to find it. 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.

  3. Run the following command to bootstrap the node:

    curl https://get.greatbear.io/pub/get.sh | \
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.

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

Troubleshooting

In case you encounter problems, see our Troubleshooting guide.

Stop or delete the VM

If you stop the VM, the Great Bear dashboard will show that the node is offline. You can start the node again to bring it back online later if needed.

If you delete the VM and create a new one you will have to register the new node on the Great Bear dashboard.