Segfault Research > Projects > Server > NetXMS Simple Dashboard > NetXMS Simple Dashboard - Setup
First published on: 02-Nov-2013

You'll see a lot of text here as I try to put all possible details, but in the end configuring the utility is very easy.

Index:


Starting point

You have just installed the utility, have restarted your webserver and when trying to access NetXMS Simple Dashboard the only thing you see is the following message:
ERROR DETECTED - (in function "index.php")
Custom error message is: The user "noauth" is not authorized to access this application.

This is good - the first thing that has to be configured are the authorizations.


Authorization

NetXMS Simple Dashboard does offer a basic form of authorization, but does not perform any authentication.

Option 1 - free access

The simpliest option is to authorize anybody to access the utility.
To do so, edit the file "[your_base_dir]/netxms-simple-dashboard/config/authorized_users.txt" and change/uncomment the line "#noauth", resulting in a file that contains only the string "noauth".

After saving the changes and reloading the page you should be greeted by the main page:

Option 2 - allow only selected users

The job of authenticating users can be very dangerous if the code in charge is not 100% correct and has been tested extensively.
Additionally, the authentication methanisms available are many (e.g. Apache basic or digest, ldap, kerberos, 2-way-SSL/PKI, WinNT, and many more...) and differenciate a lot from each other.

Because of the above reasons we decided not to cook something on our own, but to rely completely on the external authentication mechanisms that have anyway been written by professionals and have tested by a huge user community.

Having said this, what our utility can do is to just search for a specific HTTP-header or environment variable that is created AFTER that the user was authenticated (by Apache, 2-way-SSL, whatever) and then check in a list if that user is supposed to be allowded to access the utility.
This can be configured very easily:

0)
Set up NetXMS Simple Dashboard as mentioned under "Option 1 - free access".
You'll see on the bottom-right corner that the currently logged-in user is called "noauth".

1)
Enable whichever authentication mechanism you want to use (Apache basic or digest, LDAP, etc...).

2)
Open the file "[your_base_dir]/netxms-simple-dashboard/app/index.php" and change the line (one of the first ones) that says...
//phpinfo();
...to...
phpinfo();
...and reload the page => this time you'll have to authenticate using the method you chose (Apache basic or digest, LDAP, etc...).

3)
On the page you should now see the title "PHP Version....." together with a huge list of informations.
Search in that list for the userID that was authenticated.

For example. if you used the Apache Digest authentication and your userID is "joe", you should find in that list some lines saying e.g. ...
REMOTE_USER   joe
_SERVER["REMOTE_USER"]   joe
_SERVER["PHP_AUTH_USER"]   joe

If you cannot find any such line then all this won't work (doublecheck that your authentication is really working).
If you do find them then take note of their names and undo the changes you did above in the file "index.php" to get rid of the huge list of PHP informations.

4)
Now you know how the HTTP-headers and/or the environment variables that contain the authenticated username are called and can configure the utility to use them accordingly.
Edit "[your_base_dir]/netxms-simple-dashboard/config/config_parameters.txt" setting...
authenticate_users_using_http_header|true
...(was originally set to "false") and...
http_header_name_of_authenticated_user|REMOTE_USER
...or...
http_header_name_of_authenticated_user|PHP_AUTH_USER

If you now reload the page you should see a message saying...
ERROR DETECTED - (in function "index.php")
Custom error message is: The user "joe" is not authorized to access this application.

5)
Almost done.
Edit the file "[your_base_dir]/netxms-simple-dashboard/config/authorized_users.txt", delete or comment the line "noauth" and add "joe" => if you now reload the page you should see in the bottom-right corner that the user was recognized and authorized to access the application:

This is not very useful if for example you have only 1 user in your Apache digest authentication file, but it is if e.g. you have 100 users and don't want to explicitly mention in the Apache virtual server file who should be authorized to access this utility, if you use in a big company 2-way-SSL to authenticate all users but only 3 admins should have access, etc... .


Windows / CGI

If you're running this utility as CGI-app, which might especially be true on Windows when using IIS as webserver, things might not work as expected.
We do not have a lot of experience with this, but we have implemented a workaround which should make the utility render correctly in your browser.

1)
Open the file "[your_base_dir]/netxms-simple-dashboard/config/config_parameters.txt".

2)
Find the line...
page_needs_content_type|false
...and change its value to "true".


Subdomains vs. virtual directories

If you're not making the utility available directly through a subdomain (e.g. "https://sysmonitoring.mydomain.org") but through a virtual directory (e.g. "https://mydomain.org/sysmonitoring") then the "back" link available on each page might not work correctly.

To fix this edit in "[your_base_dir]/netxms-simple-dashboard/config/config_parameters.txt" the parameter...
main_url_workaround|https://myrootdomain.com/myuri/index.php
...putting there the utility's absolute URL.


Database

The module PDO for PHP is required.
If you see the message...
Fatal error: Class 'PDO' not found in /var/www/localhost/htdocs/netxms-simple-dashboard/app/db/common.php on line 16
...then you obviously don't have it => install it.

Open the file "[your_base_dir]netxms-simple-dashboard/config/config_parameters.txt" and uncomment & modify the following parameters so that they point to the same database that NetXMS uses:

  • DB_connString
  • DB_username
  • DB_userpwd

An example for each of the database types that we tested (Oracle, MySQL, SQLite and PostgreSQL) is included.

For best performance use Oracle and PostgreSQL.

Ideally create a new DB-user which has only read-privileges on the NetXMS database and use that credential to provide access for this utility - this utility is open for SQL injection attacks.


Optional modules

Right now we don't have anything that could be correctly defined as "module".
But please still have a look at the modules page for hints about activating the zooming/drilldown functionality and using additional fonts to be used in your graphs.