ShellShell
This guide describes the shell utility nw-shell that can be used to troubleshoot the operations of NetWitness management services like security-server, investigate-server, and correlation-server. It is the equivalent of the NwConsole utility used to interact with NetWitness capture services like Decoders and Concentrators. The shell utility is independent of the business logic of the service, and works the same with most NetWitness services.
FeaturesFeatures
The nw-shell utility implements the following features:
- Supports secure connections to the local NetWitness service instances.
- Supports navigation of the service tree to explore its operational state (for more information, see Tree View).
- Provides an intuitive display of configuration, metrics, and health-check information to help with troubleshooting.
- Supports scripting to automate simple administration tasks in field deployments.
- Supports Linux, OSX and Windows terminals.
InstallationInstallation
The nw-shell utility can be installed with the rsa-nw-shell RPM as shown here:
$ sudo yum install rsa-nw-shell
$ /usr/local/bin/nw-shell
████████ ██████ ██
██ ██ ██ ████
██ ██ ██ ██ ██
██ ████ ██████ ██ ██
██ ██ ██ ██ ██
██ ██ ██ ██ ██
██ ██ ███████ ██ ██
RSA NetWitness Shell. Version: 4.0.0
See "help" to list available commands, "help connect" to get started.
offline »UsageUsage
The primary goal of nw-shell is to help a human operator explore the runtime state of a NetWitness service. It is, essentially, an interactive program that invokes APIs on running NetWitness services. Each NetWitness service includes a system API that exposes its runtime state as a logical tree. The shell leverages the Tree API structure to present a hierarchical view of a service that is similar to a file system view. Users can navigate the tree by using the cd command to access directories, and can view or modify the corresponding configuration at the location, or invoke API methods and view the current state of components in the node.
The set of commands available to users at a given time depend on the current shell context, for example, their placement inside the logical tree. Certain commands, however, are always available, and we begin with a description of those commands.
System CommandsSystem Commands
Shell system commands operate on the shell itself, instead of the nodes of a connected service. These commands are always available.
| Command | Function | Example |
|---|---|---|
help [<command>]
|
Provides help on available commands or a particular command. | help or help connect |
clear
|
Clears the screen (shortcut Ctrl-l). | clear
|
exit or quit |
Exits the shell. | quit
|
history
|
Displays the history of previously-run commands. | history
|
- Use the
help <command>to explore the available commands. It is always available. nw-shellsupports tab completion of a command, and the applicable parameter names wherever possible. For example, pressing the Tab key after typingecompletes the command toexit.nw-shellalso supports a non-interactive mode where it executes scripts from a provided file, used by specifying the absolute filepath prefixed by the@argument. See Shell for details.
Available CommandsAvailable Commands
Built-In Commands
clear: Clear the shell screen.
exit, quit: Exit the shell.
help: Display help about available commands.
history: Display or save the history of previously run commands
script: Read and execute commands from a file.
stacktrace: Display the full stacktrace of the last error.
Context Commands
* cd: Change the current node. Usage: cd <path>
connect: Connect to a service. One of --service or --port must be specified.Usage: connect [--service <service>[.<id>]] [--broker amqp://localhost/rsa/system] [--host localhost] [--port] [--insecure false]
* where: Which service shell is connected to?
Token Commands
login: Authenticate to a service. Usage: login [connect-parameters]
login-insecure: Authenticate to a service providing user and password on the command prompt. The password is recorded in the shell history so this command must be used with care.Usage: login-insecure --user <user> --password <password> [connect-parameters]
* logout: Clear the authentication context: logout
* whoami: Who am I?
Tree Node Commands
* json: Print the current node as a JSON string
* show: Pretty print the current node
Tree Node List Commands
* config: Summarize configuration of the current subtree
* health: Summarize health of the current subtree
* ls: List the children of the current node. Usage: ls [<filter>] [--values] [--types]
* lsv: Shorthand for ls --values. Usage: lsv [<filter>] [--types]
* method: Summarize methods of the current subtree
* metrics: Summarize metrics of the current subtree
* snapshot: Snapshot the current subtree
Tree Node Method Commands
* invoke: Invokes the method that exists on the current method type node. Usage: invoke [argument] [--file jsonfile]
Tree Node Value Commands
* get: Get the value of the current node
* set: Set the value of the current node. Usage: set <new-value>
Commands marked with (*) are currently unavailable.
Type `help <command>` to learn more.
Help, History Command UsageHelp, History Command Usage
offline » help connect
connect - Connect to a service. One of --service or --port must be specified. Usage: connect [--service <service>[.<id>]] [--broker amqp://localhost/rsa/system] [--host localhost] [--port] [--insecure false]
...
...
offline » history
help
help connect
history
offline »
You can navigate previously-typed commands in nw-shell by using the Up and Down arrow keys, which can help minimize typing by recalling previously-executed commands.
Authentication CommandsAuthentication Commands
As an administration and monitoring tool, it is important that nw-shell authenticates users before handing them control over a running service. The following commands manage the shell authentication context:
| Command | Function |
|---|---|
login
|
Authenticates and retains tokens for future interactions. |
logout
|
Clears the security context and token. |
whoami
|
Prints a summary of the current identity. |
The login command can be used to authenticate the user and establish an identity. Service operators can log in once (against the NetWitness Security Server) and then use the token to connect to multiple services and perform administration based on the roles assigned. This single-sign-on workflow is simplified by separating the login and connect commands to allow the operator to authenticate once (using login) and then switch services seamlessly using connect.
In general, the login command takes the same parameters as connect (described below) to specify the service that performs the credential validation. For example:
offline » login
user: admin
password: ********
admin@offline » connect --service respond-server
INFO: Connected to respond-server (23e1dab7-0658-41a5-bb1e-d716a37d5ea5)
admin@respond-server:Folder:/rsa »
admin@respond-server:Folder:/rsa » connect --service investigate-server
INFO: Connected to investigate-server 2f21db20-4b50-48cf-8f7f-c0be0d1d1d12)
admin@investigate-server:Folder:/rsa »The current logged-in identity can be confirmed at any point using the whoami command. For example:
admin@offline » whoami
|
|
|
|
|
|
The shell security context can be cleared by using the logout command.
security-server:Folder:/rsa » logout
security-server:Folder:/rsa » whoami
You are not logged in.Some operations, such as setting certain configuration properties or invoking a method, require a certain RBAC. To perform such privileged operations, you need to authenticate with an identity that has the necessary permissions. For example:
security-server:Configuration » /rsa/logging/operations/max-file-count » get 10 security-server:Configuration:/rsa/logging/operations/max-file-count » set 15 ERROR: Failed to set the node value: Access is denied security-server:Configuration:/rsa/logging/operations/max-file-count » login user: admin password: ********** admin@security-server:Configuration:/rsa/logging/operations/max-file-count » set 15 security-server:Configuration:/rsa/logging/operations/max-file-count » get 15
Context-Changing CommandsContext-Changing Commands
The following commands change the current shell context.
| Command | Function | Options | Examples |
|---|---|---|---|
connect
|
Connect to a service | servicehost, port, http, broker |
connect --service security-server.d6a55b48...
|
cd
|
Change context to a node | cd /rsa/security, cd ../sys, cd .., cd |
Connecting to a ServiceConnecting to a Service
The shell can connect to services over AMQP or HTTP(S), however, AMQP is the preferred and default option.
To connect to a specific instance of a service, name and serviceId needs
to be supplied in the format:connect --service {service-name}.{serivceId}
For example, foo-server.d6a55b48-6103-46bd-9ead-3b4d589b302b.
If the service
identifier is skipped, it is assumed to be any,
for example, connect --service foo-server will connect with any service named
foo-server that is connected to the AMQP broker.
Change NodeChange Node
The cd command can be used to change the current node. Just like cd
on a file system shell, it takes relative or absolute paths as input and
changes the current context to the node at that path.
offline » cd
Command 'cd' was found but is not currently available because you are not connected to any service.
offline » connect
security-server:Folder:/rsa » cd log
security-server:Folder:/rsa/logging » cd ../security
security-server:Component:/rsa/security » cd /rsa/security/fips-mode
security-server:Configuration:/rsa/security/fips-mode » cd
security-server:Folder:/rsa »The shell prompt summarizes and presents the user’s current context. It
starts off with offline, and once the shell is connected to a service,
it displays the service name it is connected to, and the type and the path of
the current node. Once the user is authenticated, the userId is included in
the prompt.
Invoking cd before connecting to a service reminds
the user that some commands work only in certain contexts.
Note: Some commands are available only in certain contexts. For example, cd
works only when the shell is online. The Help command lists all the commands, but commands marked with (*) are unavailable
in the given context.
Certain node-specific commands are enabled only when the current node is
of a certain type. For example, method nodes support a command invoke,
which is not enabled for any other node type.
Node Display CommandsNode Display Commands
The following commands are available with all node types. They do not take any arguments, and display the node details for the user to review.
| Command | Function |
|---|---|
show
|
Pretty-print the current node. |
json
|
Print the current node as a JSON string. |
For example:
security-server:Configuration:/rsa/security/authentication/token-lifetime » show
|
|
|
| value
valueType defaultValue description |
10 hours
com.rsa.asoc.launch.api.helpers.Seconds 10 The time-to-live on a token. |
security-server:Configuration » /rsa/security/authentication/token-lifetime » json
{
"path" : "/rsa/security/authentication/token-lifetime",
"type" : "Configuration",
"value" : "10 HOURS",
"parent" : {
"path" : "/rsa/security/authentication",
"type" : "Component"
},
"attributes" : {
"defaultValue" : 10,
"valueType" : "com.rsa.asoc.launch.api.helpers.Seconds",
"description" : "The time-to-live on a token."
}
}The output of json dumps the API payload and may contain more details than those shown by show.
Node Value CommandsNode Value Commands
Configuration, Metric and Health nodes have values. Their current values can be obtained using the get command.
| Command | Function | Examples |
|---|---|---|
get
|
Get the current value of the node. | |
set
|
Update the value of the node. | set false, set '{"enabled": false}' |
For example:
security-server:Gauge:/rsa/process/hostname » get
"hostxyz.corp.emc.com"
security-server:Gauge:/rsa/process/hostname » cd /rsa/transport/http/secure
security-server:Configuration:/rsa/transport/http/secure » get
trueThe value of a Configuration node can be changed by invoking the set command. For example:
admin@security-server:Configuration:/rsa/security/pki/tls-protocols » show
|
|
|
| value
valueType description |
[TLSv1.2]
java.lang.String[] This property controls the TLS protocol versions supported by the applications. |
admin@security-server:Configuration:/rsa/security/pki/tls-protocols » set '["SSLv3"]'
admin@security-server:Configuration:/rsa/security/pki/tls-protocols » value
[
"SSLv3"
]Node List CommandsNode List Commands
Folder, Component and Method nodes can contain other nodes as their children. You can use the ls command to list the children nodes, their types, and where available, their current values.
| Command | Function | Options | Examples |
|---|---|---|---|
ls <filter>
|
List the child nodes of the current node. | types, values |
ls, ls cfg, ls --values |
lsv <filter>
|
Shorthand for ls <filter> --values |
types
|
lsv metrics ls name:fips |
For example:
security-server:Component:/rsa/process » ls
jvm Component
modules Component
current-time-utc Gauge
current-time-utc-pretty Gauge
fips140-mode Gauge
hostname Gauge
mode Gauge
service-id Gauge
service-name Gauge
status Gauge
uptime Gauge
uptime-pretty Gauge
version Gauge
version-full Gauge
version-raw Gauge
ready Method
shutdown Method
security-server:Component:/rsa/process » ls comp
jvm Component
modules Component
security-server:Component:/rsa/process » ls name:uptime
uptime Gauge
uptime-pretty Gauge
security-server:Component:/rsa/process » ls name:uptime --values
uptime Gauge 3713854
uptime-pretty Gauge 1 hour 1 minute 53 seconds
security-server:Component:/rsa/process » lsv
jvm
modules
current-time-utc 1483978142782
current-time-utc-pretty 2017-01-09T16:09:02.782Z
fips140-mode true
hostname hostxyz.corp.emc.com
mode Normal
service-id 1fb7572a-4d87-497e-a4da-802819c10a72
service-name no-op-server
status Running
uptime 512064
uptime-pretty 8 minutes 32 seconds
version 0.0
version-full 0.0.0.0
version-raw 0.0.0.0
ready
shutdownListing commands are not available on nodes that do not have children (for example, configuration or metric nodes):
security-server:Component:/rsa/process » cd hostname
security-server:Gauge:/rsa/process/hostname » ls
Command 'ls' exists but is not currently available because you are not logged in.Note: Values displayed in ls and lsv may be truncated for presentation purposes. Use get on the value node to get the complete (unaltered) value of a node.
Method Node CommandsMethod Node Commands
The method command shows all the available methods
and all the sub-folders under the current node.
security-server:Component:/rsa/process » method /rsa/process/ready /rsa/process/shutdown
On a node that is of Method type , the invoke command will invoke the method. For example:
security-server:Method:/rsa/process/ready » invoke { "ready" : true, "serviceId" : "84f36740-5ae7-409f-b14f-b17e98703983", "marketingVersion" : "0.0"}
If the method signature takes input, then invoke <input> will invoke the method with given parameters.
security-server:Method:/rsa/health/get » show
|
|
|
| output
input description |
java.util.List<com.rsa.asoc.launch.api.health.api.HealthStatus>
java.lang.String Get the details of a single composite health check @PAram id The health check id @return The composite health check |
|
|
|
| failed
invoked timer |
0
0 0.0 |
Method:/rsa/health/get » invoke 'rsa.health.checks.security-pki'
[
{
"name" : "rsa.security.pki.pki-health",
"status" : "Unhealthy",
"details" : {
"Reason" : "Using a self-signed certificate" }
}
]
For inline method execution with input payload, in cases where the input contains any special characters such as \, \n, \r, \t , ", the input needs to be properly escaped with a backslash (\).
In cases where method takes a complex payload, payload can be supplied with a file reference. In this case, payload does not need any special escaping.
Method:/rsa/configuration/collections/register » invoke --file /tmp/jsonfile.txtRun State of a ServiceRun State of a Service
Once nw-shell is connected to a service, commands like health, metrics,
config or snapshot can be used to retrieve the current state of the
service at the current node, and all the sub-folders under the current
node.
HealthHealth
The health command lists the health of the components, and the all the sub-folders, under the current node.
admin@security-server:Component:/rsa/process » health /rsa/process/jvm/memory-health Healthy /rsa/process/modules/module-health Healthy
Respond Server APIsRespond Server APIs
You can use nw-shell to retrieve and modify the incident details. In order for this to work, make sure that the relevant APIs are exposed. You can perform following actions using these APIs.
Retrieve IncidentsRetrieve Incidents
You can retrieve incidents using a single criteria. The criteria can include name, priority, risk score, status, alert count, etc. The invoke command returns all the incidents with the matching criteria.
Note: You must export the output to a file to avoid rollover in the shell output. You can query using single meta filters only, for example, filter by name or priority. Depending on the load, a large number of results might cause the request time-out.
Sample Query
admin@respond-server:Folder:/rsa » cd respond/incident admin@respond-server:Component:/rsa/respond/incident » cd find-incident-by-criteria admin@respond-server:Method:/rsa/respond/incident/find-incident-by-criteria » invoke '["<meta name>", "<meta value>", "<number of records>"]'
Examples
The following example command reads the query from an input file and exports the results to an output file.
invoke --file /root/incident_req.txt outputFile /root/output_incidents.json
In the above example, the incident_req.txt file contains the following information.
[root@SA ~]# cat incident_req.txt
["status", "ASSIGNED", "500"]
The output is exported to the output_incidents.json file that contains 500 incidents with ASSIGNED status.
The following are some more examples:
-
Retrieve incidents with testinc for rule as name and a maximum of 10 incidents.
["name", "testinc for rule", "10"] -
Retrieve incidents with HIGH priority and a maximum of 50 incidents.
["priority", "HIGH", "50"]"] -
Retrieve incidents with ASSIGNED status and a maximum of 500 incidents.
["status", "ASSIGNED", "500"]
Retrieve Incident DetailsRetrieve Incident Details
The invoke command is used to list the details of specific incidents.
Sample Query
admin@respond-server:Folder:/rsa » cd respond/incident admin@respond-server:Component:/rsa/respond/incident » cd find-by-ids admin@respond-server:Method:/rsa/respond/incident/find-by-ids » invoke '["INC-1", "INC-2"]'
The output is incident details in JSON format displayed in nw-shell.
Examples
You can use an input file containing the request to list the incident details.
admin@respond-server:Method:/rsa/respond/incident/find-by-ids » invoke --file /tmp/findIncidents.txt
The output is incident details in JSON format displayed in nw-shell.
In the above example, the file /tmp/findIncidents.txt file contains the following information.
[root@NWAPPLIANCE27144 ~]# cat /tmp/findIncidents.txt
["INC-10", "INC-12"]
You can store the incident details to an output file.
admin@respond-server:Folder:/rsa » cd respond/incident admin@respond-server:Component:/rsa/respond/incident » cd /rsa/respond/alert/add-alerts-to-incident admin@respond-server:Method:/rsa/respond/incident/find-by-ids » invoke '["INC-1", "INC-2"]' outputFile /root/result_output.json
The output is incident details in JSON format stored in the result_output.json file.
Retrieve AlertsRetrieve Alerts
You can retrieve alerts using a single criteria. The criteria can include any field that is part of the alert record (alert name, alert type, alert source, etc). The invoke command returns the alert with the matching criteria.
Note: You must export the output to a file to avoid rollover in the shell output. You can query using single meta filters only, for example, filter by name or type. Depending on the load, a large number of results might cause the request time-out.
Sample Query
admin@respond-server:Folder:/rsa » cd respond/alert admin@respond-server:Component:/rsa/respond/alert » cd find-alerts-by-criteria admin@respond-server:Method:/rsa/respond/alert/find-alerts-by-criteria » invoke '["<meta name>", "<meta value>", "<number of alerts to retrieve>", "<list of alert fields (include fields)>"]'
Note: If you provide <null> as the <list of alert fields> value, the output returns all the alert fields.
Examples
The following example command reads the query from an input file and exports the results to an output file.
invoke --file /root/alerts_req.txt outputFile /root/output_alerts.json
In the above example, the alerts_req.txt file contains the following information.
[root@SA ~]# cat alerts_req.txt
["alert.source","Event Stream Analysis", "20", "alert.severity"]
The output is exported to the output_alerts.json file that contains 20 alerts from Event Stream Analysis and the alert severity field included.
The following are some more examples:
-
Retrieve 20 alerts from Event Stream Analysis with the alert severity field included.
["alert.source","Event Stream Analysis", "20", "alert.severity"] -
Retrieve 20 alerts from Event Stream Analysis with all the alert fields included.
["alert.source","Event Stream Analysis", "20", "null"]
Add Alerts to an IncidentAdd Alerts to an Incident
The invoke command is used to add alerts to an existing incident. You will require alert IDs and Incident ID.
Sample Query:
admin@respond-server:Folder:/rsa » cd respond/alert
admin@respond-server:Component:/rsa/respond/incident » cd /rsa/respond/alert/add-alerts-to-incident admin@respond-server:Method:/rsa/respond/alert/add-alerts-to-incident » invoke '["INC-1","603dcc5091e818391ee57e1d","603dcc5091e818391ee57e1c", "603dcc5091e818391ee57e1e"]'
Alternatively, you can specify the add alert query in an input file.
invoke --file /tmp/add_alerts.txt
In the above example, the /tmp/add_alerts.txt file contains the following information.
[root@NWAPPLIANCE27144 ~]# cat /tmp/add_alerts.txt
["INC-1","603dcc5091e818391ee57e1d","603dcc5091e818391ee57e1c", "603dcc5091e818391ee57e1e"]
The first parameter is the incident ID (INC-1). The rest of the parameters are alert IDs (for example, 603dcc5091e818391ee57e1e) to be added to the incident mentioned in the first parameter.
The output is a list of alert IDs added to the incident.
Delete Alerts from an IncidentDelete Alerts from an Incident
The invoke command is used to remove alerts from an existing incident. You will require alert IDs and Incident ID.
Sample Query:
admin@respond-server:Folder:/rsa » cd respond/alert
admin@respond-server:Component:/rsa/respond/incident » cd /rsa/respond/alert/delete-alerts-by-alert-ids admin@respond-server:Method:/rsa/respond/alert/delete-alerts-by-alert-ids » invoke '["INC-1","603dcc5091e818391ee57e1d","603dcc5091e818391ee57e1c", "603dcc5091e818391ee57e1e"]'
Alternatively, you can specify the delete alert query in an input file.
invoke --file /tmp/delete_alerts.txt
In the above example, the file /tmp/delete_alerts.txt file contains the following information.
[root@NWAPPLIANCE27144 ~]# cat /tmp/delete_alerts.txt
["INC-1","603dcc5091e818391ee57e1d","603dcc5091e818391ee57e1c", "603dcc5091e818391ee57e1e"]
The first parameter is the incident ID (INC-1). The rest of the parameters are alerts IDs (for example, 603dcc5091e818391ee57e1e) to be removed from the incident mentioned in the first parameter.
The output is a list of alert IDs removed from the incident.
MetricsMetrics
The metrics command lists all of the available metrics,
and all the sub-folders, under the current node.
admin@respond-server:Component:/rsa/tree/node » metrics /rsa/tree/node/get/invoked 14 /rsa/tree/node/get/timer 5666541.077918259 /rsa/tree/node/list/invoked 12 /rsa/tree/node/list/timer 6652400.379371729
In the above example, /rsa/tree/node/get/invoked 14 shows that the
method get is invoked 14 times, and timer shows that it took on
average 5666541.077918259 nano seconds to process the get request.
Using cd into the timer node shows more details, such as rate of requests, for
the current node for per-minute and five minutes. For example:
admin@respond-server:Timer:/rsa/tree/node/get/timer » show
|
|
|
value
valueType
stdDeviation
fiveMinuteRate
max
count
sampleSize
oneMinuteRate
min
fifteenMinuteRate
meanRate
mean
|
|
ConfigConfig
The config command shows all the configuration properties in the
current node and all the sub-folders under the current node.
admin@respond-server:Component:/rsa/logging » config /rsa/logging/audit/max-file-count 10 /rsa/logging/audit/max-file-size 10 MB /rsa/logging/forward/categories [Audit] /rsa/logging/forward/destination SYSLOG_UDP /rsa/logging/forward/enabled true /rsa/logging/forward/host localhost /rsa/logging/forward/port 50514 /rsa/logging/forward/secure false /rsa/logging/levels /rsa/logging/operations/max-file-count 10 /rsa/logging/operations/max-file-size 10 MB
SnapshotSnapshot
The snapshot command combines metrics, configuration, and health of the
current state of the service node and all the sub-folders under the
current node. This command is very useful for troubleshooting purposes.
When opening a support case, take a snapshot dump
at the root node \rsa of a service that might be having issues, and
attach it to the case.
admin@security-server:Component:/rsa/security » snapshot /rsa/security/account/external/get-all/invoked 16 /rsa/security/account/external/get-all/timer NaN /rsa/security/account/external/get/failed 6 /rsa/security/account/external/get/invoked 6 /rsa/security/account/external/get/timer NaN /rsa/security/account/force-password-change/invoke 1 /rsa/security/account/force-password-change/timer NaN /rsa/security/account/get/invoked 123 /rsa/security/account/get/timer 902163.0 /rsa/security/account/password-policy/cannot-inclu false /rsa/security/account/password-policy/min-chars 8 /rsa/security/account/password-policy/min-lower-ch 0 /rsa/security/account/password-policy/min-non-lati 0 /rsa/security/account/password-policy/min-numeric- 0 /rsa/security/account/password-policy/min-special- 0 ----
ScriptingScripting
nw-shell supports non-interactive executions that can take commands from files. For example:
> cat /tmp/foo.script
connect --service security-server
cd /rsa/security/pki/ciphers
get
> time nw-shell @/tmp/foo.script
INFO: Connected to security-server (52c7b92c-23d5-4b3e-9973-31d8b1b27ec4)
[
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_DHE_RSA_WITH_AES_128_CBC_SHA"
]
nw-shell 5.89s user 0.33s system 305% cpu 2.032 totalnw-shell also has a built-in script which can be used to execute
scripts in the shell once the shell is launched.
offline » script --file /tmp/foo.script INFO: Connected to security-server (52c7b92c-23d5-4b3e-9973-31d8b1b27ec4) [ "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", "TLS_DHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_RSA_WITH_AES_128_CBC_SHA256" ]
Note: nw-shell is primarily meant to help a human to explore the runtime
state of a NetWitness Platform service. For most other purposes, it is
usually best to use the service published APIs.
Troubleshooting CommandsTroubleshooting Commands
The nw-shell utility provides troubleshooting commands to help recover from misconfigurations that may cause the service to work improperly.
fix-keystorefix-keystore
When a service’s keystore is corrupt or its SSL trust is broken with the rest of NetWitness, you can use the fix-keystore command to fix this issue. This command reads the keystore file of the services running on the host and attempts to reestablish trust with the NetWitness Platform CA. For example, the following is the command to repair the respond-server 's keystore:
>> fix-keystore --service respond-server
This command repairs the keystore keystore.p12 that is located at /etc/netwitness/respond-server. It does not modify the service’s original keystore. The repaired keystore can be found with the suffix
.good, for example, keystore.p12.good. If no fixes can be made to the keystore, this command does not write the new keystore.p12.good file.
Once the keystore repair is successful, the system admin can restore the service’s communication by renaming keystore.p12.good to keystore.p12 and restart the service.
print-keystoreprint-keystore
The print-keystore command prints the requested NetWitness Platform Service’s keystore certificates to the given output file in JSON format. Unless verbose is enabled, only a few key attributes of the certificates are printed to the file. For example, the following command prints the respond-server's keystore certificates.
>> print-keystore respond-server outputFile /tmp/crts
With verbose enabled:
>> print-keystore respond-server outputFile /tmp/crts verbose
reconstruct-keystore reconstruct-keystore
The reconstruct-keystore command can be used when a service's keystore needs to be restored to its original clean state.
The following command reconstructs the respond-server's keystore to the new file /etc/netwitness/respond- server/keystore.p12.new (it does not modify the original keystore).
>> reconstruct-keystore --service respond-server
To restore the service back to its healthy state, restore keystore.p12.new to keystore.p12, and restart the service.
Advanced CustomizationAdvanced Customization
The following JVM system properties can be used to customize certain
aspects of the nw-shell presentation:
| System Property | Controls | Default Value |
|---|---|---|
|
|
The width of text. |
100 |
|
|
The use of colors. |
true |
|
|
The prompt. |
|
|
|
The API timeout. |
30s |
These can be specified using the JAVA_OPTS environment variable. For example:
> export JAVA_OPTS="-Dtimeout=100s -Dconsole.width=40 -Dconsole.prompt=%s%s%s>" > export JAVA_OPTS="-Dconsole.colors=false" > nw-shell
The API timeout is a time unit which can use typical time unit values such as 30 MINUTES, 30 mins, 30 m, 5 seconds, 5 sec, 5s, 5, 8000 milliseconds, or 8000 ms (ms = milliseconds).
The value of console.prompt must contain placeholders (for example, %s) for
three strings which are replaced, in order, by:
- The node type
- A
separator (
:) - The node path
Setting console.colors to false
will not turn off all use of colors, it only disables colors used by
nw-shell in its output. The underlying libraries that the program
uses may still output some text in color.
