Installing a Modular Sensor in KVM (SaaS)

This topic describes how to install a Modular Sensor on a KVM virtual machine using the installation script and QCOW2 image file downloaded from the Download Images tab in the System | Deployment | Sensor Installation page. Refer to the following sections for details:

Use our example as a guideline, as you might be using a different software version.

Stellar Cyber does not support the installation of third-party software on its virtual or physical device sensors.

About Modular Sensors

Sensors provide the data gathering foundation for Stellar Cyber's OpenXDR platform, gathering the right data with context. Modular sensors are purpose-built Stellar Cyber sensors that include both the host and the Stellar Cyber monitoring software. They are provided as both physical devices (Photon sensors) and virtual machine images for different target environments.

Previous releases provided a variety of different types of device sensors, including Network, Security, and Modular. Going forward, the only type of device sensor is Modular. You can use the Modular Sensor Profile to enable whatever sensor features you like, creating the same functionality provided by the different sensor types in previous releases.

A modular sensor lets you easily add the features you like to your sensor. This helps simplify your deployment and lets you manage the VM requirements for the sensors based on the modular features they use.

Modular Sensors always include log ingestion. From there, you can enable different features as part of your modular sensor profile:

  • Enable the Network Traffic feature to monitor the virtual environment, the physical environment if connected to the span port of a physical switch, or the LAN segment via a mirror port on a switch. The sensor monitors network and server response times and can identify applications.

    The sensor converts that information to metadata and forwards it to the DP as Interflow. The DP can then provide security, DDoS, and breach attempt detections.

  • Enable the Sandbox and IDS features to improve your security posture:

    • Sandbox lets you detect malware in files and network traffic through Stellar Cyber's integrated cloud service and also provides anti-virus services.
    • IDS lets you detect intrusion attempts using both files and network traffic.

Keep in mind that VM resource requirements increase as you add more features to the Modular Sensor Profile. Refer to Modular Sensor Specifications for details on the resources required to run different combinations of features in a Modular Sensor Profile, as well as how to use the show module and show module request CLI commands to compare provisioned resources against those required to run specific feature combinations. Stellar Cyber only enables a Modular Sensor Profile on a sensor if the host VM's resources can support it.

Prerequisites

You can install a KVM modular sensor in the following environments:

  • CentOS 7.3 (or later)
  • Ubuntu Server 16.04
  • Ubuntu Server 18.04
  • Ubuntu Server 20.04
  • Ubuntu Server 22.04
  • Ubuntu Server 24.04

Refer to Modular Sensor Specifications for details on the resources required to run different combinations of features in a Modular Sensor Profile. Provision your modular sensor according to the features that you plan on enabling.

You will need:

Verify VM Capabilities

Before installing any software, verify whether the system has the VM capabilities required. This can be done from the command line using the instructions below for Intel-based and AMD-based system:

Intel-Bases Systems

For Intel-based systems use the command:

cat /proc/cpuinfo | grep vmx

If no lines are listed then VM hardware support is not available. It must be enabled in the system BIOS.

AMD-Based Systems

For AMD-based systems use:

cat /proc/cpuinfo | grep svm

One line will be listed for each secure-VM core available. If no lines are listed then VM hardware support must be enabled in the system BIOS.

If VM capability is not reported by these commands, do not proceed until it is enabled.

Installing KVM and Linux Bridge Tools

The system requires KVM and Linux bridge tools. Install these as follows, depending on your version:

Ubuntu 16.04/18.04

Copy 
sudo apt-get update
sudo apt-get install -y qemu-kvm libvirt-bin virtinst bridge-utils qemu-utils virtinst virt-viewer genisoimage net-tools cpu-checker

Ubuntu 20.04/22.04/24.04

Copy 
sudo apt-get update
sudo apt-get install -y qemu-kvm libvirt-daemon-system libvirt-clients virtinst bridge-utils qemu-utils virt-viewer genisoimage net-tools cpu-checker

CentOS

