Skip to content

Installing NGINX phpIPAM on RHEL, CentOS, or RockyLinux

If you’re collaboratively managing larger networks, with multiple subnets or VLANs, it’s best to move away from an spreadsheets and onto purpose built IP Address Managers.

I use phpIPAM. It’s free and open source, has a lovely friendly user interface, free and open source, and manages more than subnets and IP addresses like devices, racks, and VLANs!

Check it out here – https://phpipam.net/. Here’s how you can host it yourself.

Installing phpIPAM

Your Server

Your server can be any distribution of Linux. I’ve found to have greater success on distros similar to Red Hat Enterprise Linux, CentOS, or RockyLinux. You can use a Debian based system, but for this, I will be using RockyLinux.

Depending on your circumstances, you may wish to increase the resource allowances (say for instance if you’re serving more users/requests or have a larger database), but for me I just go with the base standard in Proxmox, 512MB Memory, 512MB Swap, 1vCPU, 8GB Disk space.

Specs TL;DR:

  • OS: RockyLinux 8.4
  • Memory: 512M
  • Swap: 512M
  • vCPU: 1
  • Disk: 8G

Installing Prerequisite Packages

I’m going to use NGINX to serve the webapp, I’ve found (for whatever reason) it performs a whole lot faster than Apache, don’t ask me why. I’ll also use MySQL as the database for phpIPAM. The application also runs in (believe it or not) PHP, so you’ll need to install PHP, and a couple other packages associated with it.

[[email protected] ~]# sudo yum update
[[email protected] ~]# sudo yum install mysql-server nginx php-fpm php-cli php-gd php-common php-ldap php-pdo php-pear php-snmp php-xml php-mbstring php-gmp php-json php-mysqlnd

Configuring MySQL

Let’s start by enabling and running the MySQL server service. Do sudo systemctl enable --now mysqld.

We now need to set the root password for MySQL, create a phpipam database, and a user to manage this database. Start by typing running sudo mysql_secure_installation, and answer the following questions;

  1. Validate Password Component: Yes
  2. Password for User Root: [Random, secure password. Write it down]
  3. Remove Anonymous Users: Yes
  4. Disallow root login remotely: Yes
  5. Remove test databases: Yes
  6. Reload privilege table: Yes

Now we create a new database, and a new user for phpipam. When creating the phpipam user, please use a secure randomised password. Replace the stand-in value “password” below with your own, and write it down.

[[email protected] ~]# mysql -u root -p
Enter password: 
mysql> CREATE DATABASE phpipam;
Query OK, 1 row affected (0.00 sec)

mysql> CREATE USER 'phpipam'@'localhost' IDENTIFIED BY 'password';
Query OK, 0 rows affected (0.02 sec)

mysql> GRANT ALL PRIVILEGES ON phpipam.* to 'phpipam'@'localhost';
Query OK, 0 rows affected (0.01 sec)

mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.01 sec)

Downloading and Configuring phpIPAM

You can download the latest copy of phpIPAM from their GitHub page. Install Git onto your server, clone the phpipam repository to the web root, and make a copy of the phpipam config file.

[[email protected] ~]# sudo yum install git
[[email protected] ~]# cd /var/www
[[email protected] www]# sudo clone https://github.com/phpipam/phpipam
[[email protected] phpipam]#  cd /var/www/phpipam
[[email protected] phpipam]# cp config.dist.php config.php

After this, update the relevant details in config.php (copied from config.dist.php above) using your preferred text editor. Usually, only “host”, “user”, “pass”, and “name” require updating.

<?php
  
/**
 * database connection details
 ******************************/
$db['host'] = 'localhost';
$db['user'] = 'phpipam';
$db['pass'] = 'password';
$db['name'] = 'phpipam';
$db['port'] = 3306;

Configuring NGINX

Start the NGINX service, sudo systemctl enable --now nginx and configure the following file.

This configuration assumes;

  1. you have installed phpIPAM into /var/www/phpipam,
  2. you have php-fpm installed and listening at unix:/var/run/php-fpm.socket,
  3. you have a signed certificate and private key installed in /etc/pki/tls/certs and /etc/pki/tls/private, making sure that only user nginx is permitted to read this key (use chown nginx:nginx [key] and chmod go-r [cert] to set as such), for use under ssl_certificate and ssl_certificate_key.

Please go through this configuration and update it for your requirements.

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

