Navigation :

API Node Installation

Overall Installation Steps

The high-level steps for installing and configuring N2ACD API nodes are:

Determine the server(s) that will supply the API logical component, bearing in mind the supported operating systems and minimum server requirements.
Ensure the installation pre-requisites are met.
Install the API package.
Perform any required post-installation steps.
Update the API configuration as desired.
Optionally, apply the recommended Apache security configuration.

Installation Pre-requisites

OS-specific Setup

Refer to the specific Red Hat or Debian instructions for any pre-requisites as required.

Apache 2

Apache 2 must be installed prior to installing the N2ACD API package. The package to install will depend on your OS type:

RHEL 8	Other RPM-based Systems	DEB-based Systems
`sudo dnf install httpd`	`sudo yum install httpd`	`sudo apt-get install apache2`

The N2ACD API package expects that the relevant Apache 2 configuration directory exists. Again, this varies depending on your OS type:

RPM-based Systems	DEB-based Systems
`/etc/httpd`	`/etc/apache2`

Finally, the apachectl program must exist (it is installed as part of the Apache 2 package) and Apache must be running.

Perl

The N2ACD API node requires several Perl packages to be available prior to installation. The package names may vary depending on your OS type:

RPM-based Systems DEB-based Systems

perl or perl-interpreter >= 1:5.12
perl(B)
perl(DBI)
perl(DBD::Pg)
perl(Data::Compare)
perl(Data::Dumper)
perl(Date::Format)
perl(DateTime::Format::Pg)
perl(Digest)
perl(Getopt::Long)
perl(JSON)
perl(List::MoreUtils)
perl(MIME::Base64)
perl(POSIX)
perl(Scalar::Util)
perl(Storable)
perl(Time::Local)
perl(XML::LibXML)
perl(boolean)
perl(strict)
perl(warnings) perl >= 5.12
perl-base
perl-modules
libdbi-perl
libdata-compare-perl
libtimedate-perl
libdatetime-format-pg-perl
libjson-perl
liblist-moreutils-perl
libxml-libxml-perl
libboolean-perl

RPM-based Systems	DEB-based Systems
`perl` or `perl-interpreter` >= 1:5.12 `perl(B)` `perl(DBI)` `perl(DBD::Pg)` `perl(Data::Compare)` `perl(Data::Dumper)` `perl(Date::Format)` `perl(DateTime::Format::Pg)` `perl(Digest)` `perl(Getopt::Long)` `perl(JSON)` `perl(List::MoreUtils)` `perl(MIME::Base64)` `perl(POSIX)` `perl(Scalar::Util)` `perl(Storable)` `perl(Time::Local)` `perl(XML::LibXML)` `perl(boolean)` `perl(strict)` `perl(warnings)`	`perl` >= 5.12 `perl-base` `perl-modules` `libdbi-perl` `libdata-compare-perl` `libtimedate-perl` `libdatetime-format-pg-perl` `libjson-perl` `liblist-moreutils-perl` `libxml-libxml-perl` `libboolean-perl`

For each of these packages (or with all as one command), execute the instructions specific to your operating system:

RHEL 8	Other RPM-based Systems	DEB-based Systems
`sudo dnf install <package(s)>`	`sudo yum install <package(s)>`	`sudo apt-get install <package(s)>`

Jarvis

The N-Squared application Jarvis must be installed. Follow the installation steps for this, noting any prerequisites.

The N2ACD API package also expects that the default Jarvis configuration directory exists:

/etc/jarvis

Installation Steps

Follow the appropriate installation steps depending on your installation sources.

From N-Squared Repository

Execute the instructions specific to your operating system:

RHEL 8	Other RPM-based Systems	DEB-based Systems
`sudo dnf install n2acd-api`	`sudo yum install n2acd-api`	`sudo apt-get install n2acd-api`

As Manual Installation

Transfer the provided package file to the target node, then follow the instructions specific to your operating system.

Execute (adjusting as appropriate for package location and version details) the following:

RPM-based Systems	DEB-based Systems
`sudo rpm -Uvh /path/to/n2acd-api-M.m.p-b.noarch.rpm`	`sudo dpkg -i /path/to/n2acd-api_M.m.p-b_all.deb`

