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.1 2006/03/10 22:36:46 neysx Exp $ -->

<guide link="/doc/en/jffnms.xml" lang="en">
<title>Jffnms Installation and Setup Guide</title>

<author title="Author">
  <mail link="angusyoung@gentoo.org">Otavio R. Piske</mail>
</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>1.0</version>
<date>2006-03-10</date>

<chapter>
<title>Jffms 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>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 apache 2 to the default runlevel">
# <i>rc-update add apache2 default</i>
 * apache2 added to runlevel default
 * rc-update complete.
</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 PHP4</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 PHP4"
</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/htdocs</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 php.ini file is usually
located in <path>/etc/php/apache2-php4/php.ini</path>. You have to set these
variables to the following values:
</p>

<pre caption="Configuring PHP">
# <i>nano -w /etc/php/apache2-php4/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/php4:/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 localy 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.
</p>
 
<pre caption="Adding PostgreSQL to the default runlevel">
# <i>rc-update add postgresql default</i>
 * postgresql added to runlevel default
 * rc-update complete.
</pre>

<p>
Now, you must prepare PostgreSQL directories. This is done through the
<c>initdb</c> command.  By default, PostgreSQL data directories are generally
stored in <path>/var/lib/postgresql/data</path>.
</p>

<impo>
The following command must be run with your PostgreSQL user. By default this
user is generally called "postgres".
</impo>
 
<pre caption="Preparing PostgreSQL Directories">
# <i>su - postgres</i>
$ <i>initdb -D /var/lib/postgresql/data</i>
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

The database cluster will be initialized with locale C.

creating directory /var/lib/postgresql/data ... ok
creating directory /var/lib/postgresql/data/global ... ok
creating directory /var/lib/postgresql/data/pg_xlog ... ok
creating directory /var/lib/postgresql/data/pg_xlog/archive_status ... ok
creating directory /var/lib/postgresql/data/pg_clog ... ok
creating directory /var/lib/postgresql/data/pg_subtrans ... ok
creating directory /var/lib/postgresql/data/base ... ok
creating directory /var/lib/postgresql/data/base/1 ... ok
creating directory /var/lib/postgresql/data/pg_tblspc ... ok
selecting default max_connections ... 100
selecting default shared_buffers ... 1000
creating configuration files ... ok
creating template1 database in /var/lib/postgresql/data/base/1 ... ok
initializing pg_shadow ... ok
enabling unlimited row size for system tables ... ok
initializing pg_depend ... ok
creating system views ... ok
loading pg_description ... ok
creating conversions ... ok
setting privileges on built-in objects ... ok
creating information schema ... ok
vacuuming database template1 ... ok
copying template1 to template0 ... ok

WARNING: enabling "trust" authentication for local connections
You can change this by editing pg_hba.conf or using the -A option the
next time you run initdb.

Success. You can now start the database server using:

    postmaster -D /var/lib/postgresql/data
or
    pg_ctl -D /var/lib/postgresql/data -l logfile start
</pre>

<p>
If initdb was successfully executed, you can go back to your root user and
start PostgreSQL.
</p>

<pre caption="Starting PostgreSQL">
# <i>/etc/init.d/postgresql 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. We provide files to do both.
</p>

<note>
If you don't use <path>/usr/portage</path> as your portage dir ($PORTDIR) you
have to change the last part of these commands to whatever your portage dir
is.
</note>

<pre caption="Creating Jffnms user">
# <i>psql template1 postgres &lt; /usr/portage/net-analyzer/jffnms/files/postgresql_db</i>
</pre>

<pre caption="Creating Jffnms database">
# <i>psql template1 postgres &lt; /usr/portage/net-analyzer/jffnms/files/postgresql_db_tables</i>
</pre>

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

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

<p>
Once you have run those steps, 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, the process is a bit simpler. We
provide two files to create database, user and tables for MySQL.
</p>

<note>
If you don't use <path>/usr/portage</path> as your portage dir ($PORTDIR) you
have to change the last part of these commands to whatever your portage dir
is.
</note>

<pre caption="Create a database and a mysql user.">
# <i>mysql -u <comment>username</comment> -p <comment>password</comment> &lt; /usr/portage/net-analyzer/jffnms/files/mysql_db</i>
</pre>

