From 637117fdf2470fb04ffb7438fd248e366e5af22a Mon Sep 17 00:00:00 2001 From: Tyler Christiansen Date: Sun, 3 Nov 2013 12:27:27 -0800 Subject: [PATCH 01/10] add emphasis to note sections --- doc/INSTALL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 013b86939c..a93cb3b968 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 ## @@ -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` From 095c767c75994c4e2c04dc34caea40b0209e221e Mon Sep 17 00:00:00 2001 From: Tyler Christiansen Date: Sun, 3 Nov 2013 12:33:50 -0800 Subject: [PATCH 02/10] add git to required packages --- doc/INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/INSTALL.md b/doc/INSTALL.md index a93cb3b968..d88abd3f0b 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -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 ### From 7c525ccd82677986d4329c76f2ef550bb6dacb74 Mon Sep 17 00:00:00 2001 From: Tyler Christiansen Date: Sun, 3 Nov 2013 13:53:53 -0800 Subject: [PATCH 03/10] add info on using the librenms vm --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 43535fb1ef..a9d67be7fd 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,25 @@ 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 at ftp://librenms.label-switched.net/pub/librenms_vm.zip, 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 what the IP of your VM is (`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 ------------ @@ -74,4 +93,6 @@ 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" + From 6c68b33108faabb7f707d0bce3c1339b4f58e9dc Mon Sep 17 00:00:00 2001 From: Paul Gear Date: Mon, 4 Nov 2013 13:42:01 +1000 Subject: [PATCH 04/10] Add contributing guidelines --- doc/CONTRIBUTING.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 doc/CONTRIBUTING.md diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md new file mode 100644 index 0000000000..1688842a0f --- /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" + From ea4777fc0e207083cd708890c0c0d480718f9245 Mon Sep 17 00:00:00 2001 From: Paul Gear Date: Mon, 4 Nov 2013 13:42:32 +1000 Subject: [PATCH 05/10] Add Observium users welcome --- doc/Observium_Welcome.md | 72 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 doc/Observium_Welcome.md diff --git a/doc/Observium_Welcome.md b/doc/Observium_Welcome.md new file mode 100644 index 0000000000..7d0d3bbeda --- /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 + r3251 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" + From b1e10c29acd8190777b975eda42cd15f4b631a78 Mon Sep 17 00:00:00 2001 From: Paul Gear Date: Mon, 4 Nov 2013 13:42:39 +1000 Subject: [PATCH 06/10] Update README - Add Observium users welcome - Add contributing guidelines - Tidy links --- README.md | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a9d67be7fd..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 @@ -54,20 +55,26 @@ 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]. +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 at ftp://librenms.label-switched.net/pub/librenms_vm.zip, open it, and log in as `root` with the password `root`. Enter the following commands: +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 what the IP of your VM is (`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: +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`. +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 @@ -83,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]. @@ -94,5 +102,11 @@ You can participate in the project by: [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 From 203c12e625e5af6ae2d1c810edf90d2b846e27ee Mon Sep 17 00:00:00 2001 From: Paul Gear Date: Mon, 4 Nov 2013 13:48:37 +1000 Subject: [PATCH 07/10] Update CONTRIBUTING.md Encourage the use of 4-digit issue ids --- doc/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 1688842a0f..9ec02f6ee4 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -29,7 +29,7 @@ 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 +- 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. From bec68c8d5db06938e1152204e5580fb0ae173fea Mon Sep 17 00:00:00 2001 From: Paul Gear Date: Mon, 4 Nov 2013 13:55:47 +1000 Subject: [PATCH 08/10] Update Observium_Welcome.md Correct revision number --- doc/Observium_Welcome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Observium_Welcome.md b/doc/Observium_Welcome.md index 7d0d3bbeda..0ede4f92f5 100644 --- a/doc/Observium_Welcome.md +++ b/doc/Observium_Welcome.md @@ -15,7 +15,7 @@ This has a few implications: - 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 - r3251 and just change it to LibreNMS. This would probably break (although + 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 From ab5feaee2f0c547c43fc17f2e5c918499b9ac6df Mon Sep 17 00:00:00 2001 From: Tyler Christiansen Date: Sun, 3 Nov 2013 22:16:01 -0800 Subject: [PATCH 09/10] add framework for new cron features; add ability to update librenms daily --- config.php.default | 2 ++ daily.php | 15 +++++++++++++++ daily.sh | 5 +++++ includes/defaults.inc.php | 3 +++ librenms.cron | 1 + 5 files changed, 26 insertions(+) create mode 100644 daily.php create mode 100644 daily.sh diff --git a/config.php.default b/config.php.default index 53e4b4569b..e527a97b61 100755 --- a/config.php.default +++ b/config.php.default @@ -39,5 +39,7 @@ $config['auth_mechanism'] = "mysql"; # default, other options: ldap, http-auth #$config['nets'][] = "172.16.0.0/12"; #$config['nets'][] = "192.168.0.0/16"; +# 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/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 b42b782acf..0738b41e98 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.php -h all >> /dev/null 2>&1 +15 0 * * * root sh /opt/librenms/daily.sh > /dev/null 2>&1 From 42d8a3c17b83a82952e304f8ce209692d60c1ad0 Mon Sep 17 00:00:00 2001 From: Tyler Christiansen Date: Sun, 3 Nov 2013 22:18:45 -0800 Subject: [PATCH 10/10] update install docs to include notice about daily updates --- doc/INSTALL.md | 11 +++++++++++ doc/INSTALL_RHEL.md | 12 ++++++++++++ 2 files changed, 23 insertions(+) diff --git a/doc/INSTALL.md b/doc/INSTALL.md index d88abd3f0b..edca1b67cc 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -107,3 +107,14 @@ 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 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 635354146e..34ce98c777 100644 --- a/doc/INSTALL_RHEL.md +++ b/doc/INSTALL_RHEL.md @@ -121,3 +121,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; + +