Nuix SDK – Installing Nuix RESTful Service

Getting Started: Installing on Windows

Thu, 07 Jan 2021 00:00:00 +0000

Nuix RESTful Service provides a wizard-based installer that guides you through the installation and initial configuration of the application. Follow the steps in this section to complete your installation of Nuix RESTful Service in a Windows environment.

If performing an upgrade, ensure that a backup of your existing Java Options is made prior to installation as these values will be overwritten. These values can be found in the bin/setenv.bat file within your installation directory. See Verifying Java Options after completing your upgrade for steps on adding these configurations back to installation.

Installation

To get started, perform the following steps to install:

Download the Windows installer from the Nuix Customer Portal.
Browse to the location that contains the installer.
Right-click on the installer and choose Run as administrator, even if you are already running as an administrator. The installer may take a moment to prepare for the installation. When the initial preparation is complete, follow the steps within the wizard to complete the installation.
From the Welcome Screen, click Next to begin.
Note

If a previous version of Nuix RESTful Service is already installed, the following options are provided:
- Update the existing installation
- Create a new installation in a separate location.
Choosing to update will bypass all further configuration steps within the wizard and begin the installation process using the configurations defined within the previous installation.
Read and understand the terms included in the Nuix End User License Agreement.
- If you agree to the terms, select I accept the agreement, and click Next.
If installing for the first time, choose a location to install Nuix RESTful Service.
- Click Next to accept the default location and proceed.
- Alternatively, click Browse to choose a specific location to install the application files.
Click Next to begin the installation.
On the License Server Configuration screen, provide the following details then click Next:
- Server address: The URL used to access a configured Nuix Management Server.
- Server port: The server port used to access the configured Nuix Management Server.
  
  Note
  To configure Nuix RESTful Service to use CLS for licensing, see Connecting to Nuix Cloud License Server (CLS) after completing the installation.
Enter credentials for an account that has access to the specified Licensing Server, then click Next.
Review and make changes, if necessary, to the details provided on the Java & Folder Options screen.

Option	Description
Java Options	Optimize the Java settings used by Nuix RESTful Service to suit your hardware specifications. Define one argument per line. Default settings are recommended for most configurations. For help or assistance with tuning your JVM settings, contact the Nuix Support team at https://nuix.service-now.com/support.
IP Address or Hostname	The URL that will be used to access Nuix RESTful Service.
Connection Timeout	Specify the amount of time that REST should wait for a response after accepting a connection. Use a value of -1 to indicate no timeout.
HTTP Port	The server port used to access Nuix RESTful Service.
Case Directory	Specify a location where case files are stored.
User Scripts Directory	Specify a location where user generated scripts are stored.
Logs Directory	Specify a location to save logs generated by Nuix RESTful Service.

After reviewing the Java & Folder Options screen, click Next to continue.
Specify how Nuix RESTful Service should be run:

Option	Description
Service	Run Nuix RESTful Service in the background as a Windows service.
Application	Run Nuix RESTful Service as a standalone application. See Starting in Application Mode after installation completes for details on starting the application.
Start Service	Select this checkbox, if the Service option was selected, to start the Nuix RESTful Service when installation completes.

Click Finish to complete the setup and exit the wizard.

Post-Installation Configurations

After completing the installation of Nuix RESTful Service, the following configurations should be reviewed.

Windows Service User Account

If Nuix RESTful Service is configured to be run as a Windows service, the default Log On account associated with the service must be changed when performing a new installation to ensure proper operation of the application.

Tip

If upgrading an existing installation, all previous configurations, including the service’s Log On account, are preserved.

To update the Log On account associated with Nuix RESTful Service:

Use the Keyboard shortcut Win + R to open the Windows Run dialog box.
Type services.msc in the text field, then press OK.
In the Windows Services Manager, locate the Nuix-Rest service.
Right-click on the service and select Properties.
Select the Log On tab.
Select This Account, and provide the appropriate credentials for an account to use
Click Apply.

Verifying Java Options

If upgrading from an installation earlier than version 7.8, backed up Java Options can be added back to the installation after the upgrade using the following steps.

