5b.deeper-cli-setup.md

Deeper CLI setup

Prerequisites:

• When editing files, either do so via a proper code editor like Visual Studio Code or on command line via nano, vi, vim etc.
• Do NOT use Notepad or a basic editor, they generally will ruin the formatting of YAML files.

Steps:

• Download the appropriate package from the main page here. to your host.
• Use whichever method you prefer to download the package, via a browser, wget, fetch, curl etc.
  • Package can be placed anywhere for now
• Unpack the download (you can use your package/archive manager, or do it via command line whatever your preference.

Example Linux/Mac

Example Windows

• Download via your browser, place into preferred directory
• Right click the download and select "Extract All" > "Extract", or or use whichever archive manager you prefer

---

Deeper CLI binary location

If you are on Linux or Mac the location of the deeper-cli binary should be in the following directory:

/var/db/newrelic-infra/newrelic-integrations/bin/

Example Linux/Mac

If you are on Windows the location of the deeper-cli.exe binary should be in the following directory:

C:\Program Files\New Relic\newrelic-infra\newrelic-integrations

Example Windows

---

Authenticating the Deeper CLI

The Deeper CLI needs to authenticate with your Deeper Connect.

• The credential file is an encrypted copy of your password so you do not need to expose your plain text password any longer. This is the exact same encryption and method the Atmos Web UI uses. Storing and using plain text passwords is insecure and bad practice, so this is why we encrypt our password.
• You can use the -e flag to encrypt your password inline (as below) or use --encrypt-password-prompt for a prompt based method.

Navigate to the directory where the deeper-cli is stored.

# Linux/Mac
cd /var/db/newrelic-infra/newrelic-integrations/bin/

# Windows
# open an administrative powershell, hit the windows key > search "powershell" > right click run as administrator

cd "C:\Program Files\New Relic\newrelic-infra\newrelic-integrations" 

Encrypt your credential

We use sudo or an administrative shell as the New Relic Infrastructure Agent directory is owned by root or windows admin.

# Linux/Mac
sudo ./deeper-cli -e yourAtmosPassword -v
or
sudo ./deeper-cli --encrypt-password-prompt -v

# Windows (in powershell)
.\deeper-cli.exe -e yourAtmosPassword -v
or
.\deeper-cli.exe --encrypt-password-prompt -v

• If you do not receive any error, your password should be successfully encrypted and it will say the path it wrote the credential too.
• You can view the encrypted credential in the following directory .deeper-cli.cache, likewise with windows you will see this directory.

---

Move the logging configuration file

In the extracted package directory there is also a log configuration file.

• Linux: deeper-cli-logging-nix.yml
• Windows: deeper-cli-logging-win.yml
• Mac: deeper-cli-logging-darwin.yml

Move your configuration file to one of the following locations depending on your operating system (create the logging.d directory if it does not exist, you will probably have to do this if you are on an ARM device).

• Windows: C:\Program Files\New Relic\newrelic-infra\logging.d

  

• Linux: /etc/newrelic-infra/logging.d/

  

• Mac: /etc/newrelic-infra/logging.d/

---

Editing your config file

Navigate into the extracted directory you will have the deeper-cli executable as well as a configuration file that we will need to edit first.

Example Config

Again, please do not use notepad or a basic text editor when editing .yml files, formatting and indentation are extremely important!

Personally I either use Visual Studio Code, nano or vi, depending on what system I am on.

You configuration file name will be either:

• Linux: deeper-cli-integration-nix.yml
• Windows: deeper-cli-integration-win.yml
• Mac: deeper-cli-integration-darwin.yml

Open your configuration file with your editor of choice. It will look something like the below.

---
integrations:
  - name: deeper-cli
    interval: 30s # how often the integration will collect data
    env:
      DEVICE_NAME: My Deeper Mini 01 # optional name to identify your deeper device
      DEVICE_TYPE: mini # optionally define your device type, eg. mini, nano, genesis
      NEWRELIC_OUTPUT: true # required to automatically format the output to new relic compatible
      NEWRELIC_ACCOUNT_ID: 1234 # replace with your account id
      NEWRELIC_INSERT_API_KEY: NRII-ABCDEF # replace with your insert key
  ### Enable second and third block below once you have seen the entity guid generated in the platform
  # - name: deeper-cli # generate peer data
  #   interval: 1m
  #   env:
  #     DEVICE_NAME: My Deeper Mini 01 # optional name to identify your deeper device
  #     DEVICE_TYPE: mini # optionally define your device type, eg. mini, nano, genesis
  #     NEWRELIC_OUTPUT: true # required to automatically format the output to new relic compatible
  #     GET_PEER_LIST: true # generate peer list data
  #     NEWRELIC_ACCOUNT_ID: 1234 # replace with your account id
  #     NEWRELIC_INSERT_API_KEY: NRII-ABCDEF # replace with your insert key
  #     NEWRELIC_NERDGRAPH_KEY: NRAK-ABCDEF # replace with your user api key https://one.newrelic.com/launcher/api-keys-ui.launcher
  # - name: deeper-cli # generate logs
  #   interval: 1m
  #   env:
  #     DEVICE_NAME: My Deeper Mini 01
  #     DEVICE_TYPE: mini # optionally define your device type, eg. mini, nano, genesis
  #     GET_SHARING_LOGS: 1 # get 1 day worth of sharing logs
  #     DECORATE_LOG_META: true # add additional log metadata to improve querying
  #     RAW: true # raw log lines
  #     NEW_ONLY: true # only output new logs
  #     OUTPUT_FILE: "/var/db/newrelic-infra/newrelic-integrations/bin/.deeper-logs/sharing.log" # location of where the log file will be written too
  #     NEWRELIC_ACCOUNT_ID: 1234 # replace with your account id
  #     NEWRELIC_NERDGRAPH_KEY: NRAK-ABCDEF # replace with your user api key https://one.newrelic.com/launcher/api-keys-ui.launcher

Update the values in both the blue and green sections. Check the configuration carefully as you will need to update the same field multiple times eg. NEWRELIC_ACCOUNT_ID appears 3 times.

Do not remove the comments (# hashtags) from the green section, we are keeping these two sections disabled for now.

Fields:

• DEVICE_NAME (Call it anything you like to easily identify it)

• DEVICE_TYPE (Defining this will make it easy to breakdown data by device type, so have a consistent convention)

• NEWRELIC_NERDGRAPH_KEY (The key you created in step 3)

• NEWRELIC_INSERT_API_KEY (The key you created in step 4)

• NEWRELIC_ACCOUNT_ID (In New Relic, in the top right hand drop down menu, go to "Manage your plan", you will see your account number next to "Plan management")

  

  If you need a full configuration file reference see:

• Linux: deeper-cli-integration-nix.yml

• Windows: deeper-cli-integration-win.yml

• Mac: deeper-cli-integration-darwin.yml

---

Enabling your configuration

With your configuration file updated, we are now ready to ingest data from your Deeper Connect device!

• Move your configuration file to one of the following locations depending on your operating system. You will require admin or sudo/root permissions as these directories require elevated permissions.

  • Windows: C:\Program Files\New Relic\newrelic-infra\integrations.d\

  • Linux: /etc/newrelic-infra/integrations.d/

  • Mac: /etc/newrelic-infra/integrations.d/

Restart the Infrastructure Agent

The New Relic Infrastructure Agent will usually hot reload integrations, but for good measure we can restart the service.

• Linux - This is dependent on your distributions system manager, restart this service newrelic-infra
  • eg. sudo systemctl restart newrelic-infra or sudo service newrelic-infra restart or whatever system manager your are using.
• Windows
  • Hit the windows key and search for "Services"
  • Or press Windows Key + R, and enter services.msc and hit enter
  • Scroll down the list find New Relic Infrastructure Agent and right click it and select restart

Check New Relic for your Deeper Connect!

If all went successfully it is now for the exciting part!

• Head back to New Relic here.

• If all went successfully, you will see your Deeper Connect device listed

  

• Clicking on your Deeper Connect device, will take you to a prebuilt dashboard (Your logs and inbound connection table will not appear yet).

• If you don't see it, clear the filter bar if anything has been applied, or click on "Deeper Connects" in the bottom left.

• If you still don't see anything it could be several reasons:

  • You have not moved the deeper-cli and your configuration file into the correct location
  • You configuration file is misconfigured or has become invalid YAML
  • You have not created your encrypted password credential
  • Restart this from the beginning of this document, or reach out for help.

  If you've been successful, continue to step 6 to capture your logs and connection data