Copy 
yum install net-tools qemu-kvm qemu-img virt-manager libvirt libvirt-python libvirt-client virt-install virt-viewer bridge-utils
systemctl start libvirtd
systemctl enable libvirtd

Obtaining the Installation File

You download the installation file for the Modular Sensor for KVM from the Download Images tab in the System | Deployment | Sensor Installation page. Use the following procedure:

Only users with the Deployment | Sensor Installation | Sensor Image Download privilege assigned to their profile in the System | Role-Based Access Privileges interface can download images.

  1. Navigate to the System | Deployment | Sensor Installation page.

  2. Set the Sensor Type dropdown to Modular Security Sensor.

  3. Set the Image Type to KVM.

    The display updates to show you the size of the file to be downloaded.

  4. Click the Download button. The system downloads the installation file (aella-modular-ds-5.x.x.qcow2.zip) along with its corresponding SHA-1 hash file.

  5. Unzip the installation file's contents (virt_deploy_modular_ds.sh and aella-modular-ds-5.x.x.qcow2).

Installing in Ubuntu 20.04/22.04/24.04

This section describes how to install a modular sensor in an Ubuntu 20.04/22.04/24.04 environment. Note the following:

  • The major difference between the instructions for Ubuntu 20+ and those for Ubuntu 16.04/18.04 is that Ubuntu 20.04+ uses the netplan utility for its network configuration.

  • The netplan configuration format changed in Ubuntu 22.04+. Separate examples of the relevant configuration files are provided for Ubuntu 20.04 and Ubuntu 22.04+ so you can see the differences.

Check the Host Resources and Interfaces

Before you start installing the sensor, you should check the configuration of the host Ubuntu server's network interfaces as well as its available system resources. Use the following commands to check the current system resources:

  • lscpu – Reports the total number of CPUs.

  • free -h – Reports the total system memory.

  • df -h – Reports the total system disk size.

You will need to take all these values under consideration when provisioning resources for the sensor VM later on.

Sample Host Configuration

For our sample installation, the host Ubuntu server has two physical network interfaces (ens160 and ens192) and will be configured as follows:

  • ens160 – For management connection

  • ens192 – For monitoring traffic mirrored from a switch SPAN port

The figure below summarizes the sample host environment:

Create Bridges for Management and Traffic Monitoring

