Linux N4 Supr
Linux N4 Supr
Linux N4 Supervisor
August 5, 2016
Linux N4 Supervisor
Tridium, Inc.
3951 Westerre Parkway, Suite 350
Richmond, Virginia 23233
U.S.A.
Confidentiality
The information contained in this document is confidential information of Tridium, Inc., a Delaware corpora-
tion (“Tridium”). Such information and the software described herein, is furnished under a license agreement
and may be used only in accordance with that agreement.
The information contained in this document is provided solely for use by Tridium employees, licensees, and
system owners; and, except as permitted under the below copyright notice, is not to be released to, or re-
produced for, anyone else.
While every effort has been made to assure the accuracy of this document, Tridium is not responsible for
damages of any kind, including without limitation consequential damages, arising from the application of the
information contained herein. Information and specifications published here are current as of the date of this
publication and are subject to change without notice. The latest product specifications can be found by con-
tacting our corporate headquarters, Richmond, Virginia.
Trademark notice
BACnet and ASHRAE are registered trademarks of American Society of Heating, Refrigerating and Air-Con-
ditioning Engineers. Microsoft, Excel, Internet Explorer, Windows, Windows Vista, Windows Server, and SQL
Server are registered trademarks of Microsoft Corporation. Oracle and Java are registered trademarks of
Oracle and/or its affiliates. Mozilla and Firefox are trademarks of the Mozilla Foundation. Echelon, LON, Lon-
Mark, LonTalk, and LonWorks are registered trademarks of Echelon Corporation. Tridium, JACE, Niagara
Framework, NiagaraAX Framework, and Sedona Framework are registered trademarks, and Workbench,
WorkPlaceAX, and AXSupervisor, are trademarks of Tridium Inc. All other product names and services men-
tioned in this publication that is known to be trademarks, registered trademarks, or service marks are the
property of their respective owners.
August 5, 2016 3
Contents Linux N4 Supervisor
4 August 5, 2016
About this guide
This document provides installation details specific to the Niagara 4.2 N4Supervisor running on Red Hat En-
terprise Linux 7/CentOS distribution on a specific PC platform.
Related documentation
Additional information about Linux Supervisor operation is available in the following documents.
• Niagara 4 Platform Guide
• Linux AX Supervisor Notes
August 5, 2016 5
Linux N4 Supervisor
6 August 5, 2016
Chapter 1 Linux N4Supervisor Notes
Topics covered in this chapter
♦ About installing the Linux N4Supervisor
Niagara 4.2 supports an N4Supervisor running on Red Hat Enterprise Linux 7/CentOS distribution on a spe-
cific PC platform (contact your Tridium sales channel for further PC platform details). This document provides
installation details specific to this Linux N4Supervisor. For related details on Niagara 4 platform operation,
see the Niagara 4 Platform Guide section “Linux-based N4Supervisor.”
N O T E : Note that the station running on a Linux N4Supervisor is “owned” by a specially created user/group
niagara:niagara, and therefore cannot bind to Linux “root owned” software ports 1-1024. This is not an
issue for either of the conventional ports (secure: 5011, or non-secure: 3011) used for a platform connection,
but does affect the standard port used by the station’s WebService (Http Port), which cannot be used at the
default port (80) setting. In addition, other software ports potentially used by various drivers must be ad-
justed above port 1024.
docs folder
install-data folder
javaodc folder
modules folder
overlay folder
Please review the README and INSTALL files. When you are ready to begin the installation process, type
the following at the command prompt:
root@<host>:/home/<user># sudo bash install.sh
N O T E : You must type "ssu d o bash install.sh" in order to run the installer since elevated permissions are re-
quired to perform some operations during the installation,
This script steps you through the installation process by asking a series of yes/no questions, where the de-
fault choice appears in capital letters, that is YES or NO instead of yes or no. Press Enter to accept the de-
fault, or type “y” or “n”.
August 5, 2016 7
Chapter 1 Linux N4Supervisor Notes Linux N4 Supervisor
cleanDist folder
conversion folder
defaults folder
docs folder
etc folder
install folder
jre folder
lib folder
logs folder
modules folder
security folder
sw folder
uninstall folder
8 August 5, 2016
Linux N4 Supervisor Chapter 1 Linux N4Supervisor Notes
n4launcher
This file is the shell script responsible for launchingNiagara 4 applications. It is used primarily by the Desktop
and Menu entries as a means to automate the creation of a suitable runtime environment (that is, env varia-
bles); although, a user could use this script from the command line if they choose.
If this file is deleted, Desktop and Menu shortcuts will no longer work. It is not advised to change the con-
tents of this file.
Default attributes are: -r-xr-x- - - niagara:niagara
gradlew
This file is a shell script responsible for downloading, if necessary, and launching gradle to build Niagara 4
modules. It corresponds to the gradlew.bat file in a Windows environment.
Default attributes are: -rwxr-xr-x niagara:niagara
lib*.so
These files are runtime libraries used by Niagara. They correspond to the *.dll files in a Windows environ-
ment. Deletion of any of these files will result in Niagara run time failure.
Default attributes are: -rwxr-xr-x niagara:niagara
.niagara
This file sets up the run time environment needed to run any Niagara 4 binary. It will properly initialize sev-
eral important variables, such as LD_LIBRARY_PATH and NIAGARA_HOME. This script can be sourced at the
command line to allow you to launch Niagara 4 binaries, such as wb, from the command line at a later time.
Deletion of this file will prevent Desktop and Menu shortcuts from functioning properly, as well as
n4launcher and niagaradctl. Do not modify the contents of this file as it is custom generated at install
time for Niagara 4.
Default attributes are: -rwxr-xr-x niagara:niagara
niagarad
This file is the niagara daemon, aka platform daemon. It corresponds to the file niagarad.exe in a Win-
dows environment. Do not execute this file manually, as it should only be controlled (e.g, started/stopped)
by the script niagaradctl. Deletion of this file will prevent the niagaradctl script from functioning prop-
erly and will prevent you from making platform connections to your host in “wb”. Do not delete or modify
this file in any way.
Default attributes are: -r-x----- - niagara:niagara
niagaradctl
This file is the control script for niagarad. It is used to start, stop, and query as to the status of niagarad.
Symbolic links from /etc/init.d and runlevel directories are made to this file at service installation
time. This script may be executed by any users who are configured to use niagarad (done at installation
time) to manually start, stop, restart or query the niagarad service. Deletion of this file will prevent niag-
arad from running as a service, and will prevent niagarad from starting at boot time, and stopping at re-
start/reboot time. Do not delete or modify the contents of this file in any fashion.
Default attributes are: -rwxr-xr-x niagara:niagara
August 5, 2016 9
Chapter 1 Linux N4Supervisor Notes Linux N4 Supervisor
niagaradlog
Executing this script allows you to see any output from niagarad. niagarad is run as a service and there-
fore his its standard output is redirected to an internal logging service. This script will locate the logs gener-
ated by niagarad and print them to the screen. Deletion of this file will prevent you from seeing niagarad
output externally from Niagara applications (that is, you'll still be able to see it in “wb”).
Default attributes are: -rwxr-xr-x niagara:niagara
nre
This file is responsible for launching the Niagara Runtime Environment (NRE). It corresponds to the nre.exe
file in a windows environment. Deletion of this file will prevent you from being able to query the NRE exter-
nally from other Niagara applications, for example for hostid.
Default attributes are: -rwxr-xr-x niagara:niagara
station
This file is responsible from launching Niagara stations on your platform. It corresponds to the station.
exe file in a Windows environment. Deletion of this file will prevent you from launching any stations on your
local platform, pretty much rendering your N4Supervisor useless.
Default attributes are: -rwxr-xr-x niagara:niagara
test
This file is responsible for running predefined test cases against the NRE. It corresponds to the test.exe
file in a Windows environment. This file is not critical, but deletion of this file will prevent you from testing
the Framework.
Default attributes are: -rwxr-xr-x niagara:niagara
wb
This file is responsible for launching wb, that is Workbench. It corresponds to the file wb.exe in a Windows
environment. Deletion of this file will prevent you from launching wb.
Default attributes are: -rwxr-xr-x niagara:niagara
install_common.sh
This script contains constants and functions used by other scripts, including but not limited to add_n4_
user.sh and install_service.sh. This script should not be executed. Do not delete or modify the con-
tents of this file in any fashion.
Default attributes are: -r-xr-x- - - niagara:niagara
a d d _ n 4 _ u s e r. s h
This script is responsible for adding users on this platform to the user group that is eligible to start and stop
theNiagara 4 daemon. This process is also available when initially running install.sh but this standalone
script permits the addition of users after installation has taken place. This script needs to be executed with
elevated permissions using “sudo”.
Default attributes are: -r-xr-x- - - niagara:niagara
10 August 5, 2016
Linux N4 Supervisor Chapter 1 Linux N4Supervisor Notes
install_service.sh
This script is responsible for installing the Niagara 4 Platform Service, also referred to as “niagarad”. You will
need root privileges to successfully run the script. It can be run as a stand-alone installer and does not re-
quire or rely on install.sh at all. When run, the script will install (but not start) the platform daemon of
that version of Niagara 4, overwriting any other Niagara 4 daemon currently installed on that platform.
This means you can use this script to switch between Niagara 4 installations on your platform. Once com-
pleted, you may start the service from the command line or simply reboot. The script relies on niagarad_
generic, and as such, might fail to function properly if that file is significantly modified. If deleted, you will
be unable to switch the platform daemon between multiple Niagara 4 installations on your machine. Aside
from the fact that this script does not start the daemon upon completion, it corresponds to the I n s t a l l P l a t -
f o r m D a e m o n command available in a Windows environment. For details, see “Installing the platform
daemon”.
Default attributes are: -r-xr-x- - - niagara:niagara
niagarad_generic
This file is a cache of the original code used to generate niagaradctl used by install.sh. The contents
of this file are concatenated to niagaradctl at its creation following the generation of platform dependent
code during install.sh and install_service.sh runtime. Deletion of this file, or more than trivial
modification will prevent you from successfully reinstalling the platform service, i.e. install_service.sh.
Default attributes are: -rwxrwxr-x niagara:niagara
r e m o v e _ n 4 _ u s e r. s h
This script is responsible for removing users on this platform from the user group that is eligible to start and
stop theNiagara 4 daemon. This process is also available when running uninstall.sh but this standalone
scripts permits the removal of users without completely uninstalling Niagara 4. This script needs to be exe-
cuted with elevated permissions using “sudo”.
Default attributes are: -r-xr-x- - - niagara:niagara
uninstall_service.sh
This script is responsible for uninstalling the Niagara 4 Platform Service, aka niagarad. You need root privi-
leges to successfully run the script. It can be run as a standalone uninstaller, and will not remove the com-
plete Niagara installation from your platform, just the service. This script is provided as a convenience for
users who would like to prevent niagarad from starting at boot-time, or would like to disable the Niagara
installation temporarily, rather than remove it completely. Modification of this file may prevent it from suc-
cessfully completing. For details, see “Uninstalling the platform daemon”.
Default attributes are: -r-xr-x- - - niagara:niagara
uninstall.sh
This script is responsible for completely removing the LinuxN4Supervisor from your platform. In a Windows
environment, this script corresponds to uninstall.exe. You will need root privileges to successfully run
the script. It steps you through the uninstallation process via a series of yes or no questions. In order to
safely and efficiently remove Niagara 4, it uses a configuration file generated at installation time named un-
install.conf. For details, see “Uninstalling the Linux N4Supervisor.” However, if this file is missing, the
uninstaller can still be executed successfully (but it may ask unnecessary questions, and/or report incorrect
information). If this file is significantly modified, you may be unable to remove Niagara via an automated
process—and you just have to do it manually file by file.
Default attributes are: -r-xr-x- - - niagara:niagara
August 5, 2016 11
Chapter 1 Linux N4Supervisor Notes Linux N4 Supervisor
uninstall.conf
This file is created at installation time based on the configuration ofNiagara 4 (install service, doc, dist, etc.)
you chose to install. The key/value pairs in this file are used to efficiently remove Niagara when running the
script uninstall.sh by asking questions tailored for your platform. Modification or deletion of this file will
not prevent you from uninstalling Niagara, but it might cause the script uninstall.sh to ask questions,
and attempt to remove items, not tailored for your platform.
Default attributes are: -r- -r- -r- - niagara:niagara
12 August 5, 2016
Chapter 2 Common tasks
Topics covered in this chapter
♦ Using the Linux Supervisor station template
♦ Interacting with the platform daemon
♦ Starting the platform daemon
♦ Stopping the platform daemon
♦ Reinstalling the platform daemon
♦ Uninstalling the platform daemon
♦ Uninstalling the Linux N4Supervisor
♦ Troubleshooting
August 5, 2016 13
Chapter 2 Common tasks Linux N4 Supervisor
14 August 5, 2016
Linux N4 Supervisor Chapter 2 Common tasks
August 5, 2016 15
Chapter 2 Common tasks Linux N4 Supervisor
To fix this error, configure your station to start its WebService bound to port 8080, or another port above
1024.
N O T E : In N4.2, the Linux Supervisor station template is provided which creates a new station with the
WebService already configured for HTTP on port 8080 and HTTPS on port 8443. You will still need to set-
up firewall rules to redirect port 80 to 8080, and port 443 to 8443.
16 August 5, 2016
Index
C U
controlling platform daemon...............................13 uninstalling
Linux Supervisor..............................................15
uninstalling platform daemon ..............................15
E using the station template...................................13
error messages
troubleshooting ..............................................15
F
folder contents
!/bin..................................................................9
!/install............................................................10
!/uninstall ........................................................11
I
installation directories...........................................7
installing Linux N4Supervisor ................................7
installing platform daemon..................................14
L
Linux N4Supervisor
about installing .................................................7
directory structure.............................................7
installation file ...................................................7
N
N4Supervisor notes ..............................................7
P
platform daemon
controlling ......................................................13
installing .........................................................14
starting ...........................................................14
stopping .........................................................14
uninstalling .....................................................15
S
starting platform daemon ...................................14
station template .................................................13
stopping platform daemon .................................14
T
troubleshooting..................................................15
August 5, 2016 17