Post-Installation Steps

GUI and Identity Management Integration

The Jarvis configuration on the API must be updated for API integration with the GUI node and the identity management platform. This is done separately for the administrative GUI and the Flow Editor.

Administrative GUI API Configuration

In the file /etc/jarvis/n2acd-admin.xml, locate the following section:

        <habitat>
            <![CDATA[{
                "auth": {
                    "auth_type": "oauth"
                    , "oauth": {
                        "site": "https://REPLACE_WITH_IDENTITY_MANAGEMENT_ADDRESS"
                        , "authorize_endpoint": "REPLACE_WITH_IDENTITY_MANAGEMENT_AUTH_ENDPOINT"
                        , "client_id": "REPLACE_WITH_CLIENT_ID"
                        , "redirect_uri": "http://REPLACE_WITH_GUI_NODE_ADDRESS/n2acd-admin/complete-oauth-login"
                        , "response_type": "code"
                    }
                }

                , "flow_editor_site": "http://REPLACE_WITH_GUI_NODE_ADDRESS/n2acd-fe/"
            }]]>
        </habitat>

        <login module="Jarvis::Login::OAuth2">
            <parameter name="client_secret"      value="REPLACE_WITH_CLIENT_SECRET"/>
            <parameter name="client_id"          value="REPLACE_WITH_CLIENT_ID"/>
            <parameter name="site"               value="https://REPLACE_WITH_IDENTITY_MANAGEMENT_ADDRESS"/>
            <parameter name="token_path"         value="REPLACE_WITH_IDENTITY_MANAGEMENT_TOKEN_ENDPOINT"/>
            <parameter name="logout_path"        value="REPLACE_WITH_IDENTITY_MANAGEMENT_LOGOUT_ENDPOINT"/>
            <parameter name="redirect_uri"       value="http://REPLACE_WITH_GUI_NODE_ADDRESS/n2acd-admin/complete-oauth-login"/>
            <parameter name="self_signed_cert"   value="REPLACE_WITH_CERTIFICATE_PATH"/>

Replace the sentinel values as follows:

REPLACE_WITH_IDENTITY_MANAGEMENT_ADDRESS must be updated to the address of the identity management server to use.
REPLACE_WITH_IDENTITY_MANAGEMENT_AUTH_ENDPOINT must be updated to the endpoint on the identity management platform for user authentication.
REPLACE_WITH_GUI_NODE_ADDRESS must be updated to the resolvable address of the machine where the GUI package is installed.
REPLACE_WITH_CLIENT_SECRET must be updated to the client secret key of the identity management platform.
REPLACE_WITH_CLIENT_ID must be updated to the client ID on the identity management platform.
REPLACE_WITH_IDENTITY_MANAGEMENT_TOKEN_ENDPOINT must be updated to the endpoint on the identity management platform for token management.
REPLACE_WITH_IDENTITY_MANAGEMENT_LOGOUT_ENDPOINT must be updated to the endpoint on the identity management platform for user logout.
REPLACE_WITH_CERTIFICATE_PATH must be updated to the path to the local signed certificate to use for SSL connections.

Flow Editor GUI API Configuration

In the file /etc/jarvis/n2acd-fe.xml, locate the following section:

                "auth": {
                    "auth_type": "oauth"
                    , "oauth": {
                        "site": "https://REPLACE_WITH_IDENTITY_MANAGEMENT_ADDRESS"
                        , "authorize_endpoint": "REPLACE_WITH_IDENTITY_MANAGEMENT_AUTH_ENDPOINT"
                        , "client_id": "n2acd"
                        , "redirect_uri": "http://REPLACE_WITH_GUI_NODE_ADDRESS/n2acd-fe/login"
                        , "response_type": "code"
                    }
                }
            }]]>
        </habitat>

        <login module="Jarvis::Login::OAuth2">
            <parameter name="client_secret"      value="REPLACE_WITH_CLIENT_SECRET"/>
            <parameter name="client_id"          value="REPLACE_WITH_CLIENT_ID"/>
            <parameter name="site"               value="https://REPLACE_WITH_IDENTITY_MANAGEMENT_ADDRESS"/>
            <parameter name="token_path"         value="REPLACE_WITH_IDENTITY_MANAGEMENT_TOKEN_ENDPOINT"/>
            <parameter name="logout_path"        value="REPLACE_WITH_IDENTITY_MANAGEMENT_LOGOUT_ENDPOINT"/>
            <parameter name="redirect_uri"       value="http://REPLACE_WITH_GUI_NODE_ADDRESS/n2acd-fe/login"/>
            <parameter name="self_signed_cert"   value="REPLACE_WITH_CERTIFICATE_PATH"/>

