geek-cookbook/manuscript/test.html

<h1 id="phpipam">phpIPAM</h1>
<p>phpIPAM is an open-source web IP address management application (<em>IPAM</em>). Its goal is to provide light, modern and useful IP address management. It is php-based application with MySQL database backend, using jQuery libraries, ajax and HTML5/CSS3 features.</p>
<figure>
<img src="../images/phpipam.png" alt="phpIPAM Screenshot" /><figcaption>phpIPAM Screenshot</figcaption>
</figure>
<p>phpIPAM fulfils a non-sexy, but important role - It helps you manage your IP address allocation.</p>
<h2 id="why-should-you-care-about-this">Why should you care about this?</h2>
<p>You probably have a home network, with 20-30 IP addresses, for your family devices, your <img src="/recipe/home-assistant" alt="IoT devices" />, your smart TV, etc. If you want to (a) monitor them, and (b) audit who does what, you care about what IPs they’re assigned by your DHCP server.</p>
<p>You could simple keep track of all devices with leases in your DHCP server, but what happens if your (<em>hypothetical?</em>) Ubiquity Edge Router X crashes and burns due to lack of disk space, and you loose track of all your leases? Well, you have to start from scratch, is what!</p>
<p>And that <a href="/recipes/homeassistant/">HomeAssistant</a> config, which you so carefully compiled, refers to each device by IP/DNS name, so you’d better make sure you recreate it consistently!</p>
<p>Enter phpIPAM. A tool designed to help home keeps as well as large organisations keep track of their IP (<em>and VLAN, VRF, and AS number</em>) allocations.</p>
<h2 id="ingredients">Ingredients</h2>
<ol type="1">
<li><a href="/ha-docker-swarm/design/">Docker swarm cluster</a> with <a href="/ha-docker-swarm/shared-storage-ceph.md">persistent shared storage</a></li>
<li><a href="/ha-docker-swarm/traefik_public">Traefik</a> configured per design</li>
<li>DNS entry for the hostname (<em>i.e. “phpipam.your-domain.com”</em>) you intend to use for phpIPAM, pointed to your <a href="ha-docker-swarm/keepalived/">keepalived</a> IPIP</li>
</ol>
<h2 id="preparation">Preparation</h2>
<h3 id="setup-data-locations">Setup data locations</h3>
<p>We’ll need several directories to bind-mount into our container, so create them in /var/data/phpipam:</p>
<pre><code>mkdir /var/data/phpipam/databases-dump -p
mkdir /var/data/runtime/phpipam -p</code></pre>
<h3 id="prepare-environment">Prepare environment</h3>
<p>Create phpipam.env, and populate with the following variables</p>
<pre><code># Setup for github, phpipam application
OAUTH2_PROXY_CLIENT_ID=
OAUTH2_PROXY_CLIENT_SECRET=
OAUTH2_PROXY_COOKIE_SECRET=

# For MariaDB/MySQL database
MYSQL_ROOT_PASSWORD=imtoosecretformyshorts
MYSQL_DATABASE=phpipam
MYSQL_USER=phpipam
MYSQL_PASSWORD=secret

# phpIPAM-specific variables
MYSQL_ENV_MYSQL_USER=phpipam
MYSQL_ENV_MYSQL_PASSWORD=secret
MYSQL_ENV_MYSQL_DB=phpipam
MYSQL_ENV_MYSQL_HOST=db

# For backup
BACKUP_NUM_KEEP=7
BACKUP_FREQUENCY=1d</code></pre>
<p>Additionally, create phpipam-backup.env, and populate with the following variables:</p>
<pre><code># For MariaDB/MySQL database
MYSQL_ROOT_PASSWORD=imtoosecretformyshorts
MYSQL_DATABASE=phpipam
MYSQL_USER=phpipam
MYSQL_PASSWORD=secret

# For backup
BACKUP_NUM_KEEP=7
BACKUP_FREQUENCY=1d</code></pre>
<h3 id="create-nginx.conf">Create nginx.conf</h3>
<p>I usually protect my stacks using an <a href="/reference/oauth_proxy/">oauth proxy</a> container in front of the app. This protects me from either accidentally exposing a platform to the world, or having a insecure platform accessed and abused.</p>
<p>In the case of phpIPAM, the oauth_proxy creates an additional complexity, since it passes the “Authorization” HTTP header to the phpIPAM container. phpIPAH then examines the header, determines that the provided username (<em>my email address associated with my oauth provider</em>) doesn’t match a local user account, and denies me access without the opportunity to retry.</p>
<p>The (<em>dirty</em>) solution I’ve come up with is to insert an Nginx instance in the path between the oauth_proxy and the phpIPAM container itself. Nginx can remove the authorization header, so that phpIPAM can prompt me to login with a web-based form.</p>
<p>Create /var/data/phpipam/nginx.conf as follows:</p>
<pre><code>upstream app-upstream {
    server app:80;
}

