doc/en/jffnms.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/jffnms.xml,v 1.11 2011/09/04 17:53:40 swift Exp $ -->

<guide>
<title>Jffnms Installation and Setup Guide</title>

<author title="Author">
  <mail link="angusyoung"/>
</author>

<abstract>
This guide shows you how to proceed with the post installation setup of Jffnms,
a network management and monitoring system, and how to monitor your systems
with it.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>2</version>
<date>2012-08-30</date>

<chapter>
<title>Jffnms Basics</title>
<section>
<title>Introduction</title>
<body>

<p>
<uri link="http://www.jffnms.org">Jffnms</uri> is a network management and
monitoring system. It allows you to grab information from many different kinds
of hosts and protocols. With this guide, we aim to show you how to get Jffnms
properly installed and have your systems monitored by this amazing tool.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Initial Setup</title>
<section>
<title>Choosing your USE flags</title>
<body>

<p>
The Jffnms ebuild has the following USE flags available:
</p>

<table>
<tr>
  <th>USE Flags for Jffnms</th>
  <th>Description</th>
</tr>
<tr>
  <ti><c>mysql</c></ti>
  <ti>Uses Mysql to store Jffnms data</ti>
</tr>
<tr>
  <ti><c>postgres</c></ti>
  <ti>Uses PostgreSQL to store Jffnms data</ti>
</tr>
<tr>
  <ti><c>snmp</c></ti>
  <ti>
    Adds support for snmp, which enables jffnms to gather data from other hosts.
  </ti>
</tr>
</table>

</body>
</section>
<section>
<title>USE flags for PHP</title>
<body>

<p>
Being written in PHP, Jffnms is heavily dependent on PHP USE flags. In order to
install Jffnms successfully, you are required to have your PHP package installed
with (at least) the following USE flags:
</p>

<table>
<tr>
  <th>USE Flags for PHP</th>
  <th>Description</th>
</tr>
<tr>
  <ti><c>gd</c></ti>
  <ti>Adds support for media-libs/gd (to generate graphics on the fly)</ti>
</tr>
<tr>
  <ti><c>wddx</c></ti>
  <ti>Adds support for Web Distributed Data eXchange </ti>
</tr>
<tr>
  <ti><c>sockets</c></ti>
  <ti>Adds support for tcp/ip sockets</ti>
</tr>
<tr>
  <ti><c>session</c></ti>
  <ti>Adds persistent session support</ti>
</tr>
<tr>
  <ti><c>spl</c></ti>
  <ti>Adds support for the Standard PHP Library</ti>
</tr>
<tr>
  <ti><c>cli</c></ti>
  <ti>Enable CLI SAPI</ti>
</tr>
</table>

</body>
</section>
<section>
<title>Installation</title>
<body>

<p>
Just like any package in Portage, jffnms can be installed with <c>emerge</c>:
</p>

<pre caption="Installing Jffnms">
# <i>emerge jffnms</i>
</pre>

<p>
Jffnms should be installed in <path>/opt/jffnms/</path>.
</p>

</body>
</section>
<section>
<title>Configuring Apache 2</title>
<body>

<warn>
This very basic configuration procedure for Apache does not cover all aspects
of setting up a web server.
</warn>

<p>
Sometimes you will want to run Jffnms on your local computer instead of a
remote server. If this is your case, it is very likely that you don't have an
apache setup running. Don't worry about installing apache though, Portage has
already done that for you. Nevertheless, you still have to configure and test
apache, which (luckily) is pretty straightforward. Start by adding Apache to
your default runlevel:
</p>

<pre caption="Adding apache2 to the default runlevel">
# <i>rc-update add apache2 default</i>
</pre>

<p>
If you haven't done it yet, it's time to start apache2:
</p>

<pre caption="Starting apache2">
# <i>/etc/init.d/apache2 start</i>
</pre>

<p>
Finally, point your browser at <uri>http://localhost/</uri> and you should be
presented with a home page about your newly installed Apache 2.  Now that we
know that Apache is up and running, we can proceed to the mod_php
configuration.  Fire up your favorite text editor, open
<path>/etc/conf.d/apache2</path> and add <c>-D PHP5</c> the APACHE2_OPTS
variable.
</p>

