The purpose of this guide is to help an IT administrator install and configure the STARRS network asset tracking application for a basic site.
The intended audience of this guide is IT administrators with Linux experience (specifically Red Hat) and a willingness to use open-source software.
The install process should take around an hour provided appropriate resources.
STARRS is a self-service network resource tracking and registration web application used to monitor resource utilization (such as IP addresses, DNS records, computers, etc). For more details, view the project description here.
STARRS requires a database host and web server to operate. It is recommended to use a single virtual appliance for all STARRS functionality.
- The virtual appliance is provisioned (out of scope of this guide)
- Core software is installed
- Dependent software packages are downloaded and installed
- STARRS is acquired, configured, and installed
- The web server is configured to allow access
STARRS was tested only on RHEL-based Linux distributions. Anything RHEL6.0+ is compatible. There are no major requirements for the virtual appliance and a minimal software install will suffice. In this example we will be using a Scientific Linux 6.4 virtual machine.
Ensure that you are able to log into your remote system as any administrative user (in this example, root) and have internet access.
Firewalls can get in the way of allowing web access to the server. Only perform these steps if you have a system firewall installed and intend on using it. In this example we will use the RHEL default
- Add a rule to the system firewall to allow HTTP and HTTPS traffic to the server.
- Save the firewall configuration (no restart required)
NOTE: If you have IPv6 enabled on your system, make sure to apply firewall rules to the IPv6 firewall as well.
Any RHEL administrator has dealt with SELinux at some point in their career. There are system-wide settings that allow/deny actions by programs running on the server. Disabling SELinux is not a solution.
- Allow Apache/httpd to connect to database engines
STARRS heavily depends on the PostgreSQL database engine for operation. PgSQL must be at version 9.0 or higher, which is NOT available from the standard RHELish repositories. PgSQL will also require the PL/Perl and PL/Python support packages (also NOT located in the repos). You will need to add new software repositories to your appliance.
These programs will be needed at some point or another in the installation process.
- Install the following packages through yum.
- We will also need the development tools group of packages installed.
PostgreSQL Database Engine
On your own computer, open up yum.postgresql.org and click on the latest available PostgreSQL Release link. In this case we will be using 9.2.
Locate the approprate repository link for your operating system (Fedora, CentOS, SL, etc) and architecture (i386, x86_64, etc). In this case we will be using
Scientific Linux 6 - i386.
Download the package from the link you located onto the virtual appliance into any convenient directory.
- Install the PostgreSQL repository package file that was downloaded with
yum. Answer yes if asked for verification.
- You need to ensure that the base PostgreSQL packages are hidden from future package searches and updated. Add an exclude line to your base OS repository file located in
/etc/yum.repos.d/. This will prevent any PgSQL packages from being used out of the base packages.
1 2 3 4 5 6 7
- Install the required PgSQL packages using the Yum package manager.
- Initialize the PgSQL database server
1 2 3
- Make PgSQL start on system boot
- Start the PgSQL service
1 2 3
suto the Postgres account and assign a password to the postgres user account using the query below. Exit back to root when done. This password should be kept secure!
1 2 3 4 5 6 7 8 9 10 11 12
The STARRS installer requires passwordless access to the postgres account. This is achievable by creating a
.pgpass file in the root home directory.
- Create a file at
1 2 3
You can replace the passwords with whatever you want. Note the passwords for later.
- This file should be readable only by the user that created it. Change permissions accordingly.
- You now need to allow users to login to the database server from the server itself. Open the
/var/lib/pgsql/9.2/data/pg_hba.confand change all methods to
1 2 3 4 5 6 7 8
This will enable login from Localhost only. If you need remote access, only allow the specific IP addresses or subnets that you need. Security is good.
- Reload the postgres service to bring in the changes
- Create admin and client accounts for STARRS.
1 2 3 4 5 6 7 8 9 10
- Verify that you can log into the database server without being prompted for a password.
1 2 3 4 5 6 7
If you get prompted for a password, STOP! You need to have this working in order to proceed. Make sure you typed everything in the file correctly and its permissions are set.
STARRS has many other software dependencies in order to function. These are mostly Perl modules that extend the capabilities of the language. These modules are (CPAN and package are provided however not all packages may be available):
- Net::IP (perl-Net-IP)
- Net::LDAP (perl-LDAP)
- Net::DNS (perl-Net-DNS)
- Net::SNMP (perl-Net-SNMP)
- Net::SMTP (perl-Mail-Sender)
- Crypt::DES (perl-Crypt-DES)
NOTE: The first time you run CPAN you will be asked some basic setup questions. Answering the defaults are fine for most installations.
- Install each of these modules. Some of them are available as packages in yum.
1 2 3
STARRS comes in two parts: The backend (database) and the Web interface. Each one is stored in it’s own repository on Github. You will need to download both in order to use the application. Right now we will focus on the backend.
- You will need a directory to store the downloaded repos in. I recommend using
/opt. Clone (download) the current versions of the repositories using Git into that directory.
1 2 3 4 5
- Open the installer file at
/opt/starrs/Setup/Installer.pl. You will need to edit the values in the Settings section of the file to match your specific installation. Example:
1 2 3 4 5 6 7 8 9 10 11
dbsuperuser is the root postgres account (usually just ‘postgres’).
dbadminuser is the STARRS admin user you created above.
dbclientuser is the STARRS client user you created above.
sample will populate sample data into the database. Set to anything other than
undef to enable sample content.
- Run the install script
A lot of text will flash across the screen. This is expected. If you see errors, then something is wrong and you should revisit the setup instructions.
You can verify that STARRS is functioning by running some simple queries.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
If you see “Greetings admin!” and you can perform the queries without error, then your backend is all set up and is ready for the web interface.
The STARRS web interface requires a web server to be installed. Only Apache has been tested. If you have a new system then you might not have Apache (or in RHELish, httpd) installed.
- If you do not have Apache/httpd installed, install it.
Navigate to the
welcome.confthat exists there.
- Enable httpd to start on boot
- Start the httpd service. (Warning messages are fine, as long as the service starts you should be fine)
1 2 3 4 5
A minor change to the system PHP configuration allows the use of short tags for cleaner code. This feature must be enabled in the
- In the php.ini file, set
short_open_tag = on
You will be cloning the starrs-web into the Apache web root directory to simply deployment.
- Change directory to
/var/www/html/and clone the repository. Note the . at the end of the clone command.
Edit the copied/renamed database file and enter your database connection settings. Example:
1 2 3 4
For this web environment, the defaults in this file are fine. In this file you can change which environment variable to get the current user from.
Apache needs to be given some special instructions to serve up the application correctly. Create a file at
/etc/httpd/conf.d/starrs.confwith the following contents:
1 2 3 4 5 6 7 8
- Since we reference an authenication database, you will need to create this file (
- Restart Apache to apply the changes. (A reload is not sufficient enough)
At this point you should have a fully functioning STARRS installation. Navigate to your server in a web browser and you should be prompted for login credentials. As we established in the authentication database file, the username is root and the password is admin. If you get the STARRS main page, then success! Otherwise start looking through log files to figure out what is wrong.
Detailed troubleshooting is out of the scope of this guide. System Administrator cleverness is a rare skill, but is the most useful thing when trying to figure out what happened. Shoot me an email if you really feel something is wrong. I have included a few common errors here that I have run into when I don’t follow my own instructions.
PHP DB Error
If you see this render
It probably means your DB credentials in
application/config/database.php are not correct.
If you see a blank page in the browser and something like this in the log file:
It probably means that PHP
short_open_tag is not On in