Merge branch 'master' into wrapper

Conflicts:
	config.php.default
	librenms.cron

README.md

@@ -18,7 +18,7 @@ Copyright (C) 2013 LibreNMS Contributors <librenms-project@googlegroups.com>
  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-Please see LICENSE.txt for usage requirements and restrictions.
+[LICENSE.txt][14] contains a copy of the full GPLv3 licensing conditions.
 
 
 Introduction
@@ -30,19 +30,20 @@ systems including Cisco, Linux, FreeBSD, Juniper, Brocade, Foundry, HP and
 many more.
 
 LibreNMS is a community-based fork of the last GPL-licensed version of
-Observium <http://observium.org/>.  LibreNMS intends to be a viable network
+[Observium][9].  LibreNMS intends to be a viable network monitoring project
-monitoring project and community that:
+and community that:
 - encourages contribution,
 - focuses on the needs of its users, and
 - offers a welcoming, friendly environment for everyone.
 
-The Debian Social Contract <http://www.debian.org/social_contract> will be
+If you're visiting because of a mention on the Observium mailing list,
-the basis of our priority system, and mutual respect the basis of our
+please read our [welcome to Observium users][12].
-behaviour towards others.
 
-For more about the culture we're trying to build, please read the Freenode
+The [Debian Social Contract][10] will be the basis of our priority system,
-[guidelines for running an IRC channel][6] and [being a community
+and mutual respect the basis of our behaviour towards others.  For more
-catalyst][7].
+about the culture we're trying to build, please read the [Freenode
+philosophy][13], including [guidelines for running an IRC channel][6] and
+[being a community catalyst][7].
 
 
 Documentation
@@ -51,6 +52,31 @@ Documentation
 For now documentation can be found in the [doc directory][5].
 
 
+Try It
+------
+
+You can try LibreNMS by downloading a VM image.  Currently, a Debian-based
+image is supplied and has been tested with [VMware Fusion 5][8].
+
+Download the [VMware Fusion 5 image][11] at open it, and log in as `root`
+with the password `root`.  Enter the following commands:
+
+    cd /opt/librenms
+    git pull
+    php discover.php -h all
+    php poller.php -h all
+
+You'll then need to find out the IP of your VM (`ifconfig | grep add`) and
+create a DNS entry for `librenms.example.com` to point to that IP.  You can
+also edit your `/etc/hosts` file with the following line:
+
+    $ip librenms.example.com
+
+where `$ip` is the IP of your VM.  From there, just point your web browser
+to `http://librenms.example.com/` and login with username `librenms` and
+password `librenms`.
+
+
 Installation
 ------------
 
@@ -64,6 +90,7 @@ You can participate in the project by:
 - Joining the [librenms-project][1] mailing list to post questions and
   suggestions.
 - Cloning the [repo][2] and filing bug reports and pull requests on github.
+  See [CONTRIBUTING][15] for more details.
 - Talking to us on [Twitter][3] or [IRC][4].
 - Improving the [documentation][5].
 
@@ -74,4 +101,12 @@ You can participate in the project by:
 [5]: https://github.com/librenms/librenms/tree/master/doc/
 [6]: http://freenode.net/channel_guidelines.shtml "Freenode channel guidelines"
 [7]: http://freenode.net/catalysts.shtml "Freenode community catalysts"
+[8]: http://www.vmware.com/products/fusion/ "VMware Fusion"
+[9]: http://observium.org/ "Observium web site"
+[10]: http://www.debian.org/social_contract "Debian project social contract"
+[11]: ftp://librenms.label-switched.net/pub/librenms_vm.zip
+[12]: https://github.com/librenms/librenms/tree/master/doc/Observium_Welcome.md
+[13]: http://freenode.net/philosophy.shtml "Freenode philosophy"
+[14]: https://github.com/librenms/librenms/tree/master/LICENSE.txt
+[15]: https://github.com/librenms/librenms/tree/master/doc/CONTRIBUTING.md
 

config.php.default

@@ -42,5 +42,7 @@ $config['auth_mechanism'] = "mysql"; # default, other options: ldap, http-auth
 # following is necessary for poller-wrapper
 # poller-wrapper is released public domain
 $config['poller-wrapper']['alerter'] = FALSE;
+# Uncomment the next line to disable daily updates
+#$config['update'] = 0;
 
 ?>

daily.php

@@ -0,0 +1,15 @@
+<?php
+
+/*
+ * Daily Task Checks
+ * (c) 2013 LibreNMS Contributors
+ */
+
+include('includes/defaults.inc.php');
+include('config.php');
+
+$options = getopt("f:");
+
+if ( $options['f'] === 'update') { echo $config['update']; }
+
+?>

daily.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+if [ $(php daily.php -f update) -eq 1 ]; then 
+  git pull --no-edit --quiet
+fi

