Administration Guide

Prepared by:

Andrew Madison, Founder and CEO

Document date:

May 05, 2014

Document number:

20140505-­01

Software version:

1.0.0

Table of Contents:

1. Installation
1. System requirements
2. System disk configuration
3. Software Packages and Locale
4. Apache Web server configuration
5. Kernel and Security Limits configuration
6. InfraTrack Portal installation
7. InfraTrack Portal configuration
2. Application customizations
1. Application directory structure
2. infratrack_WEB.ini
3. dashboard.php
4. datacenters.php
5. index.php
6. info.php
7. mgdevices.php
8. mgtemplates.php
9. profile.php
10. settings.php
11. users.php
12. datacenter.png
13. bottom.php
14. head.php
15. top.php
16. access_levels.php
17. enc_module.php
18. form_fields.php
19. access_levels.php
20. infratrack.mo

Installation

InfraTrack Portal is an open source web utility that provides full access to its source code. This allows a system administrator to customize all features to fit the business needs. The freely downloadable web utility is provided as an example of integration with InfraTrack API.

System requirements

InfraTrack Portal native development platform is Debian Linux. While the application may function properly on other operating systems, we will only support installations on Linux as presented in this document.

Support schema:

Hardware requirements:

For a number of 30 active accounts with 10 concurrent online users, here are the minimum hardware requirements:

System disk configuration

InfraTrack Portal web application is not a disk intensive utility. Yet as in any critical system having hardware disk mirroring is mandatory.

The minimum disk size for Operating System and InfraTrack Portal install is 40GB. Two separate disks should be configured:

• Disk 1: RAID5 / min. 30GB
• Disk 2: RAID10 / min. 10GB

Logical Volume Manager (LVM) should be used to configure the disks allocation in the operating system.

From Disk 1, create a 250MB primary partition to me mounted as /boot. From the remaining disk, create a second primary partition to be used with the vgsys volume group.

vgsys volume group will have the following Logical volumes:

From Disk 2 create a single primary partition and allocate the entire disk space to it. Then, create a volume group named vgsrv. vgsrv will have the following logical volume:

Additionally, on systems with more than 100 concurrent users, we recommend enabling Kernel noop scheduler. This allows for better disk performance on heavy transactions.

To enable noop scheduler, edit your Grub2 configuration file (/etc/default/grub) by appending "elevator=noop" to the GRUB_CMDLINE_LINUX_DEFAULT parameter.

Example:

GRUB_CMDLINE_LINUX_DEFAULT="quiet elevator=noop"

Install the new boot loader by issuing command:

sudo /usr/sbin/update-grub2

Now restart your system and after reboot check that noop was enabled by issuing command:

