N2SRP GUI Configuration

Introduction

The SRP GUI is largely configured by the Jarvis configuration file for the GUI, however several configuration changes must be made to the database directly. See Database Configuaration for these.

The Jarvis configuration file, located at /etc/jarvis/n2srp-gui.xml provides several configuration fields which may be adjusted on installation as required for each deployment. For more information on Jarvis and general configuration options, see the N-Squared Jarvis page on the N-Squared documentation website.

Authentication Models

The N2SRP GUI supports OAuth 2.0 and local database-based authentication.

Database Authentication

The N2SRP supports local database authentication for user login. This is the default configuration for a new system installation.

A default administration user admin is created, with the default password admin. Database authentication is enabled by having the following Jarvis- based configuration (in n2srp-gui.xml) uncommented:

    <login module="N2::SIP::Login">
        <parameter name="expiry_in_seconds" value="1800"/>
    </login>

    <hook module="N2::SIP::Login"/>

Additionally, the <habitat> should not include an "auth" section in the JSON stored in the habitat, otherwise the frontend GUI will believe that public auth should be used.

It is recommended the administrator password be changed immediately on installation. Use the user administration screens or command line tools to make this change.

OAuth 2.0

To enable OAuth 2.0, the following changes to the installed n2srp-gui.xml file must be performed. Locate the following section of the configuration file and add the auth section into the <habitat>:

This section:

    <habitat>
        <![CDATA[{
        "sync-model": "database"
        }]]>
    </habitat>

    <!-- Example Habitat configuration for an Azure Public OAuth authentication mechanism. -->
    <!--
        <habitat>
            <![CDATA[{
                "auth": {
                    "auth_type": "oauth"
                    , "oauth": {
                        "response_type"       : "code"
                        , "access_type"         : "public"
                        , "site"                : "https://login.microsoftonline.com"
                        , "authorize_endpoint"  : "/<tenant_id>/oauth2/v2.0/authorize"
                        , "client_id"           : "<client_id>"
                        , "redirect_uri"        : "http://<hostname>/n2srp/complete-oauth-login"
                        , "token_endpoint"      : "/<tenant_id>/oauth2/v2.0/token"
                        , "send_challenge_code" : true
                        , "scope"               : "api://<application_scope_id>/n2srp"
                    }
                }
            }]]>
        </habitat>
    -->

should become similar to:

    <habitat>
        <![CDATA[{
        "sync-model": "database",
        "auth": {
            "auth_type": "oauth"
            , "oauth": {
                "response_type"       : "code"
                , "access_type"         : "public"
                , "site"                : "https://login.microsoftonline.com"
                , "authorize_endpoint"  : "/<tenant_id>/oauth2/v2.0/authorize"
                , "client_id"           : "<client_id>"
                , "redirect_uri"        : "http://<hostname>/n2srp/complete-oauth-login"
                , "token_endpoint"      : "/<tenant_id>/oauth2/v2.0/token"
                , "send_challenge_code" : true
                , "scope"               : "api://<application_scope_id>/n2srp"
            }
        }
        }]]>
    </habitat>

Note that the auth configuration must be configured to use the OAuth provider selected for authentication. For more information on the Jarvis OAuth configuration, see the Jarvis configuration guide.

In addition to updating the habitat section, the following login module must be uncommented and configured with the same values used in the <habitat> section:

    <login module="Jarvis::Login::OAuth2">
        <parameter name="grant_type"                  value="auth_code"/>
        <parameter name="access_type"                 value="public"/>
        <parameter name="site"                        value="https://login.microsoftonline.com"/>
        <parameter name="public_key_path"             value="/<tenant_id>/discovery/v2.0/keys"/>
        <parameter name="public_key_store"            value="/tmp/auth_public_key"/>
        <parameter name="public_key_lifetime_seconds" value="60"/>
        <parameter name="groups_key"                  value="groups"/>
        <parameter name="username_key"                value="unique_name"/>
        <parameter name="user_identifier_key"         value="oid"/>
        <group_mappings>
            <group_mapping from="<group_oid>" to="administrator,restricted_user"/>
        </group_mappings>
    </login>

    <hook module="N2::SIP::OAuthLogin"/>

Additional group mappings can be made to associate received OAuth groups with N2SRP administrator or restricted_user groups.

Finally the following login configuration must be removed (or commented out), to disable local (DB) based authentication:

    <!--
    <login module="N2::SIP::Login">
        <parameter name="expiry_in_seconds" value="1800"/>
    </login>

    <hook module="N2::SIP::Login"/>
    -->

Additional User Configuration

To correctly work with restricted user access, the OAuth authentication mechanism requires a default restricted_user user to be added to the database. To create the necessary restricted user setup, run the following SQL against the n2srp database schema:

INSERT INTO n2srp.announcement_id_groups (group_name, min_announcement_id, max_announcement_id) VALUES ('restricted_user', 1, 100000);
INSERT INTO n2srp.users(user_name, password, enabled, access_level) VALUES ('restricted_user', '13+lROnwRYzjWgtkTfr+a9007a43afc4d3cbde349c7a9efa287ea3e0a07c82400c', TRUE, 10);
INSERT INTO n2srp.user_announcement_id_groups (user_id, announcement_id_groups_id)
SELECT user_id, (SELECT announcement_id_groups_id FROM n2srp.announcement_id_groups WHERE group_name = 'restricted_user')
FROM n2srp.users WHERE user_name = 'restricted_user';

Note that the maximum announcement ID to be used on-platform can be set to a maximum of 2147483647. It can be decreased as low as is appropriate for the deployment.

A value of 100000 is selected as a default.

Note that the admin and restricted_user users stored in the database are never used for login authentication, only for group (resource ID) authorization.

Database or File Based Audio Replication

The N2SRP GUI supports both file-based and database-based replication of audio content and announcement configuration from the GUI (SMS) node to service nodes. By default database replication is enabled and expected to be used. However if file-based replication should be enabled, change the configuration in the habitat:

        <habitat>
            <![CDATA[{
            "sync-model": "database"
            }]]>
        </habitat>

to rsync:

        <habitat>
            <![CDATA[{
            "sync-model": "rsync"
            }]]>
        </habitat>

When using file-base replication the live directory on the service nodes must be configured, and optionally the rsync path. These are configured in the default_parameters section:

    <default_parameters>
        <!-- this has moved to default parameters -->
        <parameter name="remote_live_target_directory" value="/var/lib/n2srp/resources/live"/>

        <!-- for file copy/syncing -->
        <parameter name="rsync" value="/usr/bin/rsync"/>
        <parameter name="remote_rsync" value="/usr/bin/rsync"/>
    </default_parameters>

Audio Encodings

