Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve CentOS related installation docs #42

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Improve CentOS related installation docs #42

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
98a97a3
Improve CentOS related installation docs
obscurerichard Dec 30, 2019
46891d8
Fix typo
obscurerichard Dec 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 100 additions & 13 deletions doc/02-Installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,14 +145,45 @@ This has to sit on top of the page, but after the `<?php` line.

### PHP on CentOS

**Warning:** If you are running NagVis on CentOS - you also have to switch NagVis to PHP-FPM, so that the runtime
environment has access to the same PHP session data (if not you only see "not authenticated").
**Warning:** If you are running NagVis on CentOS you must account for two additional factors:

1. graphviz will need to be installed
2. icingaweb2 may use an PHP runtime that is not the vendor PHP
3. icingaweb2 runs under PHP-FPM
4. SELinux

The following instructions have been tested on CentOS 7.x.

#### Graphviz installation

Graphviz, required by `nagviz` may not be installed. Ensure it is installed before beginning the installation:

```shell
yum install -q -y grapviz
```

#### PHP runtime update
The `icingaweb2` module uses the PHP 7.1 runtime from the Red Hat Sofware Collections. The `php` program is not in the system path and the nagvis `install.sh` script will not find the PHP program it uses. Before running `install.sh`, issue this command to alter the path to include the PHP 7.1 `php` program:

```shell
export PATH=/opt/rh/rh-php71/root/bin:"$PATH"
```

#### PHP-FPM on CentOS

The nagvis install.sh script does not account for PHP-FPM, so you must make some manual changes to compensate.

Switch NagVis to run under PHP-FPM, so that the runtime environment has access to the same PHP session data. If you do not do this, you will only see the message "not authenticated" in the browser.

