Setting Configuration Values

These settings only apply to on-site installations. When using a hosted SaaS plan, Veracity will manage the settings for your deployment. Contact support if you require modifications to the settings on your hosted instance.

1. Command line flags override environment.
   
2. Environment overrides .env file.
   
3. .env file overrides defaults.

It's typical to use the .env file to store configuration settings.

Configuration values are sensitive and should be protected.

Example Command Line

$ ./lrs2 [--port 8080] --disableAccountCreation
$ ./lrs2 --help

Example .env File

inProcessJobs=true
selfServiceAccounts=false
mongoServer=mongodb://localhost
adminDBName=VTCLRS
elasticSearchServer=
host=local.veracity.it
port=80
displayPort=80
protocol=http
domainRouting=false
SERVER_SECRET=9bcf20cc-b326-4d6f-9691-8c384e5dfbf8

Required Settings

host

1. lrs.mycompany.org
   
2. veracity.mycompany.com
   
3. myveracitylrs.io
   

1. https://testlrs.com
   
2. FE80:CD00:0000:0CDE:1257:0000:211E:729C
   
3. myhostname

port

displayPort

protocol

mongoServer

MongoDB connection strings that include the term localhost may need to be updated. If the LRS does not connect to your local database, please change localhost to 127.0.0.1.

1. mongodb://localhost
   
2. mongodb://dbUserName:password@local.veracity.it:27017
   
3. mongodb+srv://root:xxxxxxx@test.xxxxx.mongodb.net

adminDBName

elasticSearchServer

Server_Secret

1. http://elastic:w3FKZHaoREVf4EA8S6yf@localhost:9200
   
2. http://localhost:9200

Outgoing Email

Some STMP processors require that the system_email_from address be from a validated address. Check with your SMTP provider.

Setting Name	Discussion
system_email_from	This is the email address that will appear in the "From" field.
email_pass	This is the password for the given SMTP server.
email_server	This is the URL of the SMTP server. For example: smtp.sendgrid.net.
email_to	This address is used to send notifications to the system administrator.
email_user	The username used to access the SMTP server.

All five of the above settings must be populated to enable outgoing email. You can verify that outgoing email is configured by checking the current configuration page from the administrative tools.

Serving SSL

Setting Name	Discussion
protocol	should be https.
port	This is the port that the LRS actually listens on. Generally, this would be 443 for SSL.
displayPort	When not behind a proxy, the displayPort should match the port value.
sslCert	This is the path (relative to the working directory) to the SSL certificate file. This file should be in the PEM format and may contain additional chained certificates. For example: testcerts/certificate.crt.
sslKey	This is the private key associated with the certificate in the .crt file. This file should be in the PEM format. For example: testcerts/privatekey.key.

Example certificate and key files are provided in the article attachments

Serving Behind a Proxy

Some organizations will choose to use another webserver to proxy HTTP to the LRS. This is useful in a case where you wish for more granular control over the HTTP requests, such as to set specific SSL configurations, to add additional headers, or for logging purposes. There are several considerations when running the LRS behind a proxy.

SSL termination

One common use case is to configure the proxy to terminate the SSL connection to the client and form a regular HTTP connection to the LRS. In this scenario, the LRS needs to know that the end user is seeing an SSL connection, even when the LRS is not serving SSL. Set the protocol setting to https but leave sslCert and sslKey blank.

Streaming and file sizes

The LRS has many functions intended to work for arbitrarily large data sizes, such as database backup or xAPI statement JSON upload. It's important to prevent your proxy server from buffering requests and responses, or some data loads may exceed the buffer limits and fail. Additionally, some data is streamed down to the client as it's processed. The software is designed such that most long running exports of reports or xAPI statements should begin downloading immediately, and new bytes are returned to the client as they are available. With buffering enabled in your proxy, no bytes will be returned to the client until the entire export completes. This can cause the client to abort the connection after no bytes are received in a given time, thus making it impossible to retrieve long running reports.

WebSockets

The LRS uses a WebSocket connection to update various portions of the UI. While WebSockets are optional, it's important that the server understands whether or not to expect WebSockets to work. If enableWebsockets is set to true, then the proxy must be configured to forward WebSocket connections to the LRS. If this is not possible, be sure to set enableWebsockets to false.

HTTP Headers

The LRS will examine the incoming host header to determine that the end client accessed the site from the expected domain. Set your proxy to echo the host header as received from the client, not to overwrite the header with the internal network host value.

If you've set secureCookie to true, you'll need to inform the system that the upstream proxy is trusted. To do so, set a header on the HTTP request called X-Forwarded-Proto and make the value https. This will inform the LRS server that the incoming connection was secure, and thus the server will obey the secureCookie setting.

For the LRS's inbuilt brute force protection to work, the IP address of the end client needs to be known to the server. Brute force protection is keyed by the incoming IP address, so a client hitting the login URL repeatedly will be throttled. Since the throttle is controlled by the IP, other clients are not affected by the delay. If the LRS sees the upstream proxy as in incoming IP, then one client may cause all clients to be slowed down, and users may experience a message telling them to wait to log in. To inform the LRS of the actual client IP, not the proxy's IP, set the header X-Forwarded-For to the actual client IP address.

Paths

One reason to run the LRS behind a proxy is to use the same webserver to host multiple applications. Set the setting webRoot to be a path on your server and configure your proxy to forward only those paths to the LRS application.

