A Rails application for managing a wISP's access points
Clone or download
idemarinis and nemesisdesign Added username viewer role to hide username
when operator is not auhorized. Last login shows
last 5 charachters
Latest commit 8c203df Mar 9, 2017

README.rdoc

OpenWISP Geographic Monitoring

What is it?

OpenWISP Geographic Monitoring (OWGM) is a Ruby on Rails application, capable of monitoring a wISP's access points.

OWGM supports the following functionalities:

  • monitoring access point availability and position via GMaps

  • english/italian translation

Even though the application can be used as standalone, such use will result in a pretty useless application. OpenWISP Geographic Monitoring is in fact made to be integrated OWM.

How to install

Prerequisites

The OpenWISP Gegraphic Monitoring is currently being developed with Ruby on Rails 3.0. Being a RoR application, it can be deployed using any of the methods Rails supports. Even so, what we are currently using (and find quite stable) is the following environment:

Installation

Once deployed using your favourite environment, you need to configure a deamon OpenWISP Geographic Monitoring needs to perform its usual activities (mainly using ICMP to check for AP connectivity).

To do this, you can use the following init.d script (customization may be needed, this script was coded for Ubuntu 10.04).

Startup script

The following script (Ubuntu/Debian style) should be named owgm-daemons. It assumes OpenWISP Geographic Monitoring running on ruby enterprise and that the application was deployed to /var/rails/owgm. Of course you can change any of that to whatever fits your needs.

#!/bin/sh
### BEGIN INIT INFO
# Provides:          owgm-daemons
# Required-Start:    $local_fs $network
# Required-Stop:     $local_fs $network
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Starting owgm-daemons
# Description:       Starting owgm-daemons
### END INIT INFO#

########## Variables for openwisp-daemons ##########

# The directory in which all the various OpenWisp
# applications are deployed. Generally it's /var/www
# or /var/rails
OPENWISP_BASE_PATH="/var/rails"

# The daemon you wish to start with this script
# (it must have already been deployed of course).
OPENWISP_APP="owgm"

# The Rails environment in which the script must be run.
# It will almost always be set to production.
RAILS_ENV="production"

####################################################

export PATH RAILS_ENV

# Define LSB log_* functions.
# Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
. /lib/lsb/init-functions

bundle_exec() {
  cd $1 && bundle exec $2
  return $?
}

openwisp_daemons_start() {
  bundle_exec $OPENWISP_BASE_PATH/$OPENWISP_APP 'rake daemons:start'
}

openwisp_daemons_stop() {
  bundle_exec $OPENWISP_BASE_PATH/$OPENWISP_APP 'rake daemons:stop'
}

openwisp_daemons_restart() {
  bundle_exec $OPENWISP_BASE_PATH/$OPENWISP_APP 'rake daemons:restart'
}

openwisp_daemons_status() {
  bundle_exec $OPENWISP_BASE_PATH/$OPENWISP_APP 'rake daemons:status'
}

case "$1" in
  start)
    log_daemon_msg "Starting OpenWISP daemon" "$NAME"
    openwisp_daemons_start
    RET="$?"
    log_end_msg $RET
    return $RET
    ;;
  stop)
    log_daemon_msg "Stopping OpenWISP daemon" "$NAME"
    openwisp_daemons_stop
    RET="$?"
    log_end_msg $RET
    return $RET
    ;;
  restart)
    log_daemon_msg "Restarting OpenWISP daemon" "$NAME"
    openwisp_daemons_restart
    RET="$?"
    log_end_msg $RET
    return $RET
    ;;
  status)
    openwisp_daemons_status
    RET="$?"
    return $RET
    ;;
  *)
    echo "Usage: /etc/init.d/$NAME {start|stop|restart|status}" >&2
    exit 1
    ;;
esac

exit 0

As usual, you need to

chmod +x owgm-daemons
/etc/init.d/owgm-daemons start

and enable the script to be run at boot (e.g.: with the @update-rc.d@ command).

Logs rotation

