Skip to content

Canvas Use Notes

A set of notes for using Canvas.

SHA Hash

To validate VEN connections, the application calculates the VEN certificate fingerprint using a SHA hash. The default hash used is SHA1 but SHA 224, 256, 384, and 512 can be used instead. To select a different hash, set the environment variable CANVAS_FP_HASH to the SHA bit number.

The following will set the hash to SHA256:

CANVAS_FP_HASH=256 puma -C config/puma.rb -b tcp://0.0.0.0:8080

Since certificate fingerprint matching happens after TLS negotiation, the hash selection does not affect the security of the system. Choosing a higher bit number may have a small impact on performance on a high volume server.

NOTE: Once the hash is set and VENs are registered, changing the hash will cause communication to existing VENs to fail. If the hash function is changed, the fingerprints for existing records will need to be reentered.

Logrotate

  • Default on ubuntu runs 24 hours
  • Move to hourly, or schedule cron to run hourly: https://www.digitalocean.com/community/tutorials/how-to-manage-logfiles-with-logrotate-on-ubuntu-16-04

There’s a sample log rotate file under the documentation directory. Update the paths to match your install and copy this file to /etc/logrotate.d/.

Creating Site Admins

Site admins (who can create and modify namespaces, as well as occupy any namespace as a user) can only be created using the Rails console. They do not appear in the list of accounts for the namespace they are occupying.

Regular admin users will be able to see the site-admin setting on their account page, but cannot change the setting.

Promote a user to site admin with the console

rails console
account = Account.find_by_name("name")
account.is_site_admin = true
account.save

(Replace name with the account you are looking for)

Get list of site admin accounts

rails console
accounts = Account.where(is_site_admin: true)

Reverse Proxy

Configure either Apache or Nginx as a reverse proxy to the Puma application server on port 8080. Sample config files for Apache and Nginx are provided in the documentation directory. When using TLS, it’s recommended TLS is terminated at the proxy.

The VEN sample config files are configured for serving VEN endpoints with certificates from Eonti. Configuring TLS for OpenADR is a little different from the recommended configuration for TLS on a “standard” web server configuration. OpenADR recommends certificates from Eonti, TLS1.2, and a certain set of ciphers. Installations are free to modify all of these settings (eg, use certs from a different provider and use different cipher suites). However, care should be taken to not use a setup that is less secure than the OpenADR alliance recommendation.

Protecting endpoints

The application has 3 distinct endpoints that are secured by different means and have different proxy config files:

  • OpenADR endpoints: /oadrapi/ven/
    • Forward only /oadrapi/ven.
    • Use TLS certificates from Eonti
    • See canvas-ven.conf
  • API endpoints: /api/
    • Forward only /api
    • Use any certificates
    • Protect with http auth or authentication built into each API
  • Admin UI: everything else
    • Forward /
    • Block /api and /oadrapi/ven
    • See canvas-ui.conf

The documentation directory contains sample config files for apache and nginx.

OpenADR

The OpenADR endpoints are secured with client side certificates and the VEN certificate fingerprint registered in the VEN record in the VTN. If TLS isn’t in use, take extreme caution as to what can access the endpoints.

API

API endpoints are served under /api/. These endpoints are only active if a script is installed in lib/api/ or an API gem is installed. The controller that handles these requests does not implement any authentication. These endpoints must be secured by the reverse proxy, or by adding authentication to the function calls inside the API.

Admin UI

Any endpoint not under the two above are for the admin UI. These endpoints are intended for use with a browser and are protected through application level accounts and SSL. This endpoint should be served over SSL and shouldn’t be accessible outside your network.

Concurrency

  • The database connection pool is configured in config/database.yml. The default pool size for production is 20.
  • The puma thread count is configured in config/puma.rb (top of file, threads 1, 6). The default is 6 (which is way too low)
  • Nginx has different settings for creating threads or processes or a combo of both. We don't provide a recommendation for how to configure nginx.

Upgrading from v1 to v2

NOTE: Before upgrading from 1.x to 2.x, install the latest version 1.8.x

Update the source

Update the source code on the server. Pull the new version from your git server, or replace the source directory entirely. If the directory is replaced, be sure to save the files database.yml, secrets.yml and server_starter.rb and restore them to the new directory.

Run commands

Run the follow commands from the root install directory as the appuser

sudo su - appuser
cd canvas-oadr-vtn
bundle install
rake db:migrate
JAVA_OPTS=-Xmx2048M rake assets:precompile

Restart the puma service.

When updating an adapter, update the adapter code and follow step 2 above (run the commands from the Canvas root directory, not from the adapter root directory).

VEN Settings

VEN Interaction Logging

As of v3 the UI will display all correspondence with the VEN so it may be debugged more easily. These can be found in the UI on the VEN screen.

These must be enabled in the VEN settings screen - there are three check boxes under logging:

  • Log Requests: Must be checked, or nothing will be logged
  • Log Responses: If checked, responses from VTN => VEN will be logged as well
  • Skip Poll Requests: filter out polls from the VEN

Message processing

In order to turn off report data processing (to save space), uncheck the Process Update Report checkbox in the VEN UI. If unchecked, Canvas will no longer save the report data into the database, and so it will not show up as telemetry data in the UI.