Update the sentinel values in this file in the same manner as for the administrative GUI.

Database Integration

In the file /etc/jarvis/n2acd-admin.xml, locate the following section:

        <database connect="dbi:Pg:dbname=n2in;host=REPLACE_WITH_DB_ADDRESS;port=REPLACE_WITH_DB_PORT"
                  username="n2acd_web"
                  password="REPLACE_WITH_DB_PASSWORD"/>

Replace the sentinel values as follows:

REPLACE_WITH_DB_ADDRESS must be updated to the address of the primary database node (or proxy) to connect to.
REPLACE_WITH_DB_PORT must be updated to the listening port configured for the primary database node (or proxy).
REPLACE_WITH_DB_PASSWORD must be updated to the n2acd_web database user’s password, as created during database preparation.

Locate the same section in the file /etc/jarvis/n2acd-fe.xml and repeat the sentinel replacements.

REP Integration

If one or more REP nodes are planned, API statistics measurements, EDRs, and reporting requests must be configured to go to the appropriate REP node(s) destinations.

If no REP node is planned:

Statistics and EDRs may be disabled or sent to an alternative data repository. Note that if EDRs are not disabled or transferred, they may eventually fill the file system.
Reporting access on the API should be disabled to avoid GUI errors.

Firewall

The firewall (if any) on the API node must be updated to allow:

Inbound user and API requests on the listening Apache port(s).
Outbound database requests to the DB node(s).

If a non-co-hosted REP node is planned, the firewall must also allow access for:

Outbound statistics measurements to the REP node(s).
Outbound EDRs to the REP node(s).
Outbound reporting requests to the REP node(s).

Otherwise, if an alternative data repository is to be used for statistics and EDRs, the firewall must be updated to allow access for:

Outbound statistics measurements to the repository.
Outbound EDRs to the repository.

The exact commands to do this will depend both on the firewall on your platform and also which port(s) are in use. For example, to allow the default Apache ports when using firewalld, the commands might be:

firewall-cmd --zone=public --add-port=80/tcp --permanent
firewall-cmd --zone=public --add-port=443/tcp --permanent
service firewalld restart

SELinux

If SELinux is in use, Apache must be allowed to initiate proxy connections. To enable this, execute:

sudo /usr/sbin/setsebool -P httpd_can_network_connect 1

License File

The N2ACD API platform must have a license file provided to operate in an unrestricted manner. Contact N-Squared Support to arrange a license file for your deployment.

Place the received license file on the API node. The recommended directory and filename is:

/etc/jarvis/license.n2acd-fe.xml

Ensure that the license file is readable by the user running the Apache processes.

In the file /etc/jarvis/n2acd-fe.xml, locate the following section:

        <hook module="AfterStatus">
            <parameter name="license" value="REPLACE_WITH_LICENSE_PATH"/>
        </hook>

Replace the sentinel values as follows:

REPLACE_WITH_LICENSE_PATH must be updated to the full path of the license file.

Session Security

Jarvis allows for session security to be increased by configuring a number of configuration parameters. In particular, the following parameters may be updated:

app => csrf_protection
app => cross_origin_protection
app => xsrf_protection
app.sessiondb.parameter => Path
app.sessiondb.parameter => Domain
app.sessiondb.parameter => Secure

Refer to the Jarvis documentation for more details. Further information is also available in the documentation for the Perl modules CGI::Session and CGI::Cookie.