mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Install doc update

Browse Source 
- Skip to correct section
- Reword poller-wrapper section
- Fix cron job creation
- move snmpd config to NMS, add note about configuring it
- add a bit more of a git introduction
- add an install complete section
- reword many other parts
This commit is contained in:
Paul Gear
2014-07-17 11:22:20 +10:00
parent b89037da09
commit a4efa332f6
1 changed files with 38 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
doc/INSTALL.md
View File

@@ -1,15 +1,15 @@
> NOTE: What follows is a very rough list of commands. This works on a fresh install of Ubuntu 12.04.
> NOTE: These instructions have been tested on a fresh install of Ubuntu 12.04 and 14.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 the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
## On the DB Server ##
## On the database server ##
apt-get install mysql-server mysql-client snmpd
apt-get install mysql-server mysql-client
mysql -uroot -p
Enter the MySQL root password to enter the MySQL command-line interface.
Input the MySQL root password to enter the MySQL command-line interface.
Create database.
Create the database:
CREATE DATABASE librenms;
GRANT ALL PRIVILEGES ON librenms.*
@@ -19,7 +19,7 @@ Create database.
FLUSH PRIVILEGES;
exit
Replace `<ip>` above with the IP of the server running LibreNMS. If your database is on the same server as LibreNMS, you can just use `localhost` as the IP address.
Replace `<ip>` above with the IP or DNS name of the server running LibreNMS. If your database is on the same server as LibreNMS, you can use `localhost`.
If you are deploying a separate database server, you need to change the `bind-address`. If your MySQL database resides on the same server as LibreNMS, you should skip this step.
@@ -31,36 +31,46 @@ Change `127.0.0.1` to the IP address that your MySQL server should listen on. R
service mysql restart
## On the NMS ##
## On the network management server ##
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.
This host is where the web server and SNMP poller run. It could be the same machine as your database server.
apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear snmp graphviz php5-mcrypt php5-json apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd mysql-client php-net-ipv4 php-net-ipv6 rrdtool git
Install the required software:
apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear snmp graphviz php5-mcrypt php5-json apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd mysql-client php-net-ipv4 php-net-ipv6 rrdtool git snmpd
The packages listed above are an all-inclusive list of packages that were necessary on a clean install of Ubuntu 12.04/14.04.
You need to configure snmpd appropriately if you have not already done so. An absolute minimal config for snmpd is:
rocommunity public 127.0.0.1
Adding the above line to `/etc/snmp/snmpd.conf` and running `service snmpd restart` will activate this config.
### Cloning ###
You can clone the repository via HTTPS or SSH. In either case, you need to ensure the appropriate port (443 for HTTPS, 22 for SSH) is open in the outbound direction for your server.
LibreNMS is installed using git. If you're not familiar with git, check out the [git book][2] or the tips at [git ready][3]. The initial install from github.com is called a `git clone`; subsequent updates are done through `git pull`.
You can clone the repository via HTTPS or SSH. In either case, you need to ensure that the appropriate port (443 for HTTPS, 22 for SSH) is open in the outbound direction for your server.
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
> 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.
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.
### Web Interface ###
To prepare the web interface (and adding devices shortly), you'll need to create and chown a directory as well as create an Apache vhost.
First, create and chown the `rrd` directory and create the `logs` directory
First, create and chown the `rrd` directory and create the `logs` directory:
mkdir rrd logs
chown www-data:www-data logs/ rrd/
> NOTE: 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 or Debian, you will need to change `www-data` to the user and group which run the Apache web server.
Next, add the following to `/etc/apache2/sites-available/librenms.conf`
If you have Apache older than 2.3 then please use:
Next, add the following to `/etc/apache2/sites-available/librenms.conf`:
<VirtualHost *:80>
DocumentRoot /opt/librenms/html/
@@ -73,11 +83,11 @@ If you have Apache older than 2.3 then please use:
</Directory>
</VirtualHost>
If you have Apache 2.3 or newer then please add this line before "AllowOverride all":
If you have Apache 2.3 or newer then please add the following line before `AllowOverride All`:
Require all granted
Change 'librenms.example.com' to the appropriate hostname for your domain, then enable the vhost and restart Apache:
Change `librenms.example.com` to the appropriate hostname for your domain, then enable the vhost and restart Apache:
a2ensite librenms.conf
a2enmod rewrite
@@ -87,7 +97,7 @@ Change 'librenms.example.com' to the appropriate hostname for your domain, then
### Manual vs. web installer ###
At this stage you can either launch the web installer by going to http://IP/install.php, follow the onscreen instructions then skip to the 'Web Interface' section further down. Alternatively if you want to continue the setup manually then just keep following these instructions.
At this stage you can either launch the web installer by going to http://librenms.example.com/install.php, follow the onscreen instructions then skip to the 'Add localhost' section. Alternatively if you want to continue the setup manually then just keep following these instructions.
cp config.php.default config.php
vim config.php
@@ -116,15 +126,13 @@ Discover localhost and poll it for the first time:
php discovery.php -h all && php poller.php -h all
The polling method used by LibreNMS is `poller-wrapper.py`, which was placed in the public domain by its author. By default, the LibreNMS cronjob runs `poller-wrapper.py` with 16 threads. The current LibreNMS recommendation is to use 4 threads per core. The default if no thread count is `16 threads`.
If the thread count needs to be changed, you can do so by editing `librenms.cron` before copying (or by editing `/etc/cron.d/librenms` if you've already copied the cron file). Just add a number after `poller-wrapper.py`, as in the below example:
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the cron job runs `poller-wrapper.py` with 16 threads. The current recommendation is to use 4 threads per core as a rule of thumb. If the thread count needs to be changed, you can do so by editing `librenms.cron` before copying (or by editing `/etc/cron.d/librenms` if you've already copied the cron file). Just add a number after `poller-wrapper.py`, as in the example below:
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
Create the cronjob
ln -s librenms.cron /etc/cron.d/librenms
ln -s $PWD/librenms.cron /etc/cron.d/librenms
### Daily Updates ###
@@ -136,4 +144,10 @@ so that it looks like this:
$config['update'] = 0;
### Install complete ###
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
[1]: https://github.com/Atrato/observium-poller-wrapper
[2]: http://git-scm.com/book
[3]: http://gitready.com/