Niagara 4 Directory Structure Change

Overview

In order to improve the security of a Niagara installation and adopt standard application installation patterns, the directory structure for Niagara 4 was redesigned. The new design makes it easier for system administrators to manage security of the core application as well as the security of “user” data.

Who is Impacted

Anyone who manages a Niagara installation and is familiar with the Niagara AX directory structure.

What Changed

With a Niagara AX installation, configuration data and runtime data were intermixed. This required that users would need full access permissions to a Niagara AX installation and provided little to no flexibility for administrators to regulate access. In Niagara 4, an installation is composed of two pieces: the runtime piece and the user piece.

The runtime piece is where the core Niagara components are installed. In a typical Windows environment, this may be C:\Program Files\Niagara 4\ or in a typical Linux environment this may be /opt/niagara4. The runtime piece (except for upgrades, etc) can be read only since no configuration files are present.

The “user” piece is where the all the configurable data resides. This includes stations, system.properties, templates, etc. There are actually two types of users. The first type of user is a person (operator, administrator, etc) who logs into the system with credentials. In Windows 7, this type of user would have a directory C:\Users\<username>\Niagara4.0\<brandId>\. A Linux user would have a directory /home/<username>/Niagara4.0/<brandId>. The second type of user is the system user. This is the user that runs the Niagara Daemon. Depending on the installation, this may also be a conventional user directory or a a special directory for the system account.

From within Java, these directories can be accessed by querying Sys.getNiagaraUserHome() and Sys.getNiagaraHome().

The impact of this will mostly be felt when manipulating stations. When a new station is created in Workbench, it gets created in the Niagara User Home directory. In order to start it from Niagara Daemon, it must be installed just like you would install to a remote Niagara Daemon. Not only does this provide the security benefits that allow restricting direct access to running stations, it also allows for you to test run them yourself (with the console). Of course you have to watch out for conflicting ports.

Niagara Path File Ord Shortcut API
Niagara Home ! Sys.getNiagaraHome()
Niagara User Home ~ Sys.getNiagaraUserHome()
Niagara Shared User Home N/A Sys.getNiagaraSharedUserHome()
Station Home ^ Sys.getStationHome()
Protected Station Home ^^ Sys.getProtectedStationHome()

New Locations of Files

Niagara Home

\bin
\cleanDist
\conversion
\defaults
|- bacnetObjectTypes.xml
|- colorCoding.properties
|- lonStandardConversion.xml
|- niagaraAxBacnetObjectTypes.xml
|- nre.properties
|- system.properties
|- unitConversion.xml
|- unitDifferentialConversion.xml
|- units.xml
|- workbench
| |- facetKeys.properties
| |- newComponents.bog
| |- newWidgets.bog
| |- newfiles
\docs
\etc
|- gradle
| |- <gradle build scripts and plugins>
|- brand.properties
|- extensions.properties
\jre
|- <Java8 VM>
\lib
|- licenseAgreement.txt
|- readmeLicenses.txt
\modules
|- <Niagara Modules>
\security
|- certificates
|- licenses
|- policy
\sw

Niagara User Home

\etc
\logging
|- logging.properties
\registry
\security
|- .kr
|- cacerts.jceks
|- exemptions.tes
|- keystore.jceks
\shared - shared user home
\stations

Note: Due to application differences, there are some minor differences between the complete list of files in the logged in user’s Niagara User Home and the Niagara Daemon’s Niagara User Home. For instance, daemon.properties only exists in the Niagara Daemon’s Niagara User Home. And navTree.xml only exists in the logged in user’s Niagara User Home.

Niagara Shared User Home

With the introduction of the Security Manager, we now have tighter controls on which applications can access which parts of the file system. In particular, access to the Niagara User Home has been restricted to a few core modules.

In order to allow non-Tridium applications to be able to read and write files, we have created a new directory named “shared” under the Niagara User Home directory. All applications (including non-Tridium modules as well as program objects) have read, write and delete access to this directory.

Note that this directory is different from the “shared” directory under station home - it provides a space outside station home, so that applications may create and manage files not directly related to a particular station.

Protected Station Home

We now have tighter controls on which applications have access to which parts of the file system. The stations/<stationName>/shared directory is a publicly available folder under that station to which any module can read to and write from (this is the new stationHome directory). All other directories under the station directory are protected by the security manager.

Notes

When creating a new station via the New Station Wizard, the new station get created under the logged in user’s niagaraUserHome (C:\Users\<username>\Niagara4.0\<brandId>). To start this station via the Platform Daemon (niagarad), use the Station Copier to copy this station from your niagaraUserHome to the daemon’s niagaraUserHome.

By default, the platform daemon (niagarad)’s niagara_user_home is C:\ProgramData\NiagaraN.N\<brandId> where N.N is the Niagara minor version number and brandId is the brand.id property in brand.properties. Example: C:\ProgramData\Niagara4.0\tridium. Each user has an etc directory for providing overrides to user configurable files. For Niagara 4.0, these contents of these files replace the contents of those in <niagara_home>/etc. In the future this will allow the files in the <niagara_user_home>/etc to be merged with those in <niagara_home>/etc when doing upgrades so that the files can be updated while maintaining user overrides.