Use the following procedure to create bridges for management and traffic monitoring:

  1. Check the current management interface configuration by viewing the contents of the YAML files stored in /etc/netplan. For example, here's how the 00-installer-config.yaml file for the ens160 management interface would look for both static IP and DHCP configurations in different Ubuntu versions (note that the netplan configuration format changed in Ubuntu 22.04, replacing gateway4 with to and via routes:

    • Static IP (Ubuntu 20.04)

      Copy 
      network:
        ethernets:
          ens160:
            addresses:
            - 10.33.2.99/24
            gateway4: 10.33.2.1
            nameservers:
              addresses:
              - 8.8.8.8
              search: []
        version: 2

    • Static IP (Ubuntu 22.04 and Later)

      Copy 
      network:
        ethernets:
          ens160:
            dhcp4: no
            dhcp6: no
            addresses:
              - 10.33.2.99/24
            route:
              - to: default
                via: 10.33.2.1
            nameservers:
              addresses: [8.8.8.8, 8.8.4.4]
              search: []
        version: 2

    • DHCP (Ubuntu 20.04)

      Copy 
      network:
        ethernets:
          ens160:
            dhcp4: true
        version: 2

    • DHCP (Ubuntu 22.04 and Later))

      Copy 
      network:
        ethernets:
          ens160:
            dhcp4: yes
            dhcp6: no
        version: 2

  2. Make a backup copy of the network configuration file. For example, for the 00-installer-config.yaml file:

    cd /etc/netplan
    sudo cp 00-installer-config.yaml 00-installer-config.yaml.orig

  3. Create bridges for the management interface and traffic mirroring interface by editing the 00-installer-config.yaml file. For our example:

    • The management interface (ens160) is configured to the br0-aio bridge.

    • The traffic mirroring interface (ens192) is configured to the br0-span bridge.

    Separate examples are provided below for both static IP and DHCP configurations in both Ubuntu 20.04 and Ubuntu 22.04 and later:

    Static IP Address (Ubuntu 20.04)

    Copy 
    network:
      ethernets:
        ens160:
          dhcp4: false
          dhcp6: false
        ens192:
          dhcp4: false
          dhcp6: false
      bridges:
        br0-aio:
          interfaces: [ ens160 ]
          addresses:
          - 10.33.2.99/24
          gateway4: 10.33.2.1
          nameservers:
            addresses:
            - 8.8.8.8
            search: []
          parameters:
            stp: false
            forward-delay: 0
        br0-span:
          interfaces: [ ens192 ]
          parameters:
            stp: false
            forward-delay: 0

      version: 2

    Static IP Address (Ubuntu 22.04 and Later))

    Copy 
    network:
      ethernets:
        ens160:
          dhcp4: no
          dhcp6: no
        ens192:
          dhcp4: no
          dhcp6: no
      bridges:
        br0-aio:
          interfaces: [ ens160 ]
          addresses:
          - 10.33.2.99/24
          route:
          - to: default
              via: 10.33.2.1
          nameservers:
            addresses:
            - [8.8.8.8, 8.8.4.4]
            search: []
          parameters:
            stp: false
            forward-delay: 0
        br0-span:
          interfaces: [ ens192 ]
          parameters:
            stp: false
            forward-delay: 0

      version: 2

    DHCP Address (Ubuntu 20.04)

    Copy 
    network:
      ethernets:
        ens160:
          dhcp4: false
          dhcp6: false
        ens192:
          dhcp4: false
          dhcp6: false
      bridges:
        br0-aio:
          interfaces: [ ens160 ]
          dhcp4: true
          dhcp6: false
          parameters:
            stp: false
            forward-delay: 0
        br0-span:
          interfaces: [ ens192 ]
          dhcp4: false
          dhcp6: false
          parameters:
            stp: false
            forward-delay: 0

      version: 2

    DHCP Address (Ubuntu 22.04 and Later)

    Copy 
    network:
      ethernets:
        ens160:
          dhcp4: no
          dhcp6: no
        ens192:
          dhcp4: no
          dhcp6: no
      bridges:
        br0-aio:
          interfaces: [ ens160 ]
          dhcp4: yes
          dhcp6: no
          parameters:
            stp: false
            forward-delay: 0
        br0-span:
          interfaces: [ ens192 ]
          dhcp4: no
          dhcp6: no
          parameters:
            stp: false
            forward-delay: 0

      version: 2

  4. Apply your changes to the netplan configuration with the following command:

    sudo netplan apply

  5. Use the brctl show command to make sure you can see both the br0-aio and br0-span bridges. For example:

    root@ubuntu-20-04-kvm:$ brctl show
    bridge name bridge id STP enabled interfaces
    br0-aio 8000.000c29226a14 no ens160     <<< look here
    br0-span 8000.000c29226a1e no ens192     <<<look here
    virbr0 8000.525400221195 yes virbr0-nic

  6. Use the ip addr command to verify that the management IP address is assigned to br0-aio.

    Copy 
    aella@ubuntu-20-04-kvm:~$ ip addr
    ...
    2: ens160: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq master br0-mgt state UP group default qlen 1000
        link/ether 00:0c:29:22:6a:14 brd ff:ff:ff:ff:ff:ff
    ...
    5: br0-aio: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
        link/ether 00:0c:29:22:6a:14 brd ff:ff:ff:ff:ff:ff
        inet 10.33.2.99/24 brd 10.33.2.255 scope global br0-mgt
           valid_lft forever preferred_lft forever
        inet6 fe80::402e:31ff:fe54:f037/64 scope link
           valid_lft forever preferred_lft forever
    6: ens192: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
        link/ether 00:0c:29:22:6a:1e brd ff:ff:ff:ff:ff:ff
        inet6 fe80::20c:29ff:fe22:6a1e/64 scope link
           valid_lft forever preferred_lft forever
    ...
    9: br0-span: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
        link/ether 00:0c:29:22:6a:1e brd ff:ff:ff:ff:ff:ff
        inet6 fe80::88a9:c7ff:feb1:9fc/64 scope link
           valid_lft forever preferred_lft forever

