In addition to starting and stopping the Cribl LogStream server, LogStream's command line interface enables you to initiate many configuration and administrative tasks directly from your terminal.

Command Syntax

To execute CLI commands, the basic syntax is:

cd $CRIBL_HOME/bin
./cribl <command> <sub-command> <options> <arguments>

Not all commands have sub-commands.

To see help for any command, append the --help option, for example:

./cribl vars --help

./cribl vars get --help

./cribl vars get -i myArray --help

The scope command is an exception: it has no --help option, but it has its own CLI Reference in the AppScope documentation.

Avoiding Surprises

Immediate Execution

As indicated in the sample output below, some commands take effect immediately.

Commands that require further input will echo the sub-commands, options, and arguments they expect.

Persistent Volumes

If you start LogStream with the CRIBL_VOLUME_DIR variable, all subsequent CLI commands should have this variable defined. Otherwise, those commands will apply LogStream's default directories, yielding misleading results.

You can set CRIBL_VOLUME_DIR as an environment variable, or you can explicitly include it in each command, as in this example:

CRIBL_VOLUME_DIR=<writable-path-name> /opt/cribl/bin/cribl status

Note that $CRIBL_VOLUME_DIR, when set, overrides $CRIBL_HOME.

Commands Available

To see a list of available commands, enter ./cribl alone (or the equivalent ./cribl help). To execute a command, or to see its required parameters, enter ./cribl <command>.

help

Displays a list of commands with a description (help) for each. Defaults to a selection of generally useful commands.

Usage

./cribl help [-a]

Options

-a              - Display the list of all commands, except for `scope`.

Sample Response

Cribl LogStream - 3.1.0-f765e418
Usage: [sub-command] [options] [args]

Commands:
help                - Display help
mode-master         - Configure LogStream as a master instance
mode-single         - Configure LogStream as a single instance
mode-worker         - Configure LogStream as a worker instance
reload              - Reload Cribl LogStream
restart             - Restart Cribl LogStream
boot-start          - Start Cribl LogStream
status              - Status of Cribl LogStream
stop                - Stop Cribl LogStream
version             - Print Cribl LogStream version

auth                - Cribl LogStream Auth
boot-start          - Enable/Disable Cribl LogStream boot-start
diag                - Manage diagnostics bundles
git                 - Manage worker groups config
keys                - Manage encryption keys
nc                  - Listen on a port for traffic and output stats and data
node                - Execute a JavaScript file
pack                - Manage Cribl Packs
pipe                - Feed stdin to a pipeline
vars                - Manage global variables

📘

As of version 3.0, LogStream's former "master" application components are renamed "leader." While some legacy terminology remains within CLI commands/​options, configuration keys/values, and environment variables, this document will reflect that.

mode-master

Configures Cribl LogStream as a Leader instance.

Usage

./cribl mode-master <options> <args>

Options

[-H <host>]             - Host (defaults to 0.0.0.0).
[-p <port>]             - Port (defaults to 4200).
[-n <certName>]         – Name of saved certificate.
[-k <privKeyPath>]      – Server path containing the private key (in PEM format) to use. Can reference $ENV_VARS.
[-c <certPath>]         – Server path containing certificates (in PEM format) to use. Can reference $ENV_VARS.
[-u <authToken>]        - Optional authentication token to include as part of the connection header.
[-i <ipWhitelistRegex>] – Regex matching IP addresses that are allowed to establish a connection.

Sample Response

Settings updated.
You will need to restart LogStream before your changes take full effect.

mode-single

Configures Cribl LogStream as a single-instance deployment.

Usage

./cribl mode-single [--help]

Sample Response

Settings updated.
You will need to restart LogStream before your changes take full effect.

mode-worker

Configures Cribl LogStream as a Worker instance.

Usage

./cribl mode-worker -H <host> -p <port> <options> <args>

The -H <host> -p <port> parameters are required.

Options