<pre caption="Create a mysql tables.">
# <i>mysql -u jffnms -pjffnms jffnms &lt; /opt/jffnms/docs/docs/jffnms-0.8.2.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="Setting up udp port monitoring and discovery">
# <i>crontab -u jffnms /opt/jffnms/docs/unix/crontab</i>
# <i>crontab -e -u jffnms</i>
</pre>

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

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

<p>
Though Jffnms is a wonderful software, 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>
</ul>

<p>
You may also run into problems when configuring Apache to work with PHP
(specially if you run both PHP4 and PHP5 on the same system). In that case, our
<uri link="/proj/en/php/php4-php5-configuration.xml">Configuring Apache to Work
with PHP4 and PHP5</uri> guide may give you some help.
</p>

</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.1 2006/03/10 22:36:46 neysx Exp $ -->
4
5	<guide link="/doc/en/jffnms.xml" lang="en">
6	<title>Jffnms Installation and Setup Guide</title>
7
8	<author title="Author">
9	<mail link="angusyoung@gentoo.org">Otavio R. Piske</mail>
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>1.0</version>
23	<date>2006-03-10</date>
24
25	<chapter>
26	<title>Jffms 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>Installation</title>
46	<body>
47
48	<p>
49	Just like any package in Portage, jffnms can be installed with <c>emerge</c>:
50	</p>
51
52	<pre caption="Installing Jffnms">
53	# <i>emerge jffnms</i>
54	</pre>
55
56	<p>
57	Jffnms should be installed in <path>/opt/jffnms/</path>.
58	</p>
59
60	</body>
61	</section>
62	<section>
63	<title>Configuring Apache 2</title>
64	<body>
65
66	<warn>
67	This very basic configuration procedure for apache does not cover all aspects
68	of setting up a web server.
69	</warn>
70
71	<p>
72	Sometimes you will want to run Jffnms on your local computer instead of a
73	remote server. If this is your case, it is very likely that you don't have an
74	apache setup running. Don't worry about installing apache though, Portage has
75	already done that for you. Nevertheless, you still have to configure and test
76	apache, which (luckily) is pretty straightforward. Start by adding apache to
77	your default runlevel:
78	</p>
79
80	<pre caption="Adding apache 2 to the default runlevel">
81	# <i>rc-update add apache2 default</i>
82	* apache2 added to runlevel default
83	* rc-update complete.
84	</pre>
85
86	<p>
87	If you haven't done it yet, it's time to start apache2:
88	</p>
89
90	<pre caption="Starting apache2">
91	# <i>/etc/init.d/apache2 start</i>
92	</pre>
93
94	<p>
95	Finally, point your browser at <uri>http://localhost/</uri> and you should be
96	presented with a home page about your newly installed Apache 2. Now that we
97	know that Apache is up and running, we can proceed to the mod_php
98	configuration. Fire up your favorite text editor, open
99	<path>/etc/conf.d/apache2</path> and add <c>-D PHP4</c> the APACHE2_OPTS
100	variable.
101	</p>
102
103	<pre caption="Apache 2 Configuration">
104	# <i>nano -w /etc/conf.d/apache2</i>
105	APACHE2_OPTS="-D DEFAULT_VHOST -D PHP4"
106	</pre>
107
108	<p>
109	After that, you should create a symlink to the Jffnms install directory in your
110	Apache document root dir. In Gentoo, by default, Apache uses
111	<path>/var/www/localhost/htdocs</path> as document root. So, you should do the
112	following:
113	</p>
114
115	<pre caption="Creating Jffnms symlink">
116	# <i>cd /var/www/localhost/htdocs && ln -s /opt/jffnms/htdocs</i>
117	</pre>
118
119	</body>
120	</section>
121	<section>
122	<title>Configuring PHP</title>
123	<body>
124
125	<p>
126	Now that apache is running, it is time to configure PHP. Jffnms requires that
127	you set some variables in php.ini in order to run. The php.ini file is usually
128	located in <path>/etc/php/apache2-php4/php.ini</path>. You have to set these
129	variables to the following values:
130	</p>
131
132	<pre caption="Configuring PHP">
133	# <i>nano -w /etc/php/apache2-php4/php.ini</i>
134	register_globals = On
135	register_argc_argv = On
136	error_reporting = E_ALL & ~E_NOTICE
137	allow_url_fopen = On
138	include_path = ".:/usr/share/php4:/usr/share/php:/usr/share/php/PEAR"
139	short_open_tag = On
140	</pre>
141
142	</body>
143	</section>
144	<section>
145	<title>Database setup</title>
146	<body>
147
148	<warn>
149	Please note again that this a very basic configuration procedure for any
150	database system and does not cover all aspects of setting up such systems.
151	</warn>
152
153	<p>
154	Jffnms allows you to use either PostgreSQL or MySQL as its database. Here we'll
155	show you how to create the database and necessary tables where Jffnms will
156	store its data. It's important to note that it isn't necessary to have a
157	database running localy to run Jffnms and except for the fact that you need to
158	run this commands on the remote host, the procedure is the same.
159	</p>
160
161	</body>
162	</section>
163	<section>
164	<title>Setting Up PostgreSQL</title>
165	<body>
166
167	<note>
168	If you already have a PostgreSQL database up and running, you can proceed to
169	the <uri link="#use-pg">next section</uri>.
170	</note>
171
172	<p>
173	You should add PostgreSQL to your default runlevel so it's started each time
174	you boot your computer.
175	</p>
176
177	<pre caption="Adding PostgreSQL to the default runlevel">
178	# <i>rc-update add postgresql default</i>
179	* postgresql added to runlevel default
180	* rc-update complete.
181	</pre>
182
183	<p>
184	Now, you must prepare PostgreSQL directories. This is done through the
185	<c>initdb</c> command. By default, PostgreSQL data directories are generally
186	stored in <path>/var/lib/postgresql/data</path>.
187	</p>
188
189	<impo>
190	The following command must be run with your PostgreSQL user. By default this
191	user is generally called "postgres".
192	</impo>
193
194	<pre caption="Preparing PostgreSQL Directories">
195	# <i>su - postgres</i>
196	$ <i>initdb -D /var/lib/postgresql/data</i>
197	The files belonging to this database system will be owned by user "postgres".
198	This user must also own the server process.
199
200	The database cluster will be initialized with locale C.
201
202	creating directory /var/lib/postgresql/data ... ok
203	creating directory /var/lib/postgresql/data/global ... ok
204	creating directory /var/lib/postgresql/data/pg_xlog ... ok
205	creating directory /var/lib/postgresql/data/pg_xlog/archive_status ... ok
206	creating directory /var/lib/postgresql/data/pg_clog ... ok
207	creating directory /var/lib/postgresql/data/pg_subtrans ... ok
208	creating directory /var/lib/postgresql/data/base ... ok
209	creating directory /var/lib/postgresql/data/base/1 ... ok
210	creating directory /var/lib/postgresql/data/pg_tblspc ... ok
211	selecting default max_connections ... 100
212	selecting default shared_buffers ... 1000
213	creating configuration files ... ok
214	creating template1 database in /var/lib/postgresql/data/base/1 ... ok
215	initializing pg_shadow ... ok
216	enabling unlimited row size for system tables ... ok
217	initializing pg_depend ... ok
218	creating system views ... ok
219	loading pg_description ... ok
220	creating conversions ... ok
221	setting privileges on built-in objects ... ok
222	creating information schema ... ok
223	vacuuming database template1 ... ok
224	copying template1 to template0 ... ok
225
226	WARNING: enabling "trust" authentication for local connections
227	You can change this by editing pg_hba.conf or using the -A option the
228	next time you run initdb.
229
230	Success. You can now start the database server using:
231
232	postmaster -D /var/lib/postgresql/data
233	or
234	pg_ctl -D /var/lib/postgresql/data -l logfile start
235	</pre>
236
237	<p>
238	If initdb was successfully executed, you can go back to your root user and
239	start PostgreSQL.
240	</p>
241
242	<pre caption="Starting PostgreSQL">
243	# <i>/etc/init.d/postgresql start</i>
244	</pre>
245
246	</body>
247	</section>
248	<section id="use-pg">
249	<title>Using PostgreSQL as database</title>
250	<body>
251
252	<p>
253	Once you have your PostgreSQL set up and running, you have to create a Jffnms
254	user and a database to store host data. We provide files to do both.
255	</p>
256
257	<note>
258	If you don't use <path>/usr/portage</path> as your portage dir ($PORTDIR) you
259	have to change the last part of these commands to whatever your portage dir
260	is.
261	</note>
262
263	<pre caption="Creating Jffnms user">
264	# <i>psql template1 postgres < /usr/portage/net-analyzer/jffnms/files/postgresql_db</i>
265	</pre>
266
267	<pre caption="Creating Jffnms database">
268	# <i>psql template1 postgres < /usr/portage/net-analyzer/jffnms/files/postgresql_db_tables</i>
269	</pre>
270
271	<p>
272	Finally, you need to create all the tables where data will be stored:
273	</p>
274
275	<pre caption="Creating Jffnms database">
276	# <i>psql jffnms jffnms < /opt/jffnms/docs/jffnms-0.8.2.pgsql</i>
277	</pre>
278
279	<p>
280	Once you have run those steps, PostgreSQL database configuration for Jffnms
281	should be ok.
282	</p>
283
284	</body>
285	</section>
286	<section>
287	<title>Using MySQL as database.</title>
288	<body>
289
290	<warn>
291	Installing and configuring a MySQL database is not covered in this guide.
292	Please see our <uri link="/doc/en/mysql-howto.xml">MySQL Startup Guide</uri>.
293	</warn>
294
295	<p>
296	In case you want to run Jffnms with MySQL, the process is a bit simpler. We
297	provide two files to create database, user and tables for MySQL.
298	</p>
299
300	<note>
301	If you don't use <path>/usr/portage</path> as your portage dir ($PORTDIR) you
302	have to change the last part of these commands to whatever your portage dir
303	is.
304	</note>
305
306	<pre caption="Create a database and a mysql user.">
307	# <i>mysql -u <comment>username</comment> -p <comment>password</comment> < /usr/portage/net-analyzer/jffnms/files/mysql_db</i>
308	</pre>
309
310	<pre caption="Create a mysql tables.">
311	# <i>mysql -u jffnms -pjffnms jffnms < /opt/jffnms/docs/docs/jffnms-0.8.2.mysql</i>
312	</pre>
313
314	</body>
315	</section>
316	<section>
317	<title>UDP Port Monitoring and discovery</title>
318	<body>
319
320	<warn>
321	This section covers setting up and running suid programs, so it may not be
322	adequate for systems where security is too much an issue.
323	</warn>
324
325	<p>
326	If you want UDP port monitoring and discovery, you need to set <c>nmap</c> and
327	<c>fping</c> as a SUID programs. This may give you security hole in case
328	there's a bug in one of them. To set them as a SUID you can run the following
329	commands:
330	</p>
331
332	<pre caption="Setting up udp port monitoring and discovery">
333	# <i>chmod +s /usr/bin/nmap ; chmod a+x /usr/bin/nmap</i>
334	# <i>chmod +s /usr/sbin/fping ; chmod a+x /usr/sbin/fping</i>
335	</pre>
336
337	</body>
338	</section>
339	</chapter>
340
341	<chapter>
342	<title>Configuring Jffnms</title>
343	<section>
344	<title>Configuring the poller process</title>
345	<body>
346
347	<p>
348	The poller process is responsible for gathering data from hosts. In order to
349	collect this data at regular intervals, it must be added to crontab.
350	</p>
351
352	<pre caption="Setting up udp port monitoring and discovery">
353	# <i>crontab -u jffnms /opt/jffnms/docs/unix/crontab</i>
354	# <i>crontab -e -u jffnms</i>
355	</pre>
356
357	</body>
358	</section>
359	</chapter>
360
361	<chapter>
362	<title>Support</title>
363	<section>
364	<title>Support</title>
365	<body>
366
367	<p>
368	Though Jffnms is a wonderful software, it is a bit hard to get it up and
369	running. So if you run into problems with Jffnms, there are some places where
370	you can look for help:
371	</p>
372
373	<ul>
374	<li>
375	<uri link="http://www.jffnms.org/docs/installing.html">Jffnms Installation
376	Manual</uri>
377	</li>
378	<li>
379	<uri link="http://www.jffnms.org/docs/jffnms.html">Jffnms Manual</uri>
380	</li>
381	<li><uri link="http://forums.gentoo.org">Gentoo Forums</uri></li>
382	</ul>
383
384	<p>
385	You may also run into problems when configuring Apache to work with PHP
386	(specially if you run both PHP4 and PHP5 on the same system). In that case, our
387	<uri link="/proj/en/php/php4-php5-configuration.xml">Configuring Apache to Work
388	with PHP4 and PHP5</uri> guide may give you some help.
389	</p>
390
391	</body>
392	</section>
393	</chapter>
394	</guide>