Create Installation Directory for Virtual Machine

Use the following commands to create an installation directory for your virtual machine and move the image you downloaded in Obtaining the Installation File to it:

Default Directory

sudo mkdir -p /var/lib/libvirt/images/mds/images

sudo mv aella-modular-ds-5.2.0.qcow2* /var/lib/libvirt/images/mds/images
Non-Default Directory

sudo mkdir -p /stellar/mds/images

sudo mv aella-modular-ds-5.2.0.qcow2* /stellar/mds/images/

Install the Sensor

This section describes how to install the sensor using the image and installation script you previously downloaded. Note the following regarding the example in this section:

  • The -span option in the installation script is not compatible with the netplan implementation in Ubuntu 20.04/22.04/24.04 and should not be used.

  • The example in this section assumes that the image has already been downloaded (the nodownload parameter is set to true). You can also set nodownload to false and have the script pull the image as part of the installation.

  • You can include installation parameters directly in the installation script's command line OR you can declare them as variables and then pass them to the script in the command line. This has the advantage of reusability and is the example provided below

  1. Switch to the root user with the sudo su command.

  2. Set the following variables, making sure to change the installdir to match the directory where you stored the image in the previous section.Note that this example creates a VM with 16 vCPUs, 32GB of memory, and a 128GB disk size. You can use the guidelines in Virtual Appliance Sizing Specifications to determine the VM size you need for your anticipated needs.

    The installation example at the end of this procedure provides the exact syntax to declare and pass these variables.

    Variable

    Comments
    version=5.2.0

     
    hostname=mds

    Set as desired.
    release=5.2.0s

     
    installdir=/var/lib/libvirt/images/mds

    Set to match the directory where you copied the sensor image in the previous section.
    cpus=16

     
    memory=$(expr 32 \* 1024)

    32GB
    disksize=128 # VM disk size (e.g. DO NOT put G suffix)

     
    nodownload=true

    When set to true, the installation script does not download the sensor image but uses the one in the specified installdir.
    bridge=br0-aio

    Management bridge name.
    ip=10.33.2.98

    VM IP address.
    netmask=255.255.255.0

    VM netmask.
    gw=10.33.2.1

    VM default gateway.
    dns=8.8.8.8

    VM DNS server address.

  3. Use the following command to verify that the installation parameters are set correctly based on the table in the previous step:

    printf "\n bash virt_deploy_modular_ds.sh -- --hostname=$hostname --release=$release --CPUS=$cpus --MEM=$memory --DISKSIZE=$disksize --installdir=$installdir --nodownload=$nodownload --bridge=$bridge --ip=$ip --netmask=$netmask --gw=$gw --dns=$dns \n"

  4. Use the following command to start the deployment:

    bash virt_deploy_modular_ds.sh -- --hostname=$hostname --release=$release --CPUS=$cpus --MEM=$memory --DISKSIZE=$disksize --installdir=$installdir --nodownload=$nodownload --bridge=$bridge --ip=$ip --netmask=$netmask --gw=$gw --dns=$dns

    If you already installed the libvirt-daemon-system daemon, you can ignore any errors similar to, "E: Package 'libvirt-bin' has no installation candidate".