To add any of these options to your existing installation:

Navigate to the location where Nuix RESTful Service is installed.

Default path: C:\Program Files\Nuix\Nuix RESTful Service
Locate and open Nuix-REST.vmoptions within a text editor.
Modify the file, adding one argument per line.
Save and exit the editor.
Restart Nuix RESTful Service.

Starting in Application Mode

If Nuix RESTful Service was configured to be run as a standalone application, the service must be manually started and stopped.

To start Nuix RESTful Service in Application Mode:

Open a command prompt.
Navigate to the location where Nuix RESTful Service is installed.

Default path: C:\Program Files\Nuix\Nuix RESTful Service
Start the application using the following command:

Nuix-REST.exe /run
Stop the application using the following key combination within the command prompt:

Ctrl + C

Verifying Your Installation

Once your installation is complete, complete the following steps to verify your deployment:

Open a web browser and enter the following URL

localhost:8080/nuix-restful-service/svc/v2/about
If the installation was successful, the response body will return with information about the RESTful service.

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-oem-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null 
}

API Documentation

The Nuix RESTful Service provides a robust Application Programming Interface (API) that enables you to integrate your product or application with the Nuix Engine. For information about the endpoints that are available within the API, refer to the Nuix RESTful Service API documentation.

The API reference documentation is included with Nuix Restful Service and can be accessed at the following URL after installation.

http://<localhost>:8080/nuix-restful-service/svc/docs

Getting Started: Install on Linux

Thu, 07 Jan 2021 00:00:00 +0000

Depending on the configuration of your system, Nuix RESTful Service can be installed into both graphical and non-graphical environments using the same installer.

Warning

A JRE is not bundled with the Linux installers provided by Nuix RESTful Service. The latest version of Java 11 for your environment must be installed prior to installing Nuix RESTful Service on Linux.

If performing an upgrade, ensure that a backup of your existing Java Options is made prior to installation as these values will be overwritten. These values can be found in the bin/setenv.sh file within your installation directory. See Verifying Java Options after completing your upgrade for steps on adding these configurations back to installation.

Prerequisites

The following prerequisites must be installed prior to using Nuix RESTful Service in a Linux environment.

GTK+ graphical user interface library
X11 Screen Saver extension library
Chromium browser (if using OCR)

Perform the following steps to install all prerequisites:

Open a terminal within your Linux environment:
Based on your operating system, enter one of the following commands to install the dependences:
- Debian/Ubuntu: apt-get install libgtk-3-0 libxss1 xvfb
If using the Nuix OCR Addon, install the Chromium browser using the following command:
```
sudo apt install --assume-yes chromium-browser
```
After installation completes, start the X-Server Virtual Framebuffer using the following command:
```
Xvfb :1 &
```
Note
This command only needs to be performed after the initial installation or if the xvfb process is ever terminated.

Installation

Perform the following steps to install Nuix RESTful Service.

Download the Linux installer from the Nuix Customer Portal.
Open a terminal and navigate to the directory that contains the installer.

Enter the following command to untar the installer:

tar xvf [path to installer]rest-OEM-linux_[version].tar

Enter the following command to assign execute privileges for the installer to the current user:
```
sudo chmod u+x rest-OEM-linux_[version].sh
```
Enter the following command to run the installer:
```
./rest-OEM-linux_[version].sh
```
The installer may take a moment to prepare the wizard. When complete, follow the steps within the wizard to complete the installation. If installing in a non-graphical environment, the following steps will be presented within the terminal.
From the Welcome Screen, click Next to begin.

Note

If a previous version of Nuix RESTful Service is already installed, the following options are provided:

Update the existing installation
Create a new installation in a separate location.

Choosing to update will bypass all further configuration steps within the wizard and begin the installation process using the configurations defined within the previous installation.