The N2SRP service node on which N2SVCD and its SIP and RTP services are running will support streaming audio in one or more audio formats. Those audio formats are configured in the <config> section of the Jarvis configuration file:

    <config>
        <!-- Audio identification module. -->
        <audio_identifier binary="/usr/bin/soxi"/>
        <!-- Source encoding play flags. Kept separate to avoid special logic in the audio encodings. -->
        <source_encoding binary="/usr/bin/sox" play_flags="--magic -q '%s' '%s'"/>
        <!-- Configuration for each of our supported file codecs. -->
        <audio_encodings>
            <audio_encoding key="al"  label="A-Law"  description="ITU-T REC G.711 u-law, 8000 Hz, 64 kbit/s, mono."                         type="al"     extension=".al"  binary="/usr/bin/sox"  play_flags="--magic -r 8000 -c 1 -q '%s' '%s'"       encode_flags="'%s' -t raw -q -r 8000 -c 1 -e a-law '%s'"/>
            <audio_encoding key="ul"  label="U-Law"  description="ITU-T REC G.711 a-law, 8000 Hz, 64 kbit/s, mono."                         type="ul"     extension=".ul"  binary="/usr/bin/sox"  play_flags="--magic -r 8000 -c 1 -q '%s' '%s'"       encode_flags="'%s' -t raw -q -r 8000 -c 1 -e u-law '%s'"/>
            <audio_encoding key="amr" label="AMR-NB" description="3GPP TS 26.073 adaptive multi-rate [narrowband] (AMR-NB), 8000 Hz, mono." type="amr-nb" extension=".amr" binary="/usr/bin/bash" play_flags="-i '%s' -c:a libvorbis -b:a 64k -y '%s'" encode_flags="input_file='%s'; output_file='%s'; audio_files=(); modes=(4750 5150 5900 6700 7400 7950 10200 12200); for mode in &quot;${modes[@]}&quot;; do /usr/bin/ffmpeg -i &quot;$input_file&quot; -f amr -c:a amr_nb -ar 8000 -y -ac 1 -b:a $mode &quot;$output_file.$mode&quot;; audio_files+=(&quot;$output_file.$mode&quot;); done; /usr/bin/tar -cf &quot;$output_file&quot; &quot;${audio_files[@]}&quot;; /usr/bin/rm &quot;${audio_files[@]}&quot;"/>
            <audio_encoding key="awb" label="AMR-WB" description="ITU-T REC G.722.2 adaptive multi-rate wideband (AMR-WB), 16000 Hz, mono." type="amr-wb" extension=".awb" binary="/usr/bin/bash" play_flags="-i '%s' -c:a libvorbis -b:a 64k -y '%s'" encode_flags="input_file='%s'; output_file='%s'; audio_files=(); modes=(6600 8850 12650 14250 15850 18250 19850 23050 23850); for mode in &quot;${modes[@]}&quot;; do /usr/bin/ffmpeg -i &quot;$input_file&quot; -f amr -c:a amr_wb -ar 16000 -y -ac 1 -b:a $mode &quot;$output_file.$mode&quot;; audio_files+=(&quot;$output_file.$mode&quot;); done; /usr/bin/tar -cf &quot;$output_file&quot; &quot;${audio_files[@]}&quot;; /usr/bin/rm &quot;${audio_files[@]}&quot;"/>
        </audio_encodings>
    </config>

Supported encodings are currently A-law, U-law, AMR Narrowband, and AMR Wideband. These come preconfigured, but may be disabled by commenting out the corresponding <audio_encoding> element(s) as required.

Database Configuration

The N2SRP GUI requires several direct database updates to be made before the GUI can be used. First, connect to the SRP database as n2srp_owner and apply the following configuration:

psql -h localhost -U n2srp_owner n2in -W

Disabling the “Working” Set

By default the N2SRP GUI will require users to make changes to an interim “working” set before changes to the announcement configuration can be synced and made available to the SRP AS nodes.

However, if you want to disable the working set, and make all changes immediately available to SRP AS nodes (delayed only by database replication and N2SRP AS RPT cache timers), change the configuration in the N2SRP database.

Connected to the N2SRP database, run the following update command:

UPDATE n2srp.config set enable_working_set = FALSE;

Reload any N2SRP GUI screens open. From the point of the change on, changes can (and must) be made to the active announcement set, not the working set.

Note that if file-based sync is enabled, then the sync is still required to be performed to transfer files from the SMS node to the SRP AS nodes.

SRP Language Configuration

To configure the SRP languages available in the SRP GUI, add the language names to the n2srp.langauge table. Connect to the N2SRP database and run the following insert command for each language required:

INSERT INTO n2srp.language (language_name, creation_user) VALUES ('<language>', 'initial creation');

Where <language> is the language name.

Available language are:

Each language listed above also has an associated language codec. Other language names can be used if a specific language codec is not required.

Audio Codec Configuration

The SRP GUI must be configured to support each individual audio codec that may be uploaded or used during RTP playback.

Once connected to the SRP database as n2srp_owner define each audio codec that will be supported. Select from the following:

-- These are encodings used by the service during playback.                                                                                                                                                                                                                                                                                                              -- This list corresponds with definitions in lib/N2/RTP/Encoding.pm.
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('μ-Law', 'ul', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('AMR-NB', 'amr', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('AMR-WB', 'awb', 'initial creation');

-- These are valid encodings for source files.
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('MP3', 'mp3', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('OGG', 'ogg', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('FLAC', 'flac', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('RAW', 'raw', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('WAV', 'wav', 'initial creation');