doc/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+Guidelines for contributing to LibreNMS
+---------------------------------------
+
+- Don't submit code whose license conflicts with the GPLv3.  If you're not
+  sure, consult the [Free Software Foundation's license list][1] and see if
+  your code's license is on the compatible or incompatible list.
+  - The SNMP MIBs may be moved to a separate repository soon due to this
+    issue.  We will do everything we can to ensure this has minimal impact.
+  - The current Observium license is incompatible with GPLv3.  Do not submit
+    patches from current Observium unless you are the copyright holder, and
+    specifically note that you are releasing it under GPLv3.
+
+- Test your patches first.  It's easy to set up git to push to a bare
+  repository on a local test system, and pull from this into your live
+  installation at very frequent intervals.
+
+- Don't break the poller.  User interface blemishes are not critical, but
+  losing data from network monitoring systems might be.
+
+- Please join us in IRC at irc.freenode.net in channel ##librenms if you're
+  able.  Collaborating in real time makes the coordination of contributions
+  easier.
+
+
+Proposed workflow for submitting pull requests (currently untested)
+-------------------------------------------------------------------
+
+This is a proposed workflow designed to minimise the scope of merge
+conflicts when submitting pull requests:
+- Fork the [LibreNMS repo master branch][2] in your own GitHub account.
+- Create an [issue][3] explaining what work you plan to do.
+- Create a branch in your copy of the repo called issue-####, where #### is
+  the issue number you created.
+- Make and test your changes in the issue branch as needed - this might take
+  a few days or weeks.
+- When you are happy with your issue branch's changes and ready to submit
+  your patch, update your copy of the master branch to the current revision;
+  this should just result in a fast forward of your copy of master.
+- Rebase your issue branch from your clone of master.  Fix any conflicts at
+  this stage.
+- Merge your issue branch back into of your copy of master. Again, this
+  should be a simple fast forward.
+- Submit a pull request for your patch from your copy of master.
+
+[1]: http://www.gnu.org/licenses/license-list.html
+"Free Software Foundation's license list"
+[2]: https://github.com/librenms/librenms/tree/master
+"LibreNMS master branch"
+[3]: https://github.com/librenms/librenms/issues
+"LibreNMS issue database"
+

doc/INSTALL.md

@@ -1,6 +1,6 @@
-NOTE: What follows is a very rough list of commands.  This works on a fresh install of Ubuntu 12.04.
+> NOTE: What follows is a very rough list of commands.  This works on a fresh install of Ubuntu 12.04.
 
-NOTE: These instructions assume you are the root user.  If you are not, prepend `sudo` to all shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s`.
+> NOTE: These instructions assume you are the root user.  If you are not, prepend `sudo` to all shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s`.
 
 ## On the DB Server ##
 
@@ -35,7 +35,7 @@ Change `127.0.0.1` to the IP address that your MySQL server should listen on.  R
 
 Install necessary software.  The packages listed below are an all-inclusive list of packages that were necessary on a clean install of Ubuntu 12.04.
 
-    apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear snmp graphviz php5-mcrypt apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd mysql-client php-net-ipv4 php-net-ipv6 rrdtool
+    apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear snmp graphviz php5-mcrypt apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd mysql-client php-net-ipv4 php-net-ipv6 rrdtool git
     
 ### Cloning ###
 
@@ -47,7 +47,7 @@ You can clone the repository via HTTPS or SSH.  In either case, you need to ensu
     cp config.php.default config.php
     vim config.php
     
-NOTE: The recommended method of cloning a git repository is HTTPS.  If you would like to clone via SSH instead, use the command `git clone git@github.com:librenms/librenms.git librenms` instead.
+> NOTE: The recommended method of cloning a git repository is HTTPS.  If you would like to clone via SSH instead, use the command `git clone git@github.com:librenms/librenms.git librenms` instead.
 
 Change the values to the right of the equal sign for lines beginning with `$config[db_]` to match your database information as setup above.
 
@@ -72,7 +72,7 @@ First, create and chown the `rrd` directory and create the `logs` directory
     mkdir rrd logs
     chown www-data:www-data rrd/
 
-Note that if you're not running Ubuntu, you may need to change the owner to whomever the webserver runs as.
+> NOTE: If you're not running Ubuntu, you may need to change the owner to whomever the webserver runs as.
 
 Next, add the following to `/etc/apache2/sites-available/librenms.conf`
 
@@ -113,3 +113,14 @@ Create the cronjob
 
     ln -s librenms.cron /etc/cron.d/librenms
 
+### Daily Updates ###
+
+LibreNMS performs daily updates by default.  At 00:15 system time every day, a `git pull --no-edit --quiet` is performed.  You can override this default by editing your `config.php` file.  Remove the comment (the `#` mark) on the line:
+
+    #$config['update'] = 0;
+
+so that it looks like this:
+
+    $config['update'] = 0;
+
+

doc/INSTALL_RHEL.md

@@ -132,3 +132,15 @@ Create the cronjob
 
     cp librenms.cron /etc/cron.d/librenms
 
+### Daily Updates ###
+
+LibreNMS performs daily updates by default.  At 00:15 system time every day, a `git pull --no-edit --quiet` is performed.  You can override this default by edit
+ing your `config.php` file.  Remove the comment (the `#` mark) on the line:
+
+    #$config['update'] = 0;
+
+so that it looks like this:
+
+    $config['update'] = 0;
+
+

doc/Observium_Welcome.md

@@ -0,0 +1,72 @@
+Welcome to Observium users
+--------------------------
+
+LibreNMS is a fork of Observium.  The reason for the fork is nothing to do
+with Observium's [recent move to community vs. paid versions][1].  It is
+simply that we have different priorities and values to the Observium
+developers.  We decided to fork (reluctantly) because we like using
+Observium, but we want to collaborate on a community-based project with
+like-minded IT professionals.  See [README.md][2] and the references there
+for more information about the kind of community we're trying to promote.
+
+LibreNMS was forked from [the last GPL-licensed version of Observium][3].
+This has a few implications:
+- It doesn't look as nice as the current version of Observium.
+- We've lost quite a bit of functionality that has been added to Observium
+  in the last year.
+- You won't be able to take an existing Observium installation later than
+  r3250 and just change it to LibreNMS.  This would probably break (although
+  if you were on a version between r3250 and the next database schema
+  change, it might be feasible).  Upgrades from versions earlier than r3251
+  might work.  Please try it on an unimportant system and tell us your
+  experiences!
+
+How LibreNMS will be different from Observium:
+- We will have an inclusive community, where it's OK to ask stupid
+  questions, and OK to ask for things that aren't on the roadmap.  If you'd
+  like to see something added, add or comment on the relevant issue in our
+  [GitHub issue database][9].
+- Development decisions will be community-driven.  We want to make software
+  that fulfills its users' needs.  See the [ROADMAP][4] for more thoughts
+  on our current plans.
+- Development will probably proceed at a slower pace, at least initially.
+- There are no plans for a paid version, and we don't anticipate this ever
+  changing.
+- There are no current plans for paid support, but this may be added later
+  if there is sufficient demand.
+- We use git for version control and GitHub for hosting to make it as easy
+  and painless as possible to create forked or private versions.
+
+Reasons why you might want to use Observium instead of LibreNMS:
+- You have a financial investment in Observium and aren't concerned about
+  community contributions.
+- You need the extra functionality that has been added to Observium since
+  r3250.
+- You don't like the [GNU General Public License, version 3][5] or the
+  [philosophy of Free Software][6] in general.
+
+Reasons why you might want to use LibreNMS instead of Observium:
+- You want to work with others on the project, knowing that [your
+  investment of time and effort will not be wasted][7].
+- You want to add and experiment with features that are not a priority for
+  the Observium developers.  See [CONTRIBUTING][8] for more details.
+
+[1]: http://postman.memetic.org/pipermail/observium/2013-October/003915.html
+"Observium edition split announcement"
+[2]: https://github.com/librenms/librenms/blob/master/README.md
+"LibreNMS README"
+[3]: http://fisheye.observium.org/rdiff/Observium?csid=3251&u&N
+"Link to Observium license change"
+[4]: https://github.com/librenms/librenms/blob/master/doc/ROADMAP.md
+"LibreNMS ROADMAP"
+[5]: https://github.com/librenms/librenms/blob/master/LICENSE.txt
+"LibreNMS copy of GPL v3"
+[6]: http://www.gnu.org/philosophy/free-sw.html
+"Free Software Foundation - what is free software?"
+[7]: http://libertysys.com.au/blog/observium-and-gpl
+"Paul's blog on what the GPL offers users"
+[8]: https://github.com/librenms/librenms/blob/master/doc/CONTRIBUTING.md 
+"Contribution guidelines"
+[9]: https://github.com/librenms/librenms/issues
+"LibreNMS issue database at GitHub"
+

includes/defaults.inc.php

@@ -542,4 +542,7 @@ $config['modules_compat']['rfc1628']['netmanplus']        = 1;
 $config['modules_compat']['rfc1628']['deltaups']          = 1;
 $config['modules_compat']['rfc1628']['poweralert']        = 1;
 
+# Enable daily updates
+$config['update'] = 1;
+
 ?>

librenms.cron

@@ -1,3 +1,4 @@
 33  */6   * * *   root    /opt/librenms/discovery.php -h all >> /dev/null 2>&1
 */5  *    * * *   root    /opt/librenms/discovery.php -h new >> /dev/null 2>&1
 */5  *    * * *   root    /opt/librenms/poller-wrapper.py 16 >> /dev/null 2>&1
+15   0    * * *   root    sh /opt/librenms/daily.sh > /dev/null 2>&1