cat /sys/block/*/queue/scheduler

The result should show:

Software Packages and Locale

Linux Packages:

The following packages should be installed at their latest version:

• Apache 2.4
• Apache PHP5 module
• PHP5
• PHP5 modules: CURL, XSL, JSON, GETTEXT, MYCRYPT and JSON SERVICES

Install the packages on your system using commands:

sudo apt-get update
sudo apt-get install libapache2-mod-php5 bc
sudo apt-get install php5-curl curl wget
sudo apt-get install php5-xsl
sudo apt-get install php5-json 
sudo apt-get install php-services-json
sudo apt-get install php-gettext
sudo apt-get install php5-mcrypt

Linux Locale:

Because InfraTrack Portal uses internationalization features, you need to enable all locale variables that you plan on using with the website. Currently the following languages are included in the software:

• de_DE.UTF-8
• en_US.UTF-8
• es_ES.UTF-8
• fi_FI.UTF-8
• fr_FR.UTF-8
• nl_NL.UTF-8
• ro_RO.UTF-8
• ru_RU.UTF-8

To enable locale, edit as root /etc/locale.gen file and uncomment lines:

• de_DE.UTF-8
• en_US.UTF-8
• es_ES.UTF-8
• fi_FI.UTF-8
• fr_FR.UTF-8
• nl_NL.UTF-8
• ro_RO.UTF-8
• ru_RU.UTF-8

Execute commands to apply changes:

sudo /usr/sbin/locale-gen
sudo /usr/bin/locale -a

Repeat the above steps for all additional languages you plan to use.

Apache Web server configuration

Enable PHP Support in Apache by adding a link in /etc/apache2/mods-enabled/ to /etc/apache2/mods-available/php5.conf and /etc/apache2/mods-available/php5.load

sudo ln -s /etc/apache2/mods-available/php5.conf /etc/apache2/mods-enabled/php5.conf
sudo ln -s /etc/apache2/mods-available/php5.load /etc/apache2/mods-enabled/php5.load

If InfraTrack Portal is to be used via SSL, enable the SSL Apache module too by running commands:

sudo ln -s /etc/apache2/mods-available/ssl.conf /etc/apache2/mods-enabled/ssl.conf
sudo ln -s /etc/apache2/mods-available/ssl.load /etc/apache2/mods-enabled/ssl.load
sudo ln -s /etc/apache2/mods-available/socache_shmcb.load /etc/apache2/mods-enabled/socache_shmcb.load

A sample apache configuration for InfraTrack Portal running as a SSL Apache Virtual Host is available for download here

Ensure you customized at a minimum the following parameters before deploying the Apache SSL sample configuration file:

• ServerAdmin
• ServerName
• ServerAlias
• SSLCertificateFile
• SSLCertificateKeyFile
• SSLCACertificateFile

A sample apache configuration for InfraTrack Portal running as a HTTP Apache Virtual Host is available for download here

Ensure you customized at a minimum the following parameters before deploying the Apache HTTP sample configuration file:

• ServerAdmin
• ServerName
• ServerAlias

To deploy InfraTrack as a Virtual directory within an existing Virtual Host, add the following to your Apache host configuration:

Alias /infratrack/ "/srv/infratrack_www/"
<Directory "/srv/infratrack_www/">
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
    Order deny,allow
    Allow from All
</Directory>

Save the configuration file in /etc/apache2/sites-available and link it in /etc/apache2/sites-enabled

Kernel and Security Limits configuration

To enable maximum performance on your system, we recommend downloading our Kernel and Limits sizing scripts and executing them to generate configuration files.

The kernel sizing script is available here

The limits sizing script is available here

Execute the scripts as root user

Note:
You must restart your system after changing the kernel and security limits configuration files.

InfraTrack Portal installation

Download InfraTrack Portal web application from http://download.infra-track.com/infratrack_web_1.0.0.tar.gz

From the download location, extract the package content and change directory to infratrack_web_1.0.0

From within directory infratrack_web_1.0.0, execute as root install_web.sh

This script will create a /srv/infratrack_web directory and copy all web files to it. A configuration file will also be created in /etc/infratrack/ folder and proper permissions will be given to all new created objects.

The install_web.sh script will prompt you for the following configuration items:

1. Is Apache already configured for InfraTrack Web (yes/no)
• This question refers to the "Apache Web Server configuration" section of this document and if it was completed. If not, please answer "no"
2. What is the API server address?
• You must provide the address to the hosted InfraTrack API server or your in-house installation
• e.g.: https://sapi.infra-track.com:18892
3. Provide your API license key
• This is your permanent or trial license key
• e.g.: a8c66258-2467-4c83-79ab-24671f4556cb

If Apache is already configured a manual apache web server service restart will have to be performed at the end of the installation.

Once the installation is complete, point your browser to the configured server address and you should be able to see the InfraTrack Portal login screen.

If the page is not loading or errors are recorded in the Apache log, please verify that all components are installed

InfraTrack Portal configuration

The configuration file is located on your system at /etc/infratrack/infratrack_WEB.ini

Configurable items are:

Sample infratrack_WEB.ini file:

;  sets  the  amount  of  memory  in  bytes  to  be  used  by  the  PHP  process  
;  a  value  of  -1  disables  all  limits;  use  this  value  with  care  
;  as  it  may  impact  server  performance  
;  default  value  =  134217728  
MEMORY_LIMIT  =  134217728  
;  pipe  (|)  separated  values;  a  value  of  -1  will  log  all  errors  
;  in  production  systems,  best  setting  is:  E_ERROR  
;  default  value  =  E_ERROR  |  E_WARNING  |  E_PARSE  
ERROR_LEVEL  =  E_ERROR  |  E_WARNING  |  E_PARSE  
APP_NAME  =  "InfraTrack"  
COMPANY_ID  =  "a8c66258-2467-4c83-79ab-24671f4556cb"  
WEB_ADDRESS  =  "http://portal.phx1.az.us.amdatasoft.net/"  
WEB_SERVICE_ADDRESS  =  "https://sapi.infra-track.com:18892"
RSS_FEED  =  "http://infra-track.com/news/feed.rss"  
RSS_ITEMS  =  3  
WEB_ROOT  =  "/srv/infratrack_www"  
URL_PATH  =  ""  
MAX_RECS_PER_PAGE  =  8  
DATETIME_FORMAT  =  "Y-m-d H:i:s T"  
MAP_CENTER_LAT  =  0.00000  
MAP_CENTER_LONG  =  0.00000
MAP_ZOOM = 1

Application customizations

As previously mentioned, the InfraTrack Portal web application is an open source solution. This allows the user to fully customize all components as long as good PHP development experience and strong understanding of web services is available.

This document will focus on customizing the existing downloadable application.

Application directory structure

infratrack_WEB.ini

See the "InfraTrack Portal configuration" section of this document for customization details

dashboard.php

Modify the dashboard to display relevant information about your infrastructure. This page is also be used as a pre-loader for template, datacenter and device sessions. Ensure that all sessions are generated on page load and that no session reload occurs unless data is changed. Avoid adding forms to this page as its purpose is to display data.

datacenters.php

This page is a full-feature module that allows editing, viewing and addition of datacenters. Form field components are driven from the lib/form_fields.php file, $arr_dc_data_format array. It is mandatory that you pre-define form fields in $arr_dc_data_format and add necessary labels in all used language files before applying changes to this module. After each change or addition to the data centers list, the datacenters_list and datacenters_list_create_dt sessions must be refreshed.

index.php

The only true requirement of this page is the login screen. The validation occurs against the API and the following sessions are being set:

1. auth_head - Header authentication session for all REST requests
2. user_data - User information session
3. company_data - Company information session
4. company_data_create_dt - company_data session creation date

Note:
The RSS news feed is being configured in infratrack_WEB.ini file and NOT on this page.

info.php

The purpose of this page is to provide session and support information. The only mandatory feature is the "Sessions" tab where a user may choose to refresh their session data. Feel free to add additional support related items to this page

mgdevices.php

This page is a full-feature module that allows editing, viewing and addition of devices. Form field components are driven from the lib/form_fields.php file, $arr_device_data_format array. It is mandatory that you pre-define form fields in $arr_device_data_format and add necessary labels in all used language files before applying changes to this module. After each change or addition to the devices list, the devices_list, templates_list, devices_list_create_dt and templates_list_create_dt sessions must be refreshed.

mgtemplates.php

This page is a full-feature module that allows editing, viewing and addition of templates. Form field components are driven from the lib/form_fields.php file, $arr_template_data_format array. It is mandatory that you pre-define form fields in $arr_template_data_format and add necessary labels in all used language files before applying changes to this module. After each change or addition to the templates list, the templates_list and templates_list_create_dt sessions must be refreshed.

profile.php

On the profile page a user has the ability to change their contact information, password and locale details. Keep in mind that the user account (username) should never be a editable field as accounts are being setup by managers and administrators and must be unique for the entire organization. Form field components are driven from the lib/form_fields.php file, $arr_user_data_format array (same as the users module). It is mandatory that you pre-define form fields in $arr_user_data_format and add necessary labels in all used language files before applying changes to this module. As soon as the profile is changed, you must also update sessions:

1. auth_head - Header authentication session for all REST requests
2. user_data - User information session

settings.php

Note:
Take extreme caution and ensure backups are performed prior to making any changes to this file.

If for any reason you would like to use a different configuration ini file, or change the location of the ini file, change he path in line 45:

$app_settings_array = parse_ini_file("/etc/infratrack/infratrack_WEB.ini");

If the desired default time zone must be changed from UTC, change on line 82 with desired value:

define('DEFAULT_TIMEZONE', 'UTC');

Note that the default time zone is being used only when the user and company does not have a time zone pre-defined. In most cases, this is impossible, so changing line 60 should never be a requirement.

If the desired default language must be changed from en_US (English, USA), change on line 71 with desired value:

define('DEFAULT_LANG', 'en_US');

Note that the default language is being used only when the user and company does not have a language pre-defined. In most cases, this is impossible, so changing line 71 should never be a requirement.

users.php

This page is a full-feature module that allows editing, viewing and addition of users. Form field components are driven from the lib/form_fields.php file, $arr_user_data_format array (same as the profile module). It is mandatory that you pre-define form fields in $arr_user_data_format and add necessary labels in all used language files before applying changes to this module. After each change or addition to the users list, the users_list and users_list_create_dt sessions must be refreshed. Also, any changes to the existing logged in user should be performed from the profile page rather than from this module.

datacenter.png

1. Color depth: 24 bit
2. Size (W/H): 32 / 32
3. File format: PNG
4. Background: Transparent

bottom.php

Change as needed the <footer /> section of this file as needed but no other sections

head.php

Change as needed all components in "navbar-header" section. Consult Bootstrap documentation at http://getbootstrap.com/ on available options and styles.

top.php

Note:
Take extreme caution and ensure backups are performed prior to making any changes to this file.

Consider only adding additional javascript and stylesheed files to this module and do not remove any existing includes. The purpose of this file is to provide a framework for the entire content of the site, so making changes to existing scripts or references to scripts may damage the layout and functionality of the web application.

access_levels.php

Note:
Take extreme caution and ensure backups are performed prior to making any changes to this file.

List of configured access level parameters as $arr_access_level array. The 3 mandatory access levels are: ADMIN, MANAGER and USER

Those levels must not be modified and always in upper-case letters. Add values as needed and configure the web application security as needed to filter modules based on the new security values.

Array format must always be:

'LEVEL' => 'LEVEL'

enc_module.php

Note:
Take extreme caution and ensure backups are performed prior to making any changes to this file.

For security purposes, the device account passwords are encrypted before transmission back and from the API/Database engine. This protects your information while at rest or in flight. To do so, aes-256 encryption keys MUST be generated after a new installation of InfraTrack Web portal.

Generating keys is easy. On a Linux system with OpenSSL pre-installed, execute command:

openssl enc -aes-256-cbc -k /dev/urandom -P -md sha1

As example, the above command will result in:

salt=5D2862725AD5CA2B
key=E46EF334C839C1E1BC76F0074271A0451705593FB7E04D9D4EC6A56D46839B7D
iv =F89B1B6A80A867EF0141E5E1734E3813

From the result, copy the KEY value and locate the public $arr_crypto_keys variable in lib/enc_module.php file, enc_library class.

The variable will have multiple entries like:

'grp_01' => [
    'key_name'  => 'Admin Group',
    'key_value' => 'E46EF334C839C1E1BC76F0074271A0451705593FB7E04D9D4EC6A56D46839B7D',
    'key_pass'  => 'KuL4rT78-33V9'
]

Replace the key_value value with your new generated key.

Additionally, change the key_name and use a strong password for key_pass value.

Repeat this process for all keys required.

Also, ensure that you increment by 1 (+1) all "grp" array groups (e.g.: grp_01 followed by grp_02 followed by grp_03, etc.)

Once all keys are generated, distribute the file to all portal nodes in your environment and make sure that the keys are protected by changing ownership and read permissions on the lib/enc_module.php file:

sudo chown www-data:www-data /srv/infratrack_www/lib/enc_module.php
sudo chmod 400 /srv/infratrack_www/lib/enc_module.php

form_fields.php

Note:
Take extreme caution and ensure backups are performed prior to making any changes to this file.

Form Fields module is delivered with 4 groups of objects (arrays):

• arr_user_data_format - Users management fields
• arr_dc_data_format - Datacenters management fields
• arr_template_data_format - Templates management fields
• arr_device_data_format - Devices management fields

Each object contains multiple arrays in format:

'field_name' => [
  'field_label' => 'label_name',
  'field_name' => 'field_name',
  'field_default_val' => 'default_value',
  'field_readonly' => 'true or false',
  'field_length' => 'int. value of how many chars. are accepted',
  'field_type' => 'any',
  'field_validate' => 'true or false'
]

• field_name: unique identifier of the object. Must be equal with "field_name" sub-component
• field_label: actual label to display in page (label must be created in the language locale file)
• field_default_val: default value to display in field
• field_readonly: is the field read only (true/false)
• field_length: size of the field (numeric value representing the max. number of characters that the field will accept
• field_type: data type to be accepted in the field. Possible options are:
• any: any character
• email: email format (e.g.: user@example.com)
• phone: Phone format (e.g.: 888-123-4567)
• alpha: Letters only (upper and lower case)
• alphanum: alpha numeric values
• password: password field
• file: file upload field
• textarea: text area (must be base64 encoded before saving)
• select: dropdown select menu
• num: numeric value (int.)
• field_validate: should the data be validated before submission (true/false)

For example, we want to add a new field to the user's management form.

Steps:

1. Create the label in your language locale file (e.g.: lbl_user_middle_name)
2. Add the following object to arr_user_data_format list:



'user_middle_name' => [
  'field_label' => 'lbl_user_middle_name',
  'field_name' => 'user_middle_name',
  'field_default_val' => '',
  'field_readonly' => 'false',
  'field_length' => '20',
  'field_type' => 'alpha',
  'field_validate' => 'true'
]

3. The above object will create a new editable field in the users management form which will accept alpha characters up to 20 in length and will validate upon submission.

languages.php

List of configured locale languages as $arr_languages array.

Default array value is:

$arr_languages = [
    'en_US' => 'English (US)',
    'de_DE' => 'German (DE)',
    'es_ES' => 'Spanish (ES)',
    'fi_FI' => 'Finnish (FI)',
    'fr_FR' => 'French (FR)',
    'nl_NL' => 'Dutch (NL)',
    'ro_RO' => 'Romanian (RO)',
    'ru_RU' => 'Russian (RU)'
];

Follow instructions from the "Linux Locale" section of this document to add additional languages. After enabling additional languages at the operating system level, add them to the $arr_languages array in format:

'locale_CODE' => 'Language (Country)'

Example for Italian (Italy):

'it_IT' => 'Italian (Italy)'

infratrack.mo

For language editing we recommend using POEdit, a tool available at http://poedit.net/

.MO translations for all languages included are available for download at http://download.infra-track.com/languages_1.0.0.tar.gz

Extract the archive and open the language .PO file with POEdit. Make all necessary changes and save the .PO and resulting .MO files. Copy the updated file to all nodes as /srv/infratrack_www/locale/your_LANGUAGE/LC_MESSAGES/infratrack.mo (replace your_LANGUAGE with your actual language code; e.g.: it_IT)

It is imperative that you maintain the project name as "infratrack" and that the character set is UTF-8. When creating a new language, it is recommended that you start with an existing language file (.PO) and that you modify the language in the translation properties tab. Then continue making changes to all existing and new labels.

Note:
Do NOT remove existing labels.