Read and understand the terms included in the Nuix End User License Agreement.
- If you agree to the terms, select I accept the agreement, and click Next.
If installing for the first time, choose a location to install Nuix RESTful Service.
- Click Next to accept the default location and proceed.
- Alternatively, click Browse to choose a specific location to install the application files.
Click Next to perform the installation.
On the License Server Configuration screen, provide the following details then click Next:
- Server address: The URL used to access a configured Nuix Management Server.
- Server port: The server port used to access the configured Nuix Management Server.
  
  Note
  To configure Nuix RESTful Service to use CLS for licensing, see Connecting to Nuix Cloud License Server (CLS) after completing the installation.
Enter credentials for an account that has access to the specified Licensing Server, then click Next.
Review and make changes, if necessary, to the details provided on the Java & Folder Options screen.

Option	Description
Java Options	Optimize the Java settings used by Nuix RESTful Service to suit your hardware specifications. Define one argument per line. Default settings are recommended for most configurations. For help or assistance with tuning your JVM settings, contact the Nuix Support team at https://nuix.service-now.com/support.
IP Address or Hostname	The URL that will be used to access Nuix RESTful Service.
Connection Timeout	Specify the amount of time that REST should wait for a response after accepting a connection. Use a value of -1 to indicate no timeout.
HTTP Port	The server port used to access Nuix RESTful Service.
Case Directory	Specify a location where case files are stored.
User Scripts Directory	Specify a location where user generated scripts are stored.
Logs Directory	Specify a location to save logs generated by Nuix RESTful Service.

After reviewing the Java & Folder Options screen, click Next to continue.
Specify how Nuix RESTful Service should be run:

Option	Description
Service	Run Nuix RESTful Service in the background as a Windows service.
Application	Run Nuix RESTful Service as a standalone application. See Starting in Application Mode after installation completes for details on starting the application.
Start Service	Select this checkbox, if the Service option was selected, to start the Nuix RESTful Service when installation completes.

Click Finish to complete the setup and exit the wizard.

Post-Installation Configuration

After completing the installation of Nuix RESTful Service, the following configurations should be considered.

Verifying Java Options

If upgrading an existing installation to version 7.8, any backed up Java Options can be added back to the upgraded installation using the following steps.

To add any of these options to your existing installation:

Navigate to the location where Nuix RESTful Service is installed.
- Debian/Ubuntu default path: /opt/nuix-restful-service
Locate and open Nuix-REST.vmoptions within a text editor.
Modify the file, adding one argument per line.
Save and exit the editor.
Restart Nuix RESTful Service.

Starting in Application Mode

If Nuix RESTful Service was configured to be run as a standalone application, the service must be manually started and stopped.

To start Nuix RESTful Service in Application Mode:

Open a terminal.
Navigate to the location where Nuix RESTful Service is installed.
- Debian/Ubuntu default path: /opt/nuix-restful-service
Start the application using the following command:
```
./nuix-rest start
```
Stop the application using the following command:
```
./nuix-rest stop
```

Verifying Your Installation

Once your installation is complete, complete the following steps to verify your deployment:

Open a web browser and enter the following URL

localhost:8080/nuix-restful-service/svc/v2/about

If the installation was successful, the response body will return with information about the RESTful service.

 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-oem-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}

Getting Started: Docker

Wed, 06 Jan 2021 00:00:00 +0000

Follow the procedures in this section to install and deploy the Nuix RESTful Service Docker image within a Ubuntu Linux environment using Compose.

The Nuix RESTful Service Docker image is intended for development purposes only. Usage of this installation in a production environment is not supported.

Prerequisites

Before proceeding, the following prerequisites must be installed within your environment:

Docker Engine: An open-source containerization technology.
- Visit Get Docker Engine - Community for Ubuntu for complete instructions on installing the Docker Engine on Ubuntu.
  Note:To ensure proper operation, the Docker Engine requires a minimum of 8 GB of memory.
Docker Compose: A tool used to define and run multi-container Docker applications.
- Visit Install Docker Compose for complete instructions on installing Docker Compose.
  Note:The Docker Engine must be installed and running before installing Docker Compose. View the Post-installation steps for Linux for details on configuring different startup methods for Docker.

Preparing the Target Directory

Use the following procedure to download and extract the Nuix RESTful Service Linux archive.

