API Node Installation

Overall Installation Steps

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

  1. Determine the server(s) that will supply the API logical component, bearing in mind the supported operating systems and minimum server requirements.
  2. Ensure the installation pre-requisites are met.
  3. Install the API package.
  4. Perform any required post-installation steps.
  5. Update the API configuration as desired.
  6. 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 N2CUG 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 N2CUG 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.

Jarvis

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

The N2CUG 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 n2cug-api sudo yum install n2cug-api sudo apt-get install n2cug-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/n2cug-api-M.m.p-b.noarch.rpm sudo dpkg -i /path/to/n2cug-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 integration with the GUI node and the identity management platform.

In the file /etc/jarvis/n2cug.xml, locate the following section:

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

                , "flow_editor_site": "http://REPLACE_WITH_GUI_NODE_ADDRESS/"
            }]]>
        </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/complete-oauth-login"/>
            <parameter name="self_signed_cert"   value="REPLACE_WITH_CERTIFICATE_PATH"/>

Replace the sentinel values as follows:

Database Integration

In the file /etc/jarvis/n2cug.xml, locate the following section:

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

Replace the sentinel values as follows:

SOAP API Integration

If a SOAP API is required for CUG provisioning, the N-Squared application framework N2SVCD must be installed. Follow the installation steps for this, noting any prerequisites.

Be sure to apply any applicable N2SVCD post-installation steps once installation is complete.

Once installed, a Database N2SVCD application, a SOAP Server N2SVCD application, and a Logic N2SVCD application must be configured. At a high level, the required configuration for these applications looks like:

        <application name="SOAP-SERVER" module="SoapServerApp">
            ...
            <config>
                <handlers>
                    <handler path="/CugService" application="Logic"/>
                </handlers>
            </config>
        </application>
        <application name="Logic" module="LogicApp">
        ...
        <parameters>
            ...
            <parameter name="lua_lib_path" value="../lua/lib/?.lua;../../n2cug/lua/api/?.lua"/>
            <parameter name="default_db_app_name" value="DB"/>
        </parameters>
        <config>
            <services>
                <service script_dir="../../n2cug/lua/api" module="SoapServerApp::SoapLuaService" libs="../apps/soap_s/lib">
                    ...
                </service>
            </services>
            <agents>
                <agent module="DBApp::DBLuaAgent" libs="../apps/db/lib"/>
            </agents>
        </config>
        </application>
        <application name="DB" module="DBApp">
            ...
            <parameters>
                ...
                <parameter name="connect" value="..."/>
            </parameters>
        </application>

Refer to the individual application configuration documentation for full details of the configuration required. The database application should be configured to connect to the appropriate primary or replica DB node that the SOAP API will use.

Firewall

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

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

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:

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.