server {
    listen 80;
    server_name ~.;

    # Just redirect everything to the upstream
    # Yes, it&#39;s embarassing. We are just a mechanism to strip an AUTH header :(
    location ^~ / {
        proxy_pass http://app-upstream;
    proxy_set_header       Authorization &quot;&quot;;
    }

}</code></pre>
<h3 id="setup-docker-swarm">Setup Docker Swarm</h3>
<p>Create a docker swarm config file in docker-compose syntax (v3), something like this:</p>
<p>!!! tip I share (<em>with my <a href="https://www.patreon.com/funkypenguin">patreon patrons</a></em>) a private “<em>premix</em>” git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a <code>git pull</code> and a <code>docker stack deploy</code> 👍</p>
<pre><code>version: &#39;3&#39;

services:

  db:
    image: mariadb:10
    env_file: /var/data/config/phpipam/phpipam.env
    networks:
      - internal
    volumes:
      - /var/data/runtime/phpipam/db:/var/lib/mysql

  proxy:
    image: funkypenguin/oauth2_proxy
    env_file: /var/data/config/phpipam/phpipam.env
    networks:
      - internal
      - traefik_public
    deploy:
      labels:
        - traefik.frontend.rule=Host:phpipam.example.com
        - traefik.docker.network=traefik_public
        - traefik.port=4180
    volumes:
      - /var/data/config/phpipam/authenticated-emails.txt:/authenticated-emails.txt
    command: |
      -cookie-secure=false
      -upstream=http://nginx
      -redirect-url=https://phpipam.example.com
      -http-address=http://0.0.0.0:4180
      -email-domain=example.com
      -provider=github
      -authenticated-emails-file=/authenticated-emails.txt

  # Wait, what? Why do we have an oauth_proxy _and_ an nginx frontend for a simple webapp?
  # Well, it&#39;s a long story. Basically, the phpipam container sees the &quot;auth&quot; headers passed by the
  # oauth_proxy, and decides to use these exclusively to authenticate users. So no web-based login form, just &quot;access denied&quot;
  # To work around this, we add nginx reverse proxy to the mix. A PITA, but an easy way to solve without altering the PHPIPAM code
  nginx:
    image: nginx:latest
    networks:
      - internal
    volumes:
      - /var/data/phpipam/nginx.conf:/etc/nginx/conf.d/default.conf:ro

  app:
    image: pierrecdn/phpipam
    env_file: /var/data/config/phpipam/phpipam.env
    networks:
      - internal

  db-backup:
    image: mariadb:10
    env_file: /var/data/config/phpipam/phpipam.env
    volumes:
      - /var/data/phpipam/database-dump:/dump
      - /etc/localtime:/etc/localtime:ro
    entrypoint: |
      bash -c &#39;bash -s &lt;&lt;EOF
      trap &quot;break;exit&quot; SIGHUP SIGINT SIGTERM
      sleep 2m
      while /bin/true; do
        mysqldump -h db --all-databases | gzip -c &gt; /dump/dump_\`date +%d-%m-%Y&quot;_&quot;%H_%M_%S\`.sql.gz
        (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sql.gz)|sort|uniq -u|xargs rm -- {}
        sleep $$BACKUP_FREQUENCY
      done
      EOF&#39;
    networks:
      - internal

networks:
  traefik_public:
    external: true
  internal:
    driver: overlay
    ipam:
      config:
        - subnet: 172.16.47.0/24</code></pre>
<p>!!! note Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See <a href="/reference/networks/">my list</a> here.</p>
<h2 id="serving">Serving</h2>
<h3 id="launch-phpipam-stack">Launch phpIPAM stack</h3>
<p>Launch the phpIPAM stack by running <code>docker stack deploy phpipam -c &lt;path -to-docker-compose.yml&gt;</code></p>
<p>Log into your new instance at https://<strong>YOUR-FQDN</strong>, and follow the on-screen prompts to set your first user/password.</p>
<h2 id="chefs-notes">Chef’s Notes</h2>
<ol type="1">
<li>If you wanted to expose the phpIPAM UI directly, you could remove the oauth2_proxy and the nginx services from the design, and move the traefik_public-related labels directly to the phpipam container. You’d also need to add the traefik_public network to the phpipam container.</li>
</ol>
<h3 id="tip-your-waiter-donate">Tip your waiter (support me) 👏</h3>
<p>Did you receive excellent service? Want to make your waiter happy? (<em>..and support development of current and future recipes!</em>) See the <a href="/support/">support</a> page for (<em>free or paid)</em> ways to say thank you! 👏</p>
<h3 id="your-comments">Your comments? 💬</h3>