/[gentoo]/xml/htdocs/doc/en/jffnms.xml
Gentoo

Contents of /xml/htdocs/doc/en/jffnms.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (hide annotations) (download) (as text)
Tue Apr 25 10:58:33 2006 UTC (7 years, 11 months ago) by neysx
Branch: MAIN
Changes since 1.2: +102 -5 lines
File MIME type: application/xml
Updates from #127455 & #128854

1 neysx 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 neysx 1.3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/jffnms.xml,v 1.2 2006/04/15 19:56:03 rane Exp $ -->
4 neysx 1.1
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 neysx 1.3 <version>1.1</version>
23     <date>2006-04-25</date>
24 neysx 1.1
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 neysx 1.3 <title>Choosing your use flags</title>
46     <body>
47    
48     <p>
49     In order to better fit your needs, Jffnms ebuild has the following USE Flags
50     available:
51     </p>
52    
53     <table>
54     <tr>
55     <th>USE Flags for Jffnms</th>
56     <th>Description</th>
57     </tr>
58     <tr>
59     <ti><c>mysql</c></ti>
60     <ti>Uses Mysql to store Jffnms data</ti>
61     </tr>
62     <tr>
63     <ti><c>postgres</c></ti>
64     <ti>Uses PostgreSQL to store Jffnms data</ti>
65     </tr>
66     <tr>
67     <ti><c>snmp</c></ti>
68     <ti>
69     Adds suport for snmp, which enables jffms to gather data from other hosts.
70     </ti>
71     </tr>
72     </table>
73    
74     </body>
75     </section>
76     <section>
77     <title>USE Flags for PHP</title>
78     <body>
79    
80     <p>
81     Being written in PHP, Jffnms is heavily dependent on php USE Flags. In order
82     to install Jffnms successfully, it is required that you have your php package
83     installed with (at least) the following USE flags:
84     </p>
85    
86     <table>
87     <tr>
88     <th>USE Flags for PHP</th>
89     <th>Description</th>
90     </tr>
91     <tr>
92     <ti><c>gd</c></ti>
93     <ti>Adds support for media-libs/gd (to generate graphics on the fly)</ti>
94     </tr>
95     <tr>
96     <ti><c>wddx</c></ti>
97     <ti>Adds support for Web Distributed Data eXchange </ti>
98     </tr>
99     <tr>
100     <ti><c>sockets</c></ti>
101     <ti>Adds support for tcp/ip sockets</ti>
102     </tr>
103     <tr>
104     <ti><c>session</c></ti>
105     <ti>Adds persistent session support</ti>
106     </tr>
107     <tr>
108     <ti><c>spl</c></ti>
109     <ti>Adds support for the Standard PHP Library</ti>
110     </tr>
111     <tr>
112     <ti><c>cli</c></ti>
113     <ti>Enable CLI SAPI</ti>
114     </tr>
115     </table>
116    
117     </body>
118     </section>
119     <section>
120 neysx 1.1 <title>Installation</title>
121     <body>
122    
123     <p>
124     Just like any package in Portage, jffnms can be installed with <c>emerge</c>:
125     </p>
126    
127     <pre caption="Installing Jffnms">
128     # <i>emerge jffnms</i>
129     </pre>
130    
131     <p>
132     Jffnms should be installed in <path>/opt/jffnms/</path>.
133     </p>
134    
135     </body>
136     </section>
137     <section>
138     <title>Configuring Apache 2</title>
139     <body>
140    
141     <warn>
142     This very basic configuration procedure for apache does not cover all aspects
143     of setting up a web server.
144     </warn>
145    
146     <p>
147     Sometimes you will want to run Jffnms on your local computer instead of a
148     remote server. If this is your case, it is very likely that you don't have an
149     apache setup running. Don't worry about installing apache though, Portage has
150     already done that for you. Nevertheless, you still have to configure and test
151     apache, which (luckily) is pretty straightforward. Start by adding apache to
152     your default runlevel:
153     </p>
154    
155     <pre caption="Adding apache 2 to the default runlevel">
156     # <i>rc-update add apache2 default</i>
157     * apache2 added to runlevel default
158     * rc-update complete.
159     </pre>
160    
161     <p>
162     If you haven't done it yet, it's time to start apache2:
163     </p>
164    
165     <pre caption="Starting apache2">
166     # <i>/etc/init.d/apache2 start</i>
167     </pre>
168    
169     <p>
170     Finally, point your browser at <uri>http://localhost/</uri> and you should be
171     presented with a home page about your newly installed Apache 2. Now that we
172     know that Apache is up and running, we can proceed to the mod_php
173     configuration. Fire up your favorite text editor, open
174     <path>/etc/conf.d/apache2</path> and add <c>-D PHP4</c> the APACHE2_OPTS
175     variable.
176     </p>
177    
178     <pre caption="Apache 2 Configuration">
179     # <i>nano -w /etc/conf.d/apache2</i>
180     APACHE2_OPTS="-D DEFAULT_VHOST -D PHP4"
181     </pre>
182    
183     <p>
184     After that, you should create a symlink to the Jffnms install directory in your
185     Apache document root dir. In Gentoo, by default, Apache uses
186     <path>/var/www/localhost/htdocs</path> as document root. So, you should do the
187     following:
188     </p>
189    
190     <pre caption="Creating Jffnms symlink">
191     # <i>cd /var/www/localhost/htdocs &amp;&amp; ln -s /opt/jffnms/htdocs</i>
192     </pre>
193    
194     </body>
195     </section>
196     <section>
197     <title>Configuring PHP</title>
198     <body>
199    
200     <p>
201     Now that apache is running, it is time to configure PHP. Jffnms requires that
202     you set some variables in php.ini in order to run. The php.ini file is usually
203     located in <path>/etc/php/apache2-php4/php.ini</path>. You have to set these
204     variables to the following values:
205     </p>
206    
207     <pre caption="Configuring PHP">
208     # <i>nano -w /etc/php/apache2-php4/php.ini</i>
209     register_globals = On
210     register_argc_argv = On
211     error_reporting = E_ALL &amp; ~E_NOTICE
212     allow_url_fopen = On
213     include_path = ".:/usr/share/php4:/usr/share/php:/usr/share/php/PEAR"
214     short_open_tag = On
215     </pre>
216    
217     </body>
218     </section>
219     <section>
220     <title>Database setup</title>
221     <body>
222    
223     <warn>
224     Please note again that this a very basic configuration procedure for any
225     database system and does not cover all aspects of setting up such systems.
226     </warn>
227    
228     <p>
229     Jffnms allows you to use either PostgreSQL or MySQL as its database. Here we'll
230     show you how to create the database and necessary tables where Jffnms will
231     store its data. It's important to note that it isn't necessary to have a
232     database running localy to run Jffnms and except for the fact that you need to
233     run this commands on the remote host, the procedure is the same.
234     </p>
235    
236     </body>
237     </section>
238     <section>
239     <title>Setting Up PostgreSQL</title>
240     <body>
241    
242     <note>
243     If you already have a PostgreSQL database up and running, you can proceed to
244     the <uri link="#use-pg">next section</uri>.
245     </note>
246    
247     <p>
248     You should add PostgreSQL to your default runlevel so it's started each time
249     you boot your computer.
250     </p>
251    
252     <pre caption="Adding PostgreSQL to the default runlevel">
253     # <i>rc-update add postgresql default</i>
254     * postgresql added to runlevel default
255     * rc-update complete.
256     </pre>
257    
258     <p>
259     Now, you must prepare PostgreSQL directories. This is done through the
260     <c>initdb</c> command. By default, PostgreSQL data directories are generally
261     stored in <path>/var/lib/postgresql/data</path>.
262     </p>
263    
264     <impo>
265     The following command must be run with your PostgreSQL user. By default this
266     user is generally called "postgres".
267     </impo>
268    
269     <pre caption="Preparing PostgreSQL Directories">
270     # <i>su - postgres</i>
271     $ <i>initdb -D /var/lib/postgresql/data</i>
272     The files belonging to this database system will be owned by user "postgres".
273     This user must also own the server process.
274    
275     The database cluster will be initialized with locale C.
276    
277     creating directory /var/lib/postgresql/data ... ok
278     creating directory /var/lib/postgresql/data/global ... ok
279     creating directory /var/lib/postgresql/data/pg_xlog ... ok
280     creating directory /var/lib/postgresql/data/pg_xlog/archive_status ... ok
281     creating directory /var/lib/postgresql/data/pg_clog ... ok
282     creating directory /var/lib/postgresql/data/pg_subtrans ... ok
283     creating directory /var/lib/postgresql/data/base ... ok
284     creating directory /var/lib/postgresql/data/base/1 ... ok
285     creating directory /var/lib/postgresql/data/pg_tblspc ... ok
286     selecting default max_connections ... 100
287     selecting default shared_buffers ... 1000
288     creating configuration files ... ok
289     creating template1 database in /var/lib/postgresql/data/base/1 ... ok
290     initializing pg_shadow ... ok
291     enabling unlimited row size for system tables ... ok
292     initializing pg_depend ... ok
293     creating system views ... ok
294     loading pg_description ... ok
295     creating conversions ... ok
296     setting privileges on built-in objects ... ok
297     creating information schema ... ok
298     vacuuming database template1 ... ok
299     copying template1 to template0 ... ok
300    
301     WARNING: enabling "trust" authentication for local connections
302     You can change this by editing pg_hba.conf or using the -A option the
303     next time you run initdb.
304    
305     Success. You can now start the database server using:
306    
307     postmaster -D /var/lib/postgresql/data
308     or
309     pg_ctl -D /var/lib/postgresql/data -l logfile start
310     </pre>
311    
312     <p>
313     If initdb was successfully executed, you can go back to your root user and
314     start PostgreSQL.
315     </p>
316    
317     <pre caption="Starting PostgreSQL">
318     # <i>/etc/init.d/postgresql start</i>
319     </pre>
320    
321     </body>
322     </section>
323     <section id="use-pg">
324     <title>Using PostgreSQL as database</title>
325     <body>
326    
327     <p>
328     Once you have your PostgreSQL set up and running, you have to create a Jffnms
329     user and a database to store host data. We provide files to do both.
330     </p>
331    
332     <note>
333     If you don't use <path>/usr/portage</path> as your portage dir ($PORTDIR) you
334     have to change the last part of these commands to whatever your portage dir
335     is.
336     </note>
337    
338     <pre caption="Creating Jffnms user">
339     # <i>psql template1 postgres &lt; /usr/portage/net-analyzer/jffnms/files/postgresql_db</i>
340     </pre>
341    
342     <pre caption="Creating Jffnms database">
343 neysx 1.3 # <i>psql template1 postgres &lt; /usr/portage/net-analyzer/jffnms/files/postgresql_db_table</i>
344 neysx 1.1 </pre>
345    
346     <p>
347     Finally, you need to create all the tables where data will be stored:
348     </p>
349    
350     <pre caption="Creating Jffnms database">
351     # <i>psql jffnms jffnms &lt; /opt/jffnms/docs/jffnms-0.8.2.pgsql</i>
352     </pre>
353    
354     <p>
355     Once you have run those steps, PostgreSQL database configuration for Jffnms
356     should be ok.
357     </p>
358    
359     </body>
360     </section>
361     <section>
362     <title>Using MySQL as database.</title>
363     <body>
364    
365     <warn>
366     Installing and configuring a MySQL database is not covered in this guide.
367     Please see our <uri link="/doc/en/mysql-howto.xml">MySQL Startup Guide</uri>.
368     </warn>
369    
370     <p>
371     In case you want to run Jffnms with MySQL, the process is a bit simpler. We
372     provide two files to create database, user and tables for MySQL.
373     </p>
374    
375     <note>
376     If you don't use <path>/usr/portage</path> as your portage dir ($PORTDIR) you
377     have to change the last part of these commands to whatever your portage dir
378     is.
379     </note>
380    
381     <pre caption="Create a database and a mysql user.">
382     # <i>mysql -u <comment>username</comment> -p <comment>password</comment> &lt; /usr/portage/net-analyzer/jffnms/files/mysql_db</i>
383     </pre>
384    
385     <pre caption="Create a mysql tables.">
386     # <i>mysql -u jffnms -pjffnms jffnms &lt; /opt/jffnms/docs/docs/jffnms-0.8.2.mysql</i>
387     </pre>
388    
389     </body>
390     </section>
391     <section>
392     <title>UDP Port Monitoring and discovery</title>
393     <body>
394    
395     <warn>
396     This section covers setting up and running suid programs, so it may not be
397     adequate for systems where security is too much an issue.
398     </warn>
399    
400     <p>
401     If you want UDP port monitoring and discovery, you need to set <c>nmap</c> and
402 rane 1.2 <c>fping</c> as a SUID programs. This may give you security hole in case
403 neysx 1.1 there's a bug in one of them. To set them as a SUID you can run the following
404     commands:
405     </p>
406    
407     <pre caption="Setting up udp port monitoring and discovery">
408     # <i>chmod +s /usr/bin/nmap ; chmod a+x /usr/bin/nmap</i>
409     # <i>chmod +s /usr/sbin/fping ; chmod a+x /usr/sbin/fping</i>
410     </pre>
411    
412     </body>
413     </section>
414     </chapter>
415    
416     <chapter>
417     <title>Configuring Jffnms</title>
418     <section>
419     <title>Configuring the poller process</title>
420     <body>
421    
422     <p>
423     The poller process is responsible for gathering data from hosts. In order to
424     collect this data at regular intervals, it must be added to crontab.
425     </p>
426    
427 neysx 1.3 <pre caption="Collecting data at regular intervals">
428 neysx 1.1 # <i>crontab -u jffnms /opt/jffnms/docs/unix/crontab</i>
429     # <i>crontab -e -u jffnms</i>
430     </pre>
431    
432     </body>
433     </section>
434 neysx 1.3 <section>
435     <title>Final Setup</title>
436     <body>
437    
438     <p>
439     By now, Jffnms should be correctly installed on your system. You still need,
440     however, to configure Jffms. Luckily, Jffnms provides us with an easy to use
441     web page where it's possible to configure access to database, user access as
442     well as check if the current host configuration suffices Jffnms needs. You can
443     access this web interface through the following URL:
444     <uri>http://localhost/jffnms/admin/setup.php</uri>. You should visit <uri
445     link="http://www.jffnms.org/">Jffnms's home page</uri> for details on how to
446     properly configure it.
447     </p>
448    
449     </body>
450     </section>
451 neysx 1.1 </chapter>
452    
453     <chapter>
454     <title>Support</title>
455     <section>
456     <title>Support</title>
457     <body>
458    
459     <p>
460     Though Jffnms is a wonderful software, it is a bit hard to get it up and
461     running. So if you run into problems with Jffnms, there are some places where
462     you can look for help:
463     </p>
464    
465     <ul>
466     <li>
467     <uri link="http://www.jffnms.org/docs/installing.html">Jffnms Installation
468     Manual</uri>
469     </li>
470     <li>
471     <uri link="http://www.jffnms.org/docs/jffnms.html">Jffnms Manual</uri>
472     </li>
473     <li><uri link="http://forums.gentoo.org">Gentoo Forums</uri></li>
474 neysx 1.3 <li>
475     <uri link="http://www.postgresql.org/docs/8.0/static/index.html">PostgreSQL
476     8 Documentation</uri>
477     </li>
478     <li><uri link="http://dev.mysql.com/doc/">MySQL Documentation</uri></li>
479 neysx 1.1 </ul>
480    
481     <p>
482     You may also run into problems when configuring Apache to work with PHP
483     (specially if you run both PHP4 and PHP5 on the same system). In that case, our
484     <uri link="/proj/en/php/php4-php5-configuration.xml">Configuring Apache to Work
485     with PHP4 and PHP5</uri> guide may give you some help.
486     </p>
487    
488     </body>
489     </section>
490     </chapter>
491     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20