See [PHP-FPM in Apache httpd Wiki](https://wiki.apache.org/httpd/PHP-FPM) for more information about PHP-FPM.

The following options are possible:

**Switch all PHP inside Apache to FPM**
##### Switch _all_ PHP inside Apache to FPM

*Note*: This only works with Apache >= 2.4

Note: Only works with Apache >= 2.4
This configuration switches _all_ the PHP scripts on the server to run via PHP-FPM. If you have no other PHP applications running on the server except NagVis and icingaweb2, this is an easy option. However, if other scripts run via `mod_php` this may disrupt their functioning.

Add `/etc/httpd/conf.d/php-fpm.conf`:
```apache
Expand All @@ -165,24 +196,80 @@ SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
</FilesMatch>
```

**Switch NagVis to PHP-FPM**
##### Switch NagVis to PHP-FPM

Please make sure to use at least NagVis 1.9.5!
This configuration switches _only_ NagVis to run under PHP-FPM. This is a conservative option that will not disrupt the operation of other PHP applications on the server.

Update `/etc/httpd/conf.d/nagvis.conf` similar to [icingaweb2.conf](https://github.com/Icinga/icingaweb2/blob/master/packages/files/apache/icingaweb2.fpm.conf).
Please make sure to use at least NagVis 1.9.5!

**Adjust the session.save_path**
Update `/etc/httpd/conf.d/nagvis.conf` similar to [icingaweb2.conf](https://github.com/Icinga/icingaweb2/blob/master/packages/files/apache/icingaweb2.fpm.conf). Put this stanza inside the `<Directory /usr/local/nagvis/share>` directive:

For system PHP running in Apache httpd, update `/etc/httpd/conf.d/php.conf`:
```apache
php_value session.save_path "/var/opt/rh/rh-php71/lib/php/session"
```
<IfVersion >= 2.4>
# Forward PHP requests to FPM
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
<FilesMatch "\.php$">
SetHandler "proxy:fcgi://127.0.0.1:9000"
ErrorDocument 503 /icingaweb2/error_unavailable.html
</FilesMatch>
</IfVersion>
```

##### Adjust PHP-FPM php.ini include path

**Adjust the include_path**
Set the `include_path` to include `/usr/share/php`.

Update `/etc/opt/rh/rh-php71/php.ini`:
```apache
include_path = ".:/usr/share/php:/opt/rh/rh-php71/root/usr/share/pear:/opt/rh/rh-php71/root/usr/share/php"
```

Also see [PHP-FPM in Apache httpd Wiki](https://wiki.apache.org/httpd/PHP-FPM).
If you do not do this, you will either get a blank screen when you open the NagVis tab, or if errors are configured to be displayed, you may get the error:
```
Warning: Uncaught Error: (0) require_once(Icinga/Application/EmbeddedWeb.php): failed to open stream: No such file or directory
```

Set
##### Adjust www.conf PATH environment setting

In order to get NagVis properly integrated with `graphviz` you have to adjust the `www.conf` file to pass a PATH environment variable into `php-fpm` processes. Edit `/etc/opt/rh/rh-php71/php-fpm.d/www.conf` and uncomment the `env[PATH]` line: ([Thanks mj84](https://monitoring-portal.org/t/nagvis-automap-on-centos-7-5/3971))

```apache
env[PATH] = /usr/local/bin:/usr/bin:/bin
```

##### Alternative option: Run NagVis via `mod_php` and adjust the `session.save_path`

It is possible to run NagVis via the system PHP packages (these are PHP 5.4 for CentOS 7). This configuration is simpler but has risks associated with running an older PHP version and may be less performant.

If you use the system PHP to run NagVis under `mod_php` running in Apache httpd, you must adjust the session save path to have both PHP runtimes share the same session store.

For a configuration using the system PHP running in Apache httpd using `mod_php`, update `/etc/httpd/conf.d/php.conf`:
```apache
php_value session.save_path "/var/opt/rh/rh-php71/lib/php/session"
```

#### SELinux on CentOS

If SELinux is enabled, when you visit `/nagvis/` in your browser, you will receive error messages about the cache directory not being writable, for example `/usr/local/nagvis/var/tmpl/cache`. Even though the standard UNIX file permissions would allow the web server user `apache` to read and write in these directories, SELinux mandatory access control rules prevent this. You can confirm this by examining `/var/log/audit/audit.log`, you will see entries similar to:

```
type=AVC msg=audit(1577662574.710:926674): avc: denied { write } for pid=8231 comm="httpd" name="var" dev="nvme0n1p1" ino=18240328 scontext=system_u:system_r:httpd_t:s0 tcontext=unconfined_u:object_r:httpd_sys_content_t:s0 tclass=dir permissive=0
```

To fix this, you must tell the system that it is OK for the web server to perform these operations. These commands will permanently adjust the file labels under the `nagvis` directory to work with `httpd` and PHP-FPM:
```shell
# Ensure you hae the semanage utility installed
yum install -q -y policycoreutils-python
# Adjust NAGVIS_ROOT to be the root of your installation
NAGVIS_ROOT=/usr/local/nagvis
semanage fcontext -a -t httpd_sys_content_t "$NAGVIS_ROOT(/.*)?"
semanage fcontext -a -t httpd_sys_rw_content_t "$NAGVIS_ROOT/var(/.*)?"
semanage fcontext -a -t httpd_sys_rw_content_t "$NAGVIS_ROOT/etc(/.*)?"
semanage fcontext -a -t httpd_sys_rw_content_t "$NAGVIS_ROOT/share/userfiles/(/.*)?"
restorecon -R "$NAGVIS_ROOT"
```

_*WARNING*_: Many system administrators would advise you to disable SELinux or set it to permissive to work around the problem, however this will weaken the security posture of your system. Other advice might counsel you to change the SELinux policy via `audit2allow` to broaden the permissions. Both of these approaches are flawed and will weaken the security of your system overall. Instead, configure file labels for SELinux in order to tell the system that the `nagvis` directories are related to `httpd`, and some of them are OK for the web server to write to.