Download the Docker Image for Linux 64-bit package from the Nuix Customer Portal.
Open a terminal and enter the following command to create a target directory for the package:
```
sudo mkdir -p /opt/nuix/rest
```
Note: /opt/nuix/rest is the recommended location for this package.
Extract the contents of the rest-docker-compose archive to the target directory:
```
sudo tar xzf rest-docker-compose-VERSION.tar.gz -C /opt/nuix/rest
```
Navigate to the target directory to view the extracted contents of the package:
```
cd /opt/nuix/rest
```

The rest directory contains the directory structure described in the following table:

    .
    |-- bin                                       # Binaries and support scripts
        |-- clean.sh                              # Script to remove user data and restore directories
        |-- configure.sh                          # Script to configure the Nuix License Server settings
        |-- create-service.sh                     # Script to create a service
        |-- install.sh                            # Script to install the Nuix RESTful Service
    |-- cases                                     # Default Inventory Location for cases on the host
    |-- docs                                      # Documentation
    |-- exports                                   # Default Nuix exports directory on the host
    |-- images                                    # Distributed Docker images
    |-- logs                                      # Default Nuix logs directory on the host
    |-- raw-data                                  # Default Nuix raw-data directory on the host
    |-- scripts                                   # Default Nuix scripts directory on the host
    |-- secrets                                   # Sensitive properties used by the Nuix Rest SDK
        |-- nuix-rest-secret.properties           # Sensitive Nuix License Server properties
    |-- tmp                                       # Default Nuix tmp directory on the host
    |-- user-data-extra                           # Default Nuix user-data-extra folder on the host
    |-- .env                                      # Docker compose environment configuration.
    |-- rest.env                                  # Nuix RESTful Service environment configuration
    |-- docker-compose.yml                        # Docker compose file

Installing the Docker Image

After extracting the package to the target directory, use the following procedure to complete the installation process using the provided scripts.

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to begin the installation.
```
sudo ./bin/install.sh
```
The install.sh script verifies that all prerequisites are in place before loading the included Nuix RESTful service Docker images and calling all other scripts that are required for the installation.
Note: The first time install.sh is run, a warning is returned indicating that rest.env is missing and will be created from an example file that contains default values. This is expected and can be ignored. See Post-Installation Configuration after completing the installation for information on modifying the default environment configurations.
When prompted, specify the Nuix License Server that will be used for licensing.
1. Enter a URL where the license server can be accessed.
2. Provide user credentials for an account associated within the specified license server.

After installation completes, proceed to the remaining sections in this guide for information on:

Post-Installation Configuration

After completing the installation of Nuix RESTful Service, the following configurations can be made to the installation.

Configuring Environment Settings

Nuix RESTful Service includes several configurations that can be modified to change the how the application operates.

Use the following procedure to access the available environment configurations:

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Using the editor of your choice, open the following configuration file.
```
rest.env
```
Review the properties included within the file and make changes as necessary.

The following table provides details about the properties that are configurable.