include /usr/share/nginx/modules/*.conf;

events { worker_connections 1024; }

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;
    
    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   65;
    types_hash_max_size 2048;
    
    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;
    
    include /etc/nginx/conf.d/*.conf;

    server {
        listen       80 default_server;
        listen       [::]:80 default_server;
        server_name  _;

        include /etc/nginx/default.d/*.conf;

        return 301 https://$host$request_uri;

        error_page 404 /404.html;            
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    }

    server {
        listen       443 ssl http2 default_server;
        listen       [::]:443 ssl http2 default_server;
        server_name  _;
        root         /var/www/phpipam;

        ssl_certificate "/etc/pki/tls/certs/signed.cert";
        ssl_certificate_key "/etc/pki/tls/private/private.key";
        ssl_session_cache shared:SSL:1m;
        ssl_session_timeout  10m;
        ssl_ciphers PROFILE=SYSTEM;
        ssl_prefer_server_ciphers on;

        include /etc/nginx/default.d/*.conf;

        location / {
                try_files $uri $uri/ /index.php;
                index index.php;
        }

        location /api/ {
                try_files $uri $uri/ /api/index.php;
        }

        location ~ \.php$ {
                fastcgi_pass unix:/var/run/php-fpm.socket;
                fastcgi_index index.php;
                try_files $uri $uri/ index.php = 404;
                include fastcgi_params;
        }

        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    }
}

If after configuring nginx, you should be able to run nginx -t and receive a successful test. Once this is done, you can restart nginx to reload the configuration.

[[email protected] ~]# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
[[email protected] ~]# sudo systemctl restart nginx

Hopefully after this, you should be able to connect to the server on your web browser and see the phpIPAM installation page. Let’s set it up!

phpIPAM Setup

Depending on your circumstances, you may wish to migrate from a previous installation of phpIPAM. You’re able to export the database from one server, and import it into this one. The website offers clear instructions on how to do this, so refer to that. Otherwise, for a fresh installation click the “New phpipam installation” button.

I find using the “MySQL/MariaDB Import Instructions” button to be more reliable. Since we’ve already configured the user and database access, let’s click that (option 2).

The website gives us a couple instructions, but we’ve most of them already. Let’s just import the SQL SCHEMA.

[[email protected] ~]# cd /var/www/phpipam/db/
[[email protected] db]# mysql -u phpipam -p phpipam < SCHEMA.sql 
Enter password:

After entering the password for the phpipam database user, you should be able to click “Login”. You’ll then be presented with the phpIPAM login page, login using the default credentials admin/ipamadmin.

That should be it! You’re ready to rock and roll.

First Steps

User, Groups, and Authentication

If you have centralised or federated authentication servers, you can use them to authenticate users against! Go to Administration > Authentication Methods > Create New. Select the appropriate server type, and enter in it’s details. Users are not automatically added after an authentication server is applied. You must create a new user on phpIPAM and set it’s authentication method to use the authentication server you have configured.

To create a new user, go to Administration > Users > Create user. Fill in the appropriate details and provide the user with N/R/W/A permissions per function, add them to a group, or just make application administrators. If you want to use an authentication server, select it under “Authentication method”.

Groups can be used to easily apply permissions to content within phpIPAM. To create a new group, go to Administration > Groups > Create group.

Section, Subnets, and IP Addresses

Without getting into too much detail, phpIPAM groups IP Addresses into subnets, and subnets into sections. You can also create subnet folders to contain sets of subnets within a section. Hierarchically from greatest to smallest; Section > Subnet Folder > Subnet > IP Address.

You can manage sections as an administrator, by going to Administration > Sections. To clean-up the defaults, delete the “Customers” and “IPv6” sections, and create a new section for your network. Generally, I create a new section for each common network. In my case, that’s just rajchert.net.

Once you’ve created the new subnet, you can find it under the Subnets drop-down menu at the top toolbar.

Within the section, you can add a Subnet.

Within the Subnet, you can add IP addresses.

Locations, Racks, and Devices

PhpIPAM can also track physical equipment within your network. You can create a new location for your equipment by clicking on the Map icon at the top toolbar, or by going to All Tools > Locations. Create a new location here.

We can create a new rack within this location. Click on the Rack icon at the top toolbar, or by going to All Tools > Racks. Create a new rack here, and set it’s Location to the one we have just created.

Within this rack, we can create add a new device. Click on the Computer icon at the top toolbar, or go to All Tools > Devices. Create a new device here, and add it to our rack we have just created.

Once added, click on the device to see a diagram of it represented within your rack!

Potential Issues

Missing Packages

PhpIPAM is able to identify if packages are missing, and it should generally tell you. Packages for stuff usually start with php-. So if phpIPAM is complaining the php-json is missing for example, you can do sudo yum install php-json.

404 Not Found

2022/03/04 11:56:10 [error] 3973#0: *1 open() "/var/www/phpipam/50x.html" failed (2: No such file or directory), client: 10.52.99.102, server: _, request: "GET / HTTP/2.0", upstream: "fastcgi://unix:/run/php-fpm/www.sock", host: "10.52.59.104"

Sometimes, php-fpm and nginx can ship with different configuration to what I have here. If you refer to /etc/nginx/conf.d/php-fpm.conf you’ll find setting for an upstream php-fpm server, likely with the value unix:/run/php-fpm/www.sock. If this value is different to the listen value in /etc/php-fpm/conf.d/www.conf, apache will fail to load php pages. Refer to the following configuration

# PHP-FPM FastCGI server
# network or unix domain socket configuration

upstream php-fpm {
        server unix:/run/php-fpm/www.sock;
}
; The address on which to accept FastCGI requests.
; Note: This value is mandatory.
listen = /run/php-fpm/www.sock

Upgrading phpIPAM

phpIPAM has been blessed with an active community, and frequently receives changes to the git repository here and there. To upgrade phpIPAM, simply cd in to the web root and run git pull.

[[email protected] php-fpm.d]# cd /var/www/phpipam/
[[email protected] phpipam]# git pull
Already up to date.

Leave a Reply

Your email address will not be published. Required fields are marked *