Command-Line Interface (humioctl)
LogScale can be controlled via a command-line interface (CLI), called humioctl; short for "Humio Control".
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 to get a summary of the available commands:
humioctl help
Sending Data:
LogScale'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 LogScale, 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 LogScale:
$ 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:
alerts Manage alerts
cluster Manage cluster
completion Generate autocompletions script for the specified shell (bash or zsh)
files Manage files
groups Manage groups
health Health
help Help about any command
ingest Send data to LogScale.
ingest-tokens Manage ingest tokens
license Manage the LogScale license [Root Only]
notifiers Manage notifiers
packages Manage packages
parsers Manage parsers
profiles List and manage configuration profiles.
repos Manage repositories
search Search
status Shows general status information
users Manage users [Root Only]
views Manage views
Flags:
-a, --address string The HTTP address of the LogScale 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)
-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 LogScale. 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.
To stream the content of /var/log/system.log
data to
LogScale:
tail -f /var/log/system.log | humioctl ingest -o
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 a datashipper like for example, Vector or Filebeat. See Ingesting Data for a list of available ingest tools.
Installation
Simply download the CLI using one of the options below, and run humioctl. The application will guide you in setting up your environment.
MacOS
brew tap humio/humio
brew install humioctl
Linux (via Snapcraft)
snap install humioctl
Nix
nix-env -i humioctl
Any OS (via Go)
go install github.com/humio/cli/cmd/humioctl@latest
Initializing humioctl
The first time humioctl is executed, it will need to be configured to connect to a default LogScale instance.
To perform the initialization, execute humioctl without any arguments and this will start the configuration process:
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 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.
==> 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.
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:
==> Logged in as: developer
==> Writing settings to: /home/mc/snap/humioctl/12/.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 by using the humioctl status command:
humioctl status
Status : OK
Address : http://localhost:8080/
Version : 1.31.0--build-32501--sha-a7699507657391712a8a0c2a22e2184f22a04a85
Username : developer
Open Source
The CLI is open source and freely available from Github. Contributions and suggestions are very welcome.