<pre caption="Apache 2 Configuration">
# <i>nano -w /etc/conf.d/apache2</i>
APACHE2_OPTS="-D DEFAULT_VHOST -D PHP5"
</pre>

<p>
After that, you should create a symlink to the Jffnms install directory in your
Apache document root dir. In Gentoo, by default, Apache uses
<path>/var/www/localhost/htdocs</path> as document root. So, you should do the
following:
</p>

<pre caption="Creating Jffnms symlink">
# <i>cd /var/www/localhost/htdocs &amp;&amp; ln -s /opt/jffnms/</i>
</pre>

</body>
</section>
<section>
<title>Configuring PHP</title>
<body>

<p>
Now that Apache is running, it is time to configure PHP. Jffnms requires that
you set some variables in php.ini in order to run. The <path>php.ini</path> file
is usually located in <path>/etc/php/apache2-php5/php.ini</path>. You have to
set these variables to the following values:
</p>

<pre caption="Configuring PHP">
# <i>nano -w /etc/php/apache2-php5/php.ini</i>
register_globals = On
register_argc_argv = On 
error_reporting  =  E_ALL &amp; ~E_NOTICE
allow_url_fopen = On
include_path = ".:/usr/share/php5:/usr/share/php:/usr/share/php/PEAR"
short_open_tag = On
</pre>

</body>
</section>
<section>
<title>Database setup</title>
<body>

<warn>
Please note again that this a very basic configuration procedure for any
database system and does not cover all aspects of setting up such systems.
</warn>

<p>
Jffnms allows you to use either PostgreSQL or MySQL as its database. Here we'll
show you how to create the database and necessary tables where Jffnms will
store its data.  It's important to note that it isn't necessary to have a
database running locally to run Jffnms and except for the fact that you need to
run this commands on the remote host, the procedure is the same.
</p>

</body>
</section>
<section>
<title>Setting up PostgreSQL</title>
<body>

<note>
If you already have a PostgreSQL database up and running, you can proceed to
the <uri link="#use-pg">next section</uri>.
</note>

<p>
You should add PostgreSQL to your default runlevel so it's started each time you
boot your computer. Make sure to change <c>${SLOT}</c> to your PostgreSQL
slot, such as 9.1 or 9.2.
</p>
 
<pre caption="Adding PostgreSQL to the default runlevel">
# <i>rc-update add postgresql-${SLOT} default</i>
</pre>

<p>
Now you must setup the PostgreSQL database. Make sure to change
<c>${VERSION}</c> to your PostgreSQL version, such as 9.0.9 or 9.1.5.
</p>

<pre caption="Preparing PostgreSQL">
# <i>emerge --config postgresql-server-${VERSION}</i>
</pre>

<p>
Now start PostgreSQL:
</p>

<pre caption="Starting PostgreSQL">
# <i>/etc/init.d/postgresql-${SLOT} start</i>
</pre>

</body>
</section>
<section id="use-pg">
<title>Using PostgreSQL as database</title>
<body>

<p>
Once you have your PostgreSQL set up and running, you have to create a Jffnms
user and a database to store host data.
</p>

<pre caption="Creating the Jffnms user and database">
# <i>psql template1 postgres</i>
template1=# <i>create user jffnms password 'jfnms' createdb;</i>
template1=# <i>\connect template1 jffnms</i>
template1=# <i>create database jffnms;</i>
template1=# <i>\q</i>
</pre>

<p>
Finally, you need to create all the tables where data will be stored:
</p>

<pre caption="Creating Jffnms tables">
# <i>psql jffnms jffnms &lt; /opt/jffnms/docs/jffnms-0.9.3.pgsql</i>
</pre>

<p>
Once you have run those steps, the PostgreSQL database configuration for Jffnms
should be ok.
</p>

</body>
</section>
<section>
<title>Using MySQL as database</title>
<body>

<warn>
Installing and configuring a MySQL database is not covered in this guide.
Please see our <uri link="/doc/en/mysql-howto.xml">MySQL Startup Guide</uri>.
</warn>