To enable the rotation of logs it is possible to use following @logrotate@ script (it could be saved as /etc/logrotate.d/rails).

/var/rails/*/log/*.log {
    weekly
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    copytruncate
## It's possible to use the following macros instead of the "copytruncate" option
#   create 660 root www-data
#   sharedscripts
#  postrotate
#    if [ -f "`. /etc/apache2/envvars ; echo ${APACHE_PID_FILE:-/var/run/apache2.pid}`" ]; then
#      /etc/init.d/apache2 reload > /dev/null
#    fi
#    /etc/init.d/owgm-daemons restart
#  endscript
}

Configuration options

in the YAML file in config/config.default.yml are specified some configuration options for this web application.

If you need to customize these options proceed by copying the file and rename it config/config.yml

$ cp config/config.default.yml config/config.yml

The options you can customize are:

  • pagination in access point list

  • show “status” column in availability report

  • last_logins: shows session information of users in AP detail page (depends on OWMW and OWMW must be enabled for specific wisps)

  • max_threads: number of threads used by background job

  • ping_timeout: minutes between pings

  • housekeeping_interval: months for the housekeeping

The following options must be configured if the alert system is in use

  • protocol: http or https, defaults to https for security reasons

  • host: domain or ip address where OWGM is installed

  • subdir: subdir in which owgm is installed, defaults to “owgm”, leave blank if owgm is installed in the root public directory

  • from_email: email address that will be used as *“from”* when sending alerts

  • alerts_threshold_down: default “threshold down” value for group alert settings

  • alerts_threshold_up: default “threshold up” value for group alert settings

  • alerts_email: default email value for group alert settings

Alerts

Since version 1.3, OWGM can send email alerts when an access point changes status from reachable to unreachable and vice versa.

Alerts can be configured on a group of access points, by editing the group settings, or can be configured specifically for a single access point. The only requirement is that the access point is in a group that is being monitored, that is has the flag “Monitoring active?” set as true.

For alerts to work, rails SMTP configuration must be set correctly. If alerts are not being sent, edit your environment file and check if the SMTP settings are configured, eg:

# config/environments/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
    :address =>              '127.0.0.1',
    :port =>                 25,
    :domain =>               'mail.mydomain.com',
    #:user_name =>            'user',
    #:password =>             'password',
    #:authentication =>       'plain',
    #:enable_starttls_auto => false
}

Some default values can be configured in *config.yml*:

  • alerts_threshold_down

  • alerts_threshold_up

  • alerts_email

Since version 1.4 it is also possible to customize the alert subject and body text by uncommenting and tweaking the following configuration keys in config.yml:

  • alert_down_subject_suffix

  • alert_up_subject_suffix

  • alert_body_text_admin (message sent to admins)

  • alert_body_text_manager (message sent to emails set in the “Manager email” field of each access point)

OWUMS graphs

Enable each wisp you need by configuring the owums hash in *config.yml*:

owums: {
    "wisp-slug": {
      url: "https://mydomain.com/owums",
      username: "username",
      password: "password"
    }
}

Keep in mind that:

  • each key in the owums hash represents a wisp

  • keys must contain wisp slug (lowercase name and dashes instead of spaces)

  • user must have 'stats_viewer' permission

Exception notifications

Since version 1.3 OWGM can send exceptions via email.

To make it work be sure to configure your smtp_settings correctly as described before and then set the following configuration keys in your config.yml:

  • exception_notification_recipients

  • mail_subject_prefix

Sentry exception notification

Available since OWGM-1.4.1.

Just add to your configuration file in config/config.yml the following line:

sentry_dsn: 'http://public:secret@example.com/project-id'

To obtain a new dsn setting key, create a new project in your sentry account, add the domain of the OWUMS instance on to the allowed domains, then get the dsn setting by going to the “installation & setup” page on the project.

Copyright

Copyright (C) 2012 OpenWISP.org

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <www.gnu.org/licenses/>.

External Credits

2 icons (table.png and page_excel.png) from www.famfamfam.com/lab/icons/silk/ (Creative Common Attribution 2.5 License)