diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 259 |
1 files changed, 259 insertions, 0 deletions
@@ -0,0 +1,259 @@ +downtimed - system downtime monitoring and reporting tool +========================================================= + +Copyright (c) 2009-2013 EPIPE Communications. All rights reserved. + +This software is licensed under the terms and conditions of the FreeBSD +License which is also known as the Simplified BSD License. You should have +received a copy of that license along with this software. + +Software web site: + + http://dist.epipe.com/downtimed/ + +Development version is available at Launchpad: + + https://launchpad.net/downtimed + +Main development branch of downtimed is available with Bazaar VCS: + + bzr branch lp:downtimed + +Author's e-mail address for reporting bugs, sending contributions etc: + + opensource@epipe.com + + +Portability +=========== + +Currently supported operating systems: + - Recent versions of FreeBSD, NetBSD and OpenBSD + - Modern GNU/Linux distributions + - Mac OS X/Darwin + - GNU/Hurd + - Solaris / OpenSolaris / OpenIndiana + +The software probably works on other modern *BSD variants with zero or +little modifications. + +The only really non-portable part of the program is the getboottime() +function which uses an operating system specific interface for finding +the exact moment when the kernel started again. The function can be +easily altered to add support for additional operating systems. The +author would appreciate receiving any such patches to be integrated in +the main distribution. + +Also for the sake of convenience the program uses some functions which +are available only in modern operating systems. These include for example +asprintf(3), vasprintf(3), snprintf(3), err(3) and errx(3). + + +History +======= + +The author of this software had a Xen based virtual private server +(VPS) running FreeBSD operating system. Occasionally the owner of the +physical non-virtual machine would turn off the VPS to do some system +administration tasks on the host operating system, which the author did +not have access to. The author wanted to have some sort of record of when, +why and how long the VPS had been down. The standard FreeBSD system did +not provide such a facility. + +After some looking around it seemed that there was only programs for +monitoring uptime but not downtime. Also most of these programs were +complicated and were intended to be run on a remote host and thus they +would be actually monitoring the system availability through the network +instead of the actual downtime of the FreeBSD operating system running +on the VPS. Also they would require an another server for monitoring +the primary server. + +Therefore downtimed was needed. + + +Features +======== + +downtimed was made to monitor operating system downtime, shutdowns and +crashes on the monitored host itself and to keep a record of such events. + +downtimed(8) is a daemon process which is intended to be started +automatically from system boot scripts every time when the operating +system of a server starts. First the daemon logs its findings about the +previous downtime to a specified logging destination as well as in a +database file which can be displayed with downtimes(1) command. + +Thereafter the downtimed(8) daemon just keeps waiting in the background +and periodically updates a time stamp file on the disk. The time stamp +is used to determine the approximate time when the system was last up +and running. In case of a graceful system shutdown it records a stamp +to another file on the disk. These files are used for reporting the next +time the daemon starts. + +downtimes(1) is a command-line tool which can be used to inspect previous +downtime records recorded in the downtime database file. + + +Installation +============ + +Installation should be preferably done through a port or a package +which is tailored to your specific operating system. + +If one does not exist or if you yourself are making such a port or a +package, the basic GNU autotools based installation should be as follows: + + ./configure + make + make install + +The above does NOT install any startup scripts which are REQUIRED for +proper function of downtimed. See the following chapter. + +The program also needs a persistent data directory for the time stamp +and the downtime database files. It should be created on *BSD and +MacOS X as follows: + + mkdir /var/db/downtimed + +...or on GNU/Linux, Debian GNU/kFreeBSD, GNU/Hurd or Solaris as follows: + + mkdir /var/lib/downtimed + +Note that you can determine the default data directory location on +your system by issuing "downtimed -v" command or you can specify a +different directory with the "-d" option. Set the directory permissions +as appropriate in your environment. If you are installing a port or +package tailored for your system, this step is most likely taken care +for you automatically. + + +Startup scripts +=============== + +It seems that every different operating system and distribution has +invented their own ways of starting system daemons during the boot +process. That is a major pain in the ass. + +The downtimed distribution includes the following operating system and +distribution specific startup script samples. They are located in the +"startup-scripts" directory. It is assumed that system administrators +or port/package maintainers will implement and configure the required +startup scripts. + +Arch Linux +---------- +Arch Linux startup script is included as archlinux-startup.sh. It should +be installed as /etc/rc.d/downtimed and added to the DAEMONS setting in +/etc/rc.conf. + +Debian +------ +A startup script for GNU/Debian and related distributions is included as +debian-startup.sh. It should be installed as /etc/init.d/downtimed. +Running the command "update-rc.d downtimed defaults" enables starting the +service at the system startup. + +FreeBSD +------- +A sample startup script for FreeBSD is included as freebsd-startup.sh. +It should be installed as /usr/local/etc/rc.d/downtimed. Add: + downtimed_enable="YES" +...in one of the following files to enable boot time startup: + /etc/rc.conf + /etc/rc.conf.local + /etc/rc.conf.d/downtimed +Add the following if you want to configure downtimed(8) command line +options: + downtimed_flags="<set as needed>" + +Mac OS X +-------- +Mac OS X/Darwin launchd(8) configuration file com.epipe.downtimed.plist is +also included. This file should be installed to /Library/LaunchDaemons. + +OpenIndiana / OpenSolaris / Solaris +----------------------------------- +SMF (Service Management Facility) manifest for OpenIndiana, OpenSolaris +and Solaris 10 & 11 is in downtimed.smf.xml. It is not usable on Solaris +9 and older as they need a SysV style init script instead. + +openSUSE +-------- +A startup script for openSUSE is included as opensuse-startup.sh. It +should be installed as /etc/init.d/downtimed. Running the command +"innserv /etc/init.d/downtimed" enables starting the service at the +system startup. + +Red Hat based distributions (RHEL, Fedora, SL, Oracle, CentOS, etc.) +-------------------------------------------------------------------- +A startup script for Red Hat related distributions is included as +redhat-startup.sh. It should be installed as /etc/rc.d/init.d/downtimed. +Running the command "chkconfig --add downtimed" enables starting the +service at the system startup. + +Ubuntu +------ +A startup script for GNU/Linux distributions using upstart(8) to bring +up system daemons, such as the Ubuntu distribution, is included in +upstart-startup.conf. It should be installed as /etc/init/downtimed.conf. + + +These startup scripts are not installed by default. + +This program is not really useful unless there is a proper startup script +in place. Refer to your operating system or distribution manual on how +to create and manage daemon startup scripts. + + +Usage documentation +=================== + +Have a look at downtimed(8) manual page: + + man downtimed + +... as well as the downtimes(1) manual page: + + man downtimes + +Alternatively you can find a PDF version of the manual pages at: + + http://dist.epipe.com/downtimed/ + + +Contributions +============= + +If you port this software to a new operating system, find bugs or +implement new features, it would be nice if you could send your patches +to the author either through Launchpad or by e-mail. See the top of this +document for contact information. + + +Acknowledgements +================ + +The following people have contributed patches or other improvements to +this software: + +Henrik Ahlgren <pablo@seestieto.com> + - Mac OS X patches + +Mats Erik Andersson <openbsd@gisladisker.se> + - OpenBSD, Debian GNU/kFreeBSD and other patches + +Federico Lucifredi <flucifredi@acm.org> + - openSUSE startup script + +Jason Melton <jason.melton@gmail.com> + - Arch Linux startup script + +Douglas Thrift <douglas@douglasthrift.net> + - FreeBSD 9 compatibility fix + +Others who I may have forgotten. (Sorry!) + +Thank You! + +/* eof */ |