Compatible with DokuWiki

• 2023-04-04 "Jack Jackrum" unknown
• 2022-07-31 "Igor" unknown
• 2020-07-29 "Hogfather" unknown
• 2018-04-22 "Greebo" yes

• Download
• Report bugs
• Donate

Fetch subnet hosts from a {php}IPAM instance into your wiki

Last updated on

2020-08-27

Provides

Syntax

Repository

Source

Similar to dig, rack

Tagged with cage, database, ip, ipam, network, rack, server, subnet

By GilCot

This plugin allows you to add IP addresses lists (and other objects description) to any DokuWiki page. The plugin is similar to the data plugin but is toward the excellent {php}IPAM!

Please, read and follow carefully the following steps.

This plugin requires the following additional PHP components that must be installed separately

• curl (required)
• mcrypt (required)
• openssl (optional)
• json (optional)

Search and install the plugin using the Extension Manager.

If you install this plugin manually, make sure it is installed in lib/plugins/phpipam/ of the webapp root folder – if the folder is called differently, it won't work !

Please refer to Plugins for additional info on how to install plugins in DokuWiki.

Preferably before installing this plugin, go to your {php}IPAM instance and setup and test an API access (see Deans example).

From version 1.3.2, API Crypt provider default to OpenSSL! If you are not using password access, you have to switch back to MCrypt by editing the settings file, config.php, and add/uncomment this line:

$api_crypt_encryption_library = "mcrypt";

Once installed, successfully, go to your “Configuration Manager” (from the “Admin” page, choose “Configuration Settings”), and put the API parameters (plus some others…) You are now ready to use the provided syntax in your DokuWiki pages.

This plugin offers at least three case-insensitive syntaxes:

• a new XML tag like:

  <phpipam ... />

• a new MoinMoin variable like:

  @phpipam ... @@

• a new DokuWiki macro like:

  ~phpipam ... ~~

The call, to produce an effect, must have some pair parameters_or_attributes=value set.

Following sub-sections will list available attributes and their meaning.

All other pairs parameter=value (i.e. parameters not listed) are passed to the API to be used as filter; so be careful…

A first category of attributes are those related to the IPAM object.

There's a parameter fmt or format that will direct the output.
For each object (subnet/device/VLAN/location) there's

• a presentation heading (when the format parameter is either head or both)
• a list (when the format parameter is either list or both) of addresses in most cases

There's an exception for racks… where the list of enclosed devices is always displayed –block representation like with plugins of Ashraff Hasson (advrack) or Tyler Bletsch (rack) from which bunch of code is stolen from– and format can be one of front or back or default both.

A second category of attributes take index of an object to produce the output to some other object previously discussed.

I think all possible cases are covered so, otherwise let me know.

But be careful: unrecognized attributes/parameters are passed to the API. So, if you pass for example foo=bah, it will fail!

But there're some additional attributes that can be used to refine results. Two useful mentioned in the documentation are filter_by with a field name and filter_value. In order to use them, you should set the required index to 0 (zero.)

Let's illustrate that. When you know that the location index is ten, that's simple as:

<phpipam lid=10 />

But if you know the exact name and can't remember/find the exact index, no worry:

<phpipam lid=0 filter_by=name filter_value="my name" />

By the same way, when you need all sub networks in folder two with the fourth name servers list, simple as:

<phpipam f2s=2 filter_by=nameserverId filter_value=4 />

That's not possible with: sid/nid, tid; and restricted with: f2s/f2n, cidr/net

The plugin can be personalized in many ways.

Each object (subnet/device/VLAN/location) is output in a box that contains:

• a title if allowed in settings
• a box for presentation heading (format=head or format=both)
• a box for list of elements (format=list or format=both)

┌────<div>─────────────────────────────────────────────────────────────┐
│ main box                                                             │
│  ┌────<h6>─────────────────────────────────────────────────────────┐ │
│  │ title box                                                       │ │
│  └────</h6>────────────────────────────────────────────────────────┘ │
│  ┌────<div>────────────────────────────────────────────────────────┐ │
│  │ presentation box (depends setting)                              │ │
│  └────</div>───────────────────────────────────────────────────────┘ │
│  ┌────<div>────────────────────────────────────────────────────────┐ │
│  │ listing box (depends setting)                                   │ │
│  └────</div>───────────────────────────────────────────────────────┘ │
└────</div>────────────────────────────────────────────────────────────┘

Position and styling of the output boxes can be done with simple CSS.
You now can style those boxes with CSS in your <dokuwiki>/conf/userstyle.css. For that purpose, some classes are provided:

They are named with the object (subnet/device/vlan/location) and it's index (i.e. XX or YY here) and the attribut (i.e. ZZ here) Listings work like presentations. Depending on the settings, some inner classes may be missing and some others added (there're often rowN and colN –with N an integer.)