Sample Syntax
Copy 
aella@ubuntu-20-04-kvm:~# version=5.2.0
aella@ubuntu-20-04-kvm:~# hostname=mds
aella@ubuntu-20-04-kvm:~# release=$version
aella@ubuntu-20-04-kvm:~# installdir=/stellar/mds
aella@ubuntu-20-04-kvm:~# cpus=16
aella@ubuntu-20-04-kvm:~# memory=$(expr 32 \* 1024) # 32GB
aella@ubuntu-20-04-kvm:~# disksize=128              # VM disk size (e.g. DO NOT put G suffix)
aella@ubuntu-20-04-kvm:~# nodownload=true           # skip to download the modular sensor image
aella@ubuntu-20-04-kvm:~#
aella@ubuntu-20-04-kvm:~# bridge=br0-aio            # management bridge name
aella@ubuntu-20-04-kvm:~#
aella@ubuntu-20-04-kvm:~# ip=10.33.2.98             # VM IP address
aella@ubuntu-20-04-kvm:~# netmask=255.255.255.0     # VM IP netmask
aella@ubuntu-20-04-kvm:~# gw=10.33.2.1              # VM IP gateway
aella@ubuntu-20-04-kvm:~# dns=8.8.8.8               # VM DNS server address
aella@ubuntu-20-04-kvm:~# printf "\n bash virt_deploy_modular_ds.sh -- --hostname=$hostname --release=$release --CPUS=$cpus --MEM=$memory --DISKSIZE=$disksize  --installdir=$installdir --nodownload=$nodownload --bridge=$bridge --ip=$ip --netmask=$netmask --gw=$gw --dns=$dns \n"

 bash virt_deploy_modular_ds.sh -- --hostname=mds --release=5.2.0 --CPUS=8 --MEM=32768 --DISKSIZE=128  --installdir=/stellar/mds --nodownload=true --bridge=br0-aio --ip=10.33.2.98 --netmask=255.255.255.0 --gw=10.33.2.1 --dns=8.8.8.8

aella@ubuntu-20-04-kvm:~# bash virt_deploy_modular_ds.sh -- --hostname=$hostname --release=$release --CPUS=$cpus --MEM=$memory --DISKSIZE=$disksize --installdir=$installdir --nodownload=$nodownload --bridge=$bridge --ip=$ip --netmask=$netmask --gw=$gw --dns=$dns
Changing memory to user customized memory  + 32768
Changing cpu to user customized cpu size  + 16
Wed, 17 Aug 2022 00:52:31 +0000 Destroying the mds domain (if it exists)...
/stellar/mds/images/aella-modular-ds-5.2.0.qcow2: OK
Checksum for /stellar/mds/images/aella-modular-ds-5.2.0.qcow2 success
Wed, 17 Aug 2022 00:52:34 +0000 Converting Qcow2 image to RAW format...
WARNING: Image format was not specified for 'mds.raw' and probing guessed raw.
         Automatically detecting the format is dangerous for raw images, write operations on block 0 will be restricted.
         Specify the 'raw' format explicitly to remove the restrictions.
Image resized.
image: mds.raw
file format: raw
virtual size: 128 GiB (137438953472 bytes)
disk size: 2.22 GiB
Wed, 17 Aug 2022 00:52:38 +0000 Installing the domain and adjusting the configuration...

Starting install...
Domain creation completed.
checking host 10.33.2.98
Fail to ping host 10.33.2.98
Waiting for ssh ready.
.ssh - ok
\n
Domain mds defined from domain-xml

Gen uninstall scripts...
Check Host health again after restarting...
checking host 10.33.2.98
ping host - ok
Waiting for ssh ready.
ssh - ok
\n
Wed, 17 Aug 2022 00:53:34 +0000 SSH to mds using 10.33.2.98 with  username 'aella'.

Attach a virtual interface to Modular Sensor VM and connect it to the traffic monitoring bridge (br0-span)

  1. Next, you need to attach a virtual interface to the Modular Sensor VM and connect it to the traffic monitoring bridge (br0-span in our example). Use the following command:

    virsh attach-interface --domain $hostname --type bridge --source $spanbr --model virtio --config --live --persistent

    Set the $hostname to the name you specified for your sensor VM during deployment (mds in this example).

  2. Use the following command to verify that you can see the attached interface in the Modular Sensor VM. Substitute the name of your host if you did not use mds:

    root@ubuntu-20-04-kvm:# virsh domiflist mds
    Interface Type Source Model MAC
    -------------------------------------------------------------
    vnet0 bridge br0-aio virtio 52:54:00:f3:3a:63
    vnet1 bridge br0-span virtio 52:54:00:38:11:80 <<< LOOK HERE