<p>
In case you want to run Jffnms with MySQL, you'll first need to create a
database and a MySQL user. After that, create your MySQL table:
</p>

<pre caption="Create a mysql table.">
# <i>mysql -u jffnms -pjffnms jffnms &lt; /opt/jffnms/docs/jffnms-0.9.3.mysql</i>
</pre>

</body>
</section>
<section>
<title>UDP Port Monitoring and discovery</title>
<body>

<warn>
This section covers setting up and running suid programs, so it may not be
adequate for systems where security is too much an issue.
</warn>

<p>
If you want UDP port monitoring and discovery, you need to set <c>nmap</c> and
<c>fping</c> as a SUID programs. This may give you security hole in case
there's a bug in one of them. To set them as a SUID you can run the following
commands:
</p>

<pre caption="Setting up udp port monitoring and discovery">
# <i>chmod +s /usr/bin/nmap ; chmod a+x /usr/bin/nmap</i>
# <i>chmod +s /usr/sbin/fping ; chmod a+x /usr/sbin/fping</i>
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Configuring Jffnms</title>
<section>
<title>Configuring the poller process</title>
<body>

<p>
The poller process is responsible for gathering data from hosts. In order to
collect this data at regular intervals, it must be added to crontab.
</p>

<pre caption="Collecting data at regular intervals">
# <i>crontab -u jffnms /opt/jffnms/docs/unix/crontab</i>
# <i>crontab -e -u jffnms</i>
</pre>

</body>
</section>
<section>
<title>Final setup</title>
<body>

<p>
By now, Jffnms should be correctly installed on your system. You still need,
however, to configure Jffnms. Luckily, Jffnms provides us with an easy to use
web page where it's possible to configure access to database, user access as
well as check if the current host configuration suffices Jffnms needs. You can
access this web interface through the following URL:
<uri>http://localhost/jffnms/admin/setup.php</uri>. You can login to your new
installation by using the username and password <c>admin</c>. You should visit
<uri link="http://www.jffnms.org/">Jffnms's home page</uri> for details on how
to properly configure it.
</p>

 </body>
</section>
</chapter>

<chapter>
<title>Support</title>
<section>
<body>

<p>
Though Jffnms is a wonderful application, it is a bit hard to get it up and
running. So if you run into problems with Jffnms, there are some places where
you can look for help:
</p>

<ul>
  <li>
    <uri link="http://www.jffnms.org/docs/installing.html">Jffnms Installation
    Manual</uri>
  </li>
  <li>
    <uri link="http://www.jffnms.org/docs/jffnms.html">Jffnms Manual</uri>
  </li>
  <li><uri link="http://forums.gentoo.org">Gentoo Forums</uri></li>
  <li>
    <uri link="http://www.postgresql.org/docs/9.1/static/index.html">PostgreSQL
    9 Documentation</uri>
  </li>
  <li><uri link="http://dev.mysql.com/doc/">MySQL Documentation</uri></li>
</ul>