┌────<div class="phpipam phpipam_OBJECT-XX">───────────────────────────┐
│ main box                                                             │
│  ┌────<h6 class="OBJECT_name">─────────────────────────────────────┐ │
│  │ title                                                           │ │
│  └────</h6>────────────────────────────────────────────────────────┘ │
│  ┌────<div class="inline phpipam_OBJECTs">─────────────────────────┐ │
│  │ presentation box (depends setting)                              │ │
│  │ ┌────<div class="phpipam_OBJECT_Param1 row0">─────────────────┐ │ │
│  │ └────</div><!-- phpipam_OBJECT_Param1 row0-->─────────────────┘ │ │
│  │ ┌────<div class="phpipam_OBJECT_Param2 row1">─────────────────┐ │ │
│  │ └────</div><!-- phpipam_OBJECT_Param2 row1-->─────────────────┘ │ │
│  └────</div>───────────────────────────────────────────────────────┘ │
│  ┌────<div class="phpipam_OBJECT">─────────────────────────────────┐ │
│  │ listing box (depends setting)                                   │ │
│  │ ┌────<div class="phpipam_OBJECT_Param1 row0">─────────────────┐ │ │
│  │ └────</div><!-- phpipam_OBJECT_Param1 row0-->─────────────────┘ │ │
│  │ ┌────<div class="phpipam_OBJECT_Param2 row1">─────────────────┐ │ │
│  │ └────</div><!-- phpipam_OBJECT_Param2 row1-->─────────────────┘ │ │
│  └────</div>───────────────────────────────────────────────────────┘ │
└────</div>────────────────────────────────────────────────────────────┘

For example, you may have things like:

phpipam {
  background-color: aliceblue;
  color: black;
}
 
phpipam_tag-1 {
  background-color: #f59c99;
  color: inherit;
}
 
phpipam_tag-2 {
  background-color: #a9c9a4;
  color: inherit;
}
 
phpipam_tag-3 {
  background-color: #9ac0cd;
  color: #efefef;
}
 
phpipam_tag-4 {
  background-color: #c9c9c9;
  color: #fefefe;
}

They may have some other classes depending on the configuration. For example, for tables, they are also rowX and colX etc.

If you use the translation plugin, you might want to use the labels and keywords in different languages. If you only want to use English field names while having them displayed in your language, you can also follow these instructions.

To create new translations, create a file in <dokuwiki>/conf/lang/<langcode>/phpipam-plugin.php. The file needs to contain a PHP array named $lang with the label in the array key and the translation in the value:

<?php
$lang['somekey']  = 'My name for some key';
$lang['otherkey'] = 'My name for other key';

After creating or modifying phpipam-plugin.php file, please update your DokuWiki configuration to refresh cache start?do=admin&page=config, otherwise modifications are not taken into account.

Important! These are hacks – there is no guarantee they'll always work, and they will not survive updates.

If it breaks you get to keep the pieces.

This plugin is opensource.

Please submit bugs and feature requests in the issue tracker on GitHub.

Patches should be sent unified diff format or as Git patches against the master branch.
Or even better: fork the repository at GitHub and send a merge request.

This plugin came to life because a company I'm working is switching from DokuWiki (for our department) and others (some department use spreadsheet and some other department another tool) to a common IPAM. As our wiki is for general infrastructure documentation with some subnet addresses listed here and there, I wrote a this plugin in order to avoid switching between tabs and ease migration…
So, the first implementations is what is given by sid/nid or (added later) net/cidr attributes. But later we had DHCP addresses we'd like to show in compressed form (whereas maybe some other users would like to “hide” some other tag.) Unfortunately I don't have time to incorporate it.

When we updated to version 1.3, we've been pleased by the locations and racks modules. This plugin is then rewritten with newer attributes lid, eid (renamed so when I've added VRF and VLAN later), did, l2s/l2n, l2e, e2d, l2d, l2e, d2e. However, having to deal with numeric identifiers is not so friendly. A workaround is provided by the support of filters. Currently, API doesn't offer a simpler way to do that; and there's no partial search…

Also, later, before public release, I've added the other attributes: t2n/t2s, t2d, s2n/s2s, f2n/f2s, r2n/r2s, vid, s2v, 22v. Most of them are PoC and they may be room for improvement.

Last but not least; many CSS classes are added, but a consistency check must be done.
Despite that, there're some inline styles here and there: a clean should be performed…

I don't plan to add some other things ; there's already enough to play with.
That doesn't mean there aren't ideas in the hood (nat, patch panels, circuits, etc.) To be followed…

If you still have questions, search the forum, and if it hasn't been asked before ask your question there.
Please leave bug reports on GitHub's issue tracker.

• correct URL typo (2021-04-23 15:13)
• Gilcot patch 2 (#3) (2020-09-21 21:51)
• update version (2020-08-27 21:16)
• Update version (2020-08-27 21:15)
• remove 2nd param from listAddrs func (2020-08-27 21:11)
• initial public release (2018-09-12 00:32)
• Initial commit (2018-08-25 15:01)