-H <host>          – Leader Node's Hostname or IP address.
-p <port>          – Leader Node's cluster communications port (defaults to 4200).
[-n <certName>]    – Name of saved certificate.
[-k <privKeyPath>] – Server path containing the private key (in PEM format) to use. Can reference $ENV_VARS.
[-c <certPath>]    – Server path containing certificates (in PEM format) to use. Can reference $ENV_VARS.
[-u <authToken>]   – Authentication token to include as part of the connection header. By default, this token is included and is set to 'criblmaster'.
[-e <envRegex>]    – Regex that selects environment variables to report to Leader.
[-t <tags>]        – Tag values to report to Leader.
[-g <group>]       – Worker Group to report to Leader.

Sample Response

Settings updated.
You will need to restart LogStream before your changes take full effect.

pack

Manages Cribl Packs.

Usage

./cribl pack <sub-command> <options> <args>

Sub-commands and Options

export              - Export Cribl Packs, args:
   -m <mode>        - Mode to export. Accepts: merge_safe, merge, default_only..
  [-o <filename>]   - Where to export the pack on disk.
  [-n <name>]       - Name to override the installed pack's name on export.
  [-g <group>]      - The worker group to execute within
install             - Install a Cribl Pack, args:
  [-d ]             - Run install in debug.
  [-f ]             - Force install.
  [-n <name>]       - Name of the pack to install; defaults to source.
  [-g <group>]      - The worker group to execute within.
list                - List Cribl Packs, args:
  [-v ]             - Display all pack info.
  [-g <group>]      - The worker group to execute within.
uninstall           - Uninstall a Cribl Pack, args:
  [-d ]             - Run uninstall in debug.
  [-g <group>]      - The worker group to execute within.
upgrade             - Upgrade a Cribl Pack, args:
  [-d ]             - Run upgrade in debug.
  [-s <source>]     - Provide the pack source.
  [-m <minor>]      - Only upgrade to minor version.
  [-g <group>]      - The worker group to execute within.

Sample Response

id          version  spec  displayName    author       description                          source                            
------------------------------------------------------------------------------------------------------------------------------
HelloPacks  1.0.0    ----  Hello, Packs!  Cribl, Inc.  A sample pack with a simple example  file:/opt/cribl/default/HelloPacks

reload

Reloads Cribl LogStream. Executes immediately.

Usage

./cribl reload [--help]

Sample Response

Reload request submitted to Cribl LogStream

restart

Restarts Cribl LogStream. Executes immediately.

🚧

Executing this command cancels any running collection jobs.

Usage

./cribl restart [--help]

Sample Response

Stopping Cribl LogStream, process 18
............
Cribl LogStream is not running
Starting Cribl LogStream...
...
Cribl LogStream started

start

Starts Cribl LogStream. Executes immediately. Upon first run, echoes LogStream's default login credentials.

Usage

./cribl start <options> <args>

Options

[-d <dir>]  - Configuration directory
[-r <role>] - Process role

Sample Response

Starting Cribl LogStream...
...
Cribl LogStream started

status

Displays status of Cribl LogStream, including the API Server address, instance's mode (Leader or Worker), process ID, and GUID (fictitious example below). Executes immediately.

Usage

./cribl status [--help]

Sample Response

Cribl LogStream Status

Address: http://172.17.0.3:9000
Mode: master
Status: Up
Software Version: 3.1.0-f765e418
Config Version: 347079c
Master: 0.0.0.0:4200
PID: 4100
GUID: e706052a-ace9-4511-a7c7-b58a414a07d3

stop

Stops Cribl LogStream. Executes immediately.

🚧

Executing this command cancels any running collection jobs.

Usage

./cribl stop [--help]

Sample Response

Stopping Cribl LogStream, process 3951
............
Cribl LogStream is not running

version

Displays Cribl LogStream version. Executes immediately.

Usage

./cribl version [--help]

Sample Response

Software Version: 3.1.0-f765e418

auth

Log into or out of Cribl LogStream.

Usage

./cribl auth <sub-command> <options> <args>

