diff --git a/README.md b/README.md index 43535fb1ef..f75613e1ab 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Copyright (C) 2013 LibreNMS Contributors You should have received a copy of the GNU General Public License along with this program. If not, see . -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 . LibreNMS intends to be a viable network -monitoring project and community that: +[Observium][9]. LibreNMS intends to be a viable network monitoring project +and community that: - encourages contribution, - focuses on the needs of its users, and - offers a welcoming, friendly environment for everyone. -The Debian Social Contract will be -the basis of our priority system, and mutual respect the basis of our -behaviour towards others. +If you're visiting because of a mention on the Observium mailing list, +please read our [welcome to Observium users][12]. -For more about the culture we're trying to build, please read the Freenode -[guidelines for running an IRC channel][6] and [being a community -catalyst][7]. +The [Debian Social Contract][10] will be the basis of our priority system, +and mutual respect the basis of our behaviour towards others. For more +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 diff --git a/config.php.default b/config.php.default index b7691e7850..8fb1f8595b 100755 --- a/config.php.default +++ b/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; ?> diff --git a/daily.php b/daily.php new file mode 100644 index 0000000000..22ac1e47e1 --- /dev/null +++ b/daily.php @@ -0,0 +1,15 @@ + diff --git a/daily.sh b/daily.sh new file mode 100644 index 0000000000..a02a6846be --- /dev/null +++ b/daily.sh @@ -0,0 +1,5 @@ +#!/bin/bash + +if [ $(php daily.php -f update) -eq 1 ]; then + git pull --no-edit --quiet +fi diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md new file mode 100644 index 0000000000..9ec02f6ee4 --- /dev/null +++ b/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" + diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 5a57ff52d4..d998e551d7 100644 --- a/doc/INSTALL.md +++ b/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; + + diff --git a/doc/INSTALL_RHEL.md b/doc/INSTALL_RHEL.md index 7fd3e34e05..e36f156256 100644 --- a/doc/INSTALL_RHEL.md +++ b/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; + + diff --git a/doc/Observium_Welcome.md b/doc/Observium_Welcome.md new file mode 100644 index 0000000000..0ede4f92f5 --- /dev/null +++ b/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" + diff --git a/includes/defaults.inc.php b/includes/defaults.inc.php index 6fcdc23b15..46a3d4f394 100644 --- a/includes/defaults.inc.php +++ b/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; + ?> diff --git a/librenms.cron b/librenms.cron index 52a49105ec..5d346503c8 100644 --- a/librenms.cron +++ b/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