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.
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:
-
Ruby Enterprise Edition 1.8 (www.rubyenterpriseedition.com/index.html)
-
Apache 2.2 (www.apache.org/)
-
Phusion Passenger 2.2 or 3.0 (www.modrails.com/index.html)
-
MySQL 5.1 (dev.mysql.com/downloads/mysql/)
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).
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).
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
}
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
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)
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
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
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 © 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/>.
2 icons (table.png and page_excel.png) from www.famfamfam.com/lab/icons/silk/ (Creative Common Attribution 2.5 License)