</body>
</section>
</chapter>
</guide>
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/jffnms.xml,v 1.11 2011/09/04 17:53:40 swift Exp $ -->
4
5	<guide>
6	<title>Jffnms Installation and Setup Guide</title>
7
8	<author title="Author">
9	<mail link="angusyoung"/>
10	</author>
11
12	<abstract>
13	This guide shows you how to proceed with the post installation setup of Jffnms,
14	a network management and monitoring system, and how to monitor your systems
15	with it.
16	</abstract>
17
18	<!-- The content of this document is licensed under the CC-BY-SA license -->
19	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
20	<license/>
21
22	<version>2</version>
23	<date>2012-08-30</date>
24
25	<chapter>
26	<title>Jffnms Basics</title>
27	<section>
28	<title>Introduction</title>
29	<body>
30
31	<p>
32	<uri link="http://www.jffnms.org">Jffnms</uri> is a network management and
33	monitoring system. It allows you to grab information from many different kinds
34	of hosts and protocols. With this guide, we aim to show you how to get Jffnms
35	properly installed and have your systems monitored by this amazing tool.
36	</p>
37
38	</body>
39	</section>
40	</chapter>
41
42	<chapter>
43	<title>Initial Setup</title>
44	<section>
45	<title>Choosing your USE flags</title>
46	<body>
47
48	<p>
49	The Jffnms ebuild has the following USE flags available:
50	</p>
51
52	<table>
53	<tr>
54	<th>USE Flags for Jffnms</th>
55	<th>Description</th>
56	</tr>
57	<tr>
58	<ti><c>mysql</c></ti>
59	<ti>Uses Mysql to store Jffnms data</ti>
60	</tr>
61	<tr>
62	<ti><c>postgres</c></ti>
63	<ti>Uses PostgreSQL to store Jffnms data</ti>
64	</tr>
65	<tr>
66	<ti><c>snmp</c></ti>
67	<ti>
68	Adds support for snmp, which enables jffnms to gather data from other hosts.
69	</ti>
70	</tr>
71	</table>
72
73	</body>
74	</section>
75	<section>
76	<title>USE flags for PHP</title>
77	<body>
78
79	<p>
80	Being written in PHP, Jffnms is heavily dependent on PHP USE flags. In order to
81	install Jffnms successfully, you are required to have your PHP package installed
82	with (at least) the following USE flags:
83	</p>
84
85	<table>
86	<tr>
87	<th>USE Flags for PHP</th>
88	<th>Description</th>
89	</tr>
90	<tr>
91	<ti><c>gd</c></ti>
92	<ti>Adds support for media-libs/gd (to generate graphics on the fly)</ti>
93	</tr>
94	<tr>
95	<ti><c>wddx</c></ti>
96	<ti>Adds support for Web Distributed Data eXchange </ti>
97	</tr>
98	<tr>
99	<ti><c>sockets</c></ti>
100	<ti>Adds support for tcp/ip sockets</ti>
101	</tr>
102	<tr>
103	<ti><c>session</c></ti>
104	<ti>Adds persistent session support</ti>
105	</tr>
106	<tr>
107	<ti><c>spl</c></ti>
108	<ti>Adds support for the Standard PHP Library</ti>
109	</tr>
110	<tr>
111	<ti><c>cli</c></ti>
112	<ti>Enable CLI SAPI</ti>
113	</tr>
114	</table>
115
116	</body>
117	</section>
118	<section>
119	<title>Installation</title>
120	<body>
121
122	<p>
123	Just like any package in Portage, jffnms can be installed with <c>emerge</c>:
124	</p>
125
126	<pre caption="Installing Jffnms">
127	# <i>emerge jffnms</i>
128	</pre>
129
130	<p>
131	Jffnms should be installed in <path>/opt/jffnms/</path>.
132	</p>
133
134	</body>
135	</section>
136	<section>
137	<title>Configuring Apache 2</title>
138	<body>
139
140	<warn>
141	This very basic configuration procedure for Apache does not cover all aspects
142	of setting up a web server.
143	</warn>
144
145	<p>
146	Sometimes you will want to run Jffnms on your local computer instead of a
147	remote server. If this is your case, it is very likely that you don't have an
148	apache setup running. Don't worry about installing apache though, Portage has
149	already done that for you. Nevertheless, you still have to configure and test
150	apache, which (luckily) is pretty straightforward. Start by adding Apache to
151	your default runlevel:
152	</p>
153
154	<pre caption="Adding apache2 to the default runlevel">
155	# <i>rc-update add apache2 default</i>
156	</pre>
157
158	<p>
159	If you haven't done it yet, it's time to start apache2:
160	</p>
161
162	<pre caption="Starting apache2">
163	# <i>/etc/init.d/apache2 start</i>
164	</pre>
165
166	<p>
167	Finally, point your browser at <uri>http://localhost/</uri> and you should be
168	presented with a home page about your newly installed Apache 2. Now that we
169	know that Apache is up and running, we can proceed to the mod_php
170	configuration. Fire up your favorite text editor, open
171	<path>/etc/conf.d/apache2</path> and add <c>-D PHP5</c> the APACHE2_OPTS
172	variable.
173	</p>
174
175	<pre caption="Apache 2 Configuration">
176	# <i>nano -w /etc/conf.d/apache2</i>
177	APACHE2_OPTS="-D DEFAULT_VHOST -D PHP5"
178	</pre>
179
180	<p>
181	After that, you should create a symlink to the Jffnms install directory in your
182	Apache document root dir. In Gentoo, by default, Apache uses
183	<path>/var/www/localhost/htdocs</path> as document root. So, you should do the
184	following:
185	</p>
186
187	<pre caption="Creating Jffnms symlink">
188	# <i>cd /var/www/localhost/htdocs && ln -s /opt/jffnms/</i>
189	</pre>
190
191	</body>
192	</section>
193	<section>
194	<title>Configuring PHP</title>
195	<body>
196
197	<p>
198	Now that Apache is running, it is time to configure PHP. Jffnms requires that
199	you set some variables in php.ini in order to run. The <path>php.ini</path> file
200	is usually located in <path>/etc/php/apache2-php5/php.ini</path>. You have to
201	set these variables to the following values:
202	</p>
203
204	<pre caption="Configuring PHP">
205	# <i>nano -w /etc/php/apache2-php5/php.ini</i>
206	register_globals = On
207	register_argc_argv = On
208	error_reporting = E_ALL & ~E_NOTICE
209	allow_url_fopen = On
210	include_path = ".:/usr/share/php5:/usr/share/php:/usr/share/php/PEAR"
211	short_open_tag = On
212	</pre>
213
214	</body>
215	</section>
216	<section>
217	<title>Database setup</title>
218	<body>
219
220	<warn>
221	Please note again that this a very basic configuration procedure for any
222	database system and does not cover all aspects of setting up such systems.
223	</warn>
224
225	<p>
226	Jffnms allows you to use either PostgreSQL or MySQL as its database. Here we'll
227	show you how to create the database and necessary tables where Jffnms will
228	store its data. It's important to note that it isn't necessary to have a
229	database running locally to run Jffnms and except for the fact that you need to
230	run this commands on the remote host, the procedure is the same.
231	</p>
232
233	</body>
234	</section>
235	<section>
236	<title>Setting up PostgreSQL</title>
237	<body>
238
239	<note>
240	If you already have a PostgreSQL database up and running, you can proceed to
241	the <uri link="#use-pg">next section</uri>.
242	</note>
243
244	<p>
245	You should add PostgreSQL to your default runlevel so it's started each time you
246	boot your computer. Make sure to change <c>${SLOT}</c> to your PostgreSQL
247	slot, such as 9.1 or 9.2.
248	</p>
249
250	<pre caption="Adding PostgreSQL to the default runlevel">
251	# <i>rc-update add postgresql-${SLOT} default</i>
252	</pre>
253
254	<p>
255	Now you must setup the PostgreSQL database. Make sure to change
256	<c>${VERSION}</c> to your PostgreSQL version, such as 9.0.9 or 9.1.5.
257	</p>
258
259	<pre caption="Preparing PostgreSQL">
260	# <i>emerge --config postgresql-server-${VERSION}</i>
261	</pre>
262
263	<p>
264	Now start PostgreSQL:
265	</p>
266
267	<pre caption="Starting PostgreSQL">
268	# <i>/etc/init.d/postgresql-${SLOT} start</i>
269	</pre>
270
271	</body>
272	</section>
273	<section id="use-pg">
274	<title>Using PostgreSQL as database</title>
275	<body>
276
277	<p>
278	Once you have your PostgreSQL set up and running, you have to create a Jffnms
279	user and a database to store host data.
280	</p>
281
282	<pre caption="Creating the Jffnms user and database">
283	# <i>psql template1 postgres</i>
284	template1=# <i>create user jffnms password 'jfnms' createdb;</i>
285	template1=# <i>\connect template1 jffnms</i>
286	template1=# <i>create database jffnms;</i>
287	template1=# <i>\q</i>
288	</pre>
289
290	<p>
291	Finally, you need to create all the tables where data will be stored:
292	</p>
293
294	<pre caption="Creating Jffnms tables">
295	# <i>psql jffnms jffnms < /opt/jffnms/docs/jffnms-0.9.3.pgsql</i>
296	</pre>
297
298	<p>
299	Once you have run those steps, the PostgreSQL database configuration for Jffnms
300	should be ok.
301	</p>
302
303	</body>
304	</section>
305	<section>
306	<title>Using MySQL as database</title>
307	<body>
308
309	<warn>
310	Installing and configuring a MySQL database is not covered in this guide.
311	Please see our <uri link="/doc/en/mysql-howto.xml">MySQL Startup Guide</uri>.
312	</warn>
313
314	<p>
315	In case you want to run Jffnms with MySQL, you'll first need to create a
316	database and a MySQL user. After that, create your MySQL table:
317	</p>
318
319	<pre caption="Create a mysql table.">
320	# <i>mysql -u jffnms -pjffnms jffnms < /opt/jffnms/docs/jffnms-0.9.3.mysql</i>
321	</pre>
322
323	</body>
324	</section>
325	<section>
326	<title>UDP Port Monitoring and discovery</title>
327	<body>
328
329	<warn>
330	This section covers setting up and running suid programs, so it may not be
331	adequate for systems where security is too much an issue.
332	</warn>
333
334	<p>
335	If you want UDP port monitoring and discovery, you need to set <c>nmap</c> and
336	<c>fping</c> as a SUID programs. This may give you security hole in case
337	there's a bug in one of them. To set them as a SUID you can run the following
338	commands:
339	</p>
340
341	<pre caption="Setting up udp port monitoring and discovery">
342	# <i>chmod +s /usr/bin/nmap ; chmod a+x /usr/bin/nmap</i>
343	# <i>chmod +s /usr/sbin/fping ; chmod a+x /usr/sbin/fping</i>
344	</pre>
345
346	</body>
347	</section>
348	</chapter>
349
350	<chapter>
351	<title>Configuring Jffnms</title>
352	<section>
353	<title>Configuring the poller process</title>
354	<body>
355
356	<p>
357	The poller process is responsible for gathering data from hosts. In order to
358	collect this data at regular intervals, it must be added to crontab.
359	</p>
360
361	<pre caption="Collecting data at regular intervals">
362	# <i>crontab -u jffnms /opt/jffnms/docs/unix/crontab</i>
363	# <i>crontab -e -u jffnms</i>
364	</pre>
365
366	</body>
367	</section>
368	<section>
369	<title>Final setup</title>
370	<body>
371
372	<p>
373	By now, Jffnms should be correctly installed on your system. You still need,
374	however, to configure Jffnms. Luckily, Jffnms provides us with an easy to use
375	web page where it's possible to configure access to database, user access as
376	well as check if the current host configuration suffices Jffnms needs. You can
377	access this web interface through the following URL:
378	<uri>http://localhost/jffnms/admin/setup.php</uri>. You can login to your new
379	installation by using the username and password <c>admin</c>. You should visit
380	<uri link="http://www.jffnms.org/">Jffnms's home page</uri> for details on how
381	to properly configure it.
382	</p>
383
384	</body>
385	</section>
386	</chapter>
387
388	<chapter>
389	<title>Support</title>
390	<section>
391	<body>
392
393	<p>
394	Though Jffnms is a wonderful application, it is a bit hard to get it up and
395	running. So if you run into problems with Jffnms, there are some places where
396	you can look for help:
397	</p>
398
399	<ul>
400	<li>
401	<uri link="http://www.jffnms.org/docs/installing.html">Jffnms Installation
402	Manual</uri>
403	</li>
404	<li>
405	<uri link="http://www.jffnms.org/docs/jffnms.html">Jffnms Manual</uri>
406	</li>
407	<li><uri link="http://forums.gentoo.org">Gentoo Forums</uri></li>
408	<li>
409	<uri link="http://www.postgresql.org/docs/9.1/static/index.html">PostgreSQL
410	9 Documentation</uri>
411	</li>
412	<li><uri link="http://dev.mysql.com/doc/">MySQL Documentation</uri></li>
413	</ul>
414
415	</body>
416	</section>
417	</chapter>
418	</guide>