license:
GNU General Public License
About:
How 'ovpnstatd' works.
ovpnstatd is a status collector daemon for OpenVPN. ovpnstatd can be started either interactively at the console or as a daemon in the background (--daemon).
Use "--help", to get a brief listing of available options.
If started interactively, all connected users and their update-events will be shown on the console-display. This start-mode is merely meant for testing/debugging.
A tcp-port (50505) will be opened, by which a very simple but useful web page can be viewed (http://yourhost:50505). There you get an entry for every OpenVPN-user, whose status-data is available as a result of a connect-event since ovpnstatd's startup. Users who are online, appear as a light-green(ish) entry, disconnected users are shown in grey/white.
The web page will remain empty, as long as no users have connected since startup of ovpnstatd.
The web page is intended for internal (administrator) use only - no "mass media", as ovpnstatd is not a multi-threaded program.
Should ovpnstatd already be running in the background, then you would have to change the port number (--tcp-port <NNNNN>) for your interactive session (if you really want it twice).
Only if started as daemon, ovpnstatd will serve its main purpose, it will collect data of all connect, disconnect, update events, which are reported by any OpenVPN server-process, and write history in csv-format, that can easily be loaded into a database or viewed in a spread-sheet.
In the same time, this data is also written to a FIFO-file "/<status_dir>/send_nsca_data" (/var/run/openvpn/send_nsca_data) in a format suitable for nagios's "send_nsca" utility.
The default location, where collector-data is written, is /srv/www/apps/ovpnstat/datacol - it can be changed with:
"--collect-dir <path-to-your-collector-directory>".
The location where event-data of OpenVPN-hooks is expected, is "/var/run/openvpn". This can be changed with the option:
"--status-dir <path-to-Your-status-directory>".
NOTE: For this to work, you also have to turn on status-logging in OpenVPN config-file(s): "status <path-to-status-data.status>" AND activate the hooks: "client-connect <your-con-script.sh>" and: "client-disconnect <your-dis-script.sh>"
Into the hook-script "your-script.sh" simply place/add the following echo command:
into "client-connect.sh" add the lines
echo -e "OVPN_PID=$PPID\n`env`" \
>/var/run/openvpn/${common_name}.con
into "client-disconnect.sh" add the lines
echo -e "OVPN_PID=$PPID\n`env`" \
>/var/run/openvpn/${common_name}.dis
NOTE: The extension of hook output-files has to be
.con for client-connect data-files
.dis for client-disconnect data-files
.status for status data-files given in OpenVPN config-file
otherwise those files will not be recognized by ovpnstatd.
You can display your favoured icon as a header of the web page.
As default for this, a built-in OpenVPN-icon is displayed.
If you want to replace the default icon in the source (ovpnstatd.h) look for variable "def_web_img64" and substitute its assignment by the output of "base64 -w0 <your-preferred-image>".
But only take tiny images for this !!!
If the TUN/TAP device driver control is not "/dev/net/tun" on your Linux-System, change it with: "--dev-node <Your tun/tap ctrl>"
In case you want to raise the debug-level, use "--debug <N>"
Level 0 = off, 1 = default, 2 = all
Installation:
# assuming that You've downloaded the tar-file to /usr/local/src
# proceed als follows:
cd /usr/local/src
tar -xjvf ovpnstat.tar.bz2
cd ovpnstat
make clean
make
# Now for a test start openvpn status collector daemon interactively :
bash ovpnstatd-test.sh
# If You got an OpenVPN server up and running on the same host
# then You can already take a look on the web-page
firefox http://your-host-name:12345/
# But NOTE: ovpnstatd must run on the SAME HOST, where openvpn-server is on
# Also note, that collector-data is only written, if the program
# is started in the background (--daemon ) .
# So to start it for "normal" usage copy file into place:
cp init-ovpnstatd /etc/init.d/ovpnstatd
cp ovpnstatd /usr/sbin/ovpnstatd
# only if You want to send data to Nagios, otherwise leave this away:
cp send_nsca.sh
# You also will have to create the collector directory
# if this location does not meet Your needs, just modify STARTOPTS
# in /etc/init.d/ovpnstatd and set --collect-dir to Your favoured
mkdir -p /srv/www/apps/ovpnstat/datacol
# then start openvpn status daemon
/etc/init.d/ovpnstatd start
Special hints:
Regarding Nagios NSCA:
Before you use the Nagios notification script "send_nsca.sh", you need to edit it - change the ip of the Nagios host therein - have a look if all the path-names are suiting your needs - AND install the "send_nsca" binary. It comes with package nagios-nsca-<version>
Once you have installed nagios-nsca on the Nagios server, you may just copy send_nsca from there to your openvpn-server (including its config-file) - that's all it needs.
Also add a Nagios configuration - a hostname entry for your openvpn-server where ovpnstatd will be running (must match exactly the output of 'hostname' and a service entry for each common-name (service_description must match common-name), that you want to monitor passively.
An example of a passive service config also is included here.
Regarding collector data:
The collector data is in csv format which allows you to easily load it into some database for your own web application.
Bugs (and the like creepers):
ovpnstatd is tested valgrind-clean and is running stable since quite a couple of months now on my openvpn-server.
Subscribe to this comment's feed