Disable TSO on Traffic Mirroring Interface

Modify the qemu script to disable TCP Segmentation Offload (TSO) on the traffic mirroring interface. You will need both the name of your VM (mds in our example) and the name of the interface (ens192 in our example) to make these modifications. If you used other values, change the values in bold in the script below to match your own deployment.

  1. Make a backup copy of the qemu script:

    cd /etc/libvirt/hooks
    cp qemu qemu.bak

  2. Add the lines below to the script and save changes to the file:

    #!/bin/bash
# aella_hook_ds_span_mds_start
if [ "${1}" = "mds" ]; then
    if [ "${2}" = "start" ] || [ "${2}" = "reconnect" ]; then
        i=0
        str="ens192"
        for port in $str
        do
            spanbr="br""${i}""-span"
            brctl setfd $spanbr 0
            brctl setageing $spanbr 0
            ethtool -K $port lro off
            ethtool -K $port gro off
            i=`expr $i + 1`
        done
    fi
fi
# aella_hook_ds_span_mds_end

  3. Stop the VM. For example:

    virsh shutdown mds

  4. Wait for the virsh list --all command to show shut off for the VM.

  5. Restart the VM:

    virsh start mds

Next Steps

Next, you'll log in to the sensor and configure it settings, followed by sensor authorization. These steps are the same for Ubuntu 20.04/22.04 as they are for Ubuntu 16.04/18.04. Proceed to Installing a Modular Sensor in KVM (SaaS) .

Installing in Ubuntu Server 16.04, 18.04, or CentOS 7.3

Installation Steps: Bridge Mode

Install Sensor VM

You install the Modular Sensor VM by running the installation script downloaded from the DP. The syntax is different depending on whether you are installing the sensor with an IP address retrieved via DHCP or a static IP address. You use the --bridge parameter to specify the bridge for the management port and the --span parameter to specify which ports are monitored by the sensor.

Installing the Sensor with an Address from a DHCP Server

Use the following command to install the Modular Sensor with a management IP address retrieved from a DHCP server. Substitute the desired value in place of mds1 for the hostname. Refer to Available Parameters for the Installation Script for a description of how each of these parameters are used.

sudo bash virt_deploy_modular_ds.sh -- --hostname=mds1 --span=eno2 --feature=mds --bridge=<bridgename>
Installing the Sensor with a Static IP Addresss

Use the following command to install the Modular Sensor with a static management IP address. Substitute the desired value in place of mds1 for the hostname and use the appropriate IP configuration for your environment:

sudo bash virt_deploy_modular_ds.sh -- --hostname=mds1 --bridge=<bridgename> [--ip=192.168.1.223] [--netmask=<netmask>] [--gw=192.168.1.1] [--dns=8.8.8.8] [--dns-search=example.com] [--installdir=<imagedir>] [--span=eno2]  --feature=mds
Available Parameters for the Installation Script

You can supply the parameters listed and described below for the virt_deploy_modular_ds.sh script. Note that each parameter must start with the -- string. This is required by the script.

  • --feature determines the sensor type. If the value is mds the installation will be a modular sensor.

  • --hostname specifies the name of the host. The VM name and the name of the sensor within Stellar Cyber are both set to this value.

  • --bridge names the bridge to use for the management interface.

  • --ip provides the static IPv4 address.

  • --netmask must be set to the net mask of the form 255.255.255.0.

  • --gateway specifies the IP address of the gateway.

  • --dns specifies the IP addresses of the DNS servers to use.

  • --dns-search provides the default domain name for DNS searches.

  • --installdir optionally specifies what directory will be used for the VM image installation.

  • --span provides a list of host Ethernet ports to be included in the aio-span bridge.

When the script is executed it installs the VM, and creates a Linux bridge named aio-span. The ports in the --span parameter are added.

Installation Steps: NAT Mode

The process for installation in NAT mode is the same as for bridge mode except that the VM connects to the virbr0 bridge that was created by the KVM installation.

The ip and associated parameters are set to a desired private address.

You must provide the necessary NAT services either through the host iptables system or externally to the box.

