Canvas Use Notes
A set of notes for using Canvas.
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.
- 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
name with the account you are looking for)
Get list of site admin accounts
rails console accounts = Account.where(is_site_admin: true)
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 Kyrio. Configuring TLS for OpenADR is a little different from the recommended configuration for TLS on a “standard” web server configuration. OpenADR recommends certificates from Kyrio, 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.
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 Kyrio
- See oadr-ssl-test.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 oadr.conf
The documentation directory contains sample config files for apache and nginx.
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 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.
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.
- 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
server_starter.rb and restore them to the new directory.
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 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
- 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
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.