Domain Management Tools
Trisul includes two command line tools for managing domain nodes. These form the centre piece of Trisul 7.0 distributed environment.
- trisulctl_hub — used to manage a domain from a admin perspective
- trisulctl_probe — manage a domain from a probe
This section explains the various operations you can perform with these tools. For more details : see trisulctlhub Reference and trisulctl_probe Reference
Frequently Used Commands
Here are a few quick trisulctl_ commands to get you start using the domain tools. You can read the sections below for a more thorough explanation.
Common Commands for Probe
unpl@unplu14:~$ trisulctl_probe
start domain // start domain process (only once )
list nodes // show nodes active in domain
info context // show all contexts on all nodes
info context default // show context "default"
start context default // start context named "default" - on all probes/hub
stop context default // stop context named "default"
start context default@hub0 // start context "default" only on hub0
reset context default // delete data on context "default" and start over
importpcap /pcaps/pcapdump00.pcap // start context 'default' over pcap file
importpcap /pcaps/pcapdump00.pcap context="dat1" // import pcap into new context 'dat1'
testbench run /pcaps/pcapdump00.pcap // dev tool to test lua script over a pcap file
Quick commands for running on trisul-probe using trisulctl_probe
Common Commands for Hub
Many commands that work on trisulctl_probe also work from the hub. In addition, the hub CLI tool has commands to authenticate new probes, create a new domain certificate, etc that are not available in the probe node.
unpl@unplu14:~$ trisulctl_hub
start domain // start domain process (only once )
list nodes // show nodes active in domain
info context // show all contexts on all nodes
start context default // stop context named "default"
reset context default // delete data on context "default" and start over
install probe /tmp/probeEAST.cert // install a new probe cert
create context newcontext1 // create a new context called 'newcontext1'
Common commands you will want to run on trisulctl_hub
Uses of trisulctl_probe/hub
The trisulctl_hub and trisulctl_probe allow you to co-ordinate , manage,
and run commands across all the nodes in the domain. Without these tools
you would have to log in to each node and run the command manually. For
example, you can just run a command like start context default using
trisulctl_hub - this command will be executed on all nodes.
A short list of things you can do
- Check status of Trisul Probes if they are running
- Check database sizes on all nodes
- View log files from any node
- Start and stop all nodes or only particular nodes
- Install or delete new probes, hubs, or contexts
- LUA Workbench : A development environment to test your scripts
- Import PCAP tools
Many of these operations can also be performed using the web interface. However a familiarity with these tools is needed to manage a medium to large multi probe distributed Trisul. In fact, when you use operations like “Start Trisul Probe” from the web interface, behind the scenes the trisulctl_hub command “start context” is executed.
Invoking the Tools
The trisulctl_ tools are placed in /usr/local/bin when the probe/hub
packages are installed. The default install of Trisul puts the Probe and
Hub on a single machine, so both the trisulctl_hub and trisulctl_probe
are available.
To invoke the tools
root@ubuntu1604:~# trisulctl_probe
The trisulctl_ tools then connect to the Trisul domain using the following process.
- Check if there is a valid domain certificate file at /usr/local/etc/trisul-probe/domain0/domain0.cert.
- Read the domain-backend and domain-frontend connection end points from the certificate
- Use the certificate to establish a ZMQ CURVE authenticated connection to the domain endpoints
- Read and execute commands from CLI
In the following listing we type the list nodes command to query all
the nodes in the domain. If you had 3 probes you can see their details
here.
root@ubuntu1604:~# trisulctl_probe
Connecting to domain0
Trisul Network Analytics version 6.0.2762
Probe management tool
* found trisul-probe /usr/local/etc/trisul-probe/domain0/domain.xml
* connecting to domain0 at ipc:///usr/local/var/lib/trisul-probe/domain0/run/ctl_local_req
trisul_probe:ubuntu1604(domain0)>
trisul_probe:ubuntu1604(domain0)> list nodes
node-id name type register_time heartbeat_time
* config0 config0 CONFIG Mon Feb 6 11:36:01 2017 Mon Feb 6 11:36:01 2017
* hub0 hub0 HUB Mon Feb 6 11:36:01 2017 Mon Feb 6 11:36:01 2017
* probe0 probe0 PROBE Mon Feb 6 18:55:27 2017 Mon Feb 6 18:55:27 2017
* router0 router0 ROUTER Mon Feb 6 11:35:59 2017 Mon Feb 6 11:35:59 2017
trisul_probe:ubuntu1604(domain0)> quit
Closing socket
Terminating 0MQ
root@ubuntu1604:~#
CLI Features
The trisulctl_probe/hub tools have a powerful CLI. Some features are
- Single line commands can be entered on one line directly ; eg
trisulctl_probe start domaininstead of dropping into the CLI and then enteringstart domain - Tab completion
- Alias command to shortcut
- Unlimited history
Useful trisbashrc Bash Aliases
There is a very nifty set of bash aliases called trisbashrc on the
/usr/local/share/trisul-probe and trisul-hub directories. To add
these macros to your shell environment. See trisbashrc
Reference for a complete list of useful shortcuts.
Start and Stop Domain
On each node the domain processes need to be running at all times. The default Trisul installation packages automatically add a systemd script to start and stop the domains. You can also manually start and stop the domain as shown below.
Start Domain
The command to start a domain are.
| Command | Description |
|---|---|
start domain | Start domain processes on local node, no effect if domain is already running |
stop domain | Stop domain processes on local node. |
restart domain | Restart is an alias for stop + start |
Starting a domain results in processes like
trisul_cp_XXXrunning on the node. Tryps -ef | grep trisul_cpto see
Checking Successful Join
You can check if you have successfully joined a domain using a couple of commands
| Command | Description |
|---|---|
list nodes | print all nodes currently joined to domain |
info context | print all contexts on all nodes |
Stop the Domain
On quit the CLI tool exits but the domain processes still run in the
background. To stop it :
| Command | Description |
|---|---|
stop domain | stop domain |
Start and Stop Contexts
A context is a separate instance of Trisul. The default installation of
Trisul installs a context named default or context0
Start Context
trisulctl_probe Start/Stop context is the way you start and stop Trisul
The commands
| Command | Description |
|---|---|
start context default | Start the default context on all nodes |
start context context0 | Start the context named context0 - same as default |
start context default@hub0 | Start the context named default only on node hub0 |
start context default@probe0 | Start the context named default only on node probe0 |
The domain runs the command on all the relevant nodes and if any errors are seen, it is printed on screen. This has the same effect as if you login to Web Trisul as admin and then executed Context → Start/Stop Tasks → Start Probe/Hubs
Check Logs
You can check or tailf any log on any node by using the log command.
Type help log for examples.
Stop Context
The commands
| Command | Description |
|---|---|
stop context default | Stops the default context on all nodes |
stop context default@hub0 | Stop only the context on hub0 node. The context will still be running on other nodes. |
stop context default@probe0 | Stop only the context on probe0 node. The data collection and processing on probe0 alone will stop. A subsequent start context will resume the data processing. This is useful if you just want to restart a particular probe without touching the other nodes in the Trisul domain |
Info Context
You can check if you have successfully joined a domain using a couple of commands
| Command | Description |
|---|---|
info context default | Print context information for the default context |
info context | Print info about all contexts |
An example output of info context default is shown below, you can see
the two probeXX nodes and other details.
trisul_probe:trisulorg-ubuntu-1gb-sfo2-01(domain0)> info context default
node context_name version init state size_disk data_window #runs profile runmode
-----------------------------------------------------------------------------------------------------------------------------------
config0 default 6.0.2750 INIT RUNNING 180.0 kB 00h 00m 00s 0 profile0
hub0 default 6.0.2750 INIT RUNNING 61.751 GB 665h 45m 00s 0
probe0 default 6.0.2766 INIT RUNNING 5.071 GB 1343h 29m 44s 31 profile0 online_rxring
probeTRISUL default 6.0.2766 INIT RUNNING 169.15 MB 23h 33m 24s 2 profile0 online_rxring
probeUNLEASH default 6.0.2766 INIT RUNNING 12.478 GB 1041h 07m 24s 42 profile0 online_rxring
Delete vs Reset Context
There are two commands reset context and delete context - Both of
them ask for confirmation
- reset context —> delete the data from the context but keep the configuration. This is used if you want to purge all data and start over
- delete context —> delete the context itself. the data and the configuration are removed.
Note: You cannot delete the default context so that is treated as a reset
| Command | Description |
|---|---|
reset context default | Clear data but keep the configuration |
delete context default | Remove the entire context, data and config. You can create a new context with that name if you want. |
trisulctl_hub
The trisulctl_hub is the CLI tool for domain hub management. Think of
trisulctl_hub as a administrator tool.
For a complete list of commands check out the trisulctl_hub Reference
trisulctl_probe
The trisulctl_probe is the CLI tool for manage probes.
For a complete list of commands check out the trisulctl_probe Reference