Applying a Token to the Installed Sensor

The next step in installing a Modular Sensor is to obtain and apply the token used to authorize and configure the installed sensor.

Obtaining a Token for the Installation

Tokens are required to authorize and configure the installation of a sensor image downloaded from the DP in the System | Deployment | Sensor Installation page. Tokens point the installed sensor to the correct DP, assign the specified tenant, and authorize the sensor installation.

Use the following procedure to obtain a token in the Tokens tab:

  1. Navigate to the System | Deployment | Sensor Installation page and click on the Tokens tab.

  2. If a token already exists for the target tenant for the sensor installation, you can either use the Copy button to copy it to the clipboard or use the Download button to download it as a file.

    • Copy the token if you plan on applying it by pasting it into a set token string <token> command in the CLI.

    • Download the token as a file if you plan on hosting the file on an HTTP server and referring to it in a set token url <token url> command.

    Refer to Assigning Tokens for a summary of the different ways in which tokens can be applied to a sensor installation.

  3. If there is not already an unexpired token for the target tenant, click the Generate button.

    The Generate Installation Token dialog appears:

  4. Select the tenant for the token from the Tenant dropdown. This is the tenant to which all sensors authorized with this token will be automatically assigned. The dropdown lists all tenants configured for your organization in the System | Tenants page.

  5. Click the Generate button.

    The system generates the token and displays its contents in the Token field. The dialog also updates to display the expiration date for the token, as illustrated below.

  6. You can use the Copy button to copy the token to the clipboard immediately, or simply close the dialog and retrieve the token from the Tokens tab later on.

Applying the Token to the Sensor

Tokens are required to complete the installation of a sensor image downloaded from the DP in the Download Image tab.

You apply tokens to sensors as the last step in the overall installation procedure:

  1. Log in to your new Sensor. The default username/password is aella/changeme. You are immediately prompted to change the password.

  2. Apply the token to the installed sensor from the sensor CLI with the set token command using one of the options in the table below:

    You only need to use one of the options in the table below. These are just two different ways to do the same thing – apply the token.

    Option 1. Copy and Paste the Token String

    Copy the token string from the Tokens tab and paste it into the CLI command. The syntax is as follows:

    set token string <pasted string>

    Option 2. Host the Token on an HTTP Server

    Download the token as a file from the Tokens tab, upload it to an HTTP server, and reference it in the set token command. The syntax is as follows:

    set token url http://<url to token>

    You can also use an HTTPS server. In that case, the specified URL must also include the username and password for the server using the following syntax:

    set token url https://<user:password>@URL>

  3. The CLI reports that the Sensor token is successfully set.

    If you receive an error message instead, it's possible that the token has expired. Refer to the Tokens tab to see the expiration date. If you are using the File technique, it's also possible that an extra space or line may have crept into your text file – check the file to make sure it includes only the token text.

  4. Wait a minute or so. Then, verify that the token was successfully applied using any combination of the following techniques:

    • Check the System | Sensors tab in the user interface to see that the sensor has registered itself successfully.

    • Verify that the show system command shows all services as running.

    • Verify that the show receiver command displays a receiver.

    • Verify that the show json command reports some data sent in the BYTE_SENT column.

Configuring a Static IP Address (Optional)

By default, the sensor uses DHCP for the management port's IP address. For ease of troubleshooting, however, Stellar Cyber recommends that you reconfigure the management port to use a static IP address. The procedure is as follows:

  1. Log in to your sensor. The default username/password is aella/changeme, but you changed this when you applied the token in the previous section.

  2. You can set IP parameters manually using commands similar to the following (substitute your own IP parameters for the ones shown in bold below):

    set interface management ip 192.168.14.100/255.255.255.0

    set interface management gateway 192.168.14.1

    set interface management dns 8.8.8.8

  3. Verify the IP settings with the show interfaces command.

  4. Log out with the quit command.

Configure NTP and Set the Timezone

Stellar Cyber strongly recommends that configure NTP and set the timezone for the sensor.

Refer to Best Practices for NTP and Timezones for details.