Sub-commands and Options

login             - Login to Cribl LogStream, args:
  [-h <oldHost>]  - undefined
  [-H <host>]     - Host URL (e.g. http://localhost:9000)
  [-u <username>] - Username
  [-p <password>] - Password
  [-f <file>]     - File with credentials
logout            - Logout from Cribl LogStream

Login Examples

Launch interactive login:

$CRIBL_HOME/bin/cribl auth login

Append credentials as command arguments:

$CRIBL_HOME/bin/cribl auth login -h <url> -u <username> -p <password>

📘

All -h and host arguments are optional, provided that the API host and port are listed in the cribl.yml file's api: section.

Provide credentials in environment variables:

CRIBL_HOST=<url> CRIBL_USERNAME=<username> CRIBL_PASSWORD=<password> $CRIBL_HOME/bin/cribl auth login

Provide credentials in a file:

$CRIBL_HOME/bin/cribl auth login -f <path/to/file>

--

Corresponding file contents:

host=<url>
username=<username>
password=<password>

boot-start

Enables or disables Cribl LogStream boot-start.

Usage

./cribl boot-start <sub-command> <options> <args>

Sub-commands and Options

disable             - Disable Cribl LogStream boot-start, args:
  [-m <manager>]    - Init manager (systemd|initd)
  [-c <configDir>]  - Config directory for the init manager
enable              - Enable Cribl LogStream boot-start, args:
  [-m <manager>]    - Init manager (systemd|initd)
  [-u <user>]       - User to run Cribl LogStream as
  [-c <configDir>]  - Config directory for the init manager

Sample Response

Enabling Cribl LogStream to be managed by initd...
boot-start enable command needs root privileges...
Enabled Cribl LogStream to be managed by initd as user=root.

diag

Manages diagnostic bundles.

Usage

./cribl pack <sub-command> <options> <args>

Sub-commands and Options

create              - Creates diagnostic bundle for Cribl LogStream, args:
  [-d ]             - Run create in debug mode
  [-j ]             - Do not append '.txt' to js files
list                - List existing Cribl LogStream diagnostic bundles

send                - Send LogStream diagnostics bundle to Cribl Support, args:
   -c <caseNumber>  - Cribl Support Case Number
  [-p <path>]       - Diagnostic bundle path (if empty then new bundle will be created)

Sample Response

Created Cribl LogStream diagnostic bundle at /opt/cribl/diag/logstream-zedborcdb72f-20210820T204405.tar.gz

git

Manages Worker Groups configuration.

Usage

./cribl pack <sub-command> <options> <args>

Sub-commands and Options

commit            - Commit, args:
  [-g <group>]    - Group ID.
  [-m <message>]  - Commit message.
commit-deploy     - Commit & Deploy, args:
   -g <group>     - Group ID.
  [-m <message>]  - Commit message.
deploy            - Deploy, args:
   -g <group>     - Group ID.
  [-v <version>]  - Deploy version.
list-groups       - List worker groups.

Sample Response

Successfully committed version 7c04de1

groups

Deprecated. See git.

keys

Manages encryption keys. You must append the -g <group> argument to specify a Worker Group. As a fallback, append the argument -g default, e.g.:
./cribl keys list -g default

Usage

./cribl keys <sub-command> <options> <args> -g <group>

Sub-commands and Options

add               - Add encryption keys, args:
  [-c <keyclass>] - key class to set for the key
  [-k <kms>]      - KMS to use, must be configured, see cribl.yml
  [-e <expires>]  - expiration time, epoch time
  [-i ]           - use an initialization vector
   -g <group>     - Group ID
list              - List encryption keys, args:
   -g <group>     - Group ID

Sample Response

Adding key succeeded. Key count=1

nc

Listens on a port for traffic, and outputs stats and data. (Netcat-like utility.)

Usage

./cribl nc -p <port> <options> <args>

Options

 -p <port>           - Port to listen on
[-s <statsInterval>] - Stats output interval (ms), use 0 to disable
[-u]                 - Listen on UDP port instead
[-o]                 - Output received data to stdout
[-t <throttle>]      - throttle rate in (unit)/sec, where units can be KB,MB,GB and TB

Sample Response

2021-08-20T22:44:30.457Z - starting server on 0.0.0.0:9999
2021-08-20T22:44:30.462Z - server listening 0.0.0.0:9999
2021-08-20T22:44:31.461Z - messages: 0, socks: 0, thruput: 0MBps
2021-08-20T22:44:32.466Z - messages: 0, socks: 0, thruput: 0MBps
...
2021-08-20T22:44:39.212Z - got connection: 127.0.0.1:37190
2021-08-20T22:44:39.213Z - got connection: 127.0.0.1:37192

node

Run with no options, displays a command prompt, as shown here:

> 

To execute a JavaScript file, you can enter path/filename at the prompt.

With the -v option, prints the version of NodeJS that is running.

With -e, evaluates a string. Write to console to see the output, for example:

./cribl node -e 'console.log(Date.now())'
1629740667695

Usage

./cribl node <options> <args>

Options

[-e <eval>] - String to eval
[-v]        - Prints NodeJS version

Sample Response

v14.15.1

pipe

Feeds stdin to a pipeline.

Usage

./cribl pipe -p <pipelineName> <options> <args>

Examples:

cat sample.log |  ./cribl pipe -p <pipelineName> 
cat sample.log |  ./cribl pipe -p <pipelineName> 2>/dev/null

Options

-p - Pipeline to feed data thru
[-d] - Include dropped events
[-c ] - Perform CPU profiling
[-a ] - Optional Cribl Pack context

Sample Response

...
{"time":"2021-08-20T20:37:00.017Z","cid":"api","channel":"commands","level":"info","message":"creating new pipeline","id":"main","conf":{"asyncFuncTimeout":1000,"functions":[{"id":"eval","disabled":false,"filter":"true","conf":{"add":[{"name":"cribl","value":"'yes'"}],"remove":[]}}]}}
{"time":"2021-08-20T20:37:00.019Z","cid":"api","channel":"pipe:main","level":"info","message":"start loading and initializing functions","count":1}
{"time":"2021-08-20T20:37:00.021Z","cid":"api","channel":"pipe:main","level":"info","message":"finished loading and initializing functions","count":1}
{"time":"2021-08-20T20:37:00.022Z","cid":"api","channel":"commands","level":"info","message":"START pushing stdin events","id":"main"}
{"time":"2021-08-20T20:37:00.028Z","cid":"api","channel":"GrokMgr","level":"info","message":"loaded grok patterns","count":152}
...

scope

Greps your apps by the syscalls. Executes immediately.

See the AppScope CLI Reference for usage and examples.

vars

Manages LogStream Global Variables.

Usage

./cribl vars <sub-command> <options> <args>

Sub-commands and Options

Sub-commands:
add                  - Add global variable, args:
   -i <id>           - Global variable ID
   -t <type>         - Type
   -v <value>        - Value
  [-a <args>]        - Arguments
  [-d <description>] - Description
  [-c <tags>]        - Custom Tags (comma separated list)
  [-g <group>]       - Group ID
get                  - List global variables, args:
  [-i <id>]          - Global variable ID
  [-g <group>]       - Group ID
remove               - Remove global variable, args:
   -i <id>           - Global variable ID
  [-g <group>]       - Group ID
update               - Update global variable, args:
   -i <id>           - Global variable ID
  [-t <type>]        - Type
  [-v <value>]       - Value
  [-a <args>]        - Arguments
  [-d <description>] - Description
  [-c <tags>]        - Custom Tags (comma separated list)
  [-g <group>]       - Group ID

Sample Response

[
  {
    "type": "number",
    "lib": "cribl",
    "description": "Sample number variable ",
    "value": "42",
    "tags": "cribl,sample",
    "id": "theAnswer"
  }
]