Command-Line Interface (humioctl)

LogScale can be controlled using a command-line interface (CLI), called humioctl. Note that LogScale was formerly known as Humio.

The command takes sub-commands such as search and cluster to inspect and administer cluster properties or search and send data to LogScale.

To view a list of the available commands at any time, use humioctl help:

shell
Sending Data:

  Humio's CLI is not a replacement for fully-featured data-shippers like
  LogStash, FileBeat or MetricBeat. It can be handy to easily send logs
  to Humio, e.g examine a local log file or test a parser on test input.

To stream the content of "/var/log/system.log" data to Humio:

  $ tail -f /var/log/system.log | humioctl ingest -o

or

  $ humioctl ingest -o --tail=/var/log/system.log

Common Management Commands:
  users <subcommand>
  parsers <subcommand>
  views <subcommand>
	status

Usage:
  humioctl [subcommand] [flags] [arguments]
  humioctl [command]

Available Commands:
  actions               Manage actions
  aggregate-alerts      Manage aggregate alerts
  alerts                Manage alerts
  cluster               Manage cluster
  completion            Generate autocompletions script for the specified shell (bash or zsh)
  feature-flags         Manage feature flags
  files                 Manage lookup files
  filter-alerts         Manage filter alerts
  groups                Manage groups
  health                Health
  help                  Help about any command
  ingest                Send data to Humio.
  ingest-tokens         Manage ingest tokens
  license               Manage the Humio license [Root Only]
  packages              Manage packages
  parsers               Manage parsers
  profiles              List and manage configuration profiles.
  repos                 Manage repositories
  scheduled-searches    Manage scheduled searches
  scheduled-searches-v2 Manage scheduled searches
  search                Search
  status                Shows general status information
  tokens                Manage tokens
  users                 Manage users [Root Only]
  views                 Manage views

Flags:
  -a, --address string               The HTTP address of the Humio cluster. Overrides the value in your config file.
      --ca-certificate-file string   File path to a file containing the CA certificate in PEM format. Overrides the value in your config file.
  -c, --config string                Config file (default is $HOME/.humio/config.yaml)
      --format string                Change output format of commands, if supported. Valid formats: json
  -h, --help                         help for humioctl
      --insecure                     By default, all encrypted connections will verify that the hostname in the TLS certificate matches the name from the URL. Set this to true to ignore hostname validation.
  -u, --profile string               Name of the config profile to use
      --proxy-organization string    Commands are executed in the specified organization.
  -t, --token string                 The API token to use when talking to Humio. Overrides the value in your config file.
      --token-file string            File path to a file containing the API token. Overrides the value in your config file and the value of --token.
  -v, --version                      Print the client version

Use "humioctl [command] --help" for more information about a command.

humioctl returns a non-zero status code in the event of an error.

Installation

Install the CLI using one of the options below:

  • MacOS

shell
brew tap humio/humio
brew install humioctl

  • Linux (via Snapcraft)

shell
snap install humioctl

  • Nix

shell
nix-env -i humioctl

  • Any OS (via Go)

shell
go install github.com/humio/cli/cmd/humioctl@latest

Once installed, run humioctl. The application will guide you in setting up your environment - this process is described in the next section.

Initializing humioctl

The first time humioctl is run, it will need to be configured to connect to a default LogScale instance.

You need to provide two pieces of information during the initial configuration of humioctl:

  1. The URL for your LogScale cluster.
  2. A personal API token. If you don't have this already, the initialization routine can guide you to the settings page to obtain one.

To perform the initialization, run humioctl without any arguments and this will start the configuration process:

shell
humioctl
  , ,
  (O,o)
  |)__)
  -"-"-

  Welcome to LogScale

  This will guide you through setting up the LogScale CLI.

  Which LogScale instance should we talk to?

  If you are not using LogScale Cloud enter the address of your LogScale installation,
  e.g. http://localhost:8080/ or https://humio.example.com/

  Address (default: https://cloud.humio.com/ [Hit Enter]):

You will need to enter the URL of the default LogScale instance. The connection will be tested to ensure that it works. If the connection could not be verified you will be prompted again for the URL:

shell
==> Testing Connection...

==> Testing Connection...

==> Testing Connection...
[Ok]

If you are connecting to the US or EU cloud, or secured installation, you must enter your API token as displayed on your API token within your Account settings page. You can optionally open a web browser to the correct page.

default
Paste in your Personal API Token

To use LogScale's CLI you will need to get a copy of your API Token.
The API token can be found on the 'Account Settings' page of the UI.
If you are running LogScale without authorization just leave the API Token field empty.

Would you like us to open a browser on the account page? [Y/n]: n

API Token: ***********************

Once the API token has been added, the configuration will be saved:

shell
==> Logged in as: developer

==> Writing settings to: /home/user/.humio/config.yaml

The authentication info has been saved to the profile 'default'.
If you work with multiple user accounts or LogScale servers you can
add more profiles using `humio profiles add <name>`.

Bye bye now!

You can confirm correct operation of your cluster by using the humioctl status command:

shell
humioctl status
Status : OK
Address : http://localhost:8080/
Version : 1.31.0--build-32501--sha-a7699507657391712a8a0c2a22e2184f22a04a85
Username : developer

Ingesting Data

humioctl can be used to push data into LogScale. For example, to stream the content of /var/log/system.log data to LogScale:

shell
tail -f /var/log/system.log | humioctl ingest -o your-repo

It is important to note that while humioctl has some support for sending data to LogScale, it should not be used as the primary way to ship logs to LogScale. You should use something like Falcon LogScale Collector. See Ingesting Data for a list of available ingest tools.

@label and @session

When streaming data into LogScale using the ingest command, all events will be annotated with @label and @session attributes. @label gives you a way to tag your streams to easily find them again, for example:

shell
$ humioctl ingest --label=work-related --tail=/var/log/mysql.log your-repo

You can then query based on the label:

logscale
@label = "work-related" | groupby(loglevel)

@session is a unique ID that is generated for each run of the humioctl binary. This enables you to find results for this session and nothing else.

Profiles and Environment Variables

To make it easier to switch between different LogScale clusters, you can configure a profile for each cluster. The configuration file, containing the API token and server address for all profiles will be default be saved in $HOME/.humio/config.yaml.

Adding a new profile can be achieved with the following command:

shell
$ humioctl profiles add my-profile

You are then prompted to enter the URL and API token.

You can then make it the default profile with the following command:

shell
$ humioctl profiles set-default my-profile

The configuration file, ~/.humio/config.yaml stores the profile information, as shown in the following example:

shell
address: https://ls1.your-domain.com/
ca-certificate-file: ""
insecure: false
profiles:
    default:
        address: https://cloud.humio.com/
        ca_certificate: ""
        insecure: false
        token: <your-token>
        username: fred@your-domain.com
    john-profile:
        address: https://ls2.your-domain.com/
        ca_certificate: ""
        insecure: false
        token: <your-token>
        username: john@your-domain.com
    fred-profile:
        address: https://cloud.humio.com/
        ca_certificate: ""
        insecure: false
        token: <your-token>
        username: "fred@your-domain.com"
proxy-organization: ""
token: <your-token>
token-file: ""

In the previous example, fred-profile has been set as the default.

It is also possible to use environment variables to configure humioctl for your use. The environment variables take precendence over the default profile. The following shows an example from a Bash profile:

shell
# Your account API token. You can find your token in LogScale's UI under
# 'Your Account' in the account menu.
HUMIO_TOKEN=<token>

# The address of the LogScale server. E.g. https://cloud.humio.com/,
# or http://localhost:8080/
HUMIO_ADDRESS=<url>

# If access to the LogScale server requires trusting a specific Certificate Authority,
# for validating the certificate, you can specify CA certificate in PEM format.
# You can either point to a file with the certificate or provide it directly.
HUMIO_CA_CERTIFICATE=<ca-certificate>

# If access to the LogScale server uses an untrusted certificate and you
# are unable to provide a CA certificate, you can disable TLS certificate verification.
# NB: This should only ever be used on test clusters where you are in full
# control of the involved systems and underlying network.
# Do not use this for production use-cases.
HUMIO_INSECURE=<bool>

Open Source

The CLI is open source and freely available from GitHub. Contributions and suggestions are very welcome.

LogScale CLI GitHub Repository