Option	Description
`JAVA_OPTS_HEAP`	Optimize the Java heap size ranges used by Nuix RESTful service. * -Xms512m Default minimum memory allocation * -Xmx6g Default maximum memory allocation
`publicURL`	The URL used to access Nuix RESTful Service.
`logging_level`	Specify the logging level to be used with REST.
`logging_level_com_nuix_us`	Specify the logging level to be used for workers.
`casePrivilegeSecurityEnabled`	Enable or disable the ability to restrict cases from view using case security.
`threadpool_nativesearch`	The number of threads available for retrieving item metadata when searches are performed.
`threadpool_asyncfunction`	The number of threads available to perform background tasks such as tagging, exclusions, or highlighting.
`threadpool_searchUnsortedManager`	The number of threads available for retrieving item counts for the provided analytics.
`threadpool_searchUnsorted`	The number of threads available to run queries and aggregate the data required to populate the provided analytics.
`serverId`	A unique identifiable name for the REST instance.
`xpack_security_transport_ssl_enabled`	Enable or disable TLS/SSL.
`ignoreDerbyCases`	Restrict REST from processing Derby-based cases.
`nuix_engine_userDataDirs`	Specify the locations where artifacts used by the Nuix Engine are stored.
`inventoryLocations`	Specify the location where cases are stored. Mapped network drives can be configured within Linux environments if a symbolic link has been created between the mapped and local drive.
`sandboxDirectory`	Specify a location where unprocessed evidence is stored.
`server_contextPath`	Specify a context path prefix to use within the Nuix RESTful Service URL.
`workerAgentStatusHistoryUpdateIntervalMs`	Specify the frequency (in milliseconds) in which worker agent status is retrieved.
`workerAgentStatusHistoryMaxValues`	Specify the maximum number of times that worker agent status can be retrieved.
`registerAsApplication`	Specify how Nuix RESTful Service should be run.
`maxSimultaneousWorkers`	Specify the total number of workers that can be distributed by this REST instance at any given time.
`workerAgentTempPath`	Specify the path to a directory, such as /tmp, that can be used by worker agents for temporary storage. The specified location should be on performant local storage with ample space for best results.
`nuix_logdir`	Specify the directory where logs generated by Nuix RESTful Service are stored.
`nuix_engine_path`	Specify the directory where the Nuix Engine is installed.
`logging_file`	Specify the path and file name to use for the log file.
`logging_config`	Specify the path and file name of the logging configuration file.

When finished, save and exit the file, then restart Nuix RESTful Service for the changes to take effect.

Updating Nuix License Server Settings

If required, the configured Nuix License Server can be updated after the initial installation using a provided script.

Use the following procedure to update the Nuix License Server connection details:

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to run the script and update the connection details.
```
sudo ./bin/configure.sh
```
When prompted, specify the Nuix License Server to be used for licensing.
1. Enter a URL where the license server can be accessed.
2. Provide user credentials for an account associated within the specified license server.

The updated settings are saved to the ./secrets/nuix-rest-secret.properties file as well as the ./rest.env file.

Once complete, restart Nuix RESTful Service for the changes to take effect.

Removing Existing Data

Nuix RESTful Service provides a script that allows all case, evidence, and user data to be removed without impacting the installation. This script can be used to return the Docker image back to a default state when testing different scenarios.

To remove existing data from the installation:

Warning

All existing cases, engine artifacts, and raw evidence will be deleted.

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to run the script.
```
sudo ./bin/clean.sh
```

Running Nuix RESTful Service

Once the Docker image has been properly deployed and configured on your system, Docker Compose can be used to quickly start Nuix RESTful Service.

To start the service in the foreground:

Navigate to the target directory where Nuix RESTful Service is installed:
```
cd /opt/nuix/rest
```
Start the service using the following command:
```
sudo docker-compose up
```
Note:This startup method returns all logs within the terminal which may be helpful when troubleshooting an issue. While the service is running, the terminal cannot be used.
To stop the service, press Ctrl-C within the terminal.

To start the service in the background:

Navigate to the target directory where Nuix RESTful Service is installed:
```
cd /opt/nuix/rest
```
Start the service using the following command:
```
sudo docker-compose up -d
```
Note: This startup method does not return logs but allows continued use of the terminal.
To stop the service, enter the following command:
```
sudo docker-compose stop
```

Starting as a Service

The installation script provided with Nuix RESTful Service creates all required Docker entries to allow the image to be run as a service. By default, the services are not started or configured to start on boot, however, these configurations can be changed using the following commands.

Start as a service:

sudo systemctl start docker-compose@nuix-rest-sdk

Stop the service from running:

sudo systemctl stop docker-compose@nuix-rest-sdk

Configure Nuix RESTful Service to run at startup:

sudo systemctl enable docker-compose@nuix-rest-sdk

Verifying the Installation

Once your installation is complete, verify your deployment using one of the following methods.

From a web browser, access the following URL:

localhost:8080/nuix-restful-service/svc/v2/about

From the terminal, enter the following cURL:

curl http://localhost:8080/nuix-restful-service/svc/v2/about

If the installation was successful, the response body for either method will return with information about the RESTful service.

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-oem-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}