Example Nginx Location Block

location /
    {
        proxy_pass                 http://localhost:3005/;
        proxy_set_header           Host                 $host;
        proxy_set_header           X-Forwarded-For      $remote_addr;
        proxy_http_version         1.1;
        proxy_set_header           Upgrade              $http_upgrade;
        proxy_set_header           Connection           "Upgrade";
        proxy_set_header           X-Forwarded-Proto    $scheme;
        proxy_buffering            off;
        proxy_request_buffering    off;
        proxy_read_timeout         18000s;
        proxy_send_timeout         18000s;
    }

Logging

Veracity writes all log events to the process stdout stream. Your process or service control system is responsible for writing this information to disk, a database, or otherwise storing the events. Some, but not all, events are also written into a logs collection in the MongoDB database and can be viewed from the administrative UI. There are four settings that control how the log information is structured.

Setting Name	Discussion
logLevel	This is the logging verbosity. Either debug, info, warning, or error.
logFormat	Either human or lines. Some log management tools generate separate events for each newline in the output stream. In human mode, some data from single events is formatted to display on multiple lines, which can break such tools. Set the logFormat to lines to strip newlines from log events.
logSources	This is a comma separated list of log subsystem sources to display. This is useful when trying to isolate or debug specific components of the system
no-color	The LRS will normally use ANSI terminal colors to display information. Set this to true to disable all color output. Some systems are not capable of displaying this color and will show many Unicode escape characters instead of the coloring, making it difficult to view the logs.

Configuring a process control system to forward logs is beyond the scope of this documentation.

Log Format

Each line of a logged event is formatted in four fixed width columns. The first column is the ID of the worker thread that sent the message. The second is the message level — how important the message is. The third column is the log source — which subsystem generated the message. The logs can be filtered by both the source and level with the logSource and logLevel settings. The remainder of the line is the raw string of the message. This may or may not include formatted text or JSON data.

Example:

[M]    info   plugins    Found Plugin Dashboard C:\Development\­vtc2\­lrs2\­plugins\­netc-dashboards\­dashboards\­instructor\­navyInstructorActivities.js 
[M]    info   plugins    Found Plugin Dashboard C:\Development\­vtc2\­lrs2\­plugins\­netc-dashboards\­dashboards\­student\­netcStudentActivities.js  
[M]    info   websock    Starting socket server 
[M]    info   system     Listening on 3005 
[M]    info   system     Startup Complete  
[M]    info   audit      System System Start  
[M]    info   audit      EXTERNAL_CONNECTION 54.209.2.187:443 
[M]    info   audit      UI GET /lrs/test-buck/content/create/ admin@example.com 
[M]    info   audit      ACCESS lrs.content.create 640741e6240cc64d0857566f lrs.js admin@example.com true

Audit Logging

Audit logging is an Enterprise feature.

Enterprise users can activate granular logging of many system events. These events will be printed into the server logs under the audit log source. The audit logger is a built-in, system-level plugin. It can be configured to log the following event categories.

Event Type	Discussion
UI requests	This setting will cause the audit logger to save all HTTP requests to the UI, including the method, path, and any logged in user.
xAPI requests	This setting will cause the audit logger to save all HTTP requests to the xAPI, including the method, path, and query.
LRS API requests	This setting will cause the audit logger to save all HTTP requests to the LRS management APIs.
System API	This setting will cause the audit logger to save all HTTP requests to the System management API.
System ODM events	Log all system level data model changes. All DB entities will report created, modify, and delete events for the specific entity type and ID.
LRS ODM events	Log all LRS level data model changes. All DB entities will report created, modify, and delete events for the specific entity type, ID, and LRS.
User events	Users account events such as created, deleted, locked, unlocked, password reset, login, and logout.
Permissions	This system will record all access control checks including what permission was requested, by who, on what entity, and what was the outcome.
Permissions Set	The system will record all modifications to permissions, including what permissions were granted and revoked, by whom, to whom, and on what entity.
External Connections	The system reached out to another server for some purpose. The log will contain the purpose, host/URL, protocol, and remote IP.

Self Service User Accounts

This section describes topics related to allowing users to manage their own accounts. This includes password reset, LRS creation, and account creation. Generally, an Enterprise install will be configured for only the system administrator to create LRS and user accounts. It's possible to configure the system to allow self-registration and LRS creation.

Self-service account creation and password reset requires outgoing email to be enabled.

The below table shows the recommended settings for an enterprise deployment. This will allow existing accounts to request password reset emails. Users may not self-register to the system, and users may not create their own LRSs. To allow specific users to create or access an LRS, use the system level permission system.

Setting Name	Recommended Value
selfServiceAccounts	true
disableAccountCreation	true
defaultUserPermissions	(empty string)

The system can also be configured into a more permissive state, where users can create accounts for themselves and create their own LRS. This configuration supports a SaaS deployment like ours at lrs.io.

Enterprise customers should restrict network access to the LRS when in this state to prevent unauthorized users from creating accounts and LRSs

Enterprise customers are prohibited from charging for access to their LRS. Contact Veracity for the exact terms of the Enterprise license.

Setting Name	Recommended Value
selfServiceAccounts	true
disableAccountCreation	false
defaultUserPermissions	system.lrs.create

All Settings