3.2. Domain Management Tools
Trisul includes two command line tools for managing domain nodes. These form the centre piece of Trisul 6.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 trisulctl_hub Reference and trisulctl_probe Reference
3.2.1 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
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'
3.2.2 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.
- 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
- importpcap 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.
3.2.3 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:~#
3.2.4 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 domain
instead 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.
3.2.5 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.
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 |
trisul_cp_XXX
running on the node. Try ps -ef | grep trisul_cp
to seeChecking successful join
You can check if you have successfully joined a domain using a couple of commands
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 backgruound. To stop it :
stop domain |
stop domain |
3.2.6 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
The commands
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
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
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
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. |
3.2.7 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
3.2.8 trisulctl_probe
The trisulctl_probe
is the CLI tool for manage probes.
For a complete